@artos-commerce/ucp-client 0.1.0

package/dist/checkout/handlers.js

@@ -0,0 +1,288 @@
+import { isUcpError, messageOf, } from '../ucp/client.js';
+import { verifyMerchantAuthorization } from '../ap2/verify.js';
+import { availableRails, currencyOf, grandTotal, resolveRail, asAllowanceId, } from './rails.js';
+import { normalizeSearchFilters } from './money.js';
+/**
+ * Placeholder PTB sender forwarded on a buyer-bound crypto prepare call. The API
+ * ignores it and resolves the real sender from the buyer's authorization; it
+ * exists only to satisfy the required `buyer_address` field.
+ */
+const RESOLVED_SERVER_SIDE = `0x${'0'.repeat(64)}`;
+/**
+ * UCP eligibility claim for Artos cross-store coupons. Attached to the checkout
+ * context so the server resolves + applies any eligible coupon during the crypto
+ * prepare step (coupons redeem on-chain, crypto rail only).
+ */
+const ARTOS_COUPON_CLAIM = 'sh.artos.coupon';
+/** Builds an error outcome. */
+function err(code, message, checkout) {
+    return { status: 'error', code, message, checkout };
+}
+/** True when a UCP error envelope names a recoverable payment-selection gate. */
+function isPaymentSelection(body) {
+    return (body.messages ?? []).some((m) => m.code === 'payment_selection_required');
+}
+function lineItems(items) {
+    return items.map((i) => ({
+        item: { id: i.id },
+        quantity: i.quantity ?? 1,
+    }));
+}
+/**
+ * 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 function createCheckoutHandlers(deps) {
+    const { client, signer, crypto } = deps;
+    return {
+        /** Cross-store catalog search (price filters in MAJOR units). */
+        async searchProducts(args) {
+            return client.globalSearch({
+                query: args.query,
+                filters: normalizeSearchFilters(args.filters),
+                sort: args.sort,
+                pagination: args.pagination,
+                context: args.context,
+            });
+        },
+        /** Resolve products by id/handle/SKU/barcode (global). */
+        async lookupProducts(args) {
+            return client.callGlobalTool('lookup_catalog', {
+                ids: args.ids,
+                context: args.context,
+            });
+        },
+        /** Fetch a single product by id (global, no store slug needed). */
+        async getProductGlobal(args) {
+            return client.callGlobalTool('get_product', {
+                id: args.id,
+                selected: args.selected,
+                context: args.context,
+            });
+        },
+        /** Fetch a single product at a specific store. */
+        async viewProduct(args) {
+            return client.callStoreTool(args.storeSlug, 'get_product', {
+                catalog: { id: args.id },
+            });
+        },
+        async createCart(args) {
+            return client.callStoreTool(args.storeSlug, 'create_cart', { cart: { line_items: lineItems(args.items) } }, { idempotent: true });
+        },
+        async updateCart(args) {
+            return client.callStoreTool(args.storeSlug, 'update_cart', { id: args.id, cart: { line_items: lineItems(args.items) } }, { idempotent: true });
+        },
+        async viewCart(args) {
+            return client.callStoreTool(args.storeSlug, 'get_cart', { id: args.id });
+        },
+        async createCheckout(args) {
+            const checkout = {};
+            if (args.cartId)
+                checkout.cart_id = args.cartId;
+            if (args.items)
+                checkout.line_items = lineItems(args.items);
+            if (args.buyer)
+                checkout.buyer = args.buyer;
+            if (args.shippingAddress)
+                checkout.shipping_address = args.shippingAddress;
+            return client.callStoreTool(args.storeSlug, 'create_checkout', { checkout }, { idempotent: true });
+        },
+        async updateCheckout(args) {
+            const checkout = {};
+            if (args.buyer)
+                checkout.buyer = args.buyer;
+            if (args.shippingAddress)
+                checkout.shipping_address = args.shippingAddress;
+            if (args.shippingMethodId)
+                checkout.shipping_method_id = args.shippingMethodId;
+            if (args.discounts)
+                checkout.discounts = args.discounts;
+            return client.callStoreTool(args.storeSlug, 'update_checkout', { id: args.id, checkout }, { idempotent: true });
+        },
+        async getOrder(args) {
+            return client.callStoreTool(args.storeSlug, 'get_order', { id: args.id });
+        },
+        /**
+         * 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}).
+         */
+        async confirmPurchase(input) {
+            const slug = input.storeSlug;
+            const checkoutId = input.checkoutId;
+            const paymentMandateId = asAllowanceId(input.paymentMandateId);
+            const paymentMethod = input.paymentMethod;
+            // Re-price immediately before minting so the mandate total matches the
+            // server's quote (else completion fails with mandate_scope_mismatch).
+            let fresh = await client.callStoreTool(slug, 'get_checkout', {
+                id: checkoutId,
+            });
+            if (isUcpError(fresh)) {
+                return err('store_error', messageOf(fresh) ?? 'Checkout error.', fresh);
+            }
+            const signingKeys = await client.fetchStoreProfile(slug);
+            // Completes the checkout and maps the result. Shared by every rail.
+            const finish = async (checkout, auth) => {
+                const done = await client.callStoreTool(slug, 'complete_checkout', { id: checkoutId, checkout }, { idempotent: true, auth });
+                if (isUcpError(done)) {
+                    if (isPaymentSelection(done)) {
+                        return {
+                            status: 'payment_selection_required',
+                            rails: availableRails(fresh),
+                            checkout: done,
+                        };
+                    }
+                    return err('store_error', messageOf(done) ?? 'The store returned an error.', done);
+                }
+                const continueUrl = done.continue_url;
+                if (done.status === 'requires_escalation' &&
+                    continueUrl) {
+                    return {
+                        status: 'escalation_required',
+                        continueUrl,
+                        checkout: done,
+                    };
+                }
+                return { status: 'completed', checkout: done };
+            };
+            const rail = resolveRail(fresh, paymentMethod);
+            // Free order ($0 total): no rail to run, settle directly with no payment
+            // instrument. Rail-independent (no crypto config or buyer sign-in needed)
+            // and sidesteps the crypto prepare step, which rejects a $0 total.
+            if (grandTotal(fresh) === 0) {
+                if (!verifyMerchantAuthorization(fresh, signingKeys)) {
+                    return err('merchant_authorization_invalid', 'The store did not return a valid merchant_authorization for these terms; aborting.');
+                }
+                const completionAuth = client.hasBuyerToken()
+                    ? 'buyer'
+                    : 'platform';
+                return finish({
+                    ap2: {
+                        checkout_mandate: signer.mintCheckoutMandate({ checkout: fresh, merchant: slug }, { paymentMandateId }),
+                    },
+                }, completionAuth);
+            }
+            // Crypto rail: the buyer pays from their own Sui wallet via the agent's
+            // alias key. An eligible Artos coupon is resolved + applied server-side
+            // during prepare_checkout_payment, which reduces the total and re-signs the
+            // terms. So for crypto we MUST attach the coupon eligibility claim, prepare,
+            // and RE-FETCH the priced checkout BEFORE minting — otherwise the mandate is
+            // bound to the pre-coupon total and completion fails (mandate_scope_mismatch).
+            if (rail?.kind === 'crypto') {
+                if (!crypto) {
+                    return err('crypto_not_configured', 'This client is not configured to pay with crypto. Provide the agent Sui key, or choose the card rail.');
+                }
+                if (!client.hasBuyerToken()) {
+                    return err('authentication_required', 'Paying with crypto requires the buyer to sign in so their wallet and authorization can be resolved.');
+                }
+                // Opt into on-chain coupon redemption: attach the `sh.artos.coupon`
+                // eligibility claim (merged with any present) so the server applies an
+                // eligible coupon during prepare. Harmless when the buyer has none.
+                const existingClaims = fresh.context
+                    ?.eligibility ?? [];
+                if (!existingClaims.includes(ARTOS_COUPON_CLAIM)) {
+                    const updated = await client.callStoreTool(slug, 'update_checkout', {
+                        id: checkoutId,
+                        checkout: {
+                            context: {
+                                eligibility: [...existingClaims, ARTOS_COUPON_CLAIM],
+                            },
+                        },
+                    }, { idempotent: true });
+                    if (isUcpError(updated)) {
+                        return err('store_error', messageOf(updated) ?? 'The store returned an error.', updated);
+                    }
+                }
+                const prepared = await client.callStoreTool(slug, 'prepare_checkout_payment', {
+                    id: checkoutId,
+                    payment_intent: {
+                        buyer_address: RESOLVED_SERVER_SIDE,
+                        input_coin_type: crypto.inputCoinType,
+                    },
+                }, { idempotent: true, auth: 'buyer' });
+                if (isUcpError(prepared)) {
+                    return err('store_error', messageOf(prepared) ?? 'The store returned an error.', prepared);
+                }
+                const unsignedTx = prepared.payment_intent?.unsigned_tx;
+                if (!unsignedTx) {
+                    return err('payment_intent_invalid', 'The store did not return an unsigned payment transaction; aborting.');
+                }
+                // Re-fetch the priced checkout: prepare may have applied a coupon,
+                // changing the total and the store's merchant_authorization. Verify and
+                // mint the mandate over THESE final terms.
+                fresh = await client.callStoreTool(slug, 'get_checkout', {
+                    id: checkoutId,
+                });
+                if (isUcpError(fresh)) {
+                    return err('store_error', messageOf(fresh) ?? 'Checkout error.', fresh);
+                }
+                if (!verifyMerchantAuthorization(fresh, signingKeys)) {
+                    return err('merchant_authorization_invalid', 'The store did not return a valid merchant_authorization for these terms; aborting.');
+                }
+                const total = grandTotal(fresh);
+                const currency = currencyOf(fresh);
+                if (crypto.maxSpendAmount !== undefined &&
+                    total > crypto.maxSpendAmount) {
+                    return err('spend_cap_exceeded', `Order total ${total} ${currency} exceeds the agent spending cap of ${crypto.maxSpendAmount}; refusing to pay.`);
+                }
+                // Embed the verbatim (re-fetched) checkout body so the server can
+                // re-check its nested merchant_authorization; bind to the store slug.
+                const ap2 = {
+                    checkout_mandate: signer.mintCheckoutMandate({ checkout: fresh, merchant: slug }, { paymentMandateId }),
+                    payment_mandate: signer.mintPaymentMandate({ amount: total, currency, merchant: slug }, { paymentMandateId }),
+                };
+                let digest;
+                try {
+                    digest = await crypto.sui.signAndSubmit(unsignedTx);
+                }
+                catch (e) {
+                    return err('payment_execution_failed', e instanceof Error
+                        ? e.message
+                        : 'Signing the payment transaction failed.');
+                }
+                // No inline intent_mandate: the API loads the buyer's STORED standing
+                // authorization (and enforces its caps) from the forwarded bearer.
+                return finish({
+                    ap2,
+                    payment: {
+                        instruments: [
+                            {
+                                handler_id: rail.handlerId,
+                                type: 'crypto',
+                                selected: true,
+                                credential: { token: digest },
+                            },
+                        ],
+                    },
+                }, 'buyer');
+            }
+            // Card / hosted rail (or a multi-rail store with no choice yet): no coupon
+            // redemption, so verify and mint the mandate over the current terms.
+            if (!verifyMerchantAuthorization(fresh, signingKeys)) {
+                return err('merchant_authorization_invalid', 'The store did not return a valid merchant_authorization for these terms; aborting.');
+            }
+            const checkout = {
+                ap2: {
+                    checkout_mandate: signer.mintCheckoutMandate({ checkout: fresh, merchant: slug }, { paymentMandateId }),
+                },
+            };
+            if (rail) {
+                // Forward the buyer's chosen (or sole) rail; the API routes by
+                // handler_id. With no rail (multi-rail store, no choice) we send no
+                // instrument and the API returns a recoverable payment_selection_required
+                // (surfaced as that outcome) so the caller asks the buyer.
+                checkout.payment = {
+                    instruments: [{ handler_id: rail.handlerId, selected: true }],
+                };
+            }
+            const completionAuth = client.hasBuyerToken()
+                ? 'buyer'
+                : 'platform';
+            return finish(checkout, completionAuth);
+        },
+    };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/checkout/handlers.js.map

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

