@artos-commerce/ucp-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @artos-commerce/ucp-client
+
+**Path B Direct UCP client for Artos.** A typed UCP transport, AP2 mandate
+signing, and checkout orchestration so you can build your own commerce-grade UCP
+client against `api.artos.sh` — without hand-rolling the JSON-RPC envelope, the
+canonical-JSON signing bytes, the AP2 mandates, or the payment-rail rules.
+
+This is the reusable core extracted from the hosted Artos MCP bridge. If you just
+want an MCP endpoint for AI agents, point them at the hosted bridge
+(`https://agent.artos.sh/mcp`, **Path A**) and skip this package. Reach for
+`@artos-commerce/ucp-client` when you are building your **own** client/integration
+(**Path B**) and want the hard parts — signing, verification, and rail selection
+— done correctly for you.
+
+## What it does for you
+
+- **Transport** (`UcpClient`): global catalog search (REST) and per-store /
+  buyer-account shopping over the UCP MCP JSON-RPC transport, with the UCP-Agent
+  preamble, idempotency keys, the two-credential auth model, and the 401
+  silent-refresh relay all handled.
+- **AP2 signing** (`Ap2Signer`): mints the compact ES256 `checkout_mandate` /
+  `payment_mandate` the API requires, over byte-parity canonical JSON.
+- **Verification** (`verifyMerchantAuthorization`): re-checks the store-signed
+  terms before you authorize a spend.
+- **Checkout orchestration** (`createCheckoutHandlers`): a single
+  `confirmPurchase` re-prices, verifies, mints the mandate, routes to the
+  `$0` / card / crypto rail, and returns a structured `CheckoutOutcome`.
+
+## Install
+
+```bash
+npm install @artos-commerce/ucp-client
+# Only if you need the crypto settlement rail:
+npm install @mysten/sui
+```
+
+Requires Node 20+ (for global `fetch` and `base64url`). `@mysten/sui` is an
+**optional** peer dependency — card-only integrations don't need it.
+
+## Quickstart
+
+```ts
+import {
+  UcpClient,
+  Ap2Signer,
+  createCheckoutHandlers,
+  resolveCryptoDeps,
+} from '@artos-commerce/ucp-client';
+
+const client = new UcpClient(
+  {
+    artosBaseUrl: 'https://api.artos.sh',
+    platformApiKey: process.env.UCP_PLATFORM_API_KEY!, // "<clientId>.<secret>"
+    platformProfileUrl: 'https://you.example/.well-known/ucp',
+  },
+  {
+    // The current buyer's OAuth bearer (server-side only — never ship it to a
+    // browser). Omit for anonymous/card-only sessions.
+    buyerToken: session.buyerBearer,
+    // Relay a 401 challenge so the agent can silently refresh its token.
+    onAuthChallenge: (wwwAuthenticate) => respondWith401(wwwAuthenticate),
+  },
+);
+
+const signer = new Ap2Signer(
+  JSON.parse(process.env.AGENT_PRIVATE_JWK!), // EC P-256 private JWK
+  process.env.AGENT_KID!, // must match your published profile's public JWK kid
+);
+
+// Optional crypto rail (needs @mysten/sui):
+const crypto = resolveCryptoDeps({
+  agentSuiPrivateKey: process.env.AGENT_SUI_PRIVATE_KEY, // suiprivkey1...
+  suiNetwork: 'mainnet',
+  agentMaxSpendAmount: 50_000, // optional client-side cap (minor units)
+});
+
+const shop = createCheckoutHandlers({ client, signer, crypto });
+```
+
+### Search → cart → checkout → buy
+
+```ts
+// 1. Discover (price filters are MAJOR units; converted to minor for you).
+const results = await shop.searchProducts({
+  query: 'running shoes',
+  filters: { price: { max: 150, currency: 'USD' } },
+});
+
+// 2. Build a checkout (per store, by slug from the search result metadata).
+const checkout = await shop.createCheckout({
+  storeSlug: 'energy-sport',
+  items: [{ id: 'prod_123', quantity: 1 }],
+  shippingAddress: { country: 'US', postal_code: '94016' },
+});
+
+// 3. Confirm: re-prices, verifies the store signature, mints the AP2 mandate,
+//    routes the rail, and returns a structured outcome.
+const outcome = await shop.confirmPurchase({
+  storeSlug: 'energy-sport',
+  checkoutId: checkout.id as string,
+  paymentMethod: 'artos.card', // omit on a multi-rail store to be asked
+});
+
+switch (outcome.status) {
+  case 'completed':
+    return renderOrder(outcome.checkout);
+  case 'escalation_required':
+    return redirect(outcome.continueUrl); // 3-DS / hosted step
+  case 'payment_selection_required':
+    return askBuyerToPickRail(outcome.rails);
+  case 'error':
+    return showError(outcome.code, outcome.message);
+}
+```
+
+`confirmPurchase` never throws for a business outcome — it always resolves to a
+`CheckoutOutcome`. Transport failures (network / non-2xx / JSON-RPC error) still
+throw `UcpClientError`; an expired buyer bearer throws `UcpAuthError` carrying
+the `WWW-Authenticate` challenge.
+
+## The two-credential auth model
+
+The Artos API's identity guard prefers `X-API-Key` over a bearer. `UcpClient`
+encodes this for you:
+
+- **Platform `X-API-Key`** (default) authenticates at any store: catalog, cart,
+  checkout create/update, `get_order`, card completion.
+- **Buyer OAuth bearer only** is used on `auth: 'buyer'` calls — crypto
+  `prepare`/`complete` and all `/account/*` tools. The API key is omitted so the
+  API resolves the buyer account and enforces their stored authorization + caps.
+
+Never send both for a buyer-bound call.
+
+## API surface
+
+- `UcpClient` — `globalSearch`, `callGlobalTool`, `callStoreTool`,
+  `listAccountTools`, `callAccountTool`, `fetchStoreProfile`, `fetchImage`,
+  `hasBuyerToken`, `ucpAgentHeader`.
+- `Ap2Signer` — `mintCheckoutMandate`, `mintPaymentMandate`.
+- `canonicalJson`, `verifyDetachedJws`, `verifyMerchantAuthorization`.
+- `createCheckoutHandlers` — read tools + `confirmPurchase`.
+- `SuiSigner`, `resolveCryptoDeps` (crypto rail; need `@mysten/sui`).
+- Helpers: `toMinorUnits`, `normalizeSearchFilters`, `resolveRail`,
+  `grandTotal`, `currencyOf`, `asAllowanceId`, `isUcpError`, `messageOf`.
+
+Subpath entries are also published: `@artos-commerce/ucp-client/ucp`,
+`/ap2`, `/checkout`, `/sui`, `/crypto`.
+
+## Security notes
+
+- **Money is integer minor units** everywhere; only the search-filter / display
+  edge speaks major units.
+- **Canonical JSON is byte-parity** with `artos-api` so a store's
+  `merchant_authorization` (and your minted mandates) verify. Don't fork it.
+- **Keep the buyer bearer server-side.** This package mints/forwards it from a
+  server; never expose it to a browser.
+
+## License
+
+MIT

