### STAPI Client CLI Usage

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Instructions for installing and using the pystapi-client command-line interface (CLI). Examples cover listing products, getting specific products, listing and getting orders, and searching for opportunities.

```bash
# Install pystapi-client
pip install pystapi-client

# List all products from a STAPI server
stapi --url http://localhost:8000 products
stapi --url http://localhost:8000 products --limit 5 --max-items 10

# Get a specific product by ID
stapi --url http://localhost:8000 product --id optical-30cm

# List all orders
stapi --url http://localhost:8000 orders
stapi --url http://localhost:8000 orders --limit 20

# Get a specific order by ID
stapi --url http://localhost:8000 order --id your-order-uuid

# Search opportunities for a product
stapi --url http://localhost:8000 opportunities --product-id optical-30cm --limit 10
```

--------------------------------

### STAPI CLI Usage Example

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Example of using the stapi CLI to fetch product data and format it as JSON using jq. This demonstrates basic interaction with the STAPI service.

```bash
stapi --url http://localhost:8000 products | jq '.[] | {id, title}'
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/stapi-spec/pystapi/blob/main/CONTRIBUTING.md

Installs pre-commit hooks to automatically run checks on every commit. This helps maintain code quality and consistency before code is committed.

```shell
uv run pre-commit install
```

--------------------------------

### Pytest Example

Source: https://github.com/stapi-spec/pystapi/blob/main/CONTRIBUTING.md

Demonstrates the correct way to write tests using pytest, emphasizing free functions over class-based tests. This ensures consistency with the project's testing framework.

```python
def test_foo() -> None:
    assert 1 == 1
```

--------------------------------

### Get All Orders with Pagination (Python)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Lists all orders with pagination support. It retrieves orders from the database, calculates the start and end indices based on the provided 'next' token (order ID) and 'limit', and returns a page of orders along with pagination tokens for subsequent requests.

```python
async def get_orders(
    next: str | None,
    limit: int,
    request: Request,
) -> ResultE[tuple[list[Order], Maybe[str], Maybe[int]]]:
    """List all orders with pagination."""
    try:
        all_orders = list(db.orders.values())
        total_count = len(all_orders)

        start_idx = 0
        if next:
            # Find index by order ID
            order_ids = list(db.orders.keys())
            start_idx = order_ids.index(next) if next in order_ids else 0

        end_idx = start_idx + min(limit, 100)
        page = all_orders[start_idx:end_idx]

        # Return pagination token and total count
        if end_idx < total_count:
            next_token = list(db.orders.keys())[end_idx]
            return Success((page, Some(next_token), Some(total_count)))
        return Success((page, Nothing, Some(total_count)))
    except ValueError:
        return Failure(ValueError("Invalid pagination token"))
    except Exception as e:
        return Failure(e)
```

--------------------------------

### Get All Orders

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves a list of all orders.

```APIDOC
## GET /orders

### Description
Retrieves a list of all orders. Supports pagination via the `limit` query parameter.

### Method
GET

### Endpoint
/orders

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of orders to return.

### Request Example
```bash
curl -X GET "http://localhost:8000/orders?limit=10"
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **features** (array) - A list of order objects.
- **next** (string) - Optional - A token for retrieving the next page of results.
- **totalResults** (integer) - Optional - The total number of orders available.

#### Response Example
```json
{
  "features": [
    {
      "id": "some-order-id",
      "geometry": {"type": "Point", "coordinates": [0, 0]},
      "properties": {
        "product_id": "optical-30cm",
        "created": "2023-10-27T10:00:00Z",
        "status": {"timestamp": "2023-10-27T10:00:00Z", "status_code": "received"},
        "search_parameters": {
          "geometry": {"type": "Point", "coordinates": [0, 0]},
          "datetime": "2023-10-27T10:00:00Z",
          "filter": {}
        },
        "order_parameters": {"output_format": "GeoTIFF", "processing_level": "L1B"},
        "opportunity_properties": {"datetime": "2023-10-27T10:00:00Z"}
      },
      "links": []
    }
  ],
  "next": null,
  "totalResults": 1
}
```
```

--------------------------------

### Backend Implementation Guide

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Details on implementing backend services using `stapi-fastapi`, focusing on typed callback functions for handling API requests like searching opportunities and managing orders.

