@omnixhq/ucp-js-sdk 1.1.0-draft.4.1 → 2.0.0

package/README.md

@@ -30,12 +30,12 @@
 ## Overview
 
 The JavaScript SDK for the [Universal Commerce Protocol (UCP)](https://ucp.dev).
-Auto-generated from the UCP spec with full coverage — 100 schemas including
-checkout, orders, payments, fulfillment, discovery profiles, and all inline enums.
+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
+- 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](https://zod.dev/) — `.parse()` and `.safeParse()`
 - Extension-safe — `additionalProperties: true` schemas use `.passthrough()` to preserve extension data
@@ -50,8 +50,7 @@ npm install @omnixhq/ucp-js-sdk
 
 ### Draft builds
 
-To build against upcoming UCP spec changes (Catalog capability, Order updates, etc.),
-install the `next` tag:
+To build against upcoming UCP spec changes, install the `next` tag:
 
 ```bash
 # Draft (latest UCP spec main branch)
@@ -146,7 +145,7 @@ Node.js 22+ and npm.
 `src/spec_generated.ts` is auto-generated from the UCP spec:
 
 ```bash
-npm run generate                          # default release (v2026-01-23)
+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

package/dist/index.cjs

@@ -182,7 +182,7 @@ const ServicePlatformSchema = zod.intersection(zod.intersection(zod.object({
 	zod.object({ "transport": zod.literal("mcp").optional() }),
 	zod.object({ "transport": zod.literal("a2a").optional() }),
 	zod.object({ "transport": zod.literal("embedded").optional() })
-]))).describe("Full service declaration for platform-level discovery. Different transports require different fields.");
+]))).describe("Full service declaration for platform-level discovery. All transports require `version`, `spec`, and `transport`. REST and MCP additionally require `schema` and `endpoint`; A2A requires `endpoint`; embedded requires `schema`.");
 const ServiceBusinessSchema = zod.intersection(zod.intersection(zod.object({
 	"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
 	"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
@@ -657,7 +657,6 @@ const CheckoutSchema = zod.object({
 		"dev.ucp.buyer_ip": zod.string().describe("Client's IP address (IPv4 or IPv6).").optional(),
 		"dev.ucp.user_agent": zod.string().describe("Client's HTTP User-Agent header or equivalent.").optional()
 	}).passthrough().describe("Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.").optional(),
-	"risk_signals": zod.record(zod.string(), zod.unknown()).describe("Deprecated. Use signals instead. Will be removed in the next version.").optional(),
 	"status": zod.enum([
 		"incomplete",
 		"requires_escalation",
@@ -1261,7 +1260,53 @@ const OrderSchema = zod.object({
 	}).and(zod.intersection(zod.any(), zod.any())).describe("A cost breakdown entry with a category, amount, and optional display text."), zod.intersection(zod.object({ "lines": zod.array(zod.object({
 		"display_text": zod.string().describe("Human-readable label for this sub-line."),
 		"amount": zod.number().int().describe("Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).")
-	}).describe("Sub-line entry. Additional metadata MAY be included.")).describe("Optional itemized breakdown. The parent entry is always rendered; lines are supplementary. Sum of line amounts MUST equal the parent entry amount.").optional() }), zod.any()))).describe("Different totals for the order.")
+	}).describe("Sub-line entry. Additional metadata MAY be included.")).describe("Optional itemized breakdown. The parent entry is always rendered; lines are supplementary. Sum of line amounts MUST equal the parent entry amount.").optional() }), zod.any()))).describe("Different totals for the order."),
+	"messages": zod.array(zod.record(zod.string(), zod.unknown()).and(zod.unknown().superRefine((x, ctx) => {
+		const schemas = [
+			zod.object({
+				"type": zod.literal("error").describe("Message type discriminator."),
+				"code": zod.string().describe("Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted."),
+				"path": zod.string().describe("RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1]).").optional(),
+				"content_type": zod.enum(["plain", "markdown"]).describe("Content format, default = plain.").default("plain"),
+				"content": zod.string().describe("Human-readable message."),
+				"severity": zod.enum([
+					"recoverable",
+					"requires_buyer_input",
+					"requires_buyer_review",
+					"unrecoverable"
+				]).describe("Reflects the resource state and recommended action. 'recoverable': platform can resolve by modifying inputs and retrying via API. 'requires_buyer_input': merchant requires information their API doesn't support collecting programmatically (checkout incomplete). 'requires_buyer_review': buyer must authorize before order placement due to policy, regulatory, or entitlement rules. 'unrecoverable': no valid resource exists to act on, retry with new resource or inputs. Errors with 'requires_*' severity contribute to 'status: requires_escalation'.")
+			}),
+			zod.object({
+				"type": zod.literal("warning").describe("Message type discriminator."),
+				"path": zod.string().describe("JSONPath (RFC 9535) to related field (e.g., $.line_items[0]).").optional(),
+				"code": zod.string().describe("Warning code. Machine-readable identifier for the warning type (e.g., final_sale, prop65, fulfillment_changed, age_restricted, etc.)."),
+				"content": zod.string().describe("Human-readable warning message that MUST be displayed."),
+				"content_type": zod.enum(["plain", "markdown"]).describe("Content format, default = plain.").default("plain"),
+				"presentation": zod.string().describe("Rendering contract for this warning. 'notice' (default): platform MUST display, MAY dismiss. 'disclosure': platform MUST display in proximity to the path-referenced component, MUST NOT hide or auto-dismiss. See specification for full contract.").default("notice"),
+				"image_url": zod.string().url().describe("URL to a required visual element (e.g., warning symbol, energy class label).").optional(),
+				"url": zod.string().url().describe("Reference URL for more information (e.g., regulatory site, registry entry, policy page).").optional()
+			}),
+			zod.object({
+				"type": zod.literal("info").describe("Message type discriminator."),
+				"path": zod.string().describe("RFC 9535 JSONPath to the component the message refers to.").optional(),
+				"code": zod.string().describe("Info code for programmatic handling.").optional(),
+				"content_type": zod.enum(["plain", "markdown"]).describe("Content format, default = plain.").default("plain"),
+				"content": zod.string().describe("Human-readable message.")
+			})
+		];
+		const errors = schemas.reduce((errors, schema) => ((result) => result.error ? [...errors, result.error] : errors)(schema.safeParse(x)), []);
+		const passed = schemas.length - errors.length;
+		if (passed !== 1) ctx.addIssue(errors.length ? {
+			path: ctx.path,
+			code: "invalid_union",
+			unionErrors: errors,
+			message: "Invalid input: Should pass single schema. Passed " + passed
+		} : {
+			path: ctx.path,
+			code: "custom",
+			message: "Invalid input: Should pass single schema. Passed " + passed
+		});
+	})).describe("Container for error, warning, or info messages.")).describe("Business outcome messages (errors, warnings, informational). Present when the business needs to communicate status or issues to the platform.").optional()
 }).describe("Order schema with line items, buyer-facing fulfillment expectations, and event logs.");
 const PaymentSchema = zod.object({ "instruments": zod.array(zod.intersection(zod.object({
 	"id": zod.string().describe("A unique identifier for this instrument instance, assigned by the platform."),
@@ -2291,6 +2336,106 @@ const UcpBaseSchema = zod.object({
 		"constraints": zod.record(zod.string(), zod.unknown()).describe("Constraints on this instrument type. Structure depends on instrument type and active capabilities.").optional()
 	}).describe("An instrument type available from a payment handler with optional constraints.")).min(1).describe("Instrument types this handler supports, with optional constraints. When absent, every instrument should be considered available.").optional() }))))).describe("Payment handler registry keyed by reverse-domain name.").optional()
 }).describe("Base UCP metadata with shared properties for all schema types.");
