@agent-cards/commerce-sdk 0.0.0-stage → 0.1.0

package/dist/model-view.d.ts

@@ -0,0 +1,62 @@
+import type { BuyToolProduct, BuyToolResult, BuyToolStatus } from './buy-tool.js';
+export interface BuyToolModelCart {
+    store: string;
+    items: Array<{
+        name: string;
+        qty: number;
+        price: string | null;
+    }>;
+    fees: string | null;
+    tip: string | null;
+    total: string;
+}
+export interface BuyToolModelProduct {
+    name: string;
+    price: string | null;
+    /** True when the shopper holds this product's store page, which `sendLink` delivered beside the reply. */
+    link_sent: boolean;
+}
+/** The buy tool's answer as the model reads it. */
+export interface BuyToolModelView {
+    status: BuyToolStatus;
+    /** Agentcard's answer for the shopper, with every link taken out. */
+    reply: string;
+    /** The newest cart on the table. */
+    cart: BuyToolModelCart | null;
+    /** Every cart on the table, the newest last, when the shopper is buying from more than one store. */
+    carts: BuyToolModelCart[];
+    products: BuyToolModelProduct[];
+    approval_expires_at: string | null;
+    shopper_need_not_reply: boolean;
+    /** True when the shopper already has the link this answer needed. */
+    link_sent: boolean;
+    /** How many store pages of the products above the shopper holds, 0 when none went out. */
+    product_links_sent: number;
+}
+/** The text with every link taken out: a Markdown link keeps its label, and a bare address goes entirely. */
+export declare function stripLinks(text: string): string;
+/**
+ * An amount in its currency's minor unit, as the model reads it: the currency's own minor units place the
+ * decimal point, so 1331 is $13.31 in USD, CA$13.31 in CAD and ¥1,331 in JPY. An amount whose currency
+ * Agentcard did not name shows with no symbol, because a dollar sign on it could be wrong.
+ */
+export declare function money(minor: number | null | undefined, currency: string | null | undefined): string | null;
+/**
+ * The products the model reads: the first twenty that keep a name once links
+ * are taken out. The tool sends store pages for these same twenty, so the shopper
+ * never holds a product link the model cannot name.
+ */
+export declare function shownProducts(products: readonly BuyToolProduct[] | null | undefined): BuyToolProduct[];
+/**
+ * The model's view of one answer: the status, Agentcard's reply, the newest
+ * cart and every cart on the table, the products by name and price, and
+ * whether the shopper has each link. A status this version does not know
+ * reads as `needs_input`.
+ */
+export declare function forModel(result: BuyToolResult): BuyToolModelView;
+/**
+ * A thrown error as the model may read it: the same message with every link
+ * taken out, and the original error on `cause` for your logs. A TypeError
+ * stays a TypeError, so input the model got wrong still reads as such.
+ */
+export declare function forModelError(error: unknown): Error;

package/dist/model-view.js