```APIDOC
## Backend Implementation Guide

### Description
This guide explains how to implement backend services using the `stapi-fastapi` package. It emphasizes the use of typed callback functions to handle various API operations, such as searching for opportunities and processing orders. The example demonstrates a simulated database and an asynchronous function for searching opportunities, including pagination logic.

### Backend Functions

The `stapi-fastapi` package utilizes typed callback functions for backend implementations. Key function types include:

- `SearchOpportunities`: Synchronous opportunity search.
- `SearchOpportunitiesAsync`: Asynchronous opportunity search (returns search record).
- `GetOpportunityCollection`: Retrieve asynchronous search results.
- `CreateOrder`: Create a new order.
- `GetOrders`: List orders with pagination.
- `GetOrder`: Get a single order by ID.
- `GetOrderStatuses`: Get order status history.

### Example: Searching Opportunities

This example shows an asynchronous backend function for searching opportunities, including basic error handling and pagination.

```python
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4

from fastapi import Request
from returns.maybe import Maybe, Nothing, Some
from returns.result import Failure, ResultE, Success
from pydantic import BaseModel

from stapi_fastapi import RootRouter
from stapi_fastapi.models.product import Product
from stapi_fastapi.routers.product_router import ProductRouter
from stapi_pydantic import (
    Opportunity,
    OpportunityCollection,
    OpportunityPayload,
    OpportunityProperties,
    OpportunitySearchRecord,
    OpportunitySearchStatus,
    OpportunitySearchStatusCode,
    Order,
    OrderPayload,
    OrderProperties,
    OrderSearchParameters,
    OrderStatus,
    OrderStatusCode,
)

# Database simulation (replace with your actual database)
class Database:
    def __init__(self):
        self.orders: dict[str, Order] = {}
        self.order_statuses: dict[str, list[OrderStatus]] = {}
        self.search_records: dict[str, OpportunitySearchRecord] = {}

db = Database()

# Backend: Search opportunities synchronously
async def search_opportunities(
    product_router: ProductRouter,
    search: OpportunityPayload,
    next: str | None,
    limit: int,
    request: Request,
) -> ResultE[tuple[list[Opportunity], Maybe[str]]]:
    """
    Search for available imaging opportunities.

    Returns:
        Success with tuple of (opportunities_list, optional_pagination_token)
        Failure with exception for 500 errors
    """
    try:
        # Query your satellite scheduling system here
        # Apply filters from search.filter (CQL2)
        # Use search.datetime for time range
        # Use search.geometry for area of interest

        opportunities: list[Opportunity] = []  # Populate from your backend

        # Handle pagination
        start_idx = int(next) if next else 0
        end_idx = start_idx + limit
        page = opportunities[start_idx:end_idx]

        # Return pagination token if more results exist
        if end_idx < len(opportunities):
            return Success((page, Some(str(end_idx))))
        return Success((page, Nothing))
    except Exception as e:
        return Failure(e)
```

### Parameters for `search_opportunities`

- `product_router` (`ProductRouter`): The router instance for product-related operations.
- `search` (`OpportunityPayload`): The search criteria, including filters, datetime, and geometry.
- `next` (str | None): A token for pagination, indicating the starting point of the next page.
- `limit` (int): The maximum number of results to return per page.
- `request` (`Request`): The incoming FastAPI request object.

### Return Value

- `ResultE[tuple[list[Opportunity], Maybe[str]]]`:
    - On success: A tuple containing a list of `Opportunity` objects and an optional pagination token (`Maybe[str]`).
    - On failure: A `Failure` object containing the exception that occurred.
```

--------------------------------

### Get Specific Product

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves details for a specific satellite imagery product.

```APIDOC
## GET /products/{product_id}

### Description
Retrieves detailed information about a specific satellite imagery product identified by its `product_id`.

### Method
GET

### Endpoint
/products/{product_id}

### Parameters
#### Path Parameters
- **product_id** (string) - Required - The unique identifier of the product.

### Request Example
```bash
curl -X GET "http://localhost:8000/products/optical-30cm"
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the product.
- **title** (string) - The title of the product.
- **description** (string) - A description of the product.
- **license** (string) - The licensing information for the product.
- **keywords** (array) - A list of keywords associated with the product.
- **providers** (array) - Information about the providers of the product.
- **links** (array) - Links related to the product.

#### Response Example
```json
{
  "id": "optical-30cm",
  "title": "30cm Optical Imagery",
  "description": "High-resolution optical satellite imagery",
  "license": "proprietary",
  "keywords": ["satellite", "optical"],
  "providers": [
    {
      "name": "MySatellite Inc",
      "description": "Commercial satellite imagery",
      "roles": ["producer"],
      "url": "https://mysatellite.example.com"
    }
  ],
  "links": []
}
```
```

--------------------------------

### Install pystapi-client using pip

Source: https://github.com/stapi-spec/pystapi/blob/main/pystapi-client/README.md

This command installs the pystapi-client library and its dependencies, including httpx and python-dateutil, allowing you to interact with STAPI APIs from your Python projects.

```shell
python -m pip install pystapi-client
```

--------------------------------

### Pagination Endpoints

Source: https://github.com/stapi-spec/pystapi/blob/main/stapi-fastapi/README.md

This section details the endpoints that support pagination, including GET and POST requests. Pagination is token-based and uses 'limit' and 'token' query parameters for GET requests, or body parameters for POST requests.

```APIDOC
## GET /orders

