Official JavaScript library for the Universal Commerce Protocol (UCP).
This repository contains the JavaScript SDK for the Universal Commerce Protocol (UCP). It provides TypeScript types and Zod schemas for UCP models, making it easy to build UCP-compliant applications in JavaScript and TypeScript.
Starting with the 2026-08-25 UCP specification release, @ucp-js/sdk uses spec-aligned YYYYMMDD.MINOR.PATCH versioning on release/YYYY-MM-DD branches (for example, 20260825.0.0), while main tracks the draft UCP schema channel (0.0.0-draft, pinned in ucp-lock.json):
| SDK Version / Channel | UCP Schema Version | npm Dist-Tag / Install Source |
|---|---|---|
0.0.0-draft (main) |
draft (ucp@main via ucp-lock.json) |
Git-native (github:Universal-Commerce-Protocol/js-sdk#<sha>) |
YYYYMMDD.MINOR.PATCH |
YYYY-MM-DD (>= 2026-08-25) |
latest / release-YYYY-MM-DD |
0.5.x |
2026-08-25 |
Legacy 0.x release |
0.4.x |
2026-04-08 |
Legacy 0.x release |
0.1.1 |
2026-01-23 |
Legacy 0.x release |
0.1.0 |
2026-01-11 |
Legacy 0.x release |
To install the latest published UCP specification release from npm:
npm install @ucp-js/sdkTo pin your project to a specific UCP specification release track (release/YYYY-MM-DD):
npm install @ucp-js/sdk@release-YYYY-MM-DDTo install the draft schema channel directly from a commit SHA on main (which automatically compiles dist/ via the package prepare script):
npm install github:Universal-Commerce-Protocol/js-sdk#<commit-sha>The SDK provides Zod schemas and TypeScript types for UCP wire data transfer objects (DTOs). Generated Zod schemas perform structural type parsing and tolerant-reader deserialization while preserving unknown extension fields.
import { CheckoutSchema, Checkout } from "@ucp-js/sdk";
// Parse wire payload into a typed UCP DTO
const parseResult = CheckoutSchema.safeParse(checkoutData);
if (parseResult.success) {
const checkout: Checkout = parseResult.data;
console.log(checkout.status); // "incomplete" | "ready_for_complete" | ...
console.log(checkout.currency); // ISO 4217 currency code
} else {
console.error(parseResult.error);
}const { CheckoutSchema } = require("@ucp-js/sdk");
const parseResult = CheckoutSchema.safeParse(checkoutData);
if (parseResult.success) {
const checkout = parseResult.data;
// ...
}Zod DTO schemas validate structural wire types and preserve unknown extension properties for forward compatibility, but they do not enforce full UCP protocol conformance on their own.
To enforce normative UCP message constraints (capability profile composition, directional ucp_request and ucp_response visibility, dependentRequired, if/then, uniqueItems, contains, propertyNames, not.enum, and closed-schema rules):
- In-Memory Runtime Validation (Production Services): Compile your UCP discovery profile once at build or startup time into a standard JSON Schema Draft 2020-12 bundle (
ucp-schema generate-types --profile profile.json -o ucp.types.json) or OpenAPI 3.1 specification (ucp-schema generate-openapi --profile profile.json -o openapi.json). Becauseucp-schemaresolves all UCP-specific annotations and capability extensions into standard JSON Schema 2020-12, your server can validate payloads in memory on every request usingajv(Ajv2020) or standard OpenAPI middleware before parsing into SDK DTOs:
import fs from "node:fs";
import Ajv2020 from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
import { CheckoutSchema, Checkout } from "@ucp-js/sdk";
// At startup: compile the pre-generated schema bundle once in memory
const bundle = JSON.parse(fs.readFileSync("ucp.types.json", "utf8"));
const ajv = new Ajv2020({ strict: false });
addFormats(ajv);
ajv.addSchema(bundle, "https://ucp.dev/bundle.json");
const validateCheckout = ajv.getSchema(
"https://ucp.dev/bundle.json#/$defs/Checkout"
)!;
// Per request: validate in-memory, then parse into a typed DTO
if (!validateCheckout(rawPayload)) {
throw new Error(ajv.errorsText(validateCheckout.errors));
}
const checkout: Checkout = CheckoutSchema.parse(rawPayload);- CLI & CI Conformance Testing: Verify fixture payloads or recorded traffic from the command line or CI pipelines with
ucp-schema validate:
# 1. Verify a self-describing response or JSON-RPC payload
ucp-schema validate payload.json --op read
# Or verify a REST request against a negotiated discovery profile
ucp-schema validate payload.json --profile profile.json --op createThis project uses npm for package management, typescript for building, and the ucp-schema CLI for model generation.
The models are automatically generated from the JSON schemas in the
UCP Specification and pinned via ucp-lock.json.
To regenerate models deterministically from the commit pinned in ucp-lock.json:
./generate_models.shTo advance ucp-lock.json and regenerate against the latest upstream draft (ucp@main) or a specific release branch (release/YYYY-MM-DD):
./generate_models.sh --ref main --write-lock
./generate_models.sh --ref release/2026-08-25 --write-lockAlternatively, you can point to a local directory containing the UCP repository or schemas:
./generate_models.sh --spec-dir /path/to/ucpTo build the project for both CommonJS and ESM:
npm run buildWe welcome community contributions. See our Contribution Guide for details.
UCP is an open-source project under the Apache License 2.0.