package/dist/checkout/index.d.ts

@@ -0,0 +1,4 @@
+export { createCheckoutHandlers, type CheckoutHandlers } from './handlers.js';
+export { toMinorUnits, normalizeSearchFilters, type SearchFilters, } from './money.js';
+export { availableRails, resolveRail, railKind, grandTotal, currencyOf, asAllowanceId, type ResolvedRail, } from './rails.js';
+export type { CheckoutDeps, CheckoutLineItem, ConfirmPurchaseInput, CheckoutErrorCode, CheckoutOutcome, } from './types.js';

package/dist/checkout/index.js

@@ -0,0 +1,4 @@
+export { createCheckoutHandlers } from './handlers.js';
+export { toMinorUnits, normalizeSearchFilters, } from './money.js';
+export { availableRails, resolveRail, railKind, grandTotal, currencyOf, asAllowanceId, } from './rails.js';
+//# sourceMappingURL=index.js.map

package/dist/checkout/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkout/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAyB,MAAM,eAAe,CAAC;AAC9E,OAAO,EACL,YAAY,EACZ,sBAAsB,GAEvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GAEd,MAAM,YAAY,CAAC"}

package/dist/checkout/money.d.ts

@@ -0,0 +1,24 @@
+/** Converts a major-unit amount (dollars) to integer minor units (cents). */
+export declare function toMinorUnits(amount: number, currency: string | undefined): number;
+/** Model-facing search filters (price in MAJOR units, with optional currency). */
+export interface SearchFilters {
+    categories?: string[];
+    price?: {
+        min?: number;
+        max?: number;
+        currency?: string;
+    };
+    tags?: string[];
+    attributes?: Array<{
+        name: string;
+        value: string;
+    }>;
+    seller?: string;
+    available?: boolean;
+}
+/**
+ * Translates the caller-facing filters to the UCP wire shape: price is given in
+ * major units with an optional `currency`, which we convert to the integer
+ * minor units the API expects (the API has no notion of major units).
+ */
+export declare function normalizeSearchFilters(filters: SearchFilters | undefined): Record<string, unknown> | undefined;