### Description
Retrieves a paginated list of orders.

### Method
GET

### Endpoint
/orders

### Query Parameters
- **limit** (integer) - Optional - The maximum number of results to return (defaults to 10, maxes at 100).
- **token** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **next** (object) - A link object containing the URL for the next page of results, if available.

## GET /products

### Description
Retrieves a paginated list of products.

### Method
GET

### Endpoint
/products

### Query Parameters
- **limit** (integer) - Optional - The maximum number of results to return (defaults to 10, maxes at 100).
- **token** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **next** (object) - A link object containing the URL for the next page of results, if available.

## GET /orders/{order_id}/statuses

### Description
Retrieves a paginated list of statuses for a specific order.

### Method
GET

### Endpoint
/orders/{order_id}/statuses

### Path Parameters
- **order_id** (string) - Required - The ID of the order.

### Query Parameters
- **limit** (integer) - Optional - The maximum number of results to return (defaults to 10, maxes at 100).
- **token** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **next** (object) - A link object containing the URL for the next page of results, if available.

## POST /opportunities

### Description
Creates a new opportunity with pagination support.

### Method
POST

### Endpoint
/opportunities

### Request Body
- **limit** (integer) - Optional - The maximum number of results to return (defaults to 10, maxes at 100).
- **token** (string) - Optional - The token for the next page of results.

### Response
#### Success Response (200)
- **next** (object) - A link object containing the URL for the next page of results, if available.
```

--------------------------------

### Start Async Opportunity Search (Python)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Initiates an asynchronous search for opportunities. It generates a unique search ID, creates a search record, stores it, and returns the record immediately. The actual processing is intended to be handled by a background task.

```python
async def search_opportunities_async(
    product_router: ProductRouter,
    search: OpportunityPayload,
    request: Request,
) -> ResultE[OpportunitySearchRecord]:
    """
    Start an asynchronous opportunity search.
    Returns immediately with a search record ID.
    """
    try:
        search_id = str(uuid4())
        status = OpportunitySearchStatus(
            timestamp=datetime.now(UTC),
            status_code=OpportunitySearchStatusCode.received,
        )
        record = OpportunitySearchRecord(
            id=search_id,
            product_id=product_router.product.id,
            opportunity_request=search,
            status=status,
            links=[],
        )
        db.search_records[search_id] = record

        # Trigger async processing (e.g., queue a background job)
        # background_tasks.add_task(process_search, search_id, search)

        return Success(record)
    except Exception as e:
        return Failure(e)
```

--------------------------------

### STAPI Item Fulfillment Example

Source: https://github.com/stapi-spec/pystapi/blob/main/stapi-fastapi/adrs/constraints.md

An example of an Item that fulfills an Order placed on a STAPI Opportunity, demonstrating how the properties defined in the JSON Schema are represented in a concrete Feature object.

```json
{
  "type": "Feature",
  ...
  "properties": {
    "datetime": "2024-01-01T00:00:00Z",
    "sensor_type": "2",
    "craft_id": "7",
    "view:sun_elevation": 30.0,
    "view:azimuth": 105.0,
    "view:off_nadir": 9.0,
    "eo:cloud_cover": 10.0
  }
}
```

--------------------------------

### STAPI Server Interaction with Curl

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Examples of interacting with a STAPI server using curl commands. These commands demonstrate how to fetch product queryables, order parameters, search for opportunities, create orders, and list/retrieve orders.

```bash
curl -X GET "http://localhost:8000/products/optical-30cm/queryables" \
  -H "Accept: application/json"
```

```bash
curl -X GET "http://localhost:8000/products/optical-30cm/order-parameters" \
  -H "Accept: application/json"
```

```bash
curl -X POST "http://localhost:8000/products/optical-30cm/opportunities" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": ["2025-01-01T00:00:00Z", "2025-03-01T00:00:00Z"],
    "geometry": {
      "type": "Point",
      "coordinates": [-122.4194, 37.7749]
    },
    "limit": 10
  }'
```

```bash
curl -X POST "http://localhost:8000/products/optical-30cm/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": ["2025-01-15T10:00:00Z", "2025-01-15T10:30:00Z"],
    "geometry": {
      "type": "Point",
      "coordinates": [-122.4194, 37.7749]
    },
    "order_parameters": {
      "output_format": "GeoTIFF",
      "processing_level": "L1B"
    }
  }'
