@omnixhq/ucp-client 0.1.1

package/dist/index.js

@@ -0,0 +1,996 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { BuyerSchema, CheckoutResponseStatusSchema, ExtendedCheckoutCreateRequestSchema, ExtendedCheckoutResponseSchema, ExtendedCheckoutUpdateRequestSchema, FulfillmentMethodResponseSchema, FulfillmentResponseSchema, ItemResponseSchema, LineItemResponseSchema, MessageErrorSchema, MessageSchema, OrderSchema, PaymentHandlerResponseSchema, PaymentInstrumentSchema, PaymentResponseSchema, PostalAddressSchema, TotalResponseSchema, UcpDiscoveryProfileSchema } from "@ucp-js/sdk";
+
+//#region src/errors.ts
+/** Thrown when the gateway returns an error response with `messages[]`. */
+var UCPError = class extends Error {
+	code;
+	type;
+	statusCode;
+	/** JSONPath to the field that caused the error, from the first message. */
+	path;
+	contentType;
+	/** All messages from the gateway response. */
+	messages;
+	constructor(code, message, type = "error", statusCode = 400, options = {}) {
+		super(message);
+		this.name = "UCPError";
+		this.code = code;
+		this.type = type;
+		this.statusCode = statusCode;
+		this.path = options.path;
+		this.contentType = options.contentType;
+		this.messages = options.messages ?? [];
+	}
+};
+/** Thrown on HTTP 409 when no `messages[]` body is present (idempotency key collision). */
+var UCPIdempotencyConflictError = class extends UCPError {
+	constructor(message = "Idempotency key reused with different request body") {
+		super("IDEMPOTENCY_CONFLICT", message, "error", 409);
+		this.name = "UCPIdempotencyConflictError";
+	}
+};
+/** Thrown when a checkout response has `status: 'requires_escalation'` with a `continue_url`. */
+var UCPEscalationError = class extends Error {
+	/** The URL to redirect the buyer to for merchant-hosted checkout UI. */
+	continue_url;
+	constructor(continue_url, message = "Payment requires escalation") {
+		super(message);
+		this.name = "UCPEscalationError";
+		this.continue_url = continue_url;
+	}
+};
+/** Thrown when an OAuth token exchange, refresh, or revocation fails. */
+var UCPOAuthError = class extends Error {
+	statusCode;
+	constructor(message, statusCode) {
+		super(message);
+		this.name = "UCPOAuthError";
+		this.statusCode = statusCode;
+	}
+};
+
+//#endregion
+//#region src/http.ts
+var HttpClient = class HttpClient {
+	gatewayUrl;
+	agentProfileUrl;
+	ucpVersion;
+	requestSignature;
+	accessToken;
+	onValidationWarning;
+	constructor(config) {
+		this.gatewayUrl = config.gatewayUrl;
+		this.agentProfileUrl = config.agentProfileUrl;
+		this.ucpVersion = config.ucpVersion;
+		this.requestSignature = config.requestSignature;
+		this.accessToken = config.accessToken;
+		this.onValidationWarning = config.onValidationWarning ?? ((msg, detail) => console.warn(msg, detail));
+	}
+	withAccessToken(token) {
+		return new HttpClient({
+			gatewayUrl: this.gatewayUrl,
+			agentProfileUrl: this.agentProfileUrl,
+			ucpVersion: this.ucpVersion,
+			...this.requestSignature !== void 0 ? { requestSignature: this.requestSignature } : {},
+			accessToken: token,
+			onValidationWarning: this.onValidationWarning
+		});
+	}
+	async request(method, path, body) {
+		const url = `${this.gatewayUrl}${path}`;
+		const requestId = randomUUID();
+		const headers = {
+			"UCP-Agent": `profile="${this.agentProfileUrl}", version="${this.ucpVersion}"`,
+			"request-id": requestId
+		};
+		if (body !== void 0) headers["Content-Type"] = "application/json";
+		if (this.requestSignature !== void 0) headers["request-signature"] = this.requestSignature;
+		if (this.accessToken !== void 0) headers["Authorization"] = `Bearer ${this.accessToken}`;
+		if (method === "POST" || method === "PUT") headers["idempotency-key"] = randomUUID();
+		const res = await fetch(url, {
+			method,
+			headers,
+			...body !== void 0 ? { body: JSON.stringify(body) } : {}
+		});
+		const data = await res.json().catch(() => ({}));
+		if (!res.ok) this.throwFromResponse(data, res.status);
+		return data;
+	}
+	validate(data, schema) {
+		const result = schema.safeParse(data);
+		if (!result.success) {
+			this.onValidationWarning("[UCPClient] Response validation failed:", result.error.message);
+			return data;
+		}
+		return result.data;
+	}
+	throwFromResponse(data, statusCode) {
+		if (typeof data !== "object" || data === null) {
+			if (statusCode === 409) throw new UCPIdempotencyConflictError();
+			throw new UCPError("HTTP_ERROR", `Gateway returned ${statusCode}`, "error", statusCode);
+		}
+		const body = data;
+		const rawMessages = body["messages"];
+		if (Array.isArray(rawMessages) && rawMessages.length > 0) {
+			const allMessages = parseMessages(rawMessages);
+			const first = allMessages[0];
+			const code = first.code ?? "UNKNOWN";
+			throw new UCPError(code, first.content, first.type, statusCode, {
+				...first.path !== void 0 ? { path: first.path } : {},
+				...first.content_type !== void 0 ? { contentType: first.content_type } : {},
+				messages: allMessages
+			});
+		}
+		if (statusCode === 409) throw new UCPIdempotencyConflictError();
+		throw new UCPError("HTTP_ERROR", `Gateway returned ${statusCode}`, "error", statusCode);
+	}
+};
+function parseMessages(rawMessages) {
+	return rawMessages.map((m) => {
+		const record = m;
+		const rawType = String(record["type"] ?? "error");
+		const validTypes = [
+			"error",
+			"warning",
+			"info"
+		];
+		const type = validTypes.includes(rawType) ? rawType : "error";
+		return {
+			type,
+			content: String(record["content"] ?? "Unknown error"),
+			...record["code"] !== void 0 ? { code: String(record["code"]) } : {},
+			...record["severity"] !== void 0 ? { severity: String(record["severity"]) } : {},
+			...record["path"] !== void 0 ? { path: String(record["path"]) } : {},
+			...record["content_type"] !== void 0 ? { content_type: String(record["content_type"]) } : {}
+		};
+	});
+}
+
+//#endregion
+//#region src/schemas.ts
+const CheckoutSessionSchema = ExtendedCheckoutResponseSchema.passthrough();
+const UCPProfileSchema = UcpDiscoveryProfileSchema.passthrough();
+const UCPProductSchema = z.object({
+	id: z.string(),
+	title: z.string(),
+	description: z.string().nullable(),
+	price_cents: z.number().int(),
+	currency: z.string().min(3).max(3),
+	in_stock: z.boolean(),
+	stock_quantity: z.number().int().min(0),
+	images: z.array(z.string().url()),
+	variants: z.array(z.object({
+		id: z.string(),
+		title: z.string(),
+		price_cents: z.number().int(),
+		in_stock: z.boolean(),
+		attributes: z.record(z.string())
+	}).passthrough())
+}).passthrough();
+const UCPOrderSchema = z.object({
+	id: z.string(),
+	status: z.enum([
+		"pending",
+		"processing",
+		"shipped",
+		"delivered",
+		"canceled"
+	]),
+	total_cents: z.number().int(),
+	currency: z.string().min(3).max(3),
+	created_at_iso: z.string().datetime({ offset: true })
+}).passthrough();
+const CreateCheckoutRequestSchema = ExtendedCheckoutCreateRequestSchema.passthrough();
+const UpdateCheckoutRequestSchema = ExtendedCheckoutUpdateRequestSchema.passthrough();
+const CompleteCheckoutRequestSchema = z.object({ payment: z.object({ instruments: z.array(z.object({
+	id: z.string(),
+	handler_id: z.string(),
+	type: z.string(),
+	selected: z.boolean().optional(),
+	credential: z.object({
+		type: z.string(),
+		token: z.string().optional()
+	}).optional(),
+	billing_address: z.unknown().optional()
+}).passthrough()) }) });
+
+//#endregion
+//#region src/capabilities/checkout.ts
+const DEFAULT_METHOD_ID = "default";
+const DEFAULT_GROUP_ID = "default";
+/**
+* Checkout session operations. Available when the server declares `dev.ucp.shopping.checkout`.
+* Check `extensions` to see which optional features (fulfillment, discount, etc.) are supported.
+*/
+var CheckoutCapability = class {
+	/** Which checkout extensions the server supports. */
+	extensions;
+	constructor(http, extensions) {
+		this.http = http;
+		this.extensions = extensions;
+	}
+	async create(payload) {
+		const data = await this.http.request("POST", "/checkout-sessions", payload);
+		return this.validateSession(data);
+	}
+	async get(id) {
+		const data = await this.http.request("GET", `/checkout-sessions/${encodeURIComponent(id)}`);
+		return this.validateSession(data);
+	}
+	async update(id, patch) {
+		const data = await this.http.request("PUT", `/checkout-sessions/${encodeURIComponent(id)}`, patch);
+		return this.validateSession(data);
+	}
+	async complete(id, payload) {
+		const data = await this.http.request("POST", `/checkout-sessions/${encodeURIComponent(id)}/complete`, payload);
+		return this.validateSession(data);
+	}
+	async cancel(id) {
+		const data = await this.http.request("POST", `/checkout-sessions/${encodeURIComponent(id)}/cancel`);
+		return this.validateSession(data);
+	}
+	async setFulfillment(id, type, patch) {
+		return this.update(id, {
+			...patch,
+			fulfillment: { methods: [{
+				id: DEFAULT_METHOD_ID,
+				type
+			}] }
+		});
+	}
+	async selectDestination(id, destinationId, fulfillmentType = "shipping", patch) {
+		return this.update(id, {
+			...patch,
+			fulfillment: { methods: [{
+				id: DEFAULT_METHOD_ID,
+				type: fulfillmentType,
+				selected_destination_id: destinationId
+			}] }
+		});
+	}
+	async selectFulfillmentOption(id, optionId, destinationId, fulfillmentType = "shipping", patch) {
+		return this.update(id, {
+			...patch,
+			fulfillment: { methods: [{
+				id: DEFAULT_METHOD_ID,
+				type: fulfillmentType,
+				...destinationId !== void 0 ? { selected_destination_id: destinationId } : {},
+				groups: [{
+					id: DEFAULT_GROUP_ID,
+					selected_option_id: optionId
+				}]
+			}] }
+		});
+	}
+	async applyDiscountCodes(id, codes, patch) {
+		return this.update(id, {
+			...patch,
+			discounts: { codes: [...codes] }
+		});
+	}
+	validateSession(data) {
+		const session = this.http.validate(data, CheckoutSessionSchema);
+		if (session.status === "requires_escalation" && session.continue_url) throw new UCPEscalationError(session.continue_url);
+		return session;
+	}
+};
+
+//#endregion
+//#region src/capabilities/order.ts
+/** Order operations. Available when the server declares `dev.ucp.shopping.order`. */
+var OrderCapability = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/** Retrieve an order by ID. Returns the UCP spec-compliant Order object. */
+	async get(id) {
+		const data = await this.http.request("GET", `/orders/${encodeURIComponent(id)}`);
+		return this.http.validate(data, OrderSchema);
+	}
+};
+
+//#endregion
+//#region src/capabilities/identity-linking.ts
+const TokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.string(),
+	expires_in: z.number().optional(),
+	refresh_token: z.string().optional(),
+	scope: z.string().optional()
+}).passthrough();
+/**
+* OAuth 2.0 identity linking for account linking between platforms and merchants.
+* Available when the server declares `dev.ucp.common.identity_linking`.
+*/
+var IdentityLinkingCapability = class {
+	constructor(metadata) {
+		this.metadata = metadata;
+	}
+	/** Build the OAuth authorization URL to redirect the buyer to. */
+	getAuthorizationUrl(params) {
+		const url = new URL(this.metadata.authorization_endpoint);
+		url.searchParams.set("response_type", "code");
+		url.searchParams.set("client_id", params.client_id);
+		url.searchParams.set("redirect_uri", params.redirect_uri);
+		url.searchParams.set("scope", params.scope ?? "ucp:scopes:checkout_session");
+		if (params.state !== void 0) url.searchParams.set("state", params.state);
+		return url.toString();
+	}
+	async exchangeCode(params) {
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code: params.code,
+			redirect_uri: params.redirect_uri
+		});
+		return this.tokenRequest(params.client_id, params.client_secret, body);
+	}
+	async refreshToken(params) {
+		const body = new URLSearchParams({
+			grant_type: "refresh_token",
+			refresh_token: params.refresh_token
+		});
+		return this.tokenRequest(params.client_id, params.client_secret, body);
+	}
+	async revokeToken(params) {
+		const body = new URLSearchParams({ token: params.token });
+		if (params.token_type_hint !== void 0) body.set("token_type_hint", params.token_type_hint);
+		const res = await fetch(this.metadata.revocation_endpoint, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/x-www-form-urlencoded",
+				Authorization: encodeBasicAuth(params.client_id, params.client_secret)
+			},
+			body: body.toString()
+		});
+		if (!res.ok) throw new UCPOAuthError(`Token revocation failed: ${res.status}`, res.status);
+	}
+	getMetadata() {
+		return this.metadata;
+	}
+	async tokenRequest(clientId, clientSecret, body) {
+		const res = await fetch(this.metadata.token_endpoint, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/x-www-form-urlencoded",
+				Authorization: encodeBasicAuth(clientId, clientSecret)
+			},
+			body: body.toString()
+		});
+		if (!res.ok) throw new UCPOAuthError(`Token exchange failed with status ${res.status}`, res.status);
+		const raw = await res.json();
+		const parsed = TokenResponseSchema.safeParse(raw);
+		if (!parsed.success) throw new UCPOAuthError(`Invalid token response: ${parsed.error.message}`, res.status);
+		return parsed.data;
+	}
+};
+function encodeBasicAuth(username, password) {
+	return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+}
+
+//#endregion
+//#region src/capabilities/products.ts
+/** Product catalog search and retrieval. Always available (gateway-specific, not part of UCP spec). */
+var ProductsCapability = class {
+	constructor(http) {
+		this.http = http;
+	}
+	/** Search products by query string with optional filters. */
+	async search(query, filters = {}) {
+		const params = new URLSearchParams({ q: query });
+		const filterEntries = [
+			["max_price_cents", filters.max_price_cents],
+			["min_price_cents", filters.min_price_cents],
+			["in_stock", filters.in_stock],
+			["category", filters.category],
+			["limit", filters.limit],
+			["page", filters.page]
+		];
+		for (const [key, value] of filterEntries) if (value != null) params.set(key, String(value));
+		const res = await this.http.request("GET", `/ucp/products?${params.toString()}`);
+		const data = res;
+		const products = Array.isArray(data) ? data : data.products ?? [];
+		return products.map((p) => this.http.validate(p, UCPProductSchema));
+	}
+	async get(id) {
+		const data = await this.http.request("GET", `/ucp/products/${encodeURIComponent(id)}`);
+		return this.http.validate(data, UCPProductSchema);
+	}
+};
+
+//#endregion
+//#region src/types/config.ts
+const DEFAULT_UCP_VERSION = "2026-01-23";
+const UCP_CAPABILITIES = {
+	CHECKOUT: "dev.ucp.shopping.checkout",
+	FULFILLMENT: "dev.ucp.shopping.fulfillment",
+	DISCOUNT: "dev.ucp.shopping.discount",
+	BUYER_CONSENT: "dev.ucp.shopping.buyer_consent",
+	ORDER: "dev.ucp.shopping.order",
+	IDENTITY_LINKING: "dev.ucp.common.identity_linking",
+	AP2_MANDATE: "dev.ucp.shopping.ap2_mandate"
+};
+
+//#endregion
+//#region src/agent-tools.ts
+/**
+* Returns ready-to-use tool definitions for agent registration.
+* Only tools supported by the connected server are included.
+*
+* Each tool has:
+* - `name` — unique tool identifier
+* - `description` — what the tool does (for the LLM)
+* - `parameters` — JSON Schema describing the expected input
+* - `execute(params)` — function that calls the right capability method
+*
+* @example
+* ```typescript
+* const client = await UCPClient.connect(config);
+* const tools = getAgentTools(client);
+*
+* // Register with Anthropic Claude API
+* const response = await anthropic.messages.create({
+*   tools: tools.map(t => ({
+*     name: t.name,
+*     description: t.description,
+*     input_schema: t.parameters,
+*   })),
+*   // ...
+* });
+*
+* // Execute tool calls
+* for (const block of response.content) {
+*   if (block.type === 'tool_use') {
+*     const tool = tools.find(t => t.name === block.name);
+*     const result = await tool.execute(block.input);
+*   }
+* }
+* ```
+*/
+function getAgentTools(client) {
+	const tools = [...productTools(client)];
+	if (client.checkout) {
+		tools.push(...checkoutTools(client));
+		if (client.checkout.extensions.fulfillment) tools.push(...fulfillmentTools(client));
+		if (client.checkout.extensions.discount) tools.push(...discountTools(client));
+	}
+	if (client.order) tools.push(...orderTools(client));
+	return tools;
+}
+function productTools(client) {
+	return [{
+		name: "search_products",
+		description: "Search the product catalog by query string. Returns matching products with prices, availability, and images.",
+		parameters: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "Search query (e.g., \"running shoes\")"
+				},
+				max_price_cents: {
+					type: "number",
+					description: "Maximum price in cents"
+				},
+				min_price_cents: {
+					type: "number",
+					description: "Minimum price in cents"
+				},
+				in_stock: {
+					type: "boolean",
+					description: "Filter to in-stock items only"
+				},
+				category: {
+					type: "string",
+					description: "Product category"
+				},
+				limit: {
+					type: "number",
+					description: "Max results to return"
+				}
+			},
+			required: ["query"]
+		},
+		execute: async (params) => {
+			const { query,...filters } = params;
+			return client.products.search(query, filters);
+		}
+	}, {
+		name: "get_product",
+		description: "Get detailed product information by ID, including variants, images, and stock.",
+		parameters: {
+			type: "object",
+			properties: { id: {
+				type: "string",
+				description: "Product ID"
+			} },
+			required: ["id"]
+		},
+		execute: async (params) => client.products.get(params["id"])
+	}];
+}
+function checkoutTools(client) {
+	return [
+		{
+			name: "create_checkout",
+			description: "Create a new checkout session with line items. Returns a session with an ID to use in subsequent calls.",
+			parameters: {
+				type: "object",
+				properties: {
+					line_items: {
+						type: "array",
+						description: "Products to purchase",
+						items: {
+							type: "object",
+							properties: {
+								item: {
+									type: "object",
+									properties: { id: {
+										type: "string",
+										description: "Product ID"
+									} },
+									required: ["id"]
+								},
+								quantity: {
+									type: "number",
+									description: "Quantity to purchase"
+								}
+							},
+							required: ["item", "quantity"]
+						}
+					},
+					currency: {
+						type: "string",
+						description: "ISO 4217 currency code (e.g., \"USD\")"
+					}
+				},
+				required: ["line_items"]
+			},
+			execute: async (params) => client.checkout.create(params)
+		},
+		{
+			name: "get_checkout",
+			description: "Get the current state of a checkout session, including status, totals, and available options.",
+			parameters: {
+				type: "object",
+				properties: { id: {
+					type: "string",
+					description: "Checkout session ID"
+				} },
+				required: ["id"]
+			},
+			execute: async (params) => client.checkout.get(params["id"])
+		},
+		{
+			name: "update_checkout",
+			description: "Update a checkout session with buyer information, shipping address, or payment details.",
+			parameters: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Checkout session ID"
+					},
+					buyer: {
+						type: "object",
+						description: "Buyer contact information",
+						properties: {
+							first_name: { type: "string" },
+							last_name: { type: "string" },
+							email: { type: "string" },
+							phone_number: { type: "string" }
+						}
+					},
+					context: {
+						type: "object",
+						description: "Localization context for pricing and availability",
+						properties: {
+							address_country: {
+								type: "string",
+								description: "ISO 3166-1 alpha-2 country code"
+							},
+							address_region: {
+								type: "string",
+								description: "State or province"
+							},
+							postal_code: { type: "string" }
+						}
+					}
+				},
+				required: ["id"]
+			},
+			execute: async (params) => {
+				const { id,...patch } = params;
+				return client.checkout.update(id, patch);
+			}
+		},
+		{
+			name: "complete_checkout",
+			description: "Complete a checkout session with payment. Places the order. Returns the completed session with order ID.",
+			parameters: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Checkout session ID"
+					},
+					payment: {
+						type: "object",
+						description: "Payment information",
+						properties: { instruments: {
+							type: "array",
+							items: {
+								type: "object",
+								properties: {
+									id: {
+										type: "string",
+										description: "Instrument ID"
+									},
+									handler_id: {
+										type: "string",
+										description: "Payment handler ID from the server profile"
+									},
+									type: {
+										type: "string",
+										description: "Payment type (e.g., \"card\", \"offline\")"
+									},
+									credential: {
+										type: "object",
+										properties: {
+											type: {
+												type: "string",
+												description: "Credential type (e.g., \"token\")"
+											},
+											token: {
+												type: "string",
+												description: "Payment token"
+											}
+										},
+										required: ["type"]
+									}
+								},
+								required: [
+									"id",
+									"handler_id",
+									"type"
+								]
+							}
+						} },
+						required: ["instruments"]
+					}
+				},
+				required: ["id", "payment"]
+			},
+			execute: async (params) => {
+				const { id,...payload } = params;
+				return client.checkout.complete(String(id), payload);
+			}
+		},
+		{
+			name: "cancel_checkout",
+			description: "Cancel a checkout session. The session cannot be used after cancellation.",
+			parameters: {
+				type: "object",
+				properties: { id: {
+					type: "string",
+					description: "Checkout session ID"
+				} },
+				required: ["id"]
+			},
+			execute: async (params) => client.checkout.cancel(params["id"])
+		}
+	];
+}
+function fulfillmentTools(client) {
+	return [
+		{
+			name: "set_fulfillment",
+			description: "Set the fulfillment method for a checkout (e.g., \"shipping\" or \"pickup\").",
+			parameters: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Checkout session ID"
+					},
+					type: {
+						type: "string",
+						enum: ["shipping", "pickup"],
+						description: "Fulfillment method"
+					}
+				},
+				required: ["id", "type"]
+			},
+			execute: async (params) => client.checkout.setFulfillment(params["id"], params["type"])
+		},
+		{
+			name: "select_destination",
+			description: "Select a shipping destination for a checkout session.",
+			parameters: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Checkout session ID"
+					},
+					destination_id: {
+						type: "string",
+						description: "Destination ID to select"
+					},
+					fulfillment_type: {
+						type: "string",
+						default: "shipping",
+						description: "Fulfillment type"
+					}
+				},
+				required: ["id", "destination_id"]
+			},
+			execute: async (params) => client.checkout.selectDestination(params["id"], params["destination_id"], params["fulfillment_type"] ?? "shipping")
+		},
+		{
+			name: "select_fulfillment_option",
+			description: "Select a fulfillment option (e.g., standard shipping, express shipping) for a checkout session.",
+			parameters: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						description: "Checkout session ID"
+					},
+					option_id: {
+						type: "string",
+						description: "Fulfillment option ID to select"
+					},
+					destination_id: {
+						type: "string",
+						description: "Destination ID (if applicable)"
+					},
+					fulfillment_type: {
+						type: "string",
+						default: "shipping",
+						description: "Fulfillment type"
+					}
+				},
+				required: ["id", "option_id"]
+			},
+			execute: async (params) => client.checkout.selectFulfillmentOption(params["id"], params["option_id"], params["destination_id"], params["fulfillment_type"] ?? "shipping")
+		}
+	];
+}
+function discountTools(client) {
+	return [{
+		name: "apply_discount_codes",
+		description: "Apply one or more discount codes to a checkout session.",
+		parameters: {
+			type: "object",
+			properties: {
+				id: {
+					type: "string",
+					description: "Checkout session ID"
+				},
+				codes: {
+					type: "array",
+					items: { type: "string" },
+					description: "Discount codes to apply"
+				}
+			},
+			required: ["id", "codes"]
+		},
+		execute: async (params) => client.checkout.applyDiscountCodes(params["id"], params["codes"])
+	}];
+}
+function orderTools(client) {
+	return [{
+		name: "get_order",
+		description: "Get order details by ID, including line items, fulfillment status, and tracking information.",
+		parameters: {
+			type: "object",
+			properties: { id: {
+				type: "string",
+				description: "Order ID"
+			} },
+			required: ["id"]
+		},
+		execute: async (params) => client.order.get(params["id"])
+	}];
+}
+
+//#endregion
+//#region src/UCPClient.ts
+/**
+* Connect to a UCP server, discover its capabilities, and return a {@link ConnectedClient}.
+*
+* @example
+* ```typescript
+* const client = await connect({
+*   gatewayUrl: 'https://store.example.com/ucp',
+*   agentProfileUrl: 'https://platform.example.com/.well-known/ucp',
+* });
+*
+* if (client.checkout) {
+*   const session = await client.checkout.create({ line_items: [...] });
+* }
+* ```
+*/
+async function connect(config, options) {
+	validateConfig(config);
+	const http = new HttpClient({
+		gatewayUrl: config.gatewayUrl.replace(/\/+$/, ""),
+		agentProfileUrl: config.agentProfileUrl,
+		ucpVersion: config.ucpVersion ?? DEFAULT_UCP_VERSION,
+		...config.requestSignature !== void 0 ? { requestSignature: config.requestSignature } : {},
+		...options?.onValidationWarning !== void 0 ? { onValidationWarning: options.onValidationWarning } : {}
+	});
+	const rawProfile = await http.request("GET", "/.well-known/ucp");
+	const profile = http.validate(rawProfile, UCPProfileSchema);
+	const capabilityNames = extractCapabilityNames(profile);
+	const checkout = buildCheckoutCapability(http, capabilityNames);
+	const order = capabilityNames.has(UCP_CAPABILITIES.ORDER) ? new OrderCapability(http) : null;
+	const identityLinking = await buildIdentityLinking(config, capabilityNames);
+	const products = new ProductsCapability(http);
+	const paymentHandlers = extractPaymentHandlers(profile);
+	const client = {
+		profile,
+		checkout,
+		order,
+		identityLinking,
+		products,
+		paymentHandlers,
+		describeTools: () => buildToolDescriptors(checkout, order, identityLinking),
+		getAgentTools: () => getAgentTools(client)
+	};
+	return Object.freeze(client);
+}
+/**
+* UCP client entry point. Use `UCPClient.connect()` to discover server capabilities
+* and get a {@link ConnectedClient}.
+*
+* @example
+* ```typescript
+* const client = await UCPClient.connect({
+*   gatewayUrl: 'https://store.example.com/ucp',
+*   agentProfileUrl: 'https://platform.example.com/.well-known/ucp',
+* });
+* ```
+*/
+var UCPClient = class {
+	constructor() {}
+	static connect = connect;
+};
+function validateConfig(config) {
+	new URL(config.gatewayUrl);
+	if (config.agentProfileUrl.includes("\"") || config.agentProfileUrl.includes("\n")) throw new Error("agentProfileUrl must not contain double quotes or newlines");
+	new URL(config.agentProfileUrl);
+}
+function extractCapabilityNames(profile) {
+	const capabilities = profile.ucp?.capabilities;
+	if (!Array.isArray(capabilities)) return new Set();
+	return new Set(capabilities.map((c) => c.name).filter((n) => n !== void 0));
+}
+const PaymentHandlerInstanceSchema = z.object({
+	id: z.string(),
+	version: z.string(),
+	spec: z.string(),
+	schema: z.string(),
+	config: z.record(z.unknown()).optional()
+}).passthrough();
+const PaymentHandlerMapSchema = z.record(z.array(PaymentHandlerInstanceSchema));
+function extractPaymentHandlers(profile) {
+	const raw = profile["payment_handlers"];
+	if (typeof raw !== "object" || raw === null) return {};
+	const result = PaymentHandlerMapSchema.safeParse(raw);
+	if (!result.success) return {};
+	return result.data;
+}
+function buildCheckoutCapability(http, capabilityNames) {
+	if (!capabilityNames.has(UCP_CAPABILITIES.CHECKOUT)) return null;
+	const extensions = {
+		fulfillment: capabilityNames.has(UCP_CAPABILITIES.FULFILLMENT),
+		discount: capabilityNames.has(UCP_CAPABILITIES.DISCOUNT),
+		buyerConsent: capabilityNames.has(UCP_CAPABILITIES.BUYER_CONSENT),
+		ap2Mandate: capabilityNames.has(UCP_CAPABILITIES.AP2_MANDATE)
+	};
+	return new CheckoutCapability(http, extensions);
+}
+const OAuthServerMetadataSchema = z.object({
+	issuer: z.string(),
+	authorization_endpoint: z.string().url(),
+	token_endpoint: z.string().url(),
+	revocation_endpoint: z.string().url(),
+	scopes_supported: z.array(z.string()),
+	response_types_supported: z.array(z.string()),
+	grant_types_supported: z.array(z.string()),
+	token_endpoint_auth_methods_supported: z.array(z.string()),
+	service_documentation: z.string().url().optional()
+}).passthrough();
+async function buildIdentityLinking(config, capabilityNames) {
+	if (!capabilityNames.has(UCP_CAPABILITIES.IDENTITY_LINKING)) return null;
+	const gatewayUrl = config.gatewayUrl.replace(/\/+$/, "");
+	const metadataUrl = `${gatewayUrl}/.well-known/oauth-authorization-server`;
+	const res = await fetch(metadataUrl);
+	if (!res.ok) throw new Error(`Identity linking capability declared but OAuth metadata fetch failed: ${res.status} from ${metadataUrl}`);
+	const raw = await res.json();
+	const parsed = OAuthServerMetadataSchema.safeParse(raw);
+	if (!parsed.success) throw new Error(`Identity linking OAuth metadata validation failed: ${parsed.error.message}`);
+	return new IdentityLinkingCapability(parsed.data);
+}
+function buildToolDescriptors(checkout, order, identityLinking) {
+	const tools = [{
+		name: "search_products",
+		capability: "products",
+		description: "Search product catalog"
+	}, {
+		name: "get_product",
+		capability: "products",
+		description: "Get product by ID"
+	}];
+	if (checkout) {
+		tools.push({
+			name: "create_checkout",
+			capability: "checkout",
+			description: "Create a checkout session"
+		}, {
+			name: "get_checkout",
+			capability: "checkout",
+			description: "Get checkout session by ID"
+		}, {
+			name: "update_checkout",
+			capability: "checkout",
+			description: "Update a checkout session"
+		}, {
+			name: "complete_checkout",
+			capability: "checkout",
+			description: "Complete checkout with payment"
+		}, {
+			name: "cancel_checkout",
+			capability: "checkout",
+			description: "Cancel a checkout session"
+		});
+		if (checkout.extensions.fulfillment) tools.push({
+			name: "set_fulfillment",
+			capability: "checkout.fulfillment",
+			description: "Set fulfillment method (shipping/pickup)"
+		}, {
+			name: "select_destination",
+			capability: "checkout.fulfillment",
+			description: "Select shipping destination"
+		}, {
+			name: "select_fulfillment_option",
+			capability: "checkout.fulfillment",
+			description: "Select fulfillment option (e.g., express shipping)"
+		});
+		if (checkout.extensions.discount) tools.push({
+			name: "apply_discount_codes",
+			capability: "checkout.discount",
+			description: "Apply discount codes to checkout"
+		});
+	}
+	if (order) tools.push({
+		name: "get_order",
+		capability: "order",
+		description: "Get order by ID"
+	});
+	if (identityLinking) tools.push({
+		name: "get_authorization_url",
+		capability: "identity_linking",
+		description: "Get OAuth authorization URL for account linking"
+	}, {
+		name: "exchange_auth_code",
+		capability: "identity_linking",
+		description: "Exchange authorization code for access token"
+	}, {
+		name: "refresh_access_token",
+		capability: "identity_linking",
+		description: "Refresh an expired access token"
+	}, {
+		name: "revoke_token",
+		capability: "identity_linking",
+		description: "Revoke an access or refresh token"
+	});
+	return tools;
+}
+
+//#endregion
+export { BuyerSchema, CheckoutCapability, CheckoutResponseStatusSchema, CheckoutSessionSchema, CompleteCheckoutRequestSchema, CreateCheckoutRequestSchema, DEFAULT_UCP_VERSION, FulfillmentMethodResponseSchema, FulfillmentResponseSchema, IdentityLinkingCapability, ItemResponseSchema, LineItemResponseSchema, MessageErrorSchema, MessageSchema, OrderCapability, PaymentHandlerResponseSchema, PaymentInstrumentSchema, PaymentResponseSchema, PostalAddressSchema, ProductsCapability, TotalResponseSchema, UCPClient, UCPError, UCPEscalationError, UCPIdempotencyConflictError, UCPOAuthError, UCPOrderSchema, UCPProductSchema, UCPProfileSchema, OrderSchema as UCPSpecOrderSchema, UCP_CAPABILITIES, UpdateCheckoutRequestSchema, connect, getAgentTools };
+//# sourceMappingURL=index.js.map