UCP Go SDK

Go SDK for the Universal Commerce Protocol (UCP).

Overview

This repository contains the Go SDK for the Universal Commerce Protocol (UCP). It provides Go types, validation, and client/server utilities for building UCP-compliant applications.

Features

• Models: Go structs for all UCP schemas (checkout, order, payment, fulfillment, etc.)
• REST Client: Typed HTTP client for consuming UCP APIs from platforms/agents
• Server Helpers: HTTP handlers and middleware for implementing UCP endpoints
• Validation: JSON Schema validation and capability negotiation
• Extensions: Extended types for UCP extensions (fulfillment, discounts, buyer consent)

Installation

go get github.com/dhananjay2021/ucp-go-sdk

Quick Start

Platform Client (Consuming UCP APIs)

Use the client package to interact with UCP-compliant merchants:

package main

import (
    "context"
    "log"

    "github.com/dhananjay2021/ucp-go-sdk/client"
    "github.com/dhananjay2021/ucp-go-sdk/extensions"
    "github.com/dhananjay2021/ucp-go-sdk/models"
)

func main() {
    // Create a UCP client
    ucpClient := client.NewClient("https://merchant.example.com",
        client.WithAPIKey("your-api-key"),
    )

    ctx := context.Background()

    // Discover merchant capabilities
    profile, err := ucpClient.FetchProfile(ctx)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Merchant UCP version: %s", profile.UCP.Version)

    // Check for required capabilities
    if !client.HasCapability(profile, client.CapabilityCheckout) {
        log.Fatal("Merchant does not support checkout")
    }

    // Create a checkout session
    checkout, err := ucpClient.CreateCheckout(ctx, &extensions.ExtendedCheckoutCreateRequest{
        LineItems: []models.LineItemCreateRequest{
            {
                Item:     models.ItemCreateRequest{ID: "product-123"},
                Quantity: 1,
            },
        },
        Currency: "USD",
        Payment:  models.PaymentCreateRequest{},
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Created checkout: %s (status: %s)", checkout.ID, checkout.Status)
}

Business Server (Implementing UCP APIs)

Use the server package to implement UCP-compliant endpoints:

package main

import (
    "log"
    "net/http"

    "github.com/dhananjay2021/ucp-go-sdk/client"
    "github.com/dhananjay2021/ucp-go-sdk/extensions"
    "github.com/dhananjay2021/ucp-go-sdk/models"
    "github.com/dhananjay2021/ucp-go-sdk/server"
)

func main() {
    // Configure the server
    config := server.Config{
        Version: "2026-01-11",
        Capabilities: []models.CapabilityDiscovery{
            {
                CapabilityBase: models.CapabilityBase{
                    Name:    client.CapabilityCheckout,
                    Version: "2026-01-11",
                    Spec:    "https://ucp.dev/specification/checkout",
                    Schema:  "https://ucp.dev/schemas/shopping/checkout.json",
                },
            },
        },
        Services: models.Services{
            client.ServiceShopping: models.UCPService{
                Version: "2026-01-11",
                Spec:    "https://ucp.dev/specification/shopping",
                Rest: &models.RestTransport{
                    Schema:   "https://ucp.dev/schemas/services/shopping/rest.openapi.json",
                    Endpoint: "http://localhost:8080",
                },
            },
        },
    }

    // Create server and register handlers
    srv := server.NewServer(config)
    srv.HandleCreateCheckout(handleCreateCheckout)
    srv.HandleUpdateCheckout(handleUpdateCheckout)
    srv.HandleCompleteCheckout(handleCompleteCheckout)

    // Apply middleware
    handler := server.Chain(srv,
        server.LoggingMiddleware,
        server.CORSMiddleware([]string{"*"}),
    )

    log.Println("Starting UCP server on :8080")
    http.ListenAndServe(":8080", handler)
}

func handleCreateCheckout(r *http.Request, req *extensions.ExtendedCheckoutCreateRequest) (*extensions.ExtendedCheckoutResponse, error) {
    // Implement your checkout logic here
    return &extensions.ExtendedCheckoutResponse{
        ID:     "chk-123",
        Status: models.CheckoutStatusIncomplete,
        // ...
    }, nil
}

Package Structure

go-sdk/
├── models/          # Go types for all UCP schemas
├── client/          # REST client for consuming UCP APIs
├── server/          # HTTP handlers for implementing UCP endpoints
├── validation/      # JSON Schema validation and capability negotiation
├── extensions/      # Extended types for UCP extensions
├── internal/        # Internal utilities
└── examples/        # Example implementations
    ├── business_server/   # Example merchant server
    └── platform_client/   # Example platform client

Models

The models package contains Go structs for all UCP schemas:

• UCP Core: Version, CapabilityBase, DiscoveryProfile, UCPProfile
• Checkout: CheckoutCreateRequest, CheckoutUpdateRequest, CheckoutResponse
• Payment: PaymentResponse, PaymentHandlerResponse, CardCredential
• Fulfillment: FulfillmentRequest, FulfillmentResponse, ShippingDestination
• Order: Order, OrderLineItem, Adjustment
• Discount: DiscountsCreateRequest, DiscountsResponse
• Buyer Consent: BuyerWithConsentCreateRequest, BuyerWithConsentResponse

Client Package

The client package provides a REST client for platforms and agents:

// Create client with options
c := client.NewClient(baseURL,
    client.WithAPIKey("key"),
    client.WithAccessToken("token"),
    client.WithTimeout(30*time.Second),
)

// Discovery
profile, _ := c.FetchProfile(ctx)

// Checkout operations
checkout, _ := c.CreateCheckout(ctx, req)
checkout, _ := c.GetCheckout(ctx, id)
checkout, _ := c.UpdateCheckout(ctx, id, updateReq)
checkout, _ := c.CompleteCheckout(ctx, id)
checkout, _ := c.CancelCheckout(ctx, id)

// Order operations
order, _ := c.GetOrder(ctx, id)

Server Package

The server package helps implement UCP-compliant endpoints:

// Create server
srv := server.NewServer(config)

// Register handlers
srv.HandleCreateCheckout(handler)
srv.HandleGetCheckout(handler)
srv.HandleUpdateCheckout(handler)
srv.HandleCompleteCheckout(handler)
srv.HandleCancelCheckout(handler)
srv.HandleGetOrder(handler)

// Available middleware
server.LoggingMiddleware
server.CORSMiddleware(allowedOrigins)
server.APIKeyMiddleware(validKeys)
server.BearerTokenMiddleware(validator)
server.RequestIDMiddleware

// Response helpers
server.WriteJSON(w, statusCode, data)
server.WriteError(w, statusCode, code, message)

Validation Package

The validation package provides capability negotiation:

// Create negotiator with platform capabilities
negotiator := validation.NewCapabilityNegotiator(platformCaps)

// Negotiate with a business profile
result := negotiator.Negotiate(businessProfile, requiredCaps)

if result.Success {
    // Use result.CommonCapabilities
    // Use result.NegotiatedVersion
}

Extensions Package

The extensions package provides extended types that combine base schemas with extensions:

// Extended checkout with fulfillment, discounts, and buyer consent
type ExtendedCheckoutResponse struct {
    // Base checkout fields...
    Fulfillment *FulfillmentResponse
    Discounts   *DiscountsResponse
    Buyer       *BuyerWithConsentResponse
}

Running Examples

Business Server

cd examples/business_server
go run main.go

The server starts on port 8080 with a discovery endpoint at /.well-known/ucp.

Platform Client

# Start the business server first, then:
cd examples/platform_client
go run main.go

Development

Prerequisites

• Go 1.22 or later

Building

go build ./...

Testing

go test ./...

Generating Models

The models can be regenerated from UCP JSON schemas:

# Ensure the UCP spec repository is available as a sibling directory
./scripts/generate.sh

Generated types are placed in models/generated/ for reference. The hand-written models in models/ are the primary types used by the SDK.

Contributing

We welcome community contributions. See our Contribution Guide for details.

License

UCP is an open-source project under the Apache License 2.0.