```

```bash
curl -X GET "http://localhost:8000/orders?limit=10" \
  -H "Accept: application/geo+json"
```

```bash
curl -X GET "http://localhost:8000/orders/{order_id}" \
  -H "Accept: application/geo+json"
```

```bash
curl -X GET "http://localhost:8000/orders/{order_id}/statuses" \
  -H "Accept: application/json"
```

--------------------------------

### STAPI List Products Endpoint Request (Bash)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Demonstrates how to list all available products offered by the STAPI server, with an example of limiting the results to 10. The response is a JSON array of product objects.

```bash
# List all products
curl -X GET "http://localhost:8000/products?limit=10" \
  -H "Accept: application/json"
```

--------------------------------

### Get Single Order

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves details for a specific order.

```APIDOC
## GET /orders/{order_id}

### Description
Retrieves detailed information about a specific order identified by its `order_id`.

### Method
GET

### Endpoint
/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier of the order.

### Request Example
```bash
curl -X GET "http://localhost:8000/orders/some-order-id"
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the order.
- **geometry** (object) - The geometry associated with the order.
- **properties** (object) - Properties of the order, including product ID, creation time, status, search parameters, and order parameters.
- **links** (array) - Links related to the order.

#### Response Example
```json
{
  "id": "some-order-id",
  "geometry": {"type": "Point", "coordinates": [0, 0]},
  "properties": {
    "product_id": "optical-30cm",
    "created": "2023-10-27T10:00:00Z",
    "status": {"timestamp": "2023-10-27T10:00:00Z", "status_code": "received"},
    "search_parameters": {
      "geometry": {"type": "Point", "coordinates": [0, 0]},
      "datetime": "2023-10-27T10:00:00Z",
      "filter": {}
    },
    "order_parameters": {"output_format": "GeoTIFF", "processing_level": "L1B"},
    "opportunity_properties": {"datetime": "2023-10-27T10:00:00Z"}
  },
  "links": []
}
```
```

--------------------------------

### Implement Basic STAPI Server with FastAPI

Source: https://context7.com/stapi-spec/pystapi/llms.txt

This snippet shows the foundational setup for a STAPI-compliant server using `stapi-fastapi` and FastAPI. It imports necessary components like `FastAPI`, routers, and STAPI models, preparing for the integration of custom backend logic and API endpoints.

```python
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4

from fastapi import FastAPI, Request
from returns.maybe import Maybe, Nothing, Some
from returns.result import Failure, ResultE, Success
from pydantic import BaseModel, Field

from stapi_fastapi import RootRouter, ProductRouter
from stapi_fastapi.conformance import API, PRODUCT
from stapi_fastapi.models.product import Product
from stapi_pydantic import (
    Opportunity,
    OpportunityCollection,
    OpportunityPayload,
    OpportunityProperties,
    Order,
    OrderParameters,
    OrderPayload,
    OrderProperties,
    OrderSearchParameters,
    OrderStatus,
    OrderStatusCode,
    Provider,
    ProviderRole,
)


```

--------------------------------

### STAPI Backend Implementation: Search Opportunities

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Provides an example of implementing the `search_opportunities` backend function using `stapi-fastapi`. This function handles synchronous opportunity searching, including filtering, date range, geometry, and pagination. It returns a `ResultE` containing a list of opportunities and an optional pagination token.

```python
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4

from fastapi import Request
from returns.maybe import Maybe, Nothing, Some
from returns.result import Failure, ResultE, Success
from pydantic import BaseModel

from stapi_fastapi import RootRouter
from stapi_fastapi.models.product import Product
from stapi_fastapi.routers.product_router import ProductRouter
from stapi_pydantic import (
    Opportunity,
    OpportunityCollection,
    OpportunityPayload,
    OpportunityProperties,
    OpportunitySearchRecord,
    OpportunitySearchStatus,
    OpportunitySearchStatusCode,
    Order,
    OrderPayload,
    OrderProperties,
    OrderSearchParameters,
    OrderStatus,
    OrderStatusCode,
)

# Type aliases for backend functions (from stapi_fastapi.backends)
# SearchOpportunities: Sync opportunity search
# SearchOpportunitiesAsync: Async opportunity search (returns search record)
# GetOpportunityCollection: Retrieve async search results
# CreateOrder: Create a new order
# GetOrders: List orders with pagination
# GetOrder: Get single order by ID
# GetOrderStatuses: Get order status history

# Database simulation (replace with your actual database)
class Database:
    def __init__(self):
        self.orders: dict[str, Order] = {}
        self.order_statuses: dict[str, list[OrderStatus]] = {}
        self.search_records: dict[str, OpportunitySearchRecord] = {}

db = Database()

# Backend: Search opportunities synchronously
async def search_opportunities(
    product_router: ProductRouter,
    search: OpportunityPayload,
    next: str | None,
    limit: int,
    request: Request,
) -> ResultE[tuple[list[Opportunity], Maybe[str]]]:
    """
    Search for available imaging opportunities.

    Returns:
        Success with tuple of (opportunities_list, optional_pagination_token)
        Failure with exception for 500 errors
    """
    try:
        # Query your satellite scheduling system here
        # Apply filters from search.filter (CQL2)
        # Use search.datetime for time range
        # Use search.geometry for area of interest

        opportunities: list[Opportunity] = []  # Populate from your backend

        # Handle pagination
        start_idx = int(next) if next else 0
        end_idx = start_idx + limit
        page = opportunities[start_idx:end_idx]

        # Return pagination token if more results exist
        if end_idx < len(opportunities):
            return Success((page, Some(str(end_idx))))
        return Success((page, Nothing))
    except Exception as e:
        return Failure(e)

```

