@agent-cards/commerce-sdk 0.5.0 → 0.9.0

package/dist/client.d.ts

@@ -1,14 +1,55 @@
+import { type AgentcardListener, type ListenOptions } from './listen.js';
 /** The fetch the client calls: Node 18 and later have one built in. */
 export type FetchLike = (url: string, init: {
     method: string;
     headers: Record<string, string>;
     body?: string;
     signal?: AbortSignal;
-}) => Promise<{
+}) => Promise<FetchLikeResponse>;
+/**
+ * The answer a fetch returns, as far as the client reads it. `headers` and `body` are optional: a
+ * fetch without them is read whole with `text()`, and a streamed purchase answer still arrives, at its end.
+ */
+export interface FetchLikeResponse {
     status: number;
     ok: boolean;
     text(): Promise<string>;
-}>;
+    headers?: {
+        get(name: string): string | null;
+    } | null;
+    body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel?(): Promise<void>;
+        };
+    } | null;
+}
+/**
+ * What the purchase turn is doing while it runs: `searching` the stores, `building_cart`, `checking_out`,
+ * or `working` on anything else. Agentcard names only the stage, never what the shopper said.
+ */
+export type BuyProgressStage = 'searching' | 'building_cart' | 'checking_out' | 'working';
+/** One step of a running purchase turn. */
+export interface BuyProgress {
+    stage: BuyProgressStage;
+    conversationId: string | null;
+}
+/** The products a running turn's search found, sent the moment the search answers and before the reply is written. */
+export interface BuyCatalogUpdate {
+    conversationId: string;
+    catalog: BuyCatalog;
+    /** When the search ran, as the answer's `catalog.as_of` names it: the same search in the answer has the same value. */
+    asOf: string | null;
+}
+/** Called while a purchase turn runs. Passing either one asks Agentcard to stream the turn. */
+export interface BuyStreamHandlers {
+    onProgress?: (progress: BuyProgress) => void;
+    /** The client waits for what this returns before it hands back the turn's answer. */
+    onCatalog?: (update: BuyCatalogUpdate) => void | Promise<void>;
+}
 export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
 export declare const BUY_TURN_TIMEOUT_MS = 130000;