+const UcpSuccessSchema = zod.intersection(zod.object({
+	"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("UCP version in YYYY-MM-DD format."),
+	"status": zod.enum(["success", "error"]).describe("Application-level status of the UCP operation.").default("success"),
+	"services": zod.record(zod.array(zod.intersection(zod.object({
+		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
+		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
+		"schema": zod.string().url().describe("URL to JSON Schema defining this entity's structure and payloads.").optional(),
+		"id": zod.string().describe("Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.").optional(),
+		"config": zod.record(zod.string(), zod.unknown()).describe("Entity-specific configuration. Structure defined by each entity's schema.").optional()
+	}).describe("Shared foundation for all UCP entities."), zod.object({
+		"transport": zod.enum([
+			"rest",
+			"mcp",
+			"a2a",
+			"embedded"
+		]).describe("Transport protocol for this service binding."),
+		"endpoint": zod.string().url().describe("Endpoint URL for this transport binding.").optional()
+	})))).describe("Service registry keyed by reverse-domain name.").optional(),
+	"capabilities": zod.record(zod.array(zod.intersection(zod.object({
+		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
+		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
+		"schema": zod.string().url().describe("URL to JSON Schema defining this entity's structure and payloads.").optional(),
+		"id": zod.string().describe("Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.").optional(),
+		"config": zod.record(zod.string(), zod.unknown()).describe("Entity-specific configuration. Structure defined by each entity's schema.").optional()
+	}).describe("Shared foundation for all UCP entities."), zod.object({ "extends": zod.unknown().superRefine((x, ctx) => {
+		const schemas = [zod.string().regex(/* @__PURE__ */ new RegExp("^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")), zod.array(zod.string().regex(/* @__PURE__ */ new RegExp("^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"))).min(1)];
+		const errors = schemas.reduce((errors, schema) => ((result) => result.error ? [...errors, result.error] : errors)(schema.safeParse(x)), []);
+		const passed = schemas.length - errors.length;
+		if (passed !== 1) ctx.addIssue(errors.length ? {
+			path: ctx.path,
+			code: "invalid_union",
+			unionErrors: errors,
+			message: "Invalid input: Should pass single schema. Passed " + passed
+		} : {
+			path: ctx.path,
+			code: "custom",
+			message: "Invalid input: Should pass single schema. Passed " + passed
+		});
+	}).describe("Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.").optional() })))).describe("Capability registry keyed by reverse-domain name.").optional(),
+	"payment_handlers": zod.record(zod.array(zod.intersection(zod.object({
+		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
+		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
+		"schema": zod.string().url().describe("URL to JSON Schema defining this entity's structure and payloads.").optional(),
+		"id": zod.string().describe("Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.").optional(),
+		"config": zod.record(zod.string(), zod.unknown()).describe("Entity-specific configuration. Structure defined by each entity's schema.").optional()
+	}).describe("Shared foundation for all UCP entities."), zod.intersection(zod.record(zod.string(), zod.unknown()), zod.object({ "available_instruments": zod.array(zod.object({
+		"type": zod.string().describe("The instrument type identifier (e.g., 'card', 'gift_card'). References an instrument schema's type constant."),
+		"constraints": zod.record(zod.string(), zod.unknown()).describe("Constraints on this instrument type. Structure depends on instrument type and active capabilities.").optional()
+	}).describe("An instrument type available from a payment handler with optional constraints.")).min(1).describe("Instrument types this handler supports, with optional constraints. When absent, every instrument should be considered available.").optional() }))))).describe("Payment handler registry keyed by reverse-domain name.").optional()
+}).describe("Base UCP metadata with shared properties for all schema types."), zod.object({ "status": zod.literal("success") })).describe("UCP metadata with status 'success'. Use for response branches that carry the expected payload.");
+const UcpErrorSchema = zod.intersection(zod.object({
+	"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("UCP version in YYYY-MM-DD format."),
+	"status": zod.enum(["success", "error"]).describe("Application-level status of the UCP operation.").default("success"),
+	"services": zod.record(zod.array(zod.intersection(zod.object({
+		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
+		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
+		"schema": zod.string().url().describe("URL to JSON Schema defining this entity's structure and payloads.").optional(),
+		"id": zod.string().describe("Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.").optional(),
+		"config": zod.record(zod.string(), zod.unknown()).describe("Entity-specific configuration. Structure defined by each entity's schema.").optional()
+	}).describe("Shared foundation for all UCP entities."), zod.object({
+		"transport": zod.enum([
+			"rest",
+			"mcp",
+			"a2a",
+			"embedded"
+		]).describe("Transport protocol for this service binding."),
+		"endpoint": zod.string().url().describe("Endpoint URL for this transport binding.").optional()
+	})))).describe("Service registry keyed by reverse-domain name.").optional(),
+	"capabilities": zod.record(zod.array(zod.intersection(zod.object({
+		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
+		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
+		"schema": zod.string().url().describe("URL to JSON Schema defining this entity's structure and payloads.").optional(),
+		"id": zod.string().describe("Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.").optional(),
+		"config": zod.record(zod.string(), zod.unknown()).describe("Entity-specific configuration. Structure defined by each entity's schema.").optional()
+	}).describe("Shared foundation for all UCP entities."), zod.object({ "extends": zod.unknown().superRefine((x, ctx) => {
+		const schemas = [zod.string().regex(/* @__PURE__ */ new RegExp("^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$")), zod.array(zod.string().regex(/* @__PURE__ */ new RegExp("^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9_]*)+$"))).min(1)];
+		const errors = schemas.reduce((errors, schema) => ((result) => result.error ? [...errors, result.error] : errors)(schema.safeParse(x)), []);
+		const passed = schemas.length - errors.length;
+		if (passed !== 1) ctx.addIssue(errors.length ? {
+			path: ctx.path,
+			code: "invalid_union",
+			unionErrors: errors,
+			message: "Invalid input: Should pass single schema. Passed " + passed
+		} : {
+			path: ctx.path,
+			code: "custom",
+			message: "Invalid input: Should pass single schema. Passed " + passed
+		});
+	}).describe("Parent capability(s) this extends. Present for extensions, absent for root capabilities. Use array for multi-parent extensions.").optional() })))).describe("Capability registry keyed by reverse-domain name.").optional(),
+	"payment_handlers": zod.record(zod.array(zod.intersection(zod.object({
+		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
+		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
+		"schema": zod.string().url().describe("URL to JSON Schema defining this entity's structure and payloads.").optional(),
+		"id": zod.string().describe("Unique identifier for this entity instance. Used to disambiguate when multiple instances exist.").optional(),
+		"config": zod.record(zod.string(), zod.unknown()).describe("Entity-specific configuration. Structure defined by each entity's schema.").optional()
+	}).describe("Shared foundation for all UCP entities."), zod.intersection(zod.record(zod.string(), zod.unknown()), zod.object({ "available_instruments": zod.array(zod.object({
+		"type": zod.string().describe("The instrument type identifier (e.g., 'card', 'gift_card'). References an instrument schema's type constant."),
+		"constraints": zod.record(zod.string(), zod.unknown()).describe("Constraints on this instrument type. Structure depends on instrument type and active capabilities.").optional()
+	}).describe("An instrument type available from a payment handler with optional constraints.")).min(1).describe("Instrument types this handler supports, with optional constraints. When absent, every instrument should be considered available.").optional() }))))).describe("Payment handler registry keyed by reverse-domain name.").optional()
+}).describe("Base UCP metadata with shared properties for all schema types."), zod.object({ "status": zod.literal("error") })).describe("UCP metadata with status 'error'. Use for response branches that carry error information.");
 const UcpPlatformSchema = zod.intersection(zod.object({
 	"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("UCP version in YYYY-MM-DD format."),
 	"status": zod.enum(["success", "error"]).describe("Application-level status of the UCP operation.").default("success"),
@@ -2360,7 +2505,7 @@ const UcpPlatformSchema = zod.intersection(zod.object({
 		zod.object({ "transport": zod.literal("mcp").optional() }),
 		zod.object({ "transport": zod.literal("a2a").optional() }),
 		zod.object({ "transport": zod.literal("embedded").optional() })
-	]))).describe("Full service declaration for platform-level discovery. Different transports require different fields."))),
+	]))).describe("Full service declaration for platform-level discovery. All transports require `version`, `spec`, and `transport`. REST and MCP additionally require `schema` and `endpoint`; A2A requires `endpoint`; embedded requires `schema`."))),
 	"capabilities": zod.record(zod.array(zod.intersection(zod.intersection(zod.object({
 		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("Entity version in YYYY-MM-DD format."),
 		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
@@ -3025,7 +3170,7 @@ const ProfileSchemaPlatformProfileSchema = zod.intersection(zod.object({
 		zod.object({ "transport": zod.literal("mcp").optional() }),
 		zod.object({ "transport": zod.literal("a2a").optional() }),
 		zod.object({ "transport": zod.literal("embedded").optional() })
-	]))).describe("Full service declaration for platform-level discovery. Different transports require different fields."))),
+	]))).describe("Full service declaration for platform-level discovery. All transports require `version`, `spec`, and `transport`. REST and MCP additionally require `schema` and `endpoint`; A2A requires `endpoint`; embedded requires `schema`."))),
 	"capabilities": zod.record(zod.array(zod.intersection(zod.intersection(zod.object({
 		"version": zod.string().regex(/* @__PURE__ */ new RegExp("^\\d{4}-\\d{2}-\\d{2}$")).describe("UCP version in YYYY-MM-DD format."),
 		"spec": zod.string().url().describe("URL to human-readable specification document.").optional(),
@@ -3431,6 +3576,7 @@ exports.UcpDiscoveryBusinessProfileSchema = UcpDiscoveryBusinessProfileSchema;
 exports.UcpDiscoveryPlatformProfileSchema = UcpDiscoveryPlatformProfileSchema;
 exports.UcpDiscoveryProfileSchema = UcpDiscoveryProfileSchema;
 exports.UcpEntitySchema = UcpEntitySchema;
+exports.UcpErrorSchema = UcpErrorSchema;
 exports.UcpPlatformSchema = UcpPlatformSchema;
 exports.UcpRequiresSchema = UcpRequiresSchema;
 exports.UcpResponseCartSchema = UcpResponseCartSchema;
@@ -3438,6 +3584,7 @@ exports.UcpResponseCatalogSchema = UcpResponseCatalogSchema;
 exports.UcpResponseCheckoutSchema = UcpResponseCheckoutSchema;
 exports.UcpResponseOrderSchema = UcpResponseOrderSchema;
 exports.UcpSigningKeySchema = UcpSigningKeySchema;
+exports.UcpSuccessSchema = UcpSuccessSchema;
 exports.UcpVersionConstraintSchema = UcpVersionConstraintSchema;
 exports.UcpVersionSchema = UcpVersionSchema;
 exports.VariantSchema = VariantSchema;