--------------------------------

### GET /orders

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves a paginated list of all orders. Supports pagination using a `next` token and specifies the number of items per page with `limit`.

```APIDOC
## GET /orders

### Description
List all orders with pagination.

### Method
GET

### Endpoint
/orders

### Parameters
#### Query Parameters
- **next** (string) - Optional - A token for the next page of results.
- **limit** (integer) - Optional - The maximum number of orders to return per page. Defaults to a reasonable value if not provided.

#### Request Body
- **request** (object) - Required - The incoming HTTP request object.

### Response
#### Success Response (200)
- **page** (array) - A list of orders for the current page.
- **next_token** (string | null) - A token for the next page of results, or null if this is the last page.
- **total_count** (integer | null) - The total number of orders available.

#### Response Example
```json
{
  "page": [
    {
      "id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
      "geometry": {"type": "Polygon", "coordinates": [...]},
      "properties": {
        "product_id": "some_product_id",
        "created": "2023-10-27T10:05:00Z",
        "status": {"code": "received", "timestamp": "2023-10-27T10:05:00Z"},
        "search_parameters": {},
        "order_parameters": {"resolution": "3m"},
        "opportunity_properties": {}
      },
      "links": []
    }
  ],
  "next_token": "next_order_id_123",
  "total_count": 150
}
```
```

--------------------------------

### Get All Orders Backend Function (Python)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves all orders stored in the in-memory database. It supports pagination using 'next' and 'limit' parameters and returns the total count of orders.

```python
async def get_orders(
    next: str | None,
    limit: int,
    request: Request,
) -> ResultE[tuple[list[Order], Maybe[str], Maybe[int]]]:
    try:
        orders = list(orders_db.values())
        return Success((orders[:limit], Nothing, Some(len(orders))))
    except Exception as e:
        return Failure(e)
```

--------------------------------

### Get Single Order Backend Function (Python)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves a specific order from the in-memory database using its ID. Returns the order if found, otherwise returns Nothing.

```python
async def get_order(order_id: str, request: Request) -> ResultE[Maybe[Order]]:
    try:
        return Success(Maybe.from_optional(orders_db.get(order_id)))
    except Exception as e:
        return Failure(e)
```

--------------------------------

### STAPI Get Specific Product Endpoint Request (Bash)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Illustrates how to retrieve details for a specific product, identified by its ID (e.g., 'optical-30cm'). The request returns a JSON object containing the product's metadata.

```bash
# Get a specific product
curl -X GET "http://localhost:8000/products/optical-30cm" \
  -H "Accept: application/json"
```

--------------------------------

### STAPI Root Endpoint Request (Bash)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Demonstrates how to make a GET request to the root endpoint of the STAPI server to retrieve landing page information and available links. The expected JSON response includes API details and conformance information.

```bash
# Root endpoint - landing page with links
curl -X GET "http://localhost:8000/" \
  -H "Accept: application/json"
```

--------------------------------

### Build Documentation with MkDocs

Source: https://github.com/stapi-spec/pystapi/blob/main/CONTRIBUTING.md

Builds the project's documentation using MkDocs. This command generates the static site for the documentation.

```shell
uv run mkdocs build
```

--------------------------------

### Initialize and Use pystapi-client in Python

Source: https://github.com/stapi-spec/pystapi/blob/main/pystapi-client/README.md

Demonstrates how to initialize the pystapi_client.Client with an API endpoint and perform common operations such as listing and retrieving products, and listing opportunities for a product. It also shows how to list and retrieve orders.