@@ -0,0 +1,110 @@
+const MODEL_STATUSES = new Set(['needs_input', 'needs_card', 'approval_sent', 'placing', 'order_placed', 'declined']);
+/** The model sees the first twenty products the search found, the cap the backend's catalog keeps for a turn. */
+const MAX_PRODUCTS = 20;
+const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
+const SCHEME_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`)\]]*/gi;
+const WWW_URL = /\bwww\.[^\s<>"'`)\]]*/gi;
+/** A host followed by a path, a query or a fragment: `vault.agentcard.sh/a/1`, `vault.agentcard.sh?token=abc`. */
+const HOST_PATH = /\b(?:[a-z0-9-]+\.)+[a-z]{2,}[/?#][^\s<>"'`)\]]*/gi;
+/**
+ * A bare host on a common top-level domain, such as `agentcard.sh` or `amazon.com`, which a chat app
+ * turns into a link. The list keeps words with a dot, such as `Node.js`, and an email address's host.
+ */
+const BARE_HOST = /(?<![@\w.-])(?:[a-z0-9-]+\.)+(?:com|net|org|io|co|sh|ai|app|dev|me|us|uk|ca|de|fr|es|it|nl|eu|au|in|jp|br|mx|info|biz|shop|store|site|online|link|page|xyz|ly|gg|to|tv|fm|so)(?![\w-])/gi;
+/** The text with every link taken out: a Markdown link keeps its label, and a bare address goes entirely. */
+export function stripLinks(text) {
+    return String(text ?? '')
+        .replace(MARKDOWN_LINK, '$1')
+        .replace(SCHEME_URL, '')
+        .replace(WWW_URL, '')
+        .replace(HOST_PATH, '')
+        .replace(BARE_HOST, '')
+        .replace(/\(\s*\)|\[\s*\]|<\s*>/g, '')
+        .replace(/[ \t]+([.,;:!?])/g, '$1')
+        .replace(/[ \t]{2,}/g, ' ')
+        .replace(/[ \t]+$/gm, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** A currency's minor units as Intl knows them: 2 for USD and CAD, 0 for JPY. */
+function minorUnits(format) {
+    return format.resolvedOptions().maximumFractionDigits ?? 0;
+}
+/**
+ * An amount whose currency Agentcard did not name comes from an older backend, whose amount fields count
+ * cents as their names say: it scales by the US dollar's minor units and prints with no symbol.
+ */
+const UNNAMED_DIGITS = minorUnits(new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }));
+const UNNAMED = new Intl.NumberFormat('en-US', { minimumFractionDigits: UNNAMED_DIGITS, maximumFractionDigits: UNNAMED_DIGITS });
+/**
+ * The ISO 4217 codes this runtime knows, read once. `Intl.NumberFormat` takes any three letters, so a code
+ * outside this set, such as `ZZZ`, names no currency here. A runtime without the list knows none.
+ */
+const KNOWN_CURRENCIES = new Set(typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('currency') : []);
+/** The format for an ISO 4217 code, or null for a missing or unknown one. */
+function currencyFormat(currency) {
+    const code = typeof currency === 'string' ? currency.trim().toUpperCase() : '';
+    return KNOWN_CURRENCIES.has(code) ? new Intl.NumberFormat('en-US', { style: 'currency', currency: code }) : null;
+}
+/**
+ * An amount in its currency's minor unit, as the model reads it: the currency's own minor units place the
+ * decimal point, so 1331 is $13.31 in USD, CA$13.31 in CAD and ¥1,331 in JPY. An amount whose currency
+ * Agentcard did not name shows with no symbol, because a dollar sign on it could be wrong.
+ */
+export function money(minor, currency) {
+    if (typeof minor !== 'number' || !Number.isFinite(minor))
+        return null;
+    const format = currencyFormat(currency);
+    if (!format)
+        return UNNAMED.format(minor / 10 ** UNNAMED_DIGITS);
+    return format.format(minor / 10 ** minorUnits(format));
+}
+/**
+ * The products the model reads: the first twenty that keep a name once links
+ * are taken out. The tool sends store pages for these same twenty, so the shopper
+ * never holds a product link the model cannot name.
+ */
+export function shownProducts(products) {
+    return (products ?? []).filter((product) => stripLinks(product.name) !== '').slice(0, MAX_PRODUCTS);
+}
+function cartView(cart) {
+    return {
+        store: stripLinks(cart.store?.name ?? cart.merchant_name) || stripLinks(cart.merchant),
+        items: cart.items.map((line) => ({ name: stripLinks(line.name), qty: line.qty, price: money(line.priceCents, cart.currency) })),
+        fees: cart.serviceFeesCents > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
+        tip: cart.tipCents > 0 ? money(cart.tipCents, cart.currency) : null,
+        total: money(cart.totalCents, cart.currency) ?? money(0, cart.currency),
+    };
+}
+/**
+ * The model's view of one answer: the status, Agentcard's reply, the newest
+ * cart and every cart on the table, the products by name and price, and
+ * whether the shopper has each link. A status this version does not know
+ * reads as `needs_input`.
+ */
+export function forModel(result) {
+    const status = typeof result.status === 'string' && MODEL_STATUSES.has(result.status) ? result.status : 'needs_input';
+    const products = shownProducts(result.products);
+    const held = (product) => product.linkSent === true && typeof product.url === 'string' && product.url !== '';
+    return {
+        status,
+        reply: stripLinks(result.reply),
+        cart: result.cart ? cartView(result.cart) : null,
+        carts: (result.carts ?? []).map(cartView),
+        products: products.map((product) => ({ name: stripLinks(product.name), price: money(product.priceCents, product.currency), link_sent: held(product) })),
+        approval_expires_at: typeof result.approval_expires_at === 'string' ? stripLinks(result.approval_expires_at) || null : null,
+        shopper_need_not_reply: result.shopper_need_not_reply === true,
+        link_sent: result.link_sent === true,
+        // Two products on one page share one link, so the count is of pages.
+        product_links_sent: new Set(products.filter(held).map((product) => product.url)).size,
+    };
+}
+/**
+ * A thrown error as the model may read it: the same message with every link
+ * taken out, and the original error on `cause` for your logs. A TypeError
+ * stays a TypeError, so input the model got wrong still reads as such.
+ */
+export function forModelError(error) {
+    const message = stripLinks(error instanceof Error ? error.message : String(error)) || 'The buy tool failed.';
+    return error instanceof TypeError ? new TypeError(message, { cause: error }) : new Error(message, { cause: error });
+}

package/dist/verify.d.ts

@@ -0,0 +1,41 @@
+/** Why a delivery was refused. */
+export type AgentcardSignatureReason = 'missing_header' | 'malformed_header' | 'stale_timestamp' | 'wrong_signature';
+/** Thrown when a delivery's `AgentCard-Signature` does not prove Agentcard sent it; `reason` says why. */
+export declare class AgentcardSignatureError extends Error {
+    readonly reason: AgentcardSignatureReason;
+    constructor(reason: AgentcardSignatureReason, message: string);
+}
+/**
+ * Thrown when a correctly signed body is not an Agentcard event. A TypeError to callers; the
+ * webhook handler tells it apart from a bug so it answers 400 rather than 500.
+ */
+export declare class InvalidEventBodyError extends TypeError {
+}
+/** The envelope every event arrives in. Delivery is at least once: deduplicate on `id`. */
+export interface AgentcardEvent<T extends string = string, D = Record<string, unknown>> {
+    /** Stable event id (`evt_…`), the same on every redelivery. */
+    id: string;
+    type: T;
+    /** Unix seconds. */
+    created: number;
+    /** False for a sandbox event. */
+    livemode: boolean;
+    data: D;
+}
+export interface VerifyOptions {
+    /** How far the signed timestamp may sit from now, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** The current time in unix seconds. Default: the system clock. */
+    now?: number;
+}
+/** The tolerance in seconds. A value that is not a number of seconds would turn the replay check off, so it throws. */
+export declare function toleranceOf(opts: Pick<VerifyOptions, 'toleranceSeconds'>): number;
+/**
+ * Checks one delivery and returns its event. Pass the raw request body, the
+ * `AgentCard-Signature` header and the endpoint's secret. Nothing in the body
+ * is read before the signature holds. Throws `AgentcardSignatureError` for a
+ * missing, malformed, stale or wrong signature, and a TypeError when a
+ * correctly signed body is not an event.
+ */
+export declare function verifyAgentcardWebhook(rawBody: string | Uint8Array, signatureHeader: string | undefined, secret: string, opts?: VerifyOptions): AgentcardEvent;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/verify.js

@@ -0,0 +1,137 @@
+/**
+ * Webhook verification. Agentcard signs every delivery with
+ * `AgentCard-Signature: t=<unix seconds>,v1=<hex>`: HMAC-SHA256 under the
+ * endpoint's secret over `${t}.${rawBody}`. The check runs on the raw bytes,
+ * compares in constant time, and refuses a timestamp outside the tolerance,
+ * so a captured delivery cannot be replayed later.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** Thrown when a delivery's `AgentCard-Signature` does not prove Agentcard sent it; `reason` says why. */
+export class AgentcardSignatureError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'AgentcardSignatureError';
+        this.reason = reason;
+    }
+}
+/**
+ * Thrown when a correctly signed body is not an Agentcard event. A TypeError to callers; the
+ * webhook handler tells it apart from a bug so it answers 400 rather than 500.
+ */
+export class InvalidEventBodyError extends TypeError {
+}
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/** The tolerance in seconds. A value that is not a number of seconds would turn the replay check off, so it throws. */
+export function toleranceOf(opts) {
+    const tolerance = opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (typeof tolerance !== 'number' || !Number.isFinite(tolerance) || tolerance < 0) {
+        throw new TypeError('Pass toleranceSeconds as a number of seconds, 0 or more, or leave it out for 300.');
+    }
+    return tolerance;
+}
+const SIGNATURE_HEX = /^[0-9a-fA-F]{64}$/;
+const TIMESTAMP = /^\d{1,12}$/;
+/**
+ * Checks one delivery and returns its event. Pass the raw request body, the
+ * `AgentCard-Signature` header and the endpoint's secret. Nothing in the body
+ * is read before the signature holds. Throws `AgentcardSignatureError` for a
+ * missing, malformed, stale or wrong signature, and a TypeError when a
+ * correctly signed body is not an event.
+ */
+export function verifyAgentcardWebhook(rawBody, signatureHeader, secret, opts = {}) {
+    if (typeof secret !== 'string' || secret === '') {
+        throw new TypeError('Pass the webhook endpoint secret Agentcard returned when you created the endpoint.');
+    }
+    if (typeof rawBody !== 'string' && !(rawBody instanceof Uint8Array)) {
+        throw new TypeError('Pass the raw request body as a string or bytes. The signature covers the bytes Agentcard sent, never a parsed object.');
+    }
+    if (!signatureHeader) {
+        throw new AgentcardSignatureError('missing_header', 'The request has no AgentCard-Signature header.');
+    }
+    const parsed = parseSignatureHeader(signatureHeader);
+    if (!parsed) {
+        throw new AgentcardSignatureError('malformed_header', 'The AgentCard-Signature header does not read t=<unix seconds>,v1=<64 hex characters>.');
+    }
+    // The timestamp is signed as the header spells it.
+    const expected = createHmac('sha256', secret).update(`${parsed.stamp}.`).update(rawBody).digest();
+    // Every candidate is compared, so the time taken never says which one matched.
+    let matched = false;
+    for (const given of parsed.signatures) {
+        if (timingSafeEqual(expected, given))
+            matched = true;
+    }
+    if (!matched) {
+        throw new AgentcardSignatureError('wrong_signature', 'The signature does not match this body under the secret you passed. Pass the secret of the endpoint that received the delivery, and the raw request bytes, never re-serialized JSON.');
+    }
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    const tolerance = toleranceOf(opts);
+    if (!Number.isFinite(now))
+        throw new TypeError('Pass now as unix seconds, or leave it out to read the system clock.');
+    const drift = now - parsed.t;
+    if (Math.abs(drift) > tolerance) {
+        const when = drift > 0 ? `${drift} seconds ago` : `${-drift} seconds from now`;
+        throw new AgentcardSignatureError('stale_timestamp', `Agentcard signed this delivery ${when}, and the limit is ${tolerance} seconds. Check this server's clock.`);
+    }
+    return parseEnvelope(rawBody);
+}
+/** The header's timestamp and every `v1` signature on it, or null when the header is malformed. */
+function parseSignatureHeader(header) {
+    let stamp;
+    const signatures = [];
+    for (const part of header.split(',')) {
+        const item = part.trim();
+        if (item === '')
+            continue;
+        const eq = item.indexOf('=');
+        if (eq <= 0)
+            return null;
+        const key = item.slice(0, eq).trim();
+        const value = item.slice(eq + 1).trim();
+        if (key === 't') {
+            if (stamp !== undefined || !TIMESTAMP.test(value))
+                return null;
+            stamp = value;
+        }
+        else if (key === 'v1') {
+            if (!SIGNATURE_HEX.test(value))
+                return null;
+            signatures.push(hexToBytes(value));
+        }
+        // Any other scheme is skipped, so a scheme Agentcard adds later never breaks this check.
+    }
+    return stamp === undefined || signatures.length === 0 ? null : { t: Number(stamp), stamp, signatures };
+}
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value !== '';
+}
+function parseEnvelope(rawBody) {
+    const text = typeof rawBody === 'string' ? rawBody : new TextDecoder().decode(rawBody);
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new InvalidEventBodyError('The webhook body is not JSON.');
+    }
+    // A consumer deduplicates on the id, so an event without one is refused.
+    if (!isRecord(value) || !nonEmpty(value.id) || !nonEmpty(value.type) || !isRecord(value.data)) {
+        throw new InvalidEventBodyError('The webhook body is not an Agentcard event: an event carries id, type and data.');
+    }
+    return {
+        id: value.id,
+        type: value.type,
+        created: typeof value.created === 'number' ? value.created : 0,
+        livemode: value.livemode === true,
+        data: value.data,
+    };
+}

