Metadata-Version: 2.4
Name: ucp-client
Version: 0.0.1
Summary: UCP Client Library for Python
Project-URL: Homepage, https://github.com/upsonic/ucp-client
Project-URL: Documentation, https://github.com/upsonic/ucp-client
Project-URL: Repository, https://github.com/upsonic/ucp-client
Author-email: Onur Atakan <onur@upsonic.co>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

<!--
   Copyright 2026 UCP Authors

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<!-- disableFinding(LINK_RELATIVE_G3DOC) -->

# UCP SDK Client Library

## Overview

This directory contains two UCP client implementations:

1. **`simple_happy_path_client.py`** - Script demonstrating a complete "happy path" user journey
2. **`ucp_client.py`** - Type-safe client library for programmatic UCP API interactions

## Type-Safe UCP Client (`ucp_client.py`)

A fully type-safe Python client for the UCP Shopping API with proper error handling and async support.

### Features

- **Type Safety**: All requests and responses are fully typed using UCP SDK models
- **Async Support**: Built with `httpx` for async HTTP operations
- **Error Handling**: Custom `UCPClientError` with detailed error information
- **Authentication**: Supports API keys and UCP-Agent profiles
- **Idempotency**: Automatic idempotency key generation
- **Context Manager**: Proper resource management with async context managers

### Quick Start

```python
import asyncio
from ucp_client import UCPClient
from ucp_sdk.models.schemas.shopping import checkout_create_req

async def main():
    async with UCPClient(
        base_url="http://localhost:8182",
        api_key="your-api-key",  # Optional
        ucp_agent_profile='profile="https://agent.example/profile"'
    ) as client:

        # Get merchant capabilities
        profile = await client.get_merchant_profile()
        print(f"Supports {len(profile.ucp.capabilities)} capabilities")

        # Create checkout
        checkout_req = checkout_create_req.CheckoutCreateRequest(...)
        checkout = await client.create_checkout(checkout_req)
        print(f"Created checkout: {checkout.id}")

asyncio.run(main())
```

### Available Methods

#### Discovery
- `get_merchant_profile() -> UcpDiscoveryProfile`

#### Checkout Operations
- `create_checkout(request, idempotency_key?) -> CheckoutResponse`
- `get_checkout(checkout_id) -> CheckoutResponse`
- `update_checkout(checkout_id, request, idempotency_key?) -> CheckoutResponse`
- `complete_checkout(checkout_id, payment_data, risk_signals?, ap2?, idempotency_key?) -> CheckoutResponse`
- `cancel_checkout(checkout_id, idempotency_key?) -> CheckoutResponse`

#### Order Operations
- `get_order(order_id) -> Dict[str, Any]`
- `update_order(order_id, order_data) -> Dict[str, Any]`

#### Testing (Development Only)
- `simulate_shipping(order_id) -> Dict[str, Any]`

## Simple Happy Path Client Script (`simple_happy_path_client.py`)

This script demonstrates a complete "happy path" user journey: 0. **Discovery**:
Querying the merchant to see what they support. 1. **Create Checkout**: Creating
a new checkout session (cart). 2. **Add Items**: Adding items to the checkout
session. 3. **Fulfillment**: Triggering fulfillment option generation, selecting
a destination, and choosing a shipping option. 4. **Complete**: Completing the
checkout by processing a payment.

## Prerequisites

1.  **Install Dependencies**: `bash uv sync`

2.  **Start the Merchant Server**: You need a running UCP Merchant Server to
    execute this client against. Follow the instructions in the
    [Server README](../../server/README.md) to start the server on port 8182.

    *Quick start (from `../../server/`):* `bash uv run server.py
    --products_db_path=/tmp/ucp_test/products.db
    --transactions_db_path=/tmp/ucp_test/transactions.db --port=8182`

## Running the Client

Once the server is running, you can execute the client script:

```bash
uv run simple_happy_path_client.py --server_url=http://localhost:8182
```

### Options

*   `--server_url`: The base URL of the UCP Merchant Server (default:
    `http://localhost:8182`).
*   `--export_requests_to`: Path to a markdown file where the request/response
    dialog will be logged.

    ```bash
    uv run simple_happy_path_client.py --export_requests_to=interaction_log.md
    ```

## Automated Demo (extract_json_dialog.sh)

For a fully automated demonstration that sets up the database, starts the
server, runs the client, and generates a transaction log, use the included shell
script:

```bash
./extract_json_dialog.sh
```

This will output the interaction log to `/tmp/ucp_test/happy_path_dialog.md`.