```python
from pystapi_client import Client

# Initialize client
client = Client.open("https://api.example.com/stapi")

# List all products
products = list(client.get_products())

# Get specific product
product = client.get_product("test-spotlight")

# List all Opportunities for a Product
opportunities = client.get_product_opportunities("test-spotlight")

# List orders
orders = client.get_orders()

# Get specific order
order = client.get_order("test-order")
```

--------------------------------

### Get Order Status History with Pagination (Python)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves the status history for a given order, with pagination. It fetches the list of statuses for an order ID and returns a page of statuses based on the 'next' token (which represents the start index) and 'limit'. If no statuses are found or the order ID is invalid, it returns Nothing.

```python
async def get_order_statuses(
    order_id: str,
    next: str | None,
    limit: int,
    request: Request,
) -> ResultE[Maybe[tuple[list[OrderStatus], Maybe[str]]]]:
    """Get status history for an order."""
    try:
        statuses = db.order_statuses.get(order_id)
        if statuses is None:
            return Success(Nothing)

        start_idx = int(next) if next else 0
        end_idx = start_idx + limit
        page = statuses[start_idx:end_idx]

        if end_idx < len(statuses):
            return Success(Some((page, Some(str(end_idx)))))
        return Success(Some((page, Nothing)))
    except Exception as e:
        return Failure(e)
```

--------------------------------

### Serve Documentation Locally with MkDocs

Source: https://github.com/stapi-spec/pystapi/blob/main/CONTRIBUTING.md

Serves the project's documentation locally using MkDocs. This allows developers to preview documentation changes in real-time.

```shell
uv run mkdocs serve
```

--------------------------------

### List All Products

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves a list of all available satellite imagery products.

```APIDOC
## GET /products

### Description
Retrieves a list of all available satellite imagery products offered by the API. Supports pagination via the `limit` query parameter.

### Method
GET

### Endpoint
/products

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of products to return.

### Request Example
```bash
curl -X GET "http://localhost:8000/products?limit=10"
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **features** (array) - A list of product objects.

#### Response Example
```json
{
  "features": [
    {
      "id": "optical-30cm",
      "title": "30cm Optical Imagery",
      "description": "High-resolution optical satellite imagery",
      "license": "proprietary",
      "keywords": ["satellite", "optical"],
      "providers": [
        {
          "name": "MySatellite Inc",
          "description": "Commercial satellite imagery",
          "roles": ["producer"],
          "url": "https://mysatellite.example.com"
        }
      ],
      "links": []
    }
  ]
}
```
```

--------------------------------

### Define Provider and Product (Python)

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Defines a 'Provider' for satellite imagery and creates a 'Product' instance. The product is configured with custom queryables, opportunity properties, and order parameters, and linked to the backend functions.

```python
provider = Provider(
    name="MySatellite Inc",
    description="Commercial satellite imagery",
    roles=[ProviderRole.producer],
    url="https://mysatellite.example.com",
)

product = Product(
    id="optical-30cm",
    title="30cm Optical Imagery",
    description="High-resolution optical satellite imagery",
    license="proprietary",
    keywords=["satellite", "optical"],
    providers=[provider],
    links=[],
    create_order=create_order,
    search_opportunities=search_opportunities,
    queryables=SatelliteQueryables,
    opportunity_properties=SatelliteOpportunityProperties,
    order_parameters=SatelliteOrderParameters,
    conformsTo=[PRODUCT.geojson_point, PRODUCT.opportunities],
)
```

--------------------------------

### Create Order API

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Creates a new order for a specific product with specified parameters.

```APIDOC
## POST /products/{product_id}/orders

### Description
Creates a new order for a specified product.

### Method
POST

### Endpoint
/products/{product_id}/orders

### Parameters
#### Path Parameters
- **product_id** (string) - Required - The ID of the product for which to create an order.

#### Request Body
- **datetime** (array of strings) - Required - A list containing the start and end datetime for the order (ISO 8601 format).
- **geometry** (object) - Required - A GeoJSON geometry object defining the spatial area for the order.
- **order_parameters** (object) - Required - An object containing specific parameters for the order, such as output format and processing level.
  - **output_format** (string) - Required - The desired output format (e.g., "GeoTIFF").
  - **processing_level** (string) - Optional - The desired processing level (e.g., "L1B").

### Request Example
```json
{
  "datetime": ["2025-01-15T10:00:00Z", "2025-01-15T10:30:00Z"],
  "geometry": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  },
  "order_parameters": {
    "output_format": "GeoTIFF",
    "processing_level": "L1B"
  }
}
```

### Response
#### Success Response (201)
- **[Order object]** (object) - An object representing the created order.

#### Response Example
```json
{
  "example": "[Order object]"
}
```
```

--------------------------------

### Get Specific Order API

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves details of a specific order by its ID.

```APIDOC
## GET /orders/{order_id}