package/examples/anthropic.mjs

@@ -0,0 +1,55 @@
+// A shopping agent in your terminal: Claude Opus 5.5 with the buy tool, through the Anthropic SDK's tool runner.
+//
+//   npm install @anthropic-ai/sdk @agent-cards/commerce-sdk
+//   AGENTCARD_CLIENT_ID=... AGENTCARD_CLIENT_SECRET=... ANTHROPIC_API_KEY=... node anthropic.mjs
+//
+// Sandbox credentials place no real order. SHOPPER_ID is your own id for the shopper you play.
+import readline from 'node:readline';
+import Anthropic from '@anthropic-ai/sdk';
+import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';
+
+const agentcard = new AgentcardClient({
+  clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
+  clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '',
+  baseUrl: process.env.AGENTCARD_BASE_URL,
+});
+
+const buy = buyTool({
+  agentcard,
+  externalUserId: process.env.SHOPPER_ID ?? 'shopper-1',
+  // Your app texts or emails each link to the shopper. This script prints it, where the model never reads it.
+  sendLink: (link) => console.log(`\n  ${link.kind} link for the shopper: ${link.url}\n`),
+});
+
+const anthropic = new Anthropic();
+// Lines that arrive while a turn runs wait their turn, so piped input works as well as typing.
+const terminal = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: 'you> ' });
+let messages = [];
+
+terminal.prompt();
+for await (const line of terminal) {
+  const said = line.trim();
+  if (!said) break;
+  const runner = anthropic.beta.messages.toolRunner({
+    model: 'claude-opus-5-5',
+    max_tokens: 16000,
+    system: 'You are a shopping assistant. Buy what the shopper asks for with the buy tool.',
+    tools: [buy],
+    messages: [...messages, { role: 'user', content: said }],
+    // When a safety classifier declines a request, Anthropic answers it with a fallback model instead.
+    betas: ['server-side-fallback-2026-07-01'],
+    fallbacks: 'default',
+  });
+  try {
+    const final = await runner;
+    // The runner keeps every turn, the tool calls and results included, so the next message continues from all of it.
+    messages = [...runner.params.messages];
+    const text = final.content.filter((block) => block.type === 'text').map((block) => block.text).join('\n');
+    console.log(`agent> ${final.stop_reason === 'refusal' ? '(the model declined to answer)' : text}`);
+  } catch (error) {
+    // A failed turn leaves the history as it was, so the shopper can say it again.
+    console.log(`agent> (the turn failed: ${error.message})`);
+  }
+  terminal.prompt();
+}
+terminal.close();