package/dist/checkout/money.js

@@ -0,0 +1,41 @@
+/**
+ * ISO 4217 minor-unit exponents for the currencies that don't use 2 decimals.
+ * Used to turn a caller's major-unit price (dollars) into the minor units
+ * (cents) the API expects. Anything not listed defaults to 2 decimals.
+ */
+const CURRENCY_MINOR_UNITS = {
+    JPY: 0,
+    KRW: 0,
+    VND: 0,
+    CLP: 0,
+    ISK: 0,
+    BHD: 3,
+    KWD: 3,
+    OMR: 3,
+    TND: 3,
+};
+/** Converts a major-unit amount (dollars) to integer minor units (cents). */
+export function toMinorUnits(amount, currency) {
+    const exp = CURRENCY_MINOR_UNITS[(currency ?? 'USD').toUpperCase()] ?? 2;
+    return Math.round(amount * 10 ** exp);
+}
+/**
+ * Translates the caller-facing filters to the UCP wire shape: price is given in
+ * major units with an optional `currency`, which we convert to the integer
+ * minor units the API expects (the API has no notion of major units).
+ */
+export function normalizeSearchFilters(filters) {
+    if (!filters)
+        return undefined;
+    const { price, ...rest } = filters;
+    if (!price || (price.min == null && price.max == null)) {
+        return { ...rest };
+    }
+    const converted = {};
+    if (price.min != null)
+        converted.min = toMinorUnits(price.min, price.currency);
+    if (price.max != null)
+        converted.max = toMinorUnits(price.max, price.currency);
+    return { ...rest, price: converted };
+}
+//# sourceMappingURL=money.js.map

package/dist/checkout/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../../src/checkout/money.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,oBAAoB,GAA2B;IACnD,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;CACP,CAAC;AAEF,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,QAA4B;IAE5B,MAAM,GAAG,GAAG,oBAAoB,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC;AACxC,CAAC;AAYD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAkC;IAElC,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACnC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;IACrB,CAAC;IACD,MAAM,SAAS,GAAmC,EAAE,CAAC;IACrD,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI;QACnB,SAAS,CAAC,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1D,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI;QACnB,SAAS,CAAC,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1D,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AACvC,CAAC"}

package/dist/checkout/rails.d.ts

@@ -0,0 +1,36 @@
+import type { UcpResponse } from '../ucp/client.js';
+/** The payment rail a checkout settles on. */
+export interface ResolvedRail {
+    handlerId: string;
+    kind: 'card' | 'crypto';
+}
+/** A rail's kind from its handler id (`artos.crypto` -> crypto, else card). */
+export declare function railKind(handlerId: string): 'card' | 'crypto';
+/** Every payment rail the store advertises on a (re-priced) checkout body. */
+export declare function availableRails(fresh: UcpResponse): ResolvedRail[];
+/**
+ * Resolves the EFFECTIVE rail for auth + instrument routing from the buyer's
+ * choice or the store's advertised handlers, or `undefined` to defer to the API.
+ *
+ * The API drives multi-rail selection: with no selected instrument a >1-rail
+ * store returns a recoverable `payment_selection_required`. We only resolve a
+ * rail when the buyer chose one (`paymentMethod`) or the store advertises
+ * exactly one — the latter so a sole CRYPTO rail is completed with the buyer
+ * bearer instead of the platform key (which would trip the API's intent-mandate
+ * gate). Otherwise return `undefined`: send no instrument and let the API ask.
+ * The choice is passed through verbatim (no local allowlist) so the API
+ * validates the handler id.
+ */
+export declare function resolveRail(fresh: UcpResponse, paymentMethod: string | undefined): ResolvedRail | undefined;
+/** The `total` line amount from a checkout/order body (0 when absent). */
+export declare function grandTotal(body: UcpResponse): number;
+/** The body currency (top-level, else first total's currency, else USD). */
+export declare function currencyOf(body: UcpResponse): string;
+/**
+ * A `payment_mandate_id` is a server-side allowance (PaymentMandate) UUID, NOT a
+ * payment rail. Callers routinely confuse it with a handler id (e.g.
+ * `sh.artos.card`); embedding that in the AP2 mandate makes the API reject the
+ * order (`mandate_scope_mismatch` from a uuid-cast failure). Drop anything that
+ * isn't a UUID so the chosen rail proceeds unconstrained.
+ */
+export declare function asAllowanceId(value: unknown): string | undefined;

package/dist/checkout/rails.js

@@ -0,0 +1,62 @@
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A rail's kind from its handler id (`artos.crypto` -> crypto, else card). */
+export function railKind(handlerId) {
+    return handlerId.includes('crypto') ? 'crypto' : 'card';
+}
+/** Every payment rail the store advertises on a (re-priced) checkout body. */
+export function availableRails(fresh) {
+    const handlers = fresh.ucp?.payment_handlers ?? {};
+    const rails = [];
+    for (const entries of Object.values(handlers)) {
+        for (const entry of entries ?? []) {
+            if (entry?.id) {
+                rails.push({ handlerId: entry.id, kind: railKind(entry.id) });
+            }
+        }
+    }
+    return rails;
+}
+/**
+ * Resolves the EFFECTIVE rail for auth + instrument routing from the buyer's
+ * choice or the store's advertised handlers, or `undefined` to defer to the API.
+ *
+ * The API drives multi-rail selection: with no selected instrument a >1-rail
+ * store returns a recoverable `payment_selection_required`. We only resolve a
+ * rail when the buyer chose one (`paymentMethod`) or the store advertises
+ * exactly one — the latter so a sole CRYPTO rail is completed with the buyer
+ * bearer instead of the platform key (which would trip the API's intent-mandate
+ * gate). Otherwise return `undefined`: send no instrument and let the API ask.
+ * The choice is passed through verbatim (no local allowlist) so the API
+ * validates the handler id.
+ */
+export function resolveRail(fresh, paymentMethod) {
+    if (paymentMethod) {
+        return { handlerId: paymentMethod, kind: railKind(paymentMethod) };
+    }
+    const rails = availableRails(fresh);
+    return rails.length === 1 ? rails[0] : undefined;
+}
+/** The `total` line amount from a checkout/order body (0 when absent). */
+export function grandTotal(body) {
+    const totals = body.totals ?? [];
+    return totals.find((t) => t.type === 'total')?.amount ?? 0;
+}
+/** The body currency (top-level, else first total's currency, else USD). */
+export function currencyOf(body) {
+    if (typeof body.currency === 'string')
+        return body.currency;
+    const totals = body.totals ?? [];
+    return totals.find((t) => t.currency)?.currency ?? 'USD';
+}
+/**
+ * A `payment_mandate_id` is a server-side allowance (PaymentMandate) UUID, NOT a
+ * payment rail. Callers routinely confuse it with a handler id (e.g.
+ * `sh.artos.card`); embedding that in the AP2 mandate makes the API reject the
+ * order (`mandate_scope_mismatch` from a uuid-cast failure). Drop anything that
+ * isn't a UUID so the chosen rail proceeds unconstrained.
+ */
+export function asAllowanceId(value) {
+    const s = typeof value === 'string' ? value : '';
+    return UUID_RE.test(s) ? s : undefined;
+}
+//# sourceMappingURL=rails.js.map

package/dist/checkout/rails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rails.js","sourceRoot":"","sources":["../../src/checkout/rails.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,GACX,iEAAiE,CAAC;AAEpE,+EAA+E;AAC/E,MAAM,UAAU,QAAQ,CAAC,SAAiB;IACxC,OAAO,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;AAC1D,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,KAAkB;IAC/C,MAAM,QAAQ,GACX,KAAK,CAAC,GAAG,EAAE,gBACyC,IAAI,EAAE,CAAC;IAC9D,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;YAClC,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;gBACd,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,KAAkB,EAClB,aAAiC;IAEjC,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;IACrE,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACnD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,UAAU,CAAC,IAAiB;IAC1C,MAAM,MAAM,GACT,IAAI,CAAC,MAAoD,IAAI,EAAE,CAAC;IACnE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAC,IAAiB;IAC1C,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;IAC5D,MAAM,MAAM,GAAI,IAAI,CAAC,MAAuC,IAAI,EAAE,CAAC;IACnE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,QAAQ,IAAI,KAAK,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzC,CAAC"}

package/dist/checkout/types.d.ts

@@ -0,0 +1,56 @@
+import type { Ap2Signer } from '../ap2/signer.js';
+import type { CryptoDeps } from '../crypto/deps.js';
+import type { UcpClient, UcpResponse } from '../ucp/client.js';
+import type { ResolvedRail } from './rails.js';
+/** Dependencies the checkout handlers operate over (all injectable for tests). */
+export interface CheckoutDeps {
+    client: UcpClient;
+    signer: Ap2Signer;
+    /** Present only when the crypto settlement rail is fully configured. */
+    crypto?: CryptoDeps;
+}
+/** A line item in major-unit, friendly shape (`{ id, quantity }`). */
+export interface CheckoutLineItem {
+    id: string;
+    quantity?: number;
+}
+export interface ConfirmPurchaseInput {
+    storeSlug: string;
+    checkoutId: string;
+    /**
+     * The chosen rail's handler id (e.g. `artos.card` / `artos.crypto`). Omit on a
+     * multi-rail store to receive a `payment_selection_required` outcome.
+     */
+    paymentMethod?: string;
+    /** Optional server-side allowance (PaymentMandate) UUID to bind the mandate to. */
+    paymentMandateId?: string;
+}
+/**
+ * Why a `confirmPurchase` could not place the order. These map 1:1 to the inline
+ * UCP error envelopes the hosted bridge builds today; a host (e.g. the bridge)
+ * turns each into agent-facing text.
+ */
+export type CheckoutErrorCode = 'crypto_not_configured' | 'authentication_required' | 'merchant_authorization_invalid' | 'payment_intent_invalid' | 'spend_cap_exceeded' | 'payment_execution_failed'
+/** A UCP business-error envelope returned by the store, passed through. */
+ | 'store_error';
+/**
+ * The structured result of a `confirmPurchase`. The SDK never renders text;
+ * callers branch on `status` and present as they like.
+ */
+export type CheckoutOutcome = {
+    status: 'completed';
+    checkout: UcpResponse;
+} | {
+    status: 'escalation_required';
+    continueUrl: string;
+    checkout: UcpResponse;
+} | {
+    status: 'payment_selection_required';
+    rails: ResolvedRail[];
+    checkout: UcpResponse;
+} | {
+    status: 'error';
+    code: CheckoutErrorCode;
+    message: string;
+    checkout?: UcpResponse;
+};

package/dist/checkout/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/checkout/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/checkout/types.ts"],"names":[],"mappings":""}

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * UCP spec version the Artos API implements. Sent in the `UCP-Agent` header and
+ * the `meta["ucp-agent"]` envelope; must match the server.
+ */
+export declare const UCP_VERSION = "2026-04-08";
+/** A JSON Web Key. The DOM `JsonWebKey` lacks `kid`, so widen it here. */
+export type Jwk = JsonWebKey & {
+    kid?: string;
+};
+/** Sui networks the agent can settle crypto payments on. */
+export type SuiNetwork = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+/**
+ * The minimum configuration the {@link import('./ucp/client.js').UcpClient}
+ * needs: where the Artos API lives, the platform (cross-store) API key, and the
+ * HTTPS URL of the agent's published UCP profile (its `signing_keys` + caps).
+ */
+export interface UcpClientConfig {
+    /** Base URL of the Artos API, e.g. `https://api.artos.sh`. No trailing slash. */
+    artosBaseUrl: string;
+    /** Platform (cross-store) UCP API key: `<clientId>.<secret>`. */
+    platformApiKey: string;
+    /** HTTPS URL of the agent's published UCP profile (signing_keys + caps). */
+    platformProfileUrl: string;
+}
+/**
+ * The AP2 signing configuration: the agent's EC P-256 private key (JWK) and the
+ * key id, which MUST match the public JWK `kid` published in the agent profile.
+ */
+export interface AgentAp2Config {
+    agentPrivateJwk: Jwk;
+    agentKid: string;
+}
+/**
+ * Crypto-rail settlement configuration. Optional: absent => card-only. The Sui
+ * key signs payment PTBs as the buyer's on-chain alias; the buyer the spend is
+ * drawn from (and the caps) are resolved server-side from their authorization.
+ */
+export interface AgentCryptoConfig {
+    /** Agent Sui Ed25519 secret key (`suiprivkey1...` bech32). */
+    agentSuiPrivateKey?: string;
+    /** Sui network for crypto settlement. */
+    suiNetwork: SuiNetwork;
+    /** Optional client-side hard cap (ISO-4217 minor units) refused before signing. */
+    agentMaxSpendAmount?: number;
+}
+/** Strips trailing slashes so URL joins never produce a double slash. */
+export declare function normalizeBaseUrl(url: string): string;
+/**
+ * Validates that a JWK is an EC P-256 PRIVATE key (carries `d`) suitable for
+ * minting AP2 mandates. Throws with an actionable message otherwise.
+ */
+export declare function assertEcP256PrivateJwk(jwk: Jwk): void;
+/** Narrows an arbitrary string to a known {@link SuiNetwork}, defaulting to mainnet. */
+export declare function parseSuiNetwork(value: string | undefined): SuiNetwork;