@agent-cards/commerce-sdk 0.2.0 → 0.8.0

package/dist/buy-tool.js

@@ -24,8 +24,9 @@
  */
 import { AgentcardApiError, AgentcardClient, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
-import { forModel, forModelError, money, shownProducts } from './model-view.js';
+import { forModel, forModelError, money, pickId, shownProducts } from './model-view.js';
 import { toMessages } from './messages.js';
+import { ackAt, instantAck as instantAckOf, isNewRequest, nextTemplate } from './ack.js';
 /** The pause before the one read that follows a placement Agentcard is still finishing. */
 const PLACEMENT_WAIT_MS = 12_000;
 /** After a turn that outlived Agentcard's budget: one read every 5 seconds, for at most a minute. */
@@ -41,6 +42,12 @@ const RESUME_SKEW_MS = 2 * 60_000;
 const STOPPED_ORDER = new Set(['failed', 'cancelled']);
 /** The refusals a confirm gets once the order took the cart, or while the placement still runs. */
 const AFTER_PLACEMENT = new Set(['nothing_to_confirm', 'conversation_closed', 'turn_in_progress']);
+/** How long Agentcard has to answer before the instant reply goes out. */
+const ACK_DELAY_MS = 1_500;
+/** A call that starts this soon after the last one ended belongs to the same model turn, which gets one instant reply. */
+const SAME_TURN_MS = 15_000;
+/** How long after `instantAck` the model's first call still belongs to the turn it acknowledged. */
+const APP_TURN_MS = 120_000;
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
 const CARD_NEEDED = 'The shopper adds a card from a Vault link before Agentcard can buy for them.';
 const STILL_PLACING = 'The shopper approved, and the order is still going through.';
@@ -52,20 +59,37 @@ const ANSWER_LATE = "Agentcard's answer took too long to come back. Call this to
 const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shopper the cart as it stands now.';
 const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper what they want.';
 const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
+const PICK_GONE = "The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.";
+/**
+ * The pick as a later read of the conversation shows it: a pick the early answer found missing is in
+ * the cart once a line carries its catalog id, as its product id or, for a retail product whose id is
+ * its store page, as its page. A pick already in the cart, or none, stays as it was.
+ */
+function pickAfter(pick, carts) {
+    if (!pick || pick.in_cart)
+        return pick;
+    const held = carts.some((c) => c.items.some((line) => line.product_id === pick.product_id || line.url === pick.product_id));
+    return held ? { ...pick, in_cart: true } : pick;
+}
 function hashesOf(cart, carts) {
     return [...new Set([cart?.hash, ...carts.map((c) => c.hash)].filter((h) => typeof h === 'string' && h !== ''))];
 }
 function productsOf(turn) {
-    return (turn.catalog?.items ?? [])
+    return turn.catalog ? productsOfCatalog(turn.catalog) : [];
+}
+/** The products of a search, as the tool reads them. */
+function productsOfCatalog(catalog) {
+    return (catalog.items ?? [])
         .filter((item) => item.name)
         .map((item) => ({
         id: item.id,
+        ref: item.ref,
         name: item.name,
         priceCents: item.priceCents,
         currency: item.currency,
         imageUrl: item.image_url,
         ...(item.flight ? { flight: item.flight } : {}),
-        store: item.store?.name ?? item.store?.id ?? turn.catalog?.merchant_name ?? null,
+        store: item.store?.name ?? item.store?.id ?? catalog.merchant_name ?? null,
         url: item.url ?? null,
         linkSent: false,
     }));
@@ -94,6 +118,7 @@ function answerOf(turn) {
         decline_code: turn.decline_code,
         error_code: turn.error_code,
         next_action: turn.next_action,
+        pick: turn.pick,
         hashes: hashesOf(turn.cart, turn.carts),
         envelope: turn.raw,
     };
@@ -191,6 +216,7 @@ function resultOfRefusal(error) {
         decline_code: null,
         error_code: error.code,
         next_action: null,
+        pick: null,
         hashes: hashesOf(null, carts),
         envelope: error.body,
     });
@@ -202,6 +228,8 @@ function resultOfRefusal(error) {
         return answer(NOTHING_TO_CONFIRM, []);
     if (error.code === 'turn_in_progress')
         return answer(STILL_WORKING, []);
+    if (error.code === 'pick_not_found')
+        return answer(PICK_GONE, []);
     return null;
 }
 /** A shopper Agentcard has not connected to this company yet: the Vault link where they connect and add a card. */
@@ -222,6 +250,7 @@ function needsCard(link, body) {
         decline_code: null,
         error_code: 'user_not_connected',
         next_action: 'add_card',
+        pick: null,
         hashes: [],
         envelope: body,
     };
@@ -295,10 +324,103 @@ export function buyTool(options) {
         throw new TypeError('Pass sendLink as a function that delivers a link to the shopper.');
     }
     const sendLink = o.sendLink;
+    if (o.onProgress !== undefined && typeof o.onProgress !== 'function')
+        throw new TypeError('Pass onProgress as a function that takes each stage of a call.');
+    if (o.stream !== undefined && o.stream !== false)
+        throw new TypeError('Pass stream as false to wait for each whole answer, or leave it out.');
+    const onProgress = o.onProgress;
+    if (o.earlyCards !== undefined && typeof o.earlyCards !== 'boolean')
+        throw new TypeError('Pass earlyCards as true or false.');
+    const earlyCards = o.earlyCards === true && !!o.sendLink;
+    const streams = o.stream !== false && (earlyCards || !!onProgress);
+    if (o.onResult !== undefined && typeof o.onResult !== 'function') {
+        throw new TypeError('Pass onResult as a function that takes each answer.');
+    }
+    const onResult = o.onResult;
     const wait = o.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     if (typeof wait !== 'function')
         throw new TypeError('Pass wait as a function of milliseconds that resolves after the pause.');
     const who = client.company ? { externalUserId } : {};
+    if (o.onWorking !== undefined && typeof o.onWorking !== 'function')
+        throw new TypeError('Pass onWorking as a function that sends the shopper a message.');
+    if (o.ack !== undefined && o.ack !== false && typeof o.ack !== 'function')
+        throw new TypeError('Pass ack as false, or as a function that writes the instant reply from the ask.');
+    const ackDelayMs = o.ackDelayMs ?? ACK_DELAY_MS;
+    if (typeof ackDelayMs !== 'number' || !Number.isFinite(ackDelayMs) || ackDelayMs < 0)
+        throw new TypeError('Pass ackDelayMs as a number of milliseconds, 0 or more.');
+    const onWorking = o.ack === false ? undefined : o.onWorking;
+    const writeAck = typeof o.ack === 'function' ? o.ack : null;
+    /** Calls running now, when the last one ended, whether this turn's instant reply is taken, and the template it used last. */
+    let running = 0;
+    let lastEndedAt = Number.NEGATIVE_INFINITY;
+    let turnAcked = false;
+    let lastTemplate = -1;
+    /** Counts the model's turns: the calls of one turn share its number. */
+    let modelTurn = 0;
+    /** This turn's instant reply while it is being sent: every call of the turn waits for it before it hands over a link. */
+    let ackOut = null;
+    /** True once `onWorking` delivered this turn's instant reply, so the model is told not to acknowledge again. */
+    let ackDelivered = false;
+    /**
+     * The app's instant reply for the shopper's newest message, waiting for the model's first call on that
+     * message, and the step the last answer asked the shopper for. A call still running for an earlier
+     * message keeps its own turn's state.
+     */
+    let appAck = null;
+    let lastNextAction = null;
+    /** The app's own instant reply: the turn its message opens sends no `onWorking` reply. */
+    const instantAck = (shopperText) => {
+        const text = String(shopperText ?? '');
+        const said = instantAckOf(text, { nextAction: lastNextAction }) !== null;
+        // The same rotation onWorking uses, so the next reply comes from another template.
+        if (said)
+            lastTemplate = nextTemplate(lastTemplate);
+        appAck = { at: Date.now(), said };
+        return said ? ackAt(lastTemplate, text) : null;
+    };
+    /**
+     * Holds the instant reply for a new request until `ackDelayMs` passes. `cancel` stops one that has
+     * not gone out, and frees the turn's reply for a later call.
+     */
+    const holdAck = (ask) => {
+        if (!onWorking || turnAcked || !isNewRequest(ask))
+            return null;
+        turnAcked = true;
+        let held = true;
+        const timer = setTimeout(() => {
+            held = false;
+            let text;
+            if (writeAck) {
+                try {
+                    text = writeAck(ask);
+                }
+                catch {
+                    text = null;
+                }
+            }
+            else {
+                lastTemplate = nextTemplate(lastTemplate);
+                text = ackAt(lastTemplate, ask);
+            }
+            if (typeof text !== 'string' || text.trim() === '') {
+                turnAcked = false;
+                return;
+            }
+            const message = text.trim();
+            ackOut = Promise.resolve()
+                .then(() => onWorking(message))
+                .then(() => { ackDelivered = true; }, () => { });
+        }, ackDelayMs);
+        return {
+            cancel: () => {
+                if (!held)
+                    return;
+                held = false;
+                clearTimeout(timer);
+                turnAcked = false;
+            },
+        };
+    };
     /** One read of the conversation, or null when it fails: a read only ever improves an answer the tool already has. */
     const read = async (conversationId) => {
         try {
@@ -456,6 +578,8 @@ export function buyTool(options) {
                     error_code: newest ? null : base.error_code,
                     // A read replaced the answer the step was named for, and names no step of its own: the reply asks.
                     next_action: null,
+                    // The early answer judged the pick before the turn finished adding it.
+                    pick: pickAfter(base.pick, conversation.carts),
                     envelope: conversation.raw,
                 };
                 if (!conversation.turn_in_progress)
@@ -512,15 +636,21 @@ export function buyTool(options) {
         // A running turn that placed nothing may be a search rather than a placement, so the shopper hears it is still working.
         return settled.status === 'placing' && !placing ? refused : settled;
     };
-    /** The store pages this tool sent last, with their conversation. */
+    /** The store pages this tool sent last, with their conversation, the model turn that sent them, and the search they list. */
     let lastPages = null;
     /**
      * The store page of each product the model reads, sent once per page. A
      * page the last batch in this conversation already sent stays with the
-     * shopper and goes out no second time. A page whose `sendLink` throws
+     * shopper and goes out no second time, unless a later model turn's reply
+     * presents the products again (the catalog's `presented`): a repeated ask
+     * answered with the same products gets their pages beside it, so every
+     * product the reply names has a card. Calls of one model turn still send a
+     * page once. An answer that lists fewer of the same search's products, such
+     * as a pick's, keeps the pages that search already sent, so a later answer
+     * that lists them again sends none twice. A page whose `sendLink` throws
      * stays unsent, and the call goes on, so the next answer tries it again.
      */
-    const deliverPages = async (result) => {
+    const deliverPages = async (result, call) => {
         if (!sendLink)
             return result;
         const pages = new Map();
@@ -531,12 +661,21 @@ export function buyTool(options) {
         // An answer with no store page leaves the last batch as it was.
         if (pages.size === 0)
             return result;
-        const before = lastPages?.conversationId === result.conversation_id ? lastPages.urls : new Set();
-        const held = new Set();
+        const kept = lastPages?.conversationId === result.conversation_id && (!call.presented || lastPages.turn === call.turn);
+        const before = kept && lastPages ? lastPages.urls : new Set();
+        // Agentcard names the search an answer lists by when it ran. An answer that lists fewer of the same
+        // search's products, such as a pick's, keeps every page that search already sent, so a later answer
+        // that lists them again sends none twice.
+        const catalog = result.envelope?.catalog;
+        const search = typeof catalog?.as_of === 'string' ? catalog.as_of : null;
+        const sameSearch = kept && search !== null && lastPages?.search === search;
+        const held = new Set(sameSearch ? before : []);
         for (const [url, product] of pages) {
             if (!before.has(url)) {
                 try {
-                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, imageUrl: product.imageUrl, expiresAt: null });
+                    // The id the model reads and a pick takes, never the store page: the page is `url`.
+                    const productId = pickId(product);
+                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), ...(productId ? { productId } : {}), imageUrl: product.imageUrl, expiresAt: null });
                 }
                 catch {
                     continue;
@@ -544,25 +683,27 @@ export function buyTool(options) {
             }
             held.add(url);
         }
-        lastPages = { conversationId: result.conversation_id, urls: held };
+        lastPages = { conversationId: result.conversation_id, turn: call.turn, search, urls: held };
         return { ...result, products: result.products.map((product) => (product.url && held.has(product.url) ? { ...product, linkSent: true } : product)) };
     };
+    /** The products a streamed search found, as an answer the page delivery reads: its conversation, its search and its products. */
+    const earlyPages = (conversationId, asOf, products) => ({ conversation_id: conversationId, envelope: { catalog: { as_of: asOf } }, products });
     /** One batch of pages at a time: a call that overlaps another reads the pages that one sent. */
     let pagesInTurn = Promise.resolve();
-    const deliverPagesInTurn = (result) => {
-        const batch = pagesInTurn.then(() => deliverPages(result));
+    const deliverPagesInTurn = (result, call) => {
+        const batch = pagesInTurn.then(() => deliverPages(result, call));
         pagesInTurn = batch.catch(() => { });
         return batch;
     };
     /** The Vault or approval link first, because the purchase waits on it, then the store pages. */
-    const deliver = async (result) => {
+    const deliver = async (result, call) => {
         let delivered = result;
         if (result.links.length > 0 && sendLink) {
             for (const link of result.links)
                 await sendLink({ ...link });
             delivered = { ...result, link_sent: true };
         }
-        return deliverPagesInTurn(delivered);
+        return deliverPagesInTurn(delivered, call);
     };
     const answer = async (raw) => {
         const startedAt = Date.now();
@@ -572,22 +713,87 @@ export function buyTool(options) {
         const ask = input.ask.trim();
         if (!confirm && ask === '')
             throw new TypeError("Put the shopper's words in ask.");
+        // A pick chooses from the products this conversation showed: never on a confirm, and never on a new order, which shows none yet.
+        const pick = !confirm && !input.new_order && input.product_id ? { product_id: input.product_id } : null;
         const body = {
             resume: true,
             ...(confirm ? { confirm: true, payment_source: 'vault' } : { ask }),
             ...(input.new_order ? { new_order: true } : {}),
+            ...(pick ? { pick } : {}),
             ...(o.deliveryAddress ? { delivery_address: o.deliveryAddress } : {}),
             ...(client.company ? { external_user_id: externalUserId } : {}),
         };
-        let turn = null;
-        let refusal;
+        // The first call after `instantAck` opens the turn of the message it answered, whose reply is the
+        // app's. Any other call that starts while another runs, or right after one ended, is the model
+        // working through the same turn.
+        const opened = appAck && Date.now() - appAck.at < APP_TURN_MS ? appAck : null;
+        appAck = null;
+        if (opened) {
+            turnAcked = true;
+            ackOut = null;
+            ackDelivered = opened.said;
+            modelTurn += 1;
+        }
+        else if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
+            turnAcked = false;
+            ackOut = null;
+            ackDelivered = false;
+            modelTurn += 1;
+        }
+        const callTurn = modelTurn;
+        running += 1;
+        // A pick adds a product the shopper already saw, so no "looking for" reply goes out, as for "the first one".
+        const ack = confirm || pick ? null : holdAck(ask);
         try {
-            turn = await client.buy(body);
+            let turn = null;
+            let refusal;
+            // Streamed: the stages go to onProgress, and a search's store pages go out the moment it answers.
+            const handlers = streams
+                ? {
+                    ...(onProgress ? { onProgress: (progress) => { try {
+                            onProgress(progress);
+                        }
+                        catch { /* the app's display failing never fails the call */ } } } : {}),
+                    ...(earlyCards && sendLink && !confirm
+                        ? {
+                            onCatalog: async (update) => {
+                                // Products arrived before the instant reply was due: they are the reply.
+                                ack?.cancel();
+                                await ackOut;
+                                // The turn's own search presents its products, as a reply that lists them does.
+                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, productsOfCatalog(update.catalog)), { turn: callTurn, presented: true });
+                            },
+                        }
+                        : {}),
+                }
+                : undefined;
+            try {
+                turn = await client.buy(body, handlers);
+            }
+            catch (error) {
+                refusal = error;
+            }
+            ack?.cancel();
+            const settled = turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt);
+            await ackOut;
+            const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true });
+            const result = ackDelivered ? { ...delivered, shopper_already_told_looking: true } : delivered;
+            lastNextAction = result.next_action;
+            if (onResult) {
+                try {
+                    await onResult(result);
+                }
+                catch {
+                    // The app's display failing never fails the purchase call.
+                }
+            }
+            return result;
         }
