This directory contains examples for the packages in this monorepo.

• client/ - Examples for katana-openapi-client package
• mcp-server/ - Examples for katana-mcp-server package (coming soon)

The client/ directory contains various examples demonstrating different features and usage patterns of the KatanaClient.

Before running any examples, make sure you have:

1. Installed the client:

   uv sync --all-extras

2. Set up your API key:

   • Create a .env file in the project root (or set environment variable):

     KATANA_API_KEY=your_api_key_here

   • Or export it in your shell:

     export KATANA_API_KEY="your_api_key_here"

Demonstrates the core features of KatanaClient including:

• Automatic pagination
• Single page requests
• Limited pagination
• Automatic resilience and retry logic

Run:

uv run python examples/client/basic_usage.py

Key Features Shown:

• Auto-pagination is ON by default for all GET requests
• Disable auto-pagination by adding explicit page parameter (e.g., page=2)
• Configure maximum pages to collect with max_pages
• All requests get automatic retries and error handling

Compare inventory levels between an external warehouse management system and Katana to identify discrepancies.

Run:

uv run python examples/client/inventory_sync.py

Key Features Shown:

• Building SKU lookup maps for efficient data matching
• Comparing inventory across systems
• Tracking matched, mismatched, and skipped items
• Real-world inventory monitoring workflow

Monitor inventory levels and identify products that need reordering.

Run:

uv run python examples/client/low_stock_monitoring.py

Key Features Shown:

• Checking inventory against thresholds
• Fetching variant details with inventory data
• Generating low stock alerts
• Production-ready monitoring pattern

Make multiple API requests concurrently using asyncio.gather for better performance.

Run:

uv run python examples/client/concurrent_requests.py

Key Features Shown:

• Parallel API requests with asyncio
• Error handling for concurrent operations
• Performance benchmarking
• Efficient bulk data retrieval

Implement custom error handling and retry logic on top of the client's built-in resilience.

Run:

uv run python examples/client/error_handling.py

Key Features Shown:

• Custom retry logic with exponential backoff
• Application-level error handling
• Combining with KatanaClient's built-in resilience
• Production error handling patterns

All examples include proper error handling patterns. The client automatically:

• Retries network errors and 5xx server errors with exponential backoff
• Handles rate limiting with Retry-After header support
• Logs detailed error information for 4xx client errors
• Provides structured error parsing for validation errors (422 responses)

The KatanaClient supports various configuration options:

client = KatanaClient(
    api_key="your_key",           # Or set KATANA_API_KEY env var
    base_url="https://...",       # Custom base URL
    timeout=30.0,                 # Request timeout in seconds
    max_retries=5,                # Maximum retry attempts
    max_pages=100,                # Maximum pages for auto-pagination
    logger=custom_logger,         # Custom logger instance
)

The client uses a custom ResilientAsyncTransport that provides:

• Automatic retries with exponential backoff
• Rate limiting detection and handling
• Smart pagination based on request parameters
• Request/response logging and metrics

The client inherits from AuthenticatedClient and can be passed directly to generated API methods:

from katana_public_api_client import KatanaClient
from katana_public_api_client.api.product import get_all_products

async with KatanaClient() as client:
    # Pass client directly - no .client property needed
    response = await get_all_products.asyncio_detailed(
        client=client,
        limit=50  # Automatically paginates if more data available
    )

• Cookbook - Practical recipes for common integration scenarios
• Client Guide - Main documentation
• Testing Guide - Testing documentation
• uv Package Manager - Package manager guide

When adding new examples:

1. Add the file to the appropriate subdirectory (client/ or mcp-server/)
2. Include a comprehensive docstring explaining the example
3. Add proper error handling
4. Update this README with the new example
5. Test the example works with a real API key