package/examples/openrouter.mjs

@@ -0,0 +1,53 @@
+// The same shopping agent through OpenRouter's agent SDK, on any model OpenRouter routes to.
+//
+//   npm install @openrouter/agent zod @agent-cards/commerce-sdk
+//   AGENTCARD_CLIENT_ID=... AGENTCARD_CLIENT_SECRET=... OPENROUTER_API_KEY=... node openrouter.mjs
+//
+// Sandbox credentials place no real order. OPENROUTER_MODEL picks another model.
+import readline from 'node:readline';
+import { OpenRouter, tool } from '@openrouter/agent';
+import { z } from 'zod';
+import { AgentcardClient, buyTool, toOpenRouterTool } from '@agent-cards/commerce-sdk';
+
+const agentcard = new AgentcardClient({
+  clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
+  clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '',
+  baseUrl: process.env.AGENTCARD_BASE_URL,
+});
+
+const buy = buyTool({
+  agentcard,
+  externalUserId: process.env.SHOPPER_ID ?? 'shopper-1',
+  // Your app texts or emails each link to the shopper. This script prints it, where the model never reads it.
+  sendLink: (link) => console.log(`\n  ${link.kind} link for the shopper: ${link.url}\n`),
+});
+
+const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
+// OpenRouter's agent SDK takes only tools its own tool() builds from a zod schema, so this one SDK keeps the adapter.
+const tools = [toOpenRouterTool(buy, { tool, z })];
+// Lines that arrive while a turn runs wait their turn, so piped input works as well as typing.
+const terminal = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: 'you> ' });
+// Agentcard keeps the purchase itself, so the chat history only needs what each side said.
+const history = [];
+
+terminal.prompt();
+for await (const line of terminal) {
+  const said = line.trim();
+  if (!said) break;
+  try {
+    const result = openrouter.callModel({
+      model: process.env.OPENROUTER_MODEL ?? 'anthropic/claude-opus-5.5',
+      instructions: 'You are a shopping assistant. Buy what the shopper asks for with the buy tool.',
+      input: [...history, { role: 'user', content: said }],
+      tools,
+    });
+    const text = await result.getText();
+    history.push({ role: 'user', content: said }, { role: 'assistant', content: text });
+    console.log(`agent> ${text}`);
+  } catch (error) {
+    // A failed turn leaves the history as it was, so the shopper can say it again.
+    console.log(`agent> (the turn failed: ${error.message})`);
+  }
+  terminal.prompt();
+}
+terminal.close();

