UCP JavaScript SDK

Runtime-validated Zod schemas and TypeScript types for the Universal Commerce Protocol (UCP).

Overview

The JavaScript SDK for the Universal Commerce Protocol (UCP). Auto-generated from the UCP spec with full coverage — 134 schemas including checkout, cart, catalog, orders, payments, fulfillment, discovery profiles, and all inline enums.

Key features:

• 100% spec coverage — every schema, $def, request variant, and enum (134 exports)
• Fully generated from the UCP JSON Schema spec — consumer aliases in extensions.ts
• Runtime validation with Zod — .parse() and .safeParse()
• Extension-safe — additionalProperties: true schemas use .passthrough() to preserve extension data
• Dual ESM/CJS build — works everywhere

Installation

# Stable (current UCP release)
npm install @omnixhq/ucp-js-sdk

Draft builds

To build against upcoming UCP spec changes, install the next tag:

# Draft (latest UCP spec main branch)
npm install @omnixhq/ucp-js-sdk@next

Draft builds are published automatically when the UCP spec's main branch changes. They use prerelease versions (e.g., 1.0.2-draft.5.1) and won't affect your stable installs. Switch back anytime with npm install @omnixhq/ucp-js-sdk@latest.

Usage

Validate a checkout request

import {
  CheckoutCreateRequestSchema,
  type CheckoutCreateRequest,
} from "@omnixhq/ucp-js-sdk";

const result = CheckoutCreateRequestSchema.safeParse(req.body);
if (!result.success) {
  return res.status(400).json({ error: result.error.flatten() });
}
const checkout: CheckoutCreateRequest = result.data;

Validate a checkout response

import { CheckoutSchema } from "@omnixhq/ucp-js-sdk";

const checkout = CheckoutSchema.parse(apiResponse);
// Typed fields: checkout.id, checkout.status, checkout.line_items, etc.
// Extension data (fulfillment, discounts, ap2) is preserved at runtime
// via .passthrough() but not statically typed on the base schema.

Validate a discovery profile

import { UcpDiscoveryProfileSchema } from "@omnixhq/ucp-js-sdk";

const profile = await fetch(
  "https://platform.example.com/.well-known/ucp"
).then((r) => r.json());
const discovery = UcpDiscoveryProfileSchema.parse(profile);

// discovery.ucp.services        — Record<string, Service[]>
// discovery.ucp.capabilities    — Record<string, Capability[]>
// discovery.ucp.payment_handlers — Record<string, PaymentHandler[]>
// discovery.signing_keys        — JWK signing keys

Use standalone enums

import {
  CheckoutStatusEnumSchema,
  TotalTypeEnumSchema,
  ServiceBaseTransportEnumSchema,
} from "@omnixhq/ucp-js-sdk";

// Type-safe enum values
const status = CheckoutStatusEnumSchema.parse("incomplete");
const transport = ServiceBaseTransportEnumSchema.parse("mcp");

See docs/examples.md for more examples covering payment handlers, order webhooks, and fulfillment.

What's included

Category	Count	Examples
Top-level schemas	46	CheckoutSchema, OrderSchema, PaymentSchema
$defs exports	39	UcpEntitySchema, PaymentHandlerResponseSchema
Request variants	7	CheckoutCreateRequestSchema, CheckoutUpdateRequestSchema
Inline enums	15	CheckoutStatusEnumSchema, TotalTypeEnumSchema
Consumer aliases	~15	UcpDiscoveryProfileSchema, CheckoutResponseStatusSchema

All schemas have corresponding TypeScript types exported (e.g., Checkout, Order, UcpDiscoveryProfile).

Development

Prerequisites

Node.js 22+ and npm.

Generating schemas

src/spec_generated.ts is auto-generated from the UCP spec:

npm run generate                          # default release (v2026-04-08)
npm run generate -- --release v2026-01-24 # specific release tag
npm run generate -- --branch main         # latest commit on a branch
npm run generate -- --commit abc1234      # exact commit SHA
npm run generate -- /path/to/ucp/source   # local spec clone

Verifying schema coverage

npm run verify:schemas                          # default release
npm run verify:schemas -- --release v2026-01-24 # specific release
npm run verify:schemas -- --branch main         # latest on a branch

Runs automatically in CI. See docs/schema-verification.md for the full reference.

Building

npm run build      # tsdown → dual ESM (.mjs) + CJS (.cjs)
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm run format     # prettier

Draft branch workflow

The draft branch tracks the latest UCP spec main for upcoming features:

• Auto-regeneration: every Monday at 09:00 UTC (or manual trigger via Actions)
• Auto-publish: push to draft → publishes X.Y.Z-draft.N with npm next tag
• Promotion: when UCP cuts a stable release, merge draft → main → release-please handles the rest

Contributing

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

License

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