@@ -53,10 +94,14 @@ export interface BuyRequest {
     new_order?: true;
     /**
      * The product the shopper picked from the last search's `catalog.items`, by its `id` or its `ref`:
-     * Agentcard adds exactly that item, with no new search. Goes with an `ask`, never with `confirm` or `new_order`.
+     * Agentcard adds exactly that item, with no new search. Or the store the shopper picked from the last
+     * answer's `stores.items`, by its `id`: Agentcard selects exactly that store before the turn runs.
+     * Goes with an `ask`, never with `confirm` or `new_order`.
      */
     pick?: {
         product_id: string;
+    } | {
+        store_id: string;
     };
     payment_source?: 'vault';
     delivery_address?: BuyDeliveryAddress;
@@ -119,11 +164,16 @@ export interface BuyCatalogItem {
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
 }
-/** The products the last search found. */
+/**
+ * The products the last search found. `presented` is true when this answer's reply presents them: the
+ * turn searched, or answered a repeated ask from the results it already held. False when they only
+ * stand from an earlier answer, and on an older API.
+ */
 export interface BuyCatalog {
     merchant: string;
     merchant_name: string;
     items: BuyCatalogItem[];
+    presented: boolean;
 }
 /** The product a `pick` named, by its catalog id and ref, and whether the cart now holds it. */
 export interface BuyPick {
@@ -131,6 +181,30 @@ export interface BuyPick {
     ref: string | null;
     in_cart: boolean;
 }
+/**
+ * One store a delivery store search found that the answer's reply names. `id` holds no link and is what
+ * `pick.store_id` takes; `store_page_url` is the store's page at the merchant. `eta_minutes` is the
+ * merchant's delivery estimate, or null when it showed none.
+ */
+export interface BuyStoreChoice {
+    id: string;
+    name: string;
+    store_page_url: string | null;
+    eta_minutes: number | null;
+}
+/** The stores an answer's reply presents to choose from, at most three, in the order the reply names them. */
+export interface BuyStores {
+    merchant: string;
+    merchant_name: string;
+    items: BuyStoreChoice[];
+    as_of: string | null;
+}
+/** The store a store pick named, and whether Agentcard selected it before the turn ran. */
+export interface BuyStorePick {
+    store_id: string;
+    name: string | null;
+    selected: boolean;
+}
 export interface BuyPaymentSource {
     source: string;
     brand: string | null;
@@ -177,6 +251,10 @@ export interface BuyTurn {
     store_login_merchant_name: string | null;
     /** The product this turn's `pick` named, and whether the cart holds it; null for a turn without one. */
     pick: BuyPick | null;
+    /** The stores this answer's reply presents to choose from; null when it presents none, and on an older API. */
+    stores: BuyStores | null;
+    /** The store this turn's `pick.store_id` named, or an answer such as `the second one` picked; null without one. */
+    store_pick: BuyStorePick | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -260,15 +338,18 @@ export declare class AgentcardClient {
     get company(): boolean;
     /** True for a sandbox client, as the token exchange said; null until the first exchange, and under a shopper's token. */
     get sandbox(): boolean | null;
-    /** The access token the client sends: the shopper's own, or the company's, exchanged once and renewed a minute before it expires. */
-    bearer(): Promise<string>;
+    /**
+     * The access token the client sends: the shopper's own, or the company's, exchanged once and
+     * renewed a minute before it expires. Pass a company token Agentcard refused to get a new one.
+     */
+    bearer(refused?: string): Promise<string>;
     /**
      * One purchase turn, sent once with a 130-second wait. A turn is a model run
      * against live stores, so a lost answer is never sent again: read the
      * conversation instead. Only a 401 is sent again, once, with a fresh token,
      * because Agentcard refused it before anything ran.
      */
-    buy(body: BuyRequest): Promise<BuyTurn>;
+    buy(body: BuyRequest, stream?: BuyStreamHandlers): Promise<BuyTurn>;
     /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
     conversation(conversationId: string, who?: Shopper): Promise<BuyConversation>;
     /**
@@ -279,6 +360,11 @@ export declare class AgentcardClient {
     mintVaultLink(input: {
         externalUserId: string;
     }): Promise<VaultLink>;
+    /**
+     * Hear every event Agentcard sends your company over one connection your server opens, with no
+     * webhook endpoint: `listenToAgentcard(this, opts)`. Takes your company credentials.
+     */
+    listen(opts: ListenOptions): AgentcardListener;
     /** A company names the shopper exactly once; a shopper's own token already names them. */
     private checkShopper;
     private call;

package/dist/client.js

@@ -9,6 +9,8 @@
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
 import { isRecord } from './verify.js';
+import { listenToAgentcard } from './listen.js';
+const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
 export const BUY_TURN_TIMEOUT_MS = 130_000;
@@ -128,7 +130,19 @@ function catalogOf(v) {
             url: pageUrl(i.url),
         };
     }) : [];
-    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items };
+    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+}
+/** The stores an answer presents: each one with an id and a name, and no block when none has both. */
+function storesOf(v) {
+    if (!isRecord(v) || !Array.isArray(v.items))
+        return null;
+    const items = v.items.filter(isRecord).flatMap((i) => {
+        const id = str(i.id);
+        const name = str(i.name);
+        const eta = num(i.eta_minutes);
+        return id && name ? [{ id, name, store_page_url: pageUrl(i.store_page_url), eta_minutes: eta }] : [];
+    });
+    return items.length ? { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, as_of: str(v.as_of) } : null;
 }
 function paymentSourceOf(v) {
     return isRecord(v) && str(v.source) ? { source: v.source, brand: str(v.brand), last4: str(v.last4) } : null;
@@ -163,6 +177,8 @@ export function turnOf(body) {
         store_login_merchant_name: str(body.store_login_merchant_name),
         next_action: typeof body.next_action === 'string' && NEXT_ACTIONS.has(body.next_action) ? body.next_action : null,
         pick: isRecord(body.pick) && str(body.pick.product_id) ? { product_id: body.pick.product_id, ref: str(body.pick.ref), in_cart: body.pick.in_cart === true } : null,
+        stores: storesOf(body.stores),
+        store_pick: isRecord(body.store_pick) && str(body.store_pick.store_id) ? { store_id: body.store_pick.store_id, name: str(body.store_pick.name), selected: body.store_pick.selected === true } : null,
         raw: body,
     };
 }
@@ -255,6 +271,106 @@ function parseJson(text) {
         return null;
     }
 }