-        catch (error) {
-            refusal = error;
+        finally {
+            ack?.cancel();
+            running -= 1;
+            lastEndedAt = Date.now();
         }
-        return deliver(withMessages(turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt), turn));
     };
     /** Checks the model's input, with every link taken out of a refusal. */
     const parse = (input) => {
@@ -608,7 +814,7 @@ export function buyTool(options) {
         }
     };
     const { name, description, input_schema } = buyToolDefinition();
-    const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer, forModel };
+    const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer, forModel, instantAck };
     // JSON skips these three, so a runner that sends the tool to its API as is sends Anthropic's fields and nothing else.
     const unsent = (value) => ({ value, enumerable: false, writable: true, configurable: true });
     return Object.defineProperties(tool, {

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;
@@ -51,6 +92,13 @@ export interface BuyRequest {
     resume?: true;
     /** Drop the cart on the table and start a new order. */
     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`.
+     */
+    pick?: {
+        product_id: string;
+    };
     payment_source?: 'vault';
     delivery_address?: BuyDeliveryAddress;
     external_user_id?: string;
@@ -101,6 +149,8 @@ export interface BuyFlightItinerary {
 export interface BuyCatalogItem {
     flight?: BuyFlightItinerary;
     id: string;
+    /** The item's id with no link in it, which `pick.product_id` takes as it takes `id`; null from an older API. */
+    ref: string | null;
     name: string | null;
     priceCents: number | null;
     /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
@@ -110,11 +160,22 @@ 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 {
+    product_id: string;
+    ref: string | null;
+    in_cart: boolean;
 }
 export interface BuyPaymentSource {
     source: string;
@@ -160,6 +221,8 @@ export interface BuyTurn {
     store_login_expires_at: string | null;
     /** The store that page signs in to. */
     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 answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -211,7 +274,7 @@ export interface VaultLink {
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
  * (`user_not_connected`, `external_user_id_ambiguous`, `turn_in_progress`,
- * `user_id_mismatch`), one read from the shape of the answer
+ * `user_id_mismatch`, `pick_not_found`), one read from the shape of the answer
  * (`cart_changed`, `nothing_to_confirm`, `conversation_closed`,
  * `conversation_not_found`), or the client's (`unreachable`, `timeout`,
  * `oauth_failed`, `unauthorized`, `http_<status>`). `status` is 0 when
@@ -243,15 +306,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>;
     /**
@@ -262,6 +328,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;