### Description
Retrieves the details of a specific order using its unique ID.

### Method
GET

### Endpoint
/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier of the order.

### Request Example
```bash
curl -X GET "http://localhost:8000/orders/{order_id}" \
  -H "Accept: application/geo+json"
```

### Response
#### Success Response (200)
- **[Order object]** (object) - An object representing the requested order.

#### Response Example
```json
{
  "example": "[Order object]"
}
```
```

--------------------------------

### GET /orders/{order_id}

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves details for a single satellite tasking order by its unique ID.

```APIDOC
## GET /orders/{order_id}

### Description
Get a single order by ID.

### Method
GET

### Endpoint
/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier of the order to retrieve.

#### Request Body
- **request** (object) - Required - The incoming HTTP request object.

### Response
#### Success Response (200)
- **order** (object | null) - The order details if found, otherwise null.
  - **id** (string) - The unique identifier for the order.
  - **geometry** (object) - The geographic area of the order.
  - **properties** (object) - Properties of the order.
    - **product_id** (string) - The ID of the product.
    - **created** (string) - The timestamp when the order was created.
    - **status** (object) - The current status of the order.
    - **search_parameters** (object) - The search parameters used for the order.
    - **order_parameters** (object) - The specific parameters for the order.
    - **opportunity_properties** (object) - Properties related to the opportunity that led to this order.
  - **links** (array) - Links related to the order.

#### Response Example
```json
{
  "order": {
    "id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210",
    "geometry": {"type": "Polygon", "coordinates": [...]},
    "properties": {
      "product_id": "some_product_id",
      "created": "2023-10-27T10:05:00Z",
      "status": {"code": "received", "timestamp": "2023-10-27T10:05:00Z"},
      "search_parameters": {},
      "order_parameters": {"resolution": "3m"},
      "opportunity_properties": {}
    },
    "links": []
  }
}
```
OR
```json
{
  "order": null
}
```
```

--------------------------------

### Product Order Parameters API

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves the order parameters available for a specific product.

```APIDOC
## GET /products/{product_id}/order-parameters

### Description
Retrieves the order parameters for a given product.

### Method
GET

### Endpoint
/products/{product_id}/order-parameters

### Parameters
#### Path Parameters
- **product_id** (string) - Required - The ID of the product.

### Request Example
```bash
curl -X GET "http://localhost:8000/products/optical-30cm/order-parameters" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **[Schema of order parameters]** (object) - A JSON object describing the available order parameters.

#### Response Example
```json
{
  "example": "[Schema of order parameters]"
}
```
```

--------------------------------

### Get Order Status History API

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves the status history for a specific order, if enabled.

```APIDOC
## GET /orders/{order_id}/statuses

### Description
Retrieves the status history for a specific order. This endpoint may be disabled depending on server configuration.

### Method
GET

### Endpoint
/orders/{order_id}/statuses

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier of the order.

### Request Example
```bash
curl -X GET "http://localhost:8000/orders/{order_id}/statuses" \
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **[Array of status objects]** (array) - A list of status objects detailing the order's history.

#### Response Example
```json
{
  "example": "[Array of status objects]"
}
```
```

--------------------------------

### GET /opportunities/search/{opportunity_collection_id}

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves the results of an asynchronous opportunity search. This endpoint is used to fetch the collected results after a search has been initiated.

```APIDOC
## GET /opportunities/search/{opportunity_collection_id}

### Description
Retrieve results of an async opportunity search.

### Method
GET

### Endpoint
/opportunities/search/{opportunity_collection_id}

### Parameters
#### Path Parameters
- **opportunity_collection_id** (string) - Required - The ID of the opportunity search collection to retrieve.

#### Request Body
- **product_router** (object) - Required - Represents the product router configuration.
- **request** (object) - Required - The incoming HTTP request object.

### Response
#### Success Response (200)
- **collection** (object | null) - The opportunity collection if found, otherwise null.

#### Response Example
```json
{
  "collection": {
    "opportunities": [
      {
        "id": "opp_1",
        "product_id": "some_product_id",
        "properties": {}
      }
    ]
  }
}
```
OR
```json
{
  "collection": null
}
```
```

--------------------------------

### GET /orders/{order_id}/statuses

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves the status history for a specific order. This endpoint allows tracking the progression of an order through various states.

```APIDOC
## GET /orders/{order_id}/statuses

### Description
Get status history for an order.

### Method
GET

### Endpoint
/orders/{order_id}/statuses

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The unique identifier of the order whose status history is to be retrieved.

#### Query Parameters
- **next** (string) - Optional - A token for the next page of status updates.
- **limit** (integer) - Optional - The maximum number of status updates to return per page.

