@agent-cards/commerce-sdk 0.2.0 → 0.8.0

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;
@@ -20,7 +22,7 @@ const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'add_card', '
 /**
  * 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
@@ -118,6 +120,7 @@ function catalogOf(v) {
         const flight = flightOf(i.flight);
         return {
             id: str(i.id) ?? '',
+            ref: str(i.ref),
             name: str(i.name),
             priceCents: num(i.priceCents),
             currency: str(i.currency),
@@ -127,7 +130,7 @@ 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 };
 }
 function paymentSourceOf(v) {
     return isRecord(v) && str(v.source) ? { source: v.source, brand: str(v.brand), last4: str(v.last4) } : null;
@@ -161,6 +164,7 @@ export function turnOf(body) {
         store_login_expires_at: str(body.store_login_expires_at),
         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,
         raw: body,
     };
 }
@@ -253,6 +257,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;
@@ -289,10 +393,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)
@@ -305,11 +414,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 = {}) {
@@ -337,6 +449,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);
@@ -349,10 +468,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;
@@ -370,24 +489,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,17 +1,23 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with three required fields. The delivery address and the
+ * JSON Schema with four required fields, `product_id` null unless the shopper
+ * picks a product they were shown. 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.
  */
 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: all three fields, every time. */
+/**
+ * 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.
+ */
 export interface BuyToolInput {
     ask: string;
     confirm: boolean;
     new_order: boolean;
+    /** The `product_id` of the product the shopper picked from the last result's `products`, or null. */
+    product_id?: string | null;
 }
 /** A type, not an interface, so it fits the SDKs' own input schema types, which take any key. */
 export type BuyToolInputSchema = {
@@ -29,6 +35,10 @@ export type BuyToolInputSchema = {
             type: 'boolean';
             description: string;
         };
+        product_id: {
+            type: ['string', 'null'];
+            description: string;
+        };
     };
     required: Array<keyof BuyToolInput>;
     additionalProperties: false;
@@ -42,8 +52,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 and `confirm` and `new_order` booleans, and nothing
- * else. Throws a TypeError whose message tells the model what to send.
+ * 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
+ * tells the model what to send.
  */
 export declare function parseBuyToolInput(value: unknown): BuyToolInput;
 /** The buy tool in OpenAI's function-calling format, which the OpenAI SDK, OpenRouter's chat API and most other model APIs take. */

package/dist/definition.js

@@ -1,6 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with three required fields. The delivery address and the
+ * JSON Schema with four required fields, `product_id` null unless the shopper
+ * picks a product they were shown. 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.
  */
@@ -10,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.',
@@ -22,6 +24,8 @@ export const BUY_TOOL_DESCRIPTION = [
     'After `needs_card` with a cart, Agentcard keeps the cart, so set `confirm` to true once the shopper says they added the card.',
     "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 `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. */
 export function buyToolDefinition() {
@@ -37,17 +41,22 @@ export function buyToolDefinition() {
                     description: '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. False otherwise.',
                 },
                 new_order: { type: 'boolean', description: 'True only when the shopper drops the cart to start a new order. False otherwise.' },
+                product_id: {
+                    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.",
+                },
             },
-            required: ['ask', 'confirm', 'new_order'],
+            required: ['ask', 'confirm', 'new_order', 'product_id'],
             additionalProperties: false,
         },
     };
 }
-const FIELDS = new Set(['ask', 'confirm', 'new_order']);
+const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id']);
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * with `ask` a string and `confirm` and `new_order` booleans, and nothing
- * else. Throws a TypeError whose message tells the model what to send.
+ * 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
+ * tells the model what to send.
  */
 export function parseBuyToolInput(value) {
     let input = value;
@@ -65,14 +74,18 @@ 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 and new_order, and ${extra} is not one of them.`);
+        throw new TypeError(`The buy tool takes only ask, confirm, new_order and product_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')
         throw new TypeError('Set confirm to true or false.');
     if (typeof fields.new_order !== 'boolean')
         throw new TypeError('Set new_order to true or false.');
-    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order };
+    const productId = fields.product_id;
+    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 };
 }
 /** 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));
+}

package/dist/handler.d.ts

@@ -1,11 +1,13 @@
 /**
- * A Node or Express `(req, res)` handler for an Agentcard webhook endpoint. It
- * reads the raw bytes, checks the signature, hands the event to your callback,
- * and answers once the callback is done: 200 when it returns, 500 when it
- * throws, so Agentcard delivers the event again instead of losing it.
+ * Handlers for an Agentcard webhook endpoint, for a Node or Express `(req, res)`
+ * route and for a route that takes a web `Request`, such as a Next.js route
+ * handler. Each reads the raw bytes, checks the signature, hands the event to
+ * your callback, and answers once the callback is done: 200 when it returns,
+ * 500 when it throws, so Agentcard delivers the event again instead of losing it.
  */
 import { type AgentcardEvent, type VerifyOptions } from './verify.js';
 import { type PurchaseMessage } from './message.js';