package/dist/ap2/canonical-json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sorted-key canonical JSON serialization, byte-for-byte identical to the
+ * artos-api implementation (`src/modules/ucp/crypto/canonical-json.ts`) and the
+ * copies in artos-mcp-bridge / artos-my / artos-storefront. Used to recompute
+ * the bytes a store's `merchant_authorization` (and an AP2 mandate) is signed
+ * over, so a signature verifies across every repo.
+ *
+ * Caveat: this is NOT full RFC 8785 (JCS) — it does not apply JCS number
+ * canonicalization. Safe here because every monetary value is an integer
+ * (ISO-4217 minor units); we never emit floats. If that ever changes, this and
+ * every parity copy must change in lockstep.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/ap2/canonical-json.js

@@ -0,0 +1,28 @@
+/**
+ * Sorted-key canonical JSON serialization, byte-for-byte identical to the
+ * artos-api implementation (`src/modules/ucp/crypto/canonical-json.ts`) and the
+ * copies in artos-mcp-bridge / artos-my / artos-storefront. Used to recompute
+ * the bytes a store's `merchant_authorization` (and an AP2 mandate) is signed
+ * over, so a signature verifies across every repo.
+ *
+ * Caveat: this is NOT full RFC 8785 (JCS) — it does not apply JCS number
+ * canonicalization. Safe here because every monetary value is an integer
+ * (ISO-4217 minor units); we never emit floats. If that ever changes, this and
+ * every parity copy must change in lockstep.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(',')}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort();
+    return `{${keys
+        .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`)
+        .join(',')}}`;
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/ap2/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../src/ap2/canonical-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACnD,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;SACnC,IAAI,EAAE,CAAC;IACV,OAAO,IAAI,IAAI;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC"}

package/dist/ap2/index.d.ts

@@ -0,0 +1,3 @@
+export { canonicalJson } from './canonical-json.js';
+export { verifyDetachedJws, verifyMerchantAuthorization } from './verify.js';
+export { Ap2Signer, type CheckoutMandateClaims, type PaymentMandateClaims, } from './signer.js';

package/dist/ap2/index.js

@@ -0,0 +1,4 @@
+export { canonicalJson } from './canonical-json.js';
+export { verifyDetachedJws, verifyMerchantAuthorization } from './verify.js';
+export { Ap2Signer, } from './signer.js';
+//# sourceMappingURL=index.js.map

package/dist/ap2/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ap2/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EACL,SAAS,GAGV,MAAM,aAAa,CAAC"}

package/dist/ap2/signer.d.ts

@@ -0,0 +1,67 @@
+import type { Jwk } from '../config.js';
+/** Claims of an AP2 `checkout_mandate`: the full signed checkout body + binding. */
+export interface CheckoutMandateClaims {
+    /** The full get_checkout body (carrying the store's merchant_authorization). */
+    checkout: Record<string, unknown>;
+    /** The merchant (public store slug) this mandate is bound to. */
+    merchant: string;
+    jti: string;
+    exp: number;
+    /** Optional server-side allowance (PaymentMandate) id to enforce. */
+    payment_mandate_id?: string;
+}
+/** Claims of an AP2 `payment_mandate`: the authorized charge. */
+export interface PaymentMandateClaims {
+    payment: {
+        amount: number;
+        currency: string;
+        merchant: string;
+    };
+    jti: string;
+    exp: number;
+    payment_mandate_id?: string;
+}
+/** Common minting options shared by both mandate types. */
+interface MintOptions {
+    exp?: number;
+    jti?: string;
+    paymentMandateId?: string;
+}
+/**
+ * An AP2 mandate signer bound to one EC P-256 key. Mints compact ES256 JWS
+ * credentials the Artos verifier checks against the agent profile's published
+ * signing keys (whose `kid` must match `kid` here):
+ *
+ *  - {@link mintCheckoutMandate}: embeds the full signed checkout body (so the
+ *    verifier can re-check the store's nested `merchant_authorization`) and
+ *    binds the merchant slug, an expiry, and a unique `jti`.
+ *  - {@link mintPaymentMandate}: authorizes the charge amount/currency/merchant.
+ */
+export declare class Ap2Signer {
+    private readonly privateKey;
+    readonly kid: string;
+    constructor(privateJwk: Jwk, kid: string);
+    /**
+     * Mints a `checkout_mandate` embedding the full, freshly priced checkout body
+     * and bound to `merchant` (the store slug). `exp` defaults to 5 minutes out.
+     * The embedded body MUST be the verbatim get_checkout response so its nested
+     * `merchant_authorization` still verifies server-side.
+     */
+    mintCheckoutMandate(input: {
+        checkout: Record<string, unknown>;
+        merchant: string;
+    }, opts?: MintOptions): string;
+    /**
+     * Mints a `payment_mandate` authorizing a charge for `amount` (minor units),
+     * `currency`, and `merchant` (the store slug). The amount MUST equal the live
+     * priced total or the server rejects it as a scope mismatch.
+     */
+    mintPaymentMandate(input: {
+        amount: number;
+        currency: string;
+        merchant: string;
+    }, opts?: MintOptions): string;
+    /** Signs claims as a compact ES256 JWS (`header.payload.signature`). */
+    private sign;
+}
+export {};