#### Request Body
- **request** (object) - Required - The incoming HTTP request object.

### Response
#### Success Response (200)
- **statuses** (array | null) - A list of order status objects if the order exists, otherwise null.
  - **code** (string) - The status code (e.g., "received", "processing", "completed").
  - **timestamp** (string) - The timestamp when this status was recorded.
- **next_token** (string | null) - A token for the next page of status updates, or null if this is the last page.

#### Response Example
```json
{
  "statuses": [
    {
      "code": "received",
      "timestamp": "2023-10-27T10:05:00Z"
    },
    {
      "code": "processing",
      "timestamp": "2023-10-27T11:00:00Z"
    }
  ],
  "next_token": "10"
}
```
OR
```json
{
  "statuses": null
}
```
```

--------------------------------

### Advanced Client Configuration

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Demonstrates how to configure the pystapi client with custom headers, query parameters, request modifiers, and timeouts. It also shows how to manage conformance classes and access API links.

```APIDOC
## Advanced Client Configuration

### Description
Configure the `pystapi_client.Client` with custom settings for authentication, API versioning, and request modifications. This includes setting default headers, query parameters, a custom request modifier function, and specific timeouts. The client also allows for dynamic management of conformance classes and provides methods to access API links.

### Usage

```python
from pystapi_client import Client
from httpx import Request

# Custom request modifier for authentication (e.g., AWS SigV4)
def sign_request(request: Request) -> Request:
    # Add custom headers or sign the request
    request.headers["X-Custom-Header"] = "value"
    return request

# Create client with custom configuration
client = Client.open(
    url="https://api.satellite-provider.com",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "X-API-Key": "your-api-key",
    },
    parameters={
        "api_version": "v1",  # Query parameters added to all requests
    },
    request_modifier=sign_request,  # Custom request signing
    timeout=(5.0, 30.0, None, None),  # (connect, read, write, pool) timeouts
)

# Manage conformance classes manually
client.add_conforms_to("OPPORTUNITIES")  # Add conformance
client.remove_conforms_to("OPPORTUNITIES")  # Remove conformance
client.clear_conforms_to()  # Clear all conformance

# Access links from the API
products_link = client.get_single_link(rel="products")
if products_link:
    print(f"Products endpoint: {products_link.href}")
```

### Parameters

- `url` (str): The base URL of the API.
- `headers` (dict, optional): Default headers to include in all requests.
- `parameters` (dict, optional): Default query parameters to include in all requests.
- `request_modifier` (callable, optional): A function to modify outgoing requests.
- `timeout` (tuple, optional): Request timeouts in the format (connect, read, write, pool).

### Methods

- `add_conforms_to(conformance_class: str)`: Adds a conformance class to the client.
- `remove_conforms_to(conformance_class: str)`: Removes a conformance class from the client.
- `clear_conforms_to()`: Clears all conformance classes.
- `get_single_link(rel: str)`: Retrieves a single link by its relation type.
```

--------------------------------

### Conformance Classes

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Retrieves the conformance classes that the API adheres to.

```APIDOC
## GET /conformance

### Description
Retrieves the conformance classes that the API adheres to, indicating supported standards and specifications.

### Method
GET

### Endpoint
/conformance

### Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:8000/conformance"
  -H "Accept: application/json"
```

### Response
#### Success Response (200)
- **conformsTo** (array) - A list of URLs representing the conformance classes.

#### Response Example
```json
{
  "conformsTo": ["https://stapi.example.com/v0.2/core"]
}
```
```

--------------------------------

### Search Opportunities API

Source: https://context7.com/stapi-spec/pystapi/llms.txt

Searches for available opportunities (e.g., imagery) for a specific product based on temporal and spatial criteria.

```APIDOC
## POST /products/{product_id}/opportunities

### Description
Searches for opportunities for a given product based on date range and geometry.

### Method
POST

### Endpoint
/products/{product_id}/opportunities

### Parameters
#### Path Parameters
- **product_id** (string) - Required - The ID of the product.

#### Request Body
- **datetime** (array of strings) - Required - A list containing the start and end datetime for the search range (ISO 8601 format).
- **geometry** (object) - Required - A GeoJSON geometry object defining the spatial area of interest.
- **limit** (integer) - Optional - The maximum number of opportunities to return.

### Request Example
```json
{
  "datetime": ["2025-01-01T00:00:00Z", "2025-03-01T00:00:00Z"],
  "geometry": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  },
  "limit": 10
}
```

### Response
#### Success Response (200)
- **[Array of opportunity objects]** (array) - A list of opportunity objects matching the search criteria.

#### Response Example
```json
{
  "example": "[Array of opportunity objects]"
}
```
```