@artos-commerce/ucp-client 0.1.0

package/dist/config.js

@@ -0,0 +1,41 @@
+/**
+ * UCP spec version the Artos API implements. Sent in the `UCP-Agent` header and
+ * the `meta["ucp-agent"]` envelope; must match the server.
+ */
+export const UCP_VERSION = '2026-04-08';
+const SUI_NETWORKS = [
+    'mainnet',
+    'testnet',
+    'devnet',
+    'localnet',
+];
+/** Strips trailing slashes so URL joins never produce a double slash. */
+export function normalizeBaseUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        throw new Error('artosBaseUrl must be a non-empty URL.');
+    }
+    return trimmed.replace(/\/+$/, '');
+}
+/**
+ * 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 function assertEcP256PrivateJwk(jwk) {
+    if (jwk.kty !== 'EC' || jwk.crv !== 'P-256') {
+        throw new Error('agentPrivateJwk must be an EC P-256 key.');
+    }
+    if (!jwk.d) {
+        throw new Error('agentPrivateJwk must include the private component `d`.');
+    }
+}
+/** Narrows an arbitrary string to a known {@link SuiNetwork}, defaulting to mainnet. */
+export function parseSuiNetwork(value) {
+    if (!value)
+        return 'mainnet';
+    if (!SUI_NETWORKS.includes(value)) {
+        throw new Error(`suiNetwork must be one of: ${SUI_NETWORKS.join(', ')}.`);
+    }
+    return value;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AA6CxC,MAAM,YAAY,GAA0B;IAC1C,SAAS;IACT,SAAS;IACT,QAAQ;IACR,UAAU;CACX,CAAC;AAEF,yEAAyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAQ;IAC7C,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,KAAyB;IACvD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAmB,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,8BAA8B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,KAAmB,CAAC;AAC7B,CAAC"}

package/dist/crypto/deps.d.ts

@@ -0,0 +1,27 @@
+import type { AgentCryptoConfig } from '../config.js';
+import { SuiSigner } from '../sui/signer.js';
+/**
+ * Everything the checkout layer needs to settle on the crypto rail. Present only
+ * when the agent Sui key is configured; absent => the card rail only. The buyer
+ * the spend is drawn from — and the signed limits — are resolved server-side per
+ * request from the session's OAuth bearer, so no per-buyer material lives here.
+ */
+export interface CryptoDeps {
+    /** Signs + submits the server-built payment PTB as the buyer's alias. */
+    sui: SuiSigner;
+    /** Input coin the agent pays with (swapped to USDC server-side). */
+    inputCoinType: string;
+    /** Optional client-side hard cap (minor units) refused before signing. */
+    maxSpendAmount?: number;
+}
+/**
+ * Assembles the crypto settlement dependencies from config, or returns
+ * `undefined` when the crypto rail is intentionally unconfigured (card-only).
+ *
+ * The agent holds a single Sui key; each buyer aliases that address to their own
+ * wallet and signs a standing authorization (in My Artos), so the buyer the
+ * spend is drawn from — and the caps — are resolved server-side per request from
+ * the buyer's OAuth bearer. The crypto rail is therefore enabled by the agent
+ * key alone.
+ */
+export declare function resolveCryptoDeps(cfg: AgentCryptoConfig): CryptoDeps | undefined;

package/dist/crypto/deps.js

@@ -0,0 +1,23 @@
+import { SuiSigner } from '../sui/signer.js';
+/** Input coin the agent pays with by default (swapped to USDC server-side). */
+const DEFAULT_INPUT_COIN_TYPE = '0x2::sui::SUI';
+/**
+ * Assembles the crypto settlement dependencies from config, or returns
+ * `undefined` when the crypto rail is intentionally unconfigured (card-only).
+ *
+ * The agent holds a single Sui key; each buyer aliases that address to their own
+ * wallet and signs a standing authorization (in My Artos), so the buyer the
+ * spend is drawn from — and the caps — are resolved server-side per request from
+ * the buyer's OAuth bearer. The crypto rail is therefore enabled by the agent
+ * key alone.
+ */
+export function resolveCryptoDeps(cfg) {
+    if (!cfg.agentSuiPrivateKey)
+        return undefined;
+    return {
+        sui: new SuiSigner(cfg.agentSuiPrivateKey, cfg.suiNetwork),
+        inputCoinType: DEFAULT_INPUT_COIN_TYPE,
+        maxSpendAmount: cfg.agentMaxSpendAmount,
+    };
+}
+//# sourceMappingURL=deps.js.map

package/dist/crypto/deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deps.js","sourceRoot":"","sources":["../../src/crypto/deps.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAiBhD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAsB;IAEtB,IAAI,CAAC,GAAG,CAAC,kBAAkB;QAAE,OAAO,SAAS,CAAC;IAE9C,OAAO;QACL,GAAG,EAAE,IAAI,SAAS,CAAC,GAAG,CAAC,kBAAkB,EAAE,GAAG,CAAC,UAAU,CAAC;QAC1D,aAAa,EAAE,uBAAuB;QACtC,cAAc,EAAE,GAAG,CAAC,mBAAmB;KACxC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { UCP_VERSION, normalizeBaseUrl, assertEcP256PrivateJwk, parseSuiNetwork, type Jwk, type SuiNetwork, type UcpClientConfig, type AgentAp2Config, type AgentCryptoConfig, } from './config.js';
+export { UcpClient, UcpClientError, UcpAuthError, messageOf, isUcpError, type UcpResponse, type UcpClientOptions, type UcpAuthMode, type StoreToolOptions, type AccountToolSpec, type ToolAnnotations, } from './ucp/client.js';
+export { canonicalJson, verifyDetachedJws, verifyMerchantAuthorization, Ap2Signer, type CheckoutMandateClaims, type PaymentMandateClaims, } from './ap2/index.js';
+export { createCheckoutHandlers, toMinorUnits, normalizeSearchFilters, availableRails, resolveRail, railKind, grandTotal, currencyOf, asAllowanceId, type CheckoutHandlers, type CheckoutDeps, type CheckoutLineItem, type ConfirmPurchaseInput, type CheckoutErrorCode, type CheckoutOutcome, type SearchFilters, type ResolvedRail, } from './checkout/index.js';
+export { resolveCryptoDeps, type CryptoDeps } from './crypto/deps.js';
+export { SuiSigner, SuiSignerError } from './sui/signer.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+// Config
+export { UCP_VERSION, normalizeBaseUrl, assertEcP256PrivateJwk, parseSuiNetwork, } from './config.js';
+// Transport
+export { UcpClient, UcpClientError, UcpAuthError, messageOf, isUcpError, } from './ucp/client.js';
+// AP2
+export { canonicalJson, verifyDetachedJws, verifyMerchantAuthorization, Ap2Signer, } from './ap2/index.js';
+// Checkout orchestration
+export { createCheckoutHandlers, toMinorUnits, normalizeSearchFilters, availableRails, resolveRail, railKind, grandTotal, currencyOf, asAllowanceId, } from './checkout/index.js';
+// Crypto rail (requires the optional `@mysten/sui` peer dependency)
+export { resolveCryptoDeps } from './crypto/deps.js';
+export { SuiSigner, SuiSignerError } from './sui/signer.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,GAMhB,MAAM,aAAa,CAAC;AAErB,YAAY;AACZ,OAAO,EACL,SAAS,EACT,cAAc,EACd,YAAY,EACZ,SAAS,EACT,UAAU,GAOX,MAAM,iBAAiB,CAAC;AAEzB,MAAM;AACN,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,2BAA2B,EAC3B,SAAS,GAGV,MAAM,gBAAgB,CAAC;AAExB,yBAAyB;AACzB,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GASd,MAAM,qBAAqB,CAAC;AAE7B,oEAAoE;AACpE,OAAO,EAAE,iBAAiB,EAAmB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/sui/signer.d.ts

@@ -0,0 +1,27 @@
+import type { SuiNetwork } from '../config.js';
+/** Thrown when a crypto payment transaction fails to sign or execute. */
+export declare class SuiSignerError extends Error {
+}
+/**
+ * Signs and submits the crypto-payment PTBs the Artos API hands back from
+ * `prepare_checkout_payment`. The agent's Ed25519 key is configured on-chain as
+ * an alias of the buyer's wallet, so signing here authorizes a spend from the
+ * buyer's funds without the buyer being present. The unsigned transaction is the
+ * server-built DeepBook swap that routes the order total to the merchant in
+ * USDC; the resulting digest becomes the payment credential on completion.
+ *
+ * Requires the optional `@mysten/sui` peer dependency (imported only by this
+ * module / the `@artos-commerce/ucp-client/sui` entry).
+ */
+export declare class SuiSigner {
+    private readonly keypair;
+    private readonly client;
+    /** The agent's Sui address (the on-chain alias spending on the buyer's behalf). */
+    readonly address: string;
+    constructor(privateKey: string, network: SuiNetwork);
+    /**
+     * Signs the server-built unsigned transaction (a JSON-serialized PTB) and
+     * executes it, returning the on-chain transaction digest once finalized.
+     */
+    signAndSubmit(unsignedTx: string): Promise<string>;
+}

package/dist/sui/signer.js

@@ -0,0 +1,69 @@
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+import { SuiGrpcClient } from '@mysten/sui/grpc';
+import { Transaction } from '@mysten/sui/transactions';
+/** Public fullnode gRPC endpoints, keyed by network. */
+const GRPC_URLS = {
+    mainnet: 'https://fullnode.mainnet.sui.io:443',
+    testnet: 'https://fullnode.testnet.sui.io:443',
+    devnet: 'https://fullnode.devnet.sui.io:443',
+    localnet: 'http://127.0.0.1:9000',
+};
+/** Thrown when a crypto payment transaction fails to sign or execute. */
+export class SuiSignerError extends Error {
+}
+/**
+ * Signs and submits the crypto-payment PTBs the Artos API hands back from
+ * `prepare_checkout_payment`. The agent's Ed25519 key is configured on-chain as
+ * an alias of the buyer's wallet, so signing here authorizes a spend from the
+ * buyer's funds without the buyer being present. The unsigned transaction is the
+ * server-built DeepBook swap that routes the order total to the merchant in
+ * USDC; the resulting digest becomes the payment credential on completion.
+ *
+ * Requires the optional `@mysten/sui` peer dependency (imported only by this
+ * module / the `@artos-commerce/ucp-client/sui` entry).
+ */
+export class SuiSigner {
+    keypair;
+    client;
+    /** The agent's Sui address (the on-chain alias spending on the buyer's behalf). */
+    address;
+    constructor(privateKey, network) {
+        this.keypair = Ed25519Keypair.fromSecretKey(privateKey);
+        this.address = this.keypair.toSuiAddress();
+        this.client = new SuiGrpcClient({
+            network,
+            baseUrl: GRPC_URLS[network],
+        });
+    }
+    /**
+     * Signs the server-built unsigned transaction (a JSON-serialized PTB) and
+     * executes it, returning the on-chain transaction digest once finalized.
+     */
+    async signAndSubmit(unsignedTx) {
+        let tx;
+        try {
+            tx = Transaction.from(unsignedTx);
+        }
+        catch (err) {
+            throw new SuiSignerError(`Could not parse the unsigned payment transaction: ${messageOf(err)}`);
+        }
+        const result = await this.client.core.signAndExecuteTransaction({
+            transaction: tx,
+            signer: this.keypair,
+            include: { effects: true },
+        });
+        if (result.FailedTransaction) {
+            // `status.error` is a structured ExecutionError (or null); JSON-encode it
+            // so the message is informative rather than "[object Object]".
+            throw new SuiSignerError(`Payment transaction failed on-chain: ${JSON.stringify(result.FailedTransaction.status.error)}`);
+        }
+        const digest = result.Transaction.digest;
+        // Wait for finality so the API can immediately verify the receipt.
+        await this.client.core.waitForTransaction({ digest });
+        return digest;
+    }
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=signer.js.map

package/dist/sui/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/sui/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,wDAAwD;AACxD,MAAM,SAAS,GAA+B;IAC5C,OAAO,EAAE,qCAAqC;IAC9C,OAAO,EAAE,qCAAqC;IAC9C,MAAM,EAAE,oCAAoC;IAC5C,QAAQ,EAAE,uBAAuB;CAClC,CAAC;AAEF,yEAAyE;AACzE,MAAM,OAAO,cAAe,SAAQ,KAAK;CAAG;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IACH,OAAO,CAAiB;IACxB,MAAM,CAAgB;IACvC,mFAAmF;IAC1E,OAAO,CAAS;IAEzB,YAAY,UAAkB,EAAE,OAAmB;QACjD,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,aAAa,CAAC;YAC9B,OAAO;YACP,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;SAC5B,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa,CAAC,UAAkB;QACpC,IAAI,EAAe,CAAC;QACpB,IAAI,CAAC;YACH,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CACtB,qDAAqD,SAAS,CAAC,GAAG,CAAC,EAAE,CACtE,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC;YAC9D,WAAW,EAAE,EAAE;YACf,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;SAC3B,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAC7B,0EAA0E;YAC1E,+DAA+D;YAC/D,MAAM,IAAI,cAAc,CACtB,wCAAwC,IAAI,CAAC,SAAS,CACpD,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,KAAK,CACtC,EAAE,CACJ,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;QACzC,mEAAmE;QACnE,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/ucp/client.d.ts

@@ -0,0 +1,169 @@
+import { type UcpClientConfig } from '../config.js';
+/** A UCP response envelope (`ucp` meta + capability payload). */
+export type UcpResponse = {
+    ucp?: {
+        status?: string;
+        [k: string]: unknown;
+    };
+    messages?: Array<{
+        code?: string;
+        content?: string;
+    }>;
+    [k: string]: unknown;
+};
+/**
+ * Tool behavior hints as advertised by an MCP `tools/list` (a structural subset
+ * of the MCP SDK's `ToolAnnotations`). Kept local so the SDK carries no
+ * dependency on `@modelcontextprotocol/sdk`.
+ */
+export type ToolAnnotations = {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    [k: string]: unknown;
+};
+/** A buyer-account tool descriptor as advertised by the API's `tools/list`. */
+export type AccountToolSpec = {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: ToolAnnotations;
+};
+/** Thrown for transport / JSON-RPC / HTTP failures (not UCP business outcomes). */
+export declare class UcpClientError extends Error {
+}
+/**
+ * Thrown when the API rejects a buyer-bound call with a 401 (expired/invalid
+ * bearer). Carries the API's `WWW-Authenticate` challenge so a host can relay it
+ * verbatim to the agent, which then runs its refresh_token grant and retries —
+ * instead of forcing the buyer through full re-consent.
+ */
+export declare class UcpAuthError extends UcpClientError {
+    readonly wwwAuthenticate: string;
+    constructor(wwwAuthenticate: string);
+}
+type FetchLike = typeof fetch;
+/** Which credential the API call authenticates with. */
+export type UcpAuthMode = 'platform' | 'buyer';
+export interface StoreToolOptions {
+    /** State-changing tools require an idempotency key in `meta`. */
+    idempotent?: boolean;
+    /** Override the generated idempotency key (used for retry safety). */
+    idempotencyKey?: string;
+    /**
+     * Credential to authenticate with. `platform` (default) sends the cross-store
+     * `X-API-Key`. `buyer` forwards the session's OAuth bearer instead (and omits
+     * the API key), so the API resolves the buyer account and enforces their
+     * STORED agent authorization + caps. Buyer-bound calls (crypto
+     * prepare/complete) require {@link UcpClientOptions.buyerToken}.
+     */
+    auth?: UcpAuthMode;
+}
+export interface UcpClientOptions {
+    /**
+     * Inject a `fetch` implementation (for tests or a custom agent/proxy). When
+     * omitted the global `fetch` is used (Node 18+ / browsers).
+     */
+    fetch?: FetchLike;
+    /**
+     * The current session's buyer OAuth bearer (forwarded to the API on
+     * `auth: 'buyer'` calls). Absent for anonymous/unauthenticated sessions.
+     */
+    buyerToken?: string;
+    /**
+     * Invoked with the API's `WWW-Authenticate` challenge when a buyer-bound call
+     * is rejected with a 401, so the surrounding request can be answered with that
+     * 401 + header (triggering the agent's silent refresh).
+     */
+    onAuthChallenge?: (wwwAuthenticate: string) => void;
+}
+/**
+ * Talks to the Artos UCP API two ways:
+ *  - global catalog search over REST (`POST /catalog/search`), the cross-store
+ *    vendor extension; and
+ *  - per-store shopping ops over the UCP MCP JSON-RPC transport
+ *    (`POST /s/:slug/mcp`), routed by the seller slug carried on search results.
+ *
+ * Every request carries the UCP transport preamble (`UCP-Agent` with the agent
+ * profile, `Request-Id`) and the platform API key (which authenticates at any
+ * store). State-changing MCP calls also carry `meta["idempotency-key"]`.
+ */
+export declare class UcpClient {
+    private readonly cfg;
+    private readonly fetchImpl;
+    private readonly buyerToken?;
+    private readonly onAuthChallenge?;
+    constructor(cfg: UcpClientConfig, options?: UcpClientOptions);
+    /**
+     * Raises a {@link UcpAuthError} (and notifies the auth-challenge sink) when
+     * the API rejected the call with a 401, preserving the `WWW-Authenticate`
+     * header so a host can relay it for a silent refresh. No-op otherwise.
+     */
+    private relayAuthError;
+    /** True when the session carries a buyer OAuth bearer (buyer is signed in). */
+    hasBuyerToken(): boolean;
+    /** `ucp-version="...", profile="..."` per the UCP-Agent header grammar. */
+    ucpAgentHeader(): string;
+    private baseHeaders;
+    /** Cross-store catalog search. `catalog` is the UCP search request body. */
+    globalSearch(catalog: {
+        query?: string;
+        filters?: Record<string, unknown>;
+        sort?: string;
+        pagination?: Record<string, unknown>;
+        context?: Record<string, unknown>;
+    }): Promise<UcpResponse>;
+    /**
+     * Calls a read-only global (cross-store) catalog tool over the platform MCP
+     * JSON-RPC transport (`POST /mcp`) and returns the `structuredContent` payload
+     * (itself a UCP response, possibly a business-error envelope). Unlike
+     * {@link callStoreTool} there is no store slug and no idempotency key (these
+     * tools never mutate state); the server still requires the agent profile in
+     * `meta` and the request DTO wrapped under `catalog`.
+     */
+    callGlobalTool(name: 'search_catalog' | 'lookup_catalog' | 'get_product', catalog: Record<string, unknown>): Promise<UcpResponse>;
+    /**
+     * Calls a UCP MCP tool at a specific store and returns the `structuredContent`
+     * payload (itself a UCP response, which may be a business-error envelope the
+     * caller can inspect via `ucp.status`).
+     */
+    callStoreTool(slug: string, name: string, args: Record<string, unknown>, opts?: StoreToolOptions): Promise<UcpResponse>;
+    /**
+     * Lists the buyer-account tools the API advertises (`POST /account/mcp`,
+     * `tools/list`). First-party + buyer-scoped, so this sends only the buyer
+     * bearer. Throws {@link UcpAuthError} on 401.
+     */
+    listAccountTools(): Promise<AccountToolSpec[]>;
+    /**
+     * Calls a buyer-account tool (`POST /account/mcp`, `tools/call`) with the
+     * buyer bearer and returns the `structuredContent` payload (a plain JSON
+     * resource, possibly a UCP business-error envelope). Throws
+     * {@link UcpAuthError} on 401 so a host can relay the refresh challenge.
+     */
+    callAccountTool(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Fetches a store's UCP profile (`GET /s/:slug/.well-known/ucp`) and returns
+     * its published `signing_keys` (JWKs), used to verify the store's
+     * `merchant_authorization` before completing a checkout. Returns an empty
+     * array when the profile is unreachable or publishes no keys.
+     */
+    fetchStoreProfile(slug: string): Promise<Record<string, unknown>[]>;
+    /**
+     * Fetches an image and returns it as a base64 block (`{ type, data, mimeType }`),
+     * which hosts like Claude render inline natively. Returns null on any failure
+     * or if the image is too large to embed. Images are served by the Artos API
+     * itself, so no auth is needed.
+     */
+    fetchImage(url: string, maxBytes?: number): Promise<{
+        type: 'image';
+        data: string;
+        mimeType: string;
+    } | null>;
+}
+/** First message content (or undefined) from a UCP envelope. */
+export declare function messageOf(body: UcpResponse): string | undefined;
+/** True when a UCP response is a business-error envelope. */
+export declare function isUcpError(body: UcpResponse): boolean;
+export {};

package/dist/ucp/client.js

@@ -0,0 +1,269 @@
+import { randomUUID } from 'node:crypto';
+import { UCP_VERSION } from '../config.js';
+/** Thrown for transport / JSON-RPC / HTTP failures (not UCP business outcomes). */
+export class UcpClientError extends Error {
+}
+/** The default RFC 6750 challenge when the API omits its own. */
+const DEFAULT_BEARER_CHALLENGE = 'Bearer error="invalid_token"';
+/**
+ * Thrown when the API rejects a buyer-bound call with a 401 (expired/invalid
+ * bearer). Carries the API's `WWW-Authenticate` challenge so a host can relay it
+ * verbatim to the agent, which then runs its refresh_token grant and retries —
+ * instead of forcing the buyer through full re-consent.
+ */
+export class UcpAuthError extends UcpClientError {
+    wwwAuthenticate;
+    constructor(wwwAuthenticate) {
+        super('Buyer authentication required (401).');
+        this.wwwAuthenticate = wwwAuthenticate;
+        this.name = 'UcpAuthError';
+    }
+}
+/**
+ * Talks to the Artos UCP API two ways:
+ *  - global catalog search over REST (`POST /catalog/search`), the cross-store
+ *    vendor extension; and
+ *  - per-store shopping ops over the UCP MCP JSON-RPC transport
+ *    (`POST /s/:slug/mcp`), routed by the seller slug carried on search results.
+ *
+ * Every request carries the UCP transport preamble (`UCP-Agent` with the agent
+ * profile, `Request-Id`) and the platform API key (which authenticates at any
+ * store). State-changing MCP calls also carry `meta["idempotency-key"]`.
+ */
+export class UcpClient {
+    cfg;
+    fetchImpl;
+    buyerToken;
+    onAuthChallenge;
+    constructor(cfg, options = {}) {
+        this.cfg = cfg;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.buyerToken = options.buyerToken;
+        this.onAuthChallenge = options.onAuthChallenge;
+    }
+    /**
+     * Raises a {@link UcpAuthError} (and notifies the auth-challenge sink) when
+     * the API rejected the call with a 401, preserving the `WWW-Authenticate`
+     * header so a host can relay it for a silent refresh. No-op otherwise.
+     */
+    relayAuthError(res) {
+        if (res.status !== 401) {
+            return;
+        }
+        const challenge = res.headers?.get('www-authenticate') ?? DEFAULT_BEARER_CHALLENGE;
+        this.onAuthChallenge?.(challenge);
+        throw new UcpAuthError(challenge);
+    }
+    /** True when the session carries a buyer OAuth bearer (buyer is signed in). */
+    hasBuyerToken() {
+        return Boolean(this.buyerToken);
+    }
+    /** `ucp-version="...", profile="..."` per the UCP-Agent header grammar. */
+    ucpAgentHeader() {
+        return `ucp-version="${UCP_VERSION}", profile="${this.cfg.platformProfileUrl}"`;
+    }
+    baseHeaders(auth = 'platform') {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            'UCP-Agent': this.ucpAgentHeader(),
+            'Request-Id': randomUUID(),
+        };
+        // The API's identity guard prefers X-API-Key over a bearer, so buyer-bound
+        // calls must send ONLY the bearer for the buyer account to be resolved.
+        if (auth === 'buyer' && this.buyerToken) {
+            headers.Authorization = `Bearer ${this.buyerToken}`;
+        }
+        else {
+            headers['X-API-Key'] = this.cfg.platformApiKey;
+        }
+        return headers;
+    }
+    /** Cross-store catalog search. `catalog` is the UCP search request body. */
+    async globalSearch(catalog) {
+        const res = await this.fetchImpl(`${this.cfg.artosBaseUrl}/catalog/search`, {
+            method: 'POST',
+            headers: this.baseHeaders(),
+            body: JSON.stringify(catalog),
+        });
+        const body = (await res.json());
+        if (!res.ok || body.ucp?.status === 'error') {
+            throw new UcpClientError(messageOf(body) ?? `Search failed (${res.status}).`);
+        }
+        return body;
+    }
+    /**
+     * Calls a read-only global (cross-store) catalog tool over the platform MCP
+     * JSON-RPC transport (`POST /mcp`) and returns the `structuredContent` payload
+     * (itself a UCP response, possibly a business-error envelope). Unlike
+     * {@link callStoreTool} there is no store slug and no idempotency key (these
+     * tools never mutate state); the server still requires the agent profile in
+     * `meta` and the request DTO wrapped under `catalog`.
+     */
+    async callGlobalTool(name, catalog) {
+        const meta = { 'ucp-agent': { profile: this.cfg.platformProfileUrl } };
+        const res = await this.fetchImpl(`${this.cfg.artosBaseUrl}/mcp`, {
+            method: 'POST',
+            headers: this.baseHeaders(),
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: randomUUID(),
+                method: 'tools/call',
+                params: { name, arguments: { catalog, meta } },
+            }),
+        });
+        if (!res.ok) {
+            this.relayAuthError(res);
+            throw new UcpClientError(`MCP transport error (${res.status}).`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new UcpClientError(body.error.message ?? `MCP error ${body.error.code ?? ''}`.trim());
+        }
+        const structured = body.result?.structuredContent;
+        if (!structured) {
+            throw new UcpClientError('MCP response missing structuredContent.');
+        }
+        return structured;
+    }
+    /**
+     * Calls a UCP MCP tool at a specific store and returns the `structuredContent`
+     * payload (itself a UCP response, which may be a business-error envelope the
+     * caller can inspect via `ucp.status`).
+     */
+    async callStoreTool(slug, name, args, opts = {}) {
+        const meta = {
+            'ucp-agent': { profile: this.cfg.platformProfileUrl },
+        };
+        if (opts.idempotent) {
+            meta['idempotency-key'] = opts.idempotencyKey ?? randomUUID();
+        }
+        const res = await this.fetchImpl(`${this.cfg.artosBaseUrl}/s/${slug}/mcp`, {
+            method: 'POST',
+            headers: this.baseHeaders(opts.auth),
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: randomUUID(),
+                method: 'tools/call',
+                params: { name, arguments: { ...args, meta } },
+            }),
+        });
+        if (!res.ok) {
+            this.relayAuthError(res);
+            throw new UcpClientError(`MCP transport error (${res.status}).`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new UcpClientError(body.error.message ?? `MCP error ${body.error.code ?? ''}`.trim());
+        }
+        const structured = body.result?.structuredContent;
+        if (!structured) {
+            throw new UcpClientError('MCP response missing structuredContent.');
+        }
+        return structured;
+    }
+    /**
+     * Lists the buyer-account tools the API advertises (`POST /account/mcp`,
+     * `tools/list`). First-party + buyer-scoped, so this sends only the buyer
+     * bearer. Throws {@link UcpAuthError} on 401.
+     */
+    async listAccountTools() {
+        const res = await this.fetchImpl(`${this.cfg.artosBaseUrl}/account/mcp`, {
+            method: 'POST',
+            headers: this.baseHeaders('buyer'),
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: randomUUID(),
+                method: 'tools/list',
+            }),
+        });
+        if (!res.ok) {
+            this.relayAuthError(res);
+            throw new UcpClientError(`Account MCP transport error (${res.status}).`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new UcpClientError(body.error.message ??
+                `Account MCP error ${body.error.code ?? ''}`.trim());
+        }
+        return body.result?.tools ?? [];
+    }
+    /**
+     * Calls a buyer-account tool (`POST /account/mcp`, `tools/call`) with the
+     * buyer bearer and returns the `structuredContent` payload (a plain JSON
+     * resource, possibly a UCP business-error envelope). Throws
+     * {@link UcpAuthError} on 401 so a host can relay the refresh challenge.
+     */
+    async callAccountTool(name, args) {
+        const res = await this.fetchImpl(`${this.cfg.artosBaseUrl}/account/mcp`, {
+            method: 'POST',
+            headers: this.baseHeaders('buyer'),
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: randomUUID(),
+                method: 'tools/call',
+                params: { name, arguments: args },
+            }),
+        });
+        if (!res.ok) {
+            this.relayAuthError(res);
+            throw new UcpClientError(`Account MCP transport error (${res.status}).`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new UcpClientError(body.error.message ??
+                `Account MCP error ${body.error.code ?? ''}`.trim());
+        }
+        const structured = body.result?.structuredContent;
+        if (!structured) {
+            throw new UcpClientError('Account MCP response missing structuredContent.');
+        }
+        return structured;
+    }
+    /**
+     * Fetches a store's UCP profile (`GET /s/:slug/.well-known/ucp`) and returns
+     * its published `signing_keys` (JWKs), used to verify the store's
+     * `merchant_authorization` before completing a checkout. Returns an empty
+     * array when the profile is unreachable or publishes no keys.
+     */
+    async fetchStoreProfile(slug) {
+        const res = await this.fetchImpl(`${this.cfg.artosBaseUrl}/s/${slug}/.well-known/ucp`, { method: 'GET', headers: this.baseHeaders() });
+        if (!res.ok) {
+            throw new UcpClientError(`Store profile fetch failed (${res.status}).`);
+        }
+        const body = (await res.json());
+        return body.signing_keys ?? [];
+    }
+    /**
+     * Fetches an image and returns it as a base64 block (`{ type, data, mimeType }`),
+     * which hosts like Claude render inline natively. Returns null on any failure
+     * or if the image is too large to embed. Images are served by the Artos API
+     * itself, so no auth is needed.
+     */
+    async fetchImage(url, maxBytes = 4_000_000) {
+        try {
+            const res = await this.fetchImpl(url);
+            if (!res.ok)
+                return null;
+            const mimeType = (res.headers.get('content-type') ?? 'image/webp').split(';')[0];
+            if (!mimeType.startsWith('image/'))
+                return null;
+            const buf = Buffer.from(await res.arrayBuffer());
+            if (buf.byteLength === 0 || buf.byteLength > maxBytes)
+                return null;
+            return { type: 'image', data: buf.toString('base64'), mimeType };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** First message content (or undefined) from a UCP envelope. */
+export function messageOf(body) {
+    return body.messages?.find((m) => m.content)?.content;
+}
+/** True when a UCP response is a business-error envelope. */
+export function isUcpError(body) {
+    return body.ucp?.status === 'error';
+}
+//# sourceMappingURL=client.js.map