ucp-client 0.0.2

Python client library for Universal Checkout Protocol (UCP) - Type-safe async client and LLM agent tools

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

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 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:

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.

  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:

./extract_json_dialog.sh

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