+import { type ShopperMessage } from './shopper-message.js';
 /** The parts of a Node or Express request the handler reads. */
 export interface WebhookRequest {
     headers: Record<string, string | string[] | undefined>;
@@ -35,6 +37,23 @@ export interface PurchaseAgentWebhookOptions extends Pick<VerifyOptions, 'tolera
      */
     onError?: (error: unknown, event: AgentcardEvent | undefined) => void | Promise<void>;
 }
+/** The parts of a web `Request` the fetch handler reads. */
+export interface WebhookFetchRequest {
+    headers: {
+        get(name: string): string | null;
+    };
+    /** The body as a stream, read chunk by chunk so a body past the size cap is never held whole. */
+    body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel(reason?: unknown): Promise<void>;
+        };
+    } | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
 /**
  * A `(req, res)` handler for your Agentcard webhook endpoint. A delivery with a
  * missing, malformed, stale or wrong signature gets a 400 and reaches no
@@ -43,6 +62,40 @@ export interface PurchaseAgentWebhookOptions extends Pick<VerifyOptions, 'tolera
  * callback is done: 200 when it returns, and 500 when it throws, so Agentcard
  * delivers the event again. Agentcard waits 10 seconds for an answer, so keep
  * the callback short. Agentcard delivers at least once, and again after a 500,
- * so handle each `message.eventId` once.
+ * so handle each `message.eventId` once. `agentcardWebhook` does that for you.
  */
 export declare function purchaseAgentWebhook(secret: string, onMessage: (message: PurchaseMessage, event: AgentcardEvent) => void | Promise<void>, opts?: PurchaseAgentWebhookOptions): (req: WebhookRequest, res: WebhookResponse) => Promise<void>;
+export interface AgentcardWebhookOptions extends PurchaseAgentWebhookOptions {
+    /** The secret Agentcard returned once, when you created the endpoint. */
+    secret: string;
+    /**
+     * Receives each message for one of your shoppers, under your own id for them: post
+     * `message.text` into that shopper's chat, or hand `message.note` to your agent. Runs once per
+     * event, never for a stale message, and the delivery answers 500 when it throws, so Agentcard
+     * delivers the event again.
+     */
+    onMessage: (externalUserId: string, message: ShopperMessage, event: AgentcardEvent) => void | Promise<void>;
+    /**
+     * Receives every verified event that is no message for one of your shoppers: another event type,
+     * such as `vault.card_stored`, and a shopper message for a shopper you gave Agentcard no id for.
+     */
+    onEvent?: (event: AgentcardEvent) => void | Promise<void>;
+}
+/** The handler `agentcardWebhook` returns: a Node or Express `(req, res)` handler, with `fetch` for a web `Request`. */
+export interface AgentcardWebhookHandler {
+    (req: WebhookRequest, res: WebhookResponse): Promise<void>;
+    /** The same handler for a web `Request`, such as a Next.js route handler's: `export const POST = webhook.fetch`. */
+    fetch(request: WebhookFetchRequest): Promise<Response>;
+}
+/**
+ * One handler for every Agentcard event your shoppers should hear about. It checks each delivery's
+ * signature, skips an event this process already handled, reads the message the event carries for
+ * a shopper
+ * (`readShopperMessage`), drops a message whose link or window has closed (`isStale`), and calls
+ * `onMessage` with your own id for the shopper and the message, Agentcard's own text included.
+ * Every other verified event goes to `onEvent`. The answer waits for the callback: 200 when it
+ * returns, 500 when it throws, and an event whose callback threw runs again on the next delivery.
+ * The handled events live in this process's memory: with more than one server, deduplicate on
+ * `message.eventId` in your own storage too.
+ */
+export declare function agentcardWebhook(opts: AgentcardWebhookOptions): AgentcardWebhookHandler;