+/** Each event of a server-sent stream, in order, read as it arrives, or from the whole text when the fetch hands no stream. */
+async function eachEvent(res, onEvent) {
+    let buffer = '';
+    // True once onEvent says the stream is over.
+    let over = false;
+    const drain = (final) => {
+        buffer = buffer.replace(/\r\n?/g, '\n');
+        for (let end = buffer.indexOf('\n\n'); end >= 0 || (final && buffer.trim() !== ''); end = buffer.indexOf('\n\n')) {
+            const block = end >= 0 ? buffer.slice(0, end) : buffer;
+            buffer = end >= 0 ? buffer.slice(end + 2) : '';
+            let event = 'message';
+            const data = [];
+            for (const line of block.split('\n')) {
+                if (line.startsWith('event:'))
+                    event = line.slice(6).trim();
+                else if (line.startsWith('data:'))
+                    data.push(line.slice(5).replace(/^ /, ''));
+            }
+            if (data.length > 0 && onEvent(event, data.join('\n')) === true) {
+                over = true;
+                return;
+            }
+        }
+    };
+    const reader = res.body?.getReader?.();
+    if (!reader) {
+        buffer = await res.text();
+        drain(true);
+        return;
+    }
+    const decoder = new TextDecoder();
+    try {
+        while (!over) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            buffer += decoder.decode(chunk.value, { stream: true });
+            drain(false);
+        }
+        if (!over)
+            drain(true);
+    }
+    finally {
+        if (over)
+            reader.cancel?.().catch(() => { });
+    }
+}
+/**
+ * A streamed purchase turn, read to its `envelope`: the same answer a JSON turn returns, with its
+ * status in `http_status`. Each `progress` and `catalog` goes to its handler on the way. A stream that
+ * breaks or ends before its envelope, once it named the conversation, reads as a turn past its budget
+ * (`turn_timeout`), so the tool reads the conversation for what the turn left instead of losing it.
+ */
+async function readStreamedTurn(res, stream, timeoutMs) {
+    let envelope = null;
+    let conversationId = null;
+    const delivering = [];
+    let failure = null;
+    try {
+        await eachEvent(res, (event, text) => {
+            const data = parseJson(text);
+            if (!data)
+                return;
+            conversationId = str(data.conversation_id) ?? conversationId;
+            if (event === 'envelope') {
+                envelope = data;
+                return true;
+            }
+            if (event === 'progress' && typeof data.stage === 'string' && PROGRESS_STAGES.has(data.stage) && stream.onProgress) {
+                try {
+                    stream.onProgress({ stage: data.stage, conversationId: str(data.conversation_id) });
+                }
+                catch {
+                    // The app's display failing never fails the turn.
+                }
+            }
+            else if (event === 'catalog' && stream.onCatalog && str(data.conversation_id)) {
+                const catalog = catalogOf(data.catalog);
+                if (!catalog || catalog.items.length === 0)
+                    return;
+                const asOf = isRecord(data.catalog) ? str(data.catalog.as_of) : null;
+                delivering.push(Promise.resolve().then(() => stream.onCatalog({ conversationId: data.conversation_id, catalog, asOf })).catch(() => { }));
+            }
+        });
+    }
+    catch (error) {
+        failure = error;
+    }
+    await Promise.all(delivering);
+    const answered = envelope;
+    if (answered) {
+        const { http_status: httpStatus, ...body } = answered;
+        const status = typeof httpStatus === 'number' ? httpStatus : res.status;
+        return { status, ok: status >= 200 && status < 300, readable: true, body };
+    }
+    if (conversationId) {
+        return { status: 200, ok: true, readable: true, body: { conversation_id: conversationId, status: 'needs_input', reply: '', error_code: 'turn_timeout' } };
+    }
+    throw failure ? failureOf(failure, timeoutMs) : new AgentcardApiError(0, 'unreachable', 'Agentcard closed the purchase answer before it ended.');
+}
 /** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */
 export class AgentcardClient {
     baseUrl;
@@ -291,10 +407,15 @@ export class AgentcardClient {
     get sandbox() {
         return this.learnedSandbox;
     }
-    /** The access token the client sends: the shopper's own, or the company's, exchanged once and renewed a minute before it expires. */
-    async bearer() {
+    /**
+     * The access token the client sends: the shopper's own, or the company's, exchanged once and
+     * renewed a minute before it expires. Pass a company token Agentcard refused to get a new one.
+     */
+    async bearer(refused) {
         if (this.shopperToken !== null)
             return this.shopperToken;
+        if (refused !== undefined)
+            return this.renewAfter(refused);
         if (this.token && Date.now() < this.token.expiresAt)
             return this.token.value;
         if (!this.inflight)
@@ -307,11 +428,14 @@ export class AgentcardClient {
      * conversation instead. Only a 401 is sent again, once, with a fresh token,
      * because Agentcard refused it before anything ran.
      */
-    async buy(body) {
+    async buy(body, stream) {
         if (!isRecord(body))
             throw new TypeError('Pass the purchase request as an object, such as { ask: "two AA battery packs" }.');
         this.checkShopper({ externalUserId: body.external_user_id, userId: body.user_id });
-        return turnOf(await this.call('POST', '/buy', body, BUY_TURN_TIMEOUT_MS));
+        const streamed = !!stream && (typeof stream.onProgress === 'function' || typeof stream.onCatalog === 'function');
+        // A streamed turn keeps the soft budget a JSON turn has, so it answers within BUY_TURN_TIMEOUT_MS too.
+        const path = streamed ? '/buy?stream=1&soft_timeout=1' : '/buy';
+        return turnOf(await this.call('POST', path, body, BUY_TURN_TIMEOUT_MS, streamed ? stream : undefined));
     }
     /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
     async conversation(conversationId, who = {}) {
@@ -339,6 +463,13 @@ export class AgentcardClient {
             throw new AgentcardApiError(200, 'invalid_answer', 'Agentcard answered the Vault link request without a link.', answer);
         return { id: str(answer.id) ?? '', url, expiresAt: str(answer.expires_at), reused: answer.reused === true };
     }
+    /**
+     * Hear every event Agentcard sends your company over one connection your server opens, with no
+     * webhook endpoint: `listenToAgentcard(this, opts)`. Takes your company credentials.
+     */
+    listen(opts) {
+        return listenToAgentcard(this, opts);
+    }
     /** A company names the shopper exactly once; a shopper's own token already names them. */
     checkShopper(who) {
         const named = [who.externalUserId, who.userId].filter((v) => v !== undefined);
@@ -351,10 +482,10 @@ export class AgentcardClient {
             throw new TypeError('Name the shopper once: externalUserId, your own id for them, or userId, the Agentcard user id.');
         }
     }
-    async call(method, path, body, timeoutMs) {
+    async call(method, path, body, timeoutMs, stream) {
         let token = await this.bearer();
         for (let attempt = 0;; attempt++) {
-            const answer = await this.send(method, path, token, body, timeoutMs);
+            const answer = await this.send(method, path, token, body, timeoutMs, stream);
             if (answer.status === 401 && attempt === 0 && this.credentials) {
                 token = await this.renewAfter(token);
                 continue;
@@ -372,24 +503,39 @@ export class AgentcardClient {
             throw errorOf(answer.status, answer.body);
         }
     }
-    async send(method, path, token, body, timeoutMs) {
+    async send(method, path, token, body, timeoutMs, stream) {
+        let res;
         try {
-            const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+            res = await this.fetchFn(`${this.baseUrl}${path}`, {
                 method,
                 headers: {
                     authorization: `Bearer ${token}`,
-                    accept: 'application/json',
+                    accept: stream ? 'text/event-stream, application/json' : 'application/json',
                     ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
                 },
                 ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
                 signal: AbortSignal.timeout(timeoutMs),
             });
-            const parsed = parseJson(await res.text());
-            return { status: res.status, ok: res.ok, readable: parsed !== null, body: parsed ?? {} };
         }
         catch (error) {
             throw failureOf(error, timeoutMs);
         }
+        // Agentcard streams only once the turn starts: a refusal before it is plain JSON.
+        if (stream && /text\/event-stream/i.test(res.headers?.get?.('content-type') ?? ''))
+            return readStreamedTurn(res, stream, timeoutMs);
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (error) {
+            throw failureOf(error, timeoutMs);
+        }
+        const parsed = parseJson(text);
+        // A fetch that hands no headers still carries a streamed answer in its text: read it whole.
+        if (stream && parsed === null && /^(?:event|data):/m.test(text)) {
+            return readStreamedTurn({ status: res.status, ok: res.ok, text: async () => text }, stream, timeoutMs);
+        }
+        return { status: res.status, ok: res.ok, readable: parsed !== null, body: parsed ?? {} };
     }
     /** After a 401: the token another call already renewed, or one new exchange, however many calls were refused at once. */
     async renewAfter(refused) {

package/dist/definition.d.ts

@@ -1,7 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with four required fields, `product_id` null unless the shopper
- * picks a product they were shown. The delivery address and the
+ * JSON Schema with five required fields, `product_id` null unless the shopper
+ * picks a product they were shown and `store_id` null unless they pick a store. The delivery address and the
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
@@ -9,8 +9,9 @@ export declare const BUY_TOOL_NAME = "buy";
 /** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
 export declare const BUY_TOOL_DESCRIPTION: string;
 /**
- * What the model sends: `ask`, `confirm` and `new_order` every time, and `product_id`, null unless the
- * shopper picks a product from the last result. Your own code may leave `product_id` out.
+ * What the model sends: `ask`, `confirm` and `new_order` every time, `product_id`, null unless the
+ * shopper picks a product from the last result, and `store_id`, null unless they pick a store from it.
+ * Your own code may leave `product_id` and `store_id` out.
  */
 export interface BuyToolInput {
     ask: string;
@@ -18,6 +19,8 @@ export interface BuyToolInput {
     new_order: boolean;
     /** The `product_id` of the product the shopper picked from the last result's `products`, or null. */
     product_id?: string | null;
+    /** The `store_id` of the store the shopper picked from the last result's `stores`, or null. */
+    store_id?: string | null;
 }
 /** A type, not an interface, so it fits the SDKs' own input schema types, which take any key. */
 export type BuyToolInputSchema = {
@@ -39,6 +42,10 @@ export type BuyToolInputSchema = {
             type: ['string', 'null'];
             description: string;
         };
+        store_id: {
+            type: ['string', 'null'];
+            description: string;
+        };
     };
     required: Array<keyof BuyToolInput>;
     additionalProperties: false;
@@ -52,8 +59,9 @@ export interface BuyToolDefinition {
 export declare function buyToolDefinition(): BuyToolDefinition;
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
- * string, null or left out, and nothing else. Throws a TypeError whose message
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` and
+ * `store_id` each a string, null or left out, at most one of them set, and
+ * nothing else. Throws a TypeError whose message
  * tells the model what to send.
  */
 export declare function parseBuyToolInput(value: unknown): BuyToolInput;

package/dist/definition.js

@@ -1,7 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with four required fields, `product_id` null unless the shopper
- * picks a product they were shown. The delivery address and the
+ * JSON Schema with five required fields, `product_id` null unless the shopper
+ * picks a product they were shown and `store_id` null unless they pick a store. The delivery address and the
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
@@ -11,6 +11,7 @@ export const BUY_TOOL_DESCRIPTION = [
     'Buy what this shopper asks for at real stores.',
     "Put the shopper's own words in `ask`.",
     'Tell the shopper what `reply` says, in your own voice.',
+    "When `shopper_already_told_looking` is true, the shopper was already told you are working on their request, so never acknowledge it again: open with the answer or the question.",
     'Show the shopper the cart before you confirm it.',
     'Ask the shopper for exactly one thing per message: the step `next_action` names, even when `reply` lists more. Never mention a later step, and never ask for the next one until the shopper has done this one.',
     'Set `confirm` to true only when the shopper just said yes to the cart in your last result, says they added the card for a cart that waits, says they approved, or asks for the approval link again.',
@@ -24,6 +25,8 @@ export const BUY_TOOL_DESCRIPTION = [
     "After `needs_card` with no cart, call this tool again with the shopper's request once they say they added a card.",
     'Set `new_order` to true only when the shopper drops the cart.',
     "When the shopper picks one of the `products` in your last result, by its name, its place in the list or a tap that names it, set `product_id` to that product's `product_id`, so Agentcard adds exactly that product; otherwise set it to null.",
+    "When the shopper picks one of the `stores` in your last result, by its name, its place in the list or a tap that names it, set `store_id` to that store's `store_id`, so Agentcard orders from exactly that store; otherwise set it to null. Never set both `product_id` and `store_id`.",
+    'Store links reach the shopper on their own, beside your reply, as product links do: `store_links_sent` says how many.',
     'When `pick.in_cart` is false, the product the shopper picked is not in the cart: tell the shopper what `reply` says, and never ask them to confirm the cart.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
@@ -44,17 +47,22 @@ export function buyToolDefinition() {
                     type: ['string', 'null'],
                     description: "The `product_id` of the product the shopper picked from the `products` in your last result. Null when they picked none.",
                 },
+                store_id: {
+                    type: ['string', 'null'],
+                    description: 'The `store_id` of the store the shopper picked from the `stores` in your last result. Null when they picked none.',
+                },
             },
-            required: ['ask', 'confirm', 'new_order', 'product_id'],
+            required: ['ask', 'confirm', 'new_order', 'product_id', 'store_id'],
             additionalProperties: false,
         },
     };
 }
-const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id']);
+const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id', 'store_id']);
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
- * string, null or left out, and nothing else. Throws a TypeError whose message
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` and
+ * `store_id` each a string, null or left out, at most one of them set, and
+ * nothing else. Throws a TypeError whose message
  * tells the model what to send.
  */
 export function parseBuyToolInput(value) {
@@ -73,7 +81,7 @@ export function parseBuyToolInput(value) {
     const fields = input;
     const extra = Object.keys(fields).find((key) => !FIELDS.has(key));
     if (extra !== undefined)
-        throw new TypeError(`The buy tool takes only ask, confirm, new_order and product_id, and ${extra} is not one of them.`);
+        throw new TypeError(`The buy tool takes only ask, confirm, new_order, product_id and store_id, and ${extra} is not one of them.`);
     if (typeof fields.ask !== 'string')
         throw new TypeError("Set ask to the shopper's words, as a string.");
     if (typeof fields.confirm !== 'boolean')
@@ -84,7 +92,15 @@ export function parseBuyToolInput(value) {
     if (productId !== undefined && productId !== null && typeof productId !== 'string') {
         throw new TypeError("Set product_id to the picked product's product_id, as a string, or to null.");
     }
-    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order, product_id: typeof productId === 'string' && productId.trim() !== '' ? productId.trim() : null };
+    const storeId = fields.store_id;
+    if (storeId !== undefined && storeId !== null && typeof storeId !== 'string') {
+        throw new TypeError("Set store_id to the picked store's store_id, as a string, or to null.");
+    }
+    const product = typeof productId === 'string' && productId.trim() !== '' ? productId.trim() : null;
+    const store = typeof storeId === 'string' && storeId.trim() !== '' ? storeId.trim() : null;
+    if (product && store)
+        throw new TypeError('Set product_id or store_id for the one thing the shopper picked, and the other to null.');
+    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order, product_id: product, store_id: store };
 }
 /** A fresh copy of the tool in OpenAI's function-calling format: plain JSON, so an SDK that sends it as is sends exactly this. */
 export function openAIBuyTool() {

package/dist/events.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every event type Agentcard sends a company, the same list a webhook endpoint subscribes to by
+ * name. The stream (`agentcard.listen`) and a webhook endpoint carry the same types, with the same
+ * envelope and the same ids. A test holds this list to the backend's catalog.
+ */
+export declare const AGENTCARD_EVENT_TYPES: readonly ["card.created", "card.updated", "card.closed", "cardholder.created", "cardholder.updated", "transaction.authorized", "transaction.declined", "transaction.cleared", "transaction.voided", "balance.low", "cardholder_onboarding_session.completed", "platform_connect_session.completed", "merchant.connected", "order.placed", "order.confirmed", "order.failed", "order.updated", "purchase.message", "connection.created", "connected_card.updated", "vault.card_stored", "vault.session_linked", "vault.session_card_picked", "vault.payment_permission.updated", "action.confirmed", "action.done", "checkout_authorization.approved", "checkout_authorization.submitted", "checkout_authorization.declined", "checkout_authorization.cancelled", "checkout_authorization.expired", "checkout_authorization.duplicate_charge", "checkout_authorization.refused", "checkout_authorization.watched", "checkout_authorization.amount_mismatch", "checkout_authorization.settled", "checkout_authorization.settlement_unconfirmed", "checkout_authorization.outcome_reported", "card_flow.started", "card_flow.failed", "transfer.approved", "transfer.initiated", "transfer.completed", "transfer.failed", "transfer.released", "wallet.funded", "user_wallet.funding_detected", "user_wallet.funded", "wallet.balance.low", "recovery.requested", "recovery.completed", "recovery.rejected", "wallet.withdrawal.initiated", "wallet.withdrawal.completed", "wallet.withdrawal.failed", "identity.verification.updated", "approval.requested", "reward.earned", "reward.reversed", "wallet_link.opened"];
+/** One event type Agentcard sends. A type Agentcard adds later still reads as its own name. */
+export type AgentcardEventType = (typeof AGENTCARD_EVENT_TYPES)[number];
+/** Whether a filter entry names something Agentcard sends: an event type, a family such as `order.*`, or `*`. */
+export declare function isEventPattern(pattern: string): boolean;
+/** Whether an event type matches a filter entry, as a webhook subscription matches it. */
+export declare function matchesEventPattern(type: string, pattern: string): boolean;

package/dist/events.js

@@ -0,0 +1,79 @@
+/**
+ * Every event type Agentcard sends a company, the same list a webhook endpoint subscribes to by
+ * name. The stream (`agentcard.listen`) and a webhook endpoint carry the same types, with the same
+ * envelope and the same ids. A test holds this list to the backend's catalog.
+ */
+export const AGENTCARD_EVENT_TYPES = [
+    'card.created',
+    'card.updated',
+    'card.closed',
+    'cardholder.created',
+    'cardholder.updated',
+    'transaction.authorized',
+    'transaction.declined',
+    'transaction.cleared',
+    'transaction.voided',
+    'balance.low',
+    'cardholder_onboarding_session.completed',
+    'platform_connect_session.completed',
+    'merchant.connected',
+    'order.placed',
+    'order.confirmed',
+    'order.failed',
+    'order.updated',
+    'purchase.message',
+    'connection.created',
+    'connected_card.updated',
+    'vault.card_stored',
+    'vault.session_linked',
+    'vault.session_card_picked',
+    'vault.payment_permission.updated',
+    'action.confirmed',
+    'action.done',
+    'checkout_authorization.approved',
+    'checkout_authorization.submitted',
+    'checkout_authorization.declined',
+    'checkout_authorization.cancelled',
+    'checkout_authorization.expired',
+    'checkout_authorization.duplicate_charge',
+    'checkout_authorization.refused',
+    'checkout_authorization.watched',
+    'checkout_authorization.amount_mismatch',
+    'checkout_authorization.settled',
+    'checkout_authorization.settlement_unconfirmed',
+    'checkout_authorization.outcome_reported',
+    'card_flow.started',
+    'card_flow.failed',
+    'transfer.approved',
+    'transfer.initiated',
+    'transfer.completed',
+    'transfer.failed',
+    'transfer.released',
+    'wallet.funded',
+    'user_wallet.funding_detected',
+    'user_wallet.funded',
+    'wallet.balance.low',
+    'recovery.requested',
+    'recovery.completed',
+    'recovery.rejected',
+    'wallet.withdrawal.initiated',
+    'wallet.withdrawal.completed',
+    'wallet.withdrawal.failed',
+    'identity.verification.updated',
+    'approval.requested',
+    'reward.earned',
+    'reward.reversed',
+    'wallet_link.opened',
+];
+const KNOWN = new Set(AGENTCARD_EVENT_TYPES);
+const FAMILIES = new Set(AGENTCARD_EVENT_TYPES.map((t) => `${t.split('.')[0]}.*`));
+/** Whether a filter entry names something Agentcard sends: an event type, a family such as `order.*`, or `*`. */
+export function isEventPattern(pattern) {
+    return pattern === '*' || KNOWN.has(pattern) || FAMILIES.has(pattern);
+}
+/** Whether an event type matches a filter entry, as a webhook subscription matches it. */
+export function matchesEventPattern(type, pattern) {
+    if (pattern === '*' || pattern === type)
+        return true;
+    return pattern.endsWith('.*') && type.startsWith(pattern.slice(0, -1));
+}