package/dist/ap2/signer.js

@@ -0,0 +1,79 @@
+import { createPrivateKey, randomUUID, sign as cryptoSign, } from 'node:crypto';
+const DEFAULT_TTL_SECONDS = 300;
+function b64url(buf) {
+    return buf.toString('base64url');
+}
+/**
+ * An AP2 mandate signer bound to one EC P-256 key. Mints compact ES256 JWS
+ * credentials the Artos verifier checks against the agent profile's published
+ * signing keys (whose `kid` must match `kid` here):
+ *
+ *  - {@link mintCheckoutMandate}: embeds the full signed checkout body (so the
+ *    verifier can re-check the store's nested `merchant_authorization`) and
+ *    binds the merchant slug, an expiry, and a unique `jti`.
+ *  - {@link mintPaymentMandate}: authorizes the charge amount/currency/merchant.
+ */
+export class Ap2Signer {
+    privateKey;
+    kid;
+    constructor(privateJwk, kid) {
+        if (privateJwk.kty !== 'EC' || privateJwk.crv !== 'P-256') {
+            throw new Error('AP2 signer requires an EC P-256 key.');
+        }
+        this.privateKey = createPrivateKey({
+            key: privateJwk,
+            format: 'jwk',
+        });
+        this.kid = kid;
+    }
+    /**
+     * Mints a `checkout_mandate` embedding the full, freshly priced checkout body
+     * and bound to `merchant` (the store slug). `exp` defaults to 5 minutes out.
+     * The embedded body MUST be the verbatim get_checkout response so its nested
+     * `merchant_authorization` still verifies server-side.
+     */
+    mintCheckoutMandate(input, opts = {}) {
+        const claims = {
+            checkout: input.checkout,
+            merchant: input.merchant,
+            jti: opts.jti ?? `m_${randomUUID()}`,
+            exp: opts.exp ?? Math.floor(Date.now() / 1000) + DEFAULT_TTL_SECONDS,
+            ...(opts.paymentMandateId
+                ? { payment_mandate_id: opts.paymentMandateId }
+                : {}),
+        };
+        return this.sign(claims);
+    }
+    /**
+     * Mints a `payment_mandate` authorizing a charge for `amount` (minor units),
+     * `currency`, and `merchant` (the store slug). The amount MUST equal the live
+     * priced total or the server rejects it as a scope mismatch.
+     */
+    mintPaymentMandate(input, opts = {}) {
+        const claims = {
+            payment: {
+                amount: input.amount,
+                currency: input.currency,
+                merchant: input.merchant,
+            },
+            jti: opts.jti ?? `p_${randomUUID()}`,
+            exp: opts.exp ?? Math.floor(Date.now() / 1000) + DEFAULT_TTL_SECONDS,
+            ...(opts.paymentMandateId
+                ? { payment_mandate_id: opts.paymentMandateId }
+                : {}),
+        };
+        return this.sign(claims);
+    }
+    /** Signs claims as a compact ES256 JWS (`header.payload.signature`). */
+    sign(claims) {
+        const header = b64url(Buffer.from(JSON.stringify({ alg: 'ES256', kid: this.kid }), 'utf8'));
+        const payload = b64url(Buffer.from(JSON.stringify(claims), 'utf8'));
+        const signingInput = Buffer.from(`${header}.${payload}`, 'utf8');
+        const signature = cryptoSign('sha256', signingInput, {
+            key: this.privateKey,
+            dsaEncoding: 'ieee-p1363',
+        });
+        return `${header}.${payload}.${b64url(signature)}`;
+    }
+}
+//# sourceMappingURL=signer.js.map

package/dist/ap2/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/ap2/signer.ts"],"names":[],"mappings":"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"}

package/dist/ap2/verify.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Verifies a detached-content JWS (`base64url(header)..base64url(signature)`),
+ * the format artos-api uses for `merchant_authorization`. The signature covers
+ * `base64url(header).base64url(payload)` where `payload` is the supplied
+ * canonical byte string. The signing key is selected from `keys` by the header
+ * `kid` (or the first key when the header carries none). ES256 only; returns
+ * false on any failure rather than throwing.
+ */
+export declare function verifyDetachedJws(token: string, payload: string, keys: Record<string, unknown>[]): boolean;
+/**
+ * Verifies a checkout body's embedded `merchant_authorization` against the
+ * store's published signing keys. Recomputes the canonical bytes over the body
+ * with its `ap2` field removed (the field is excluded from the signing input).
+ */
+export declare function verifyMerchantAuthorization(body: Record<string, unknown>, keys: Record<string, unknown>[]): boolean;

package/dist/ap2/verify.js

@@ -0,0 +1,60 @@
+import { createPublicKey, verify as ecdsaVerify } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+/**
+ * Verifies a detached-content JWS (`base64url(header)..base64url(signature)`),
+ * the format artos-api uses for `merchant_authorization`. The signature covers
+ * `base64url(header).base64url(payload)` where `payload` is the supplied
+ * canonical byte string. The signing key is selected from `keys` by the header
+ * `kid` (or the first key when the header carries none). ES256 only; returns
+ * false on any failure rather than throwing.
+ */
+export function verifyDetachedJws(token, payload, keys) {
+    const parts = token.split('.');
+    // Detached serialization has an empty middle segment (the omitted payload).
+    if (parts.length !== 3 || !parts[0] || parts[1] !== '' || !parts[2]) {
+        return false;
+    }
+    let header;
+    try {
+        header = JSON.parse(Buffer.from(parts[0], 'base64url').toString('utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (!header || header.alg !== 'ES256') {
+        return false;
+    }
+    const kid = typeof header.kid === 'string' ? header.kid : undefined;
+    const jwk = kid
+        ? keys.find((k) => k.kid === kid)
+        : keys[0];
+    if (!jwk) {
+        return false;
+    }
+    const encodedPayload = Buffer.from(payload, 'utf8').toString('base64url');
+    const signingInput = Buffer.from(`${parts[0]}.${encodedPayload}`, 'utf8');
+    const signature = Buffer.from(parts[2], 'base64url');
+    try {
+        const key = createPublicKey({ key: jwk, format: 'jwk' });
+        return ecdsaVerify('sha256', signingInput, { key, dsaEncoding: 'ieee-p1363' }, signature);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Verifies a checkout body's embedded `merchant_authorization` against the
+ * store's published signing keys. Recomputes the canonical bytes over the body
+ * with its `ap2` field removed (the field is excluded from the signing input).
+ */
+export function verifyMerchantAuthorization(body, keys) {
+    const ap2 = body.ap2;
+    const token = ap2?.merchant_authorization;
+    if (!token) {
+        return false;
+    }
+    const bodyMinusAp2 = { ...body };
+    delete bodyMinusAp2.ap2;
+    return verifyDetachedJws(token, canonicalJson(bodyMinusAp2), keys);
+}
+//# sourceMappingURL=verify.js.map

package/dist/ap2/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/ap2/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAa,EACb,OAAe,EACf,IAA+B;IAE/B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,4EAA4E;IAC5E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CACjB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CACzB,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,MAAM,GAAG,GAAG,GAAG;QACb,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAsB,CAAC,GAAG,KAAK,GAAG,CAAC;QACvD,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACZ,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC1E,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,cAAc,EAAE,EAAE,MAAM,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,eAAe,CAAC,EAAE,GAAG,EAAE,GAAY,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAClE,OAAO,WAAW,CAChB,QAAQ,EACR,YAAY,EACZ,EAAE,GAAG,EAAE,WAAW,EAAE,YAAY,EAAE,EAClC,SAAS,CACV,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAA6B,EAC7B,IAA+B;IAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAsD,CAAC;IACxE,MAAM,KAAK,GAAG,GAAG,EAAE,sBAAsB,CAAC;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;IACjC,OAAO,YAAY,CAAC,GAAG,CAAC;IACxB,OAAO,iBAAiB,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,CAAC;AACrE,CAAC"}

package/dist/checkout/handlers.d.ts

@@ -0,0 +1,76 @@
+import { type UcpResponse } from '../ucp/client.js';
+import { type SearchFilters } from './money.js';
+import type { CheckoutDeps, CheckoutLineItem, CheckoutOutcome, ConfirmPurchaseInput } from './types.js';
+/**
+ * Pure checkout orchestration over an injected {@link CheckoutDeps}. Read methods
+ * return the raw UCP envelope (inspect with `isUcpError`); `confirmPurchase`
+ * returns a structured {@link CheckoutOutcome}. No presentation, no MCP — a host
+ * (e.g. the Artos MCP bridge) maps the result to text/widgets.
+ */
+export declare function createCheckoutHandlers(deps: CheckoutDeps): {
+    /** Cross-store catalog search (price filters in MAJOR units). */
+    searchProducts(args: {
+        query?: string;
+        filters?: SearchFilters;
+        sort?: string;
+        pagination?: Record<string, unknown>;
+        context?: Record<string, unknown>;
+    }): Promise<UcpResponse>;
+    /** Resolve products by id/handle/SKU/barcode (global). */
+    lookupProducts(args: {
+        ids: unknown;
+        context?: Record<string, unknown>;
+    }): Promise<UcpResponse>;
+    /** Fetch a single product by id (global, no store slug needed). */
+    getProductGlobal(args: {
+        id: string;
+        selected?: unknown;
+        context?: Record<string, unknown>;
+    }): Promise<UcpResponse>;
+    /** Fetch a single product at a specific store. */
+    viewProduct(args: {
+        storeSlug: string;
+        id: string;
+    }): Promise<UcpResponse>;
+    createCart(args: {
+        storeSlug: string;
+        items: CheckoutLineItem[];
+    }): Promise<UcpResponse>;
+    updateCart(args: {
+        storeSlug: string;
+        id: string;
+        items: CheckoutLineItem[];
+    }): Promise<UcpResponse>;
+    viewCart(args: {
+        storeSlug: string;
+        id: string;
+    }): Promise<UcpResponse>;
+    createCheckout(args: {
+        storeSlug: string;
+        cartId?: string;
+        items?: CheckoutLineItem[];
+        buyer?: Record<string, unknown>;
+        shippingAddress?: Record<string, unknown>;
+    }): Promise<UcpResponse>;
+    updateCheckout(args: {
+        storeSlug: string;
+        id: string;
+        buyer?: Record<string, unknown>;
+        shippingAddress?: Record<string, unknown>;
+        shippingMethodId?: string;
+        discounts?: unknown;
+    }): Promise<UcpResponse>;
+    getOrder(args: {
+        storeSlug: string;
+        id: string;
+    }): Promise<UcpResponse>;
+    /**
+     * Re-prices the checkout, verifies the store-signed terms, mints the AP2
+     * mandate(s), and places the order on the card, crypto, or $0 rail. Returns a
+     * {@link CheckoutOutcome} for every branch (no exceptions for business
+     * outcomes; transport failures still throw {@link UcpClientError}).
+     */
+    confirmPurchase(input: ConfirmPurchaseInput): Promise<CheckoutOutcome>;
+};
+/** The handler object returned by {@link createCheckoutHandlers}. */
+export type CheckoutHandlers = ReturnType<typeof createCheckoutHandlers>;