package/examples/walkthrough.mjs

@@ -0,0 +1,97 @@
+// A scripted sandbox run of the buy tool, from a new shopper to a confirmed cart, with no model in the loop.
+//
+//   AGENTCARD_CLIENT_ID=... AGENTCARD_CLIENT_SECRET=... node walkthrough.mjs
+//
+// It runs on sandbox credentials only, and it books a restaurant table: a table costs nothing, and the
+// sandbox refuses the booking itself, so nothing is booked or charged. AGENTCARD_BASE_URL points it at
+// another Agentcard, such as one on your machine, which needs the reservations key for table search.
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';
+
+/** What the shopper says, in order, and what each answer must carry. */
+const SCRIPT = [
+  { input: { ask: 'a table for 2 at an italian place in san francisco tomorrow at 7pm', confirm: false, new_order: false }, expect: 'products' },
+  { input: { ask: 'the first one, please', confirm: false, new_order: false }, expect: 'cart' },
+  { input: { ask: 'yes, book it', confirm: true, new_order: false }, expect: 'sandbox_unavailable' },
+];
+
+function check(expect, result) {
+  const ok = expect === 'products' ? result.products.length > 0
+    : expect === 'cart' ? result.cart !== null
+      : expect === 'sandbox_unavailable' ? result.status === 'declined' && result.decline_code === 'sandbox_unavailable'
+        : expect === 'needs_card' ? result.status === 'needs_card' && result.links.length === 1
+          : false;
+  if (!ok) throw new Error(`expected ${expect}, got status ${result.status} (decline_code ${result.decline_code}, reply "${result.reply}")`);
+}
+
+/** Connects a test shopper, shops through the tool, then asks as a shopper nobody connected. Throws at the first answer that is off. */
+export async function walkthrough({ clientId, clientSecret, baseUrl, fetch = globalThis.fetch, log = console.log, phone = '+14155550100', runId = Date.now().toString(36) }) {
+  const agentcard = new AgentcardClient({ clientId, clientSecret, baseUrl, fetch });
+  await agentcard.bearer();
+  if (agentcard.sandbox !== true) throw new Error('These are not sandbox credentials. The walkthrough runs on sandbox credentials only.');
+
+  const post = async (path, body) => {
+    const res = await fetch(`${agentcard.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${await agentcard.bearer()}`, 'content-type': 'application/json', accept: 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`${path} answered ${res.status}: ${text}`);
+    return text ? JSON.parse(text) : {};
+  };
+
+  // 1. Connect a shopper under your own id for them. In the sandbox, the code is always 111111.
+  const externalUserId = `walkthrough-${runId}`;
+  const attempt = await post('/api/v2/connect/start', { phone, external_user_id: externalUserId });
+  const connection = await post('/api/v2/connect/verify', { connect_id: attempt.id, code: '111111' });
+  await post('/api/v2/connect/consent', { user_id: connection.user.id });
+  log(`connected ${externalUserId} as ${connection.user.id}`);
+
+  // 2. Shop through the tool, the way a model would call it.
+  const show = (label, result) => log(`${label}\n${JSON.stringify(result, ['status', 'reply', 'decline_code', 'cart', 'items', 'name', 'qty', 'priceCents', 'totalCents', 'products', 'links', 'kind', 'url', 'link_sent'], 2)}`);
+  const buy = buyTool({ agentcard, externalUserId, sendLink: (link) => log(`${link.kind} link: ${link.url}`) });
+  const results = [];
+  for (const step of SCRIPT) {
+    const result = await buy.answer(step.input);
+    show(`> ${step.input.ask}`, result);
+    check(step.expect, result);
+    results.push(result);
+  }
+
+  // 3. A shopper nobody connected gets a Vault link, and the same link when they ask again.
+  const stranger = buyTool({ agentcard, externalUserId: `walkthrough-stranger-${runId}`, sendLink: (link) => log(`${link.kind} link: ${link.url}`) });
+  const first = await stranger.answer(SCRIPT[0].input);
+  const second = await stranger.answer(SCRIPT[0].input);
+  show('> a shopper nobody connected, twice', second);
+  check('needs_card', first);
+  check('needs_card', second);
+  if (first.links[0].url !== second.links[0].url) throw new Error('expected the same Vault link both times, got two different links');
+  return { results, stranger: [first, second] };
+}
+
+/** True when node runs this file itself. Node names a module by its real path, so a symlinked start, as from an installed package, still counts. */
+function runDirectly() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+
+if (runDirectly()) {
+  const { AGENTCARD_CLIENT_ID: clientId, AGENTCARD_CLIENT_SECRET: clientSecret, AGENTCARD_BASE_URL: baseUrl } = process.env;
+  if (!clientId || !clientSecret) {
+    console.error('Set AGENTCARD_CLIENT_ID and AGENTCARD_CLIENT_SECRET to your sandbox credentials.');
+    process.exit(1);
+  }
+  walkthrough({ clientId, clientSecret, baseUrl }).then(
+    () => console.log('walkthrough passed'),
+    (error) => {
+      console.error(`walkthrough failed: ${error.message}`);
+      process.exitCode = 1;
+    },
+  );
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Give your agent one tool that buys for your shoppers at real stores, and hear what happened to each purchase from a signed webhook.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "_comment_build": "Zero runtime dependencies: node:crypto is the one import, and the buy tool calls the global fetch. TypeScript is pinned, not installed, as in @agent-cards/sdk. types/node.d.ts declares the two node:crypto functions the source calls, so the build needs no @types package and the published declarations name no Node type; FetchLike names AbortSignal, which every runtime with fetch declares.",
+    "build": "npx -y -p typescript@5.9.3 tsc",
+    "prepublishOnly": "pnpm build",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "verify:pack": "node scripts/verify-pack.mjs",
+    "_comment_pack": "verify:pack lists what npm would publish (npm pack --dry-run) and fails on a missing manifest target, README or example, or on a test, source, shim or build-cache file; then it loads the built root and checks the names the README imports. The release workflow runs it after the build."
+  },
+  "keywords": [
+    "agentcard",
+    "agents",
+    "buy",
+    "tools",
+    "webhooks",
+    "purchases"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}