@agent-cards/commerce-sdk 0.2.0 → 0.8.0

package/dist/handler.js

@@ -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 { AgentcardSignatureError, InvalidEventBodyError, toleranceOf, verifyAgentcardWebhook, } from './verify.js';
 import { readPurchaseMessage } from './message.js';
+import { isStale, readShopperMessage } from './shopper-message.js';
 /** A signed Agentcard delivery is a few kilobytes; a body past this size did not come from Agentcard. */
 const MAX_BODY_BYTES = 1024 * 1024;
 const RAW_BODY_GONE = 'The webhook request reached the handler with its body already parsed and no raw bytes kept, so the signature cannot be checked. ' +
@@ -95,6 +97,132 @@ async function readRawBody(req) {
         return undefined;
     return readStream(req);
 }
+/** Hands an error to `onError`, or to `console.error`. A reporter that throws or rejects never takes the process down. */
+function reporter(onError) {
+    return (error, event) => {
+        try {
+            const reported = onError ? onError(error, event) : console.error('Agentcard webhook:', error);
+            // A reporter that rejects must not leave an unhandled rejection, which ends a plain Node server's process.
+            if (reported && typeof reported.then === 'function')
+                reported.then(undefined, () => { });
+        }
+        catch {
+            // A failing reporter must never take the process down with it.
+        }
+    };
+}
+function checkSecret(secret) {
+    if (typeof secret !== 'string' || secret === '') {
+        throw new TypeError('Pass the webhook endpoint secret Agentcard returned when you created the endpoint.');
+    }
+}
+/** Verifies one raw delivery and runs its callbacks. The answer waits for them, so a callback that fails gets the event delivered again. */
+async function answer(raw, signature, secret, verifyOpts, dispatch, report) {
+    let event;
+    try {
+        event = verifyAgentcardWebhook(raw, signature, secret, verifyOpts);
+    }
+    catch (error) {
+        if (error instanceof AgentcardSignatureError)
+            return { status: 400, body: { error: 'invalid_signature', reason: error.reason } };
+        if (error instanceof InvalidEventBodyError)
+            return { status: 400, body: { error: 'invalid_body' } };
+        report(error, undefined);
+        return { status: 500, body: { error: 'verification_failed' } };
+    }
+    if (await dispatch(event))
+        return { status: 200, body: { received: true } };
+    return { status: 500, body: { error: 'callback_failed' } };
+}
+/** The `(req, res)` handler around one delivery's answer. It never rejects: an unhandled rejection would end a plain Node server's process. */
+function nodeHandler(handleRaw, report) {
+    const handle = async (req, res) => {
+        let raw;
+        try {
+            raw = await readRawBody(req);
+        }
+        catch (error) {
+            if (error instanceof BodyTooLargeError)
+                return send(res, 413, { error: 'body_too_large' });
+            return send(res, 400, { error: 'unreadable_body' });
+        }
+        if (raw === undefined) {
+            report(new Error(RAW_BODY_GONE), undefined);
+            return send(res, 500, { error: 'raw_body_unavailable' });
+        }
+        const outcome = await handleRaw(raw, headerValue(req.headers['agentcard-signature']));
+        send(res, outcome.status, outcome.body);
+    };
+    return async (req, res) => {
+        try {
+            await handle(req, res);
+        }
+        catch (error) {
+            report(error, undefined);
+        }
+    };
+}
+/**
+ * The body of a web request, read chunk by chunk. Past the size cap it stops reading, cancels the
+ * stream and throws, so a caller with no signature cannot make the server hold a large body.
+ */
+async function readFetchBody(request) {
+    if (!request.body || typeof request.body.getReader !== 'function')
+        return new Uint8Array(await request.arrayBuffer());
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        size += value.length;
+        if (size > MAX_BODY_BYTES) {
+            await reader.cancel().catch(() => { });
+            throw new BodyTooLargeError();
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** A web `Response` with a JSON body, built from the runtime's own `Response`. */
+function webResponse(outcome) {
+    return new Response(JSON.stringify(outcome.body), { status: outcome.status, headers: { 'content-type': 'application/json' } });
+}
+/** The web `Request` handler around one delivery's answer. It never rejects. */
+function fetchHandler(handleRaw, report) {
+    return async (request) => {
+        try {
+            const declared = Number(request.headers.get('content-length'));
+            if (Number.isFinite(declared) && declared > MAX_BODY_BYTES)
+                return webResponse({ status: 413, body: { error: 'body_too_large' } });
+            let raw;
+            try {
+                raw = await readFetchBody(request);
+            }
+            catch (error) {
+                if (error instanceof BodyTooLargeError)
+                    return webResponse({ status: 413, body: { error: 'body_too_large' } });
+                return webResponse({ status: 400, body: { error: 'unreadable_body' } });
+            }
+            if (raw.length > MAX_BODY_BYTES)
+                return webResponse({ status: 413, body: { error: 'body_too_large' } });
+            return webResponse(await handleRaw(raw, request.headers.get('agentcard-signature') ?? undefined));
+        }
+        catch (error) {
+            report(error, undefined);
+            return webResponse({ status: 500, body: { error: 'handler_failed' } });
+        }
+    };
+}
 /**
  * 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
@@ -103,28 +231,15 @@ async function readRawBody(req) {
  * 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 function purchaseAgentWebhook(secret, onMessage, opts = {}) {
-    if (typeof secret !== 'string' || secret === '') {
-        throw new TypeError('Pass the webhook endpoint secret Agentcard returned when you created the endpoint.');
-    }
+    checkSecret(secret);
     if (typeof onMessage !== 'function') {
         throw new TypeError('Pass onMessage, the function that receives each purchase message.');
     }
     const verifyOpts = { toleranceSeconds: toleranceOf(opts) };
-    const report = (error, event) => {
-        try {
-            const reported = opts.onError ? opts.onError(error, event) : console.error('Agentcard webhook:', error);
-            // A reporter that rejects must not leave an unhandled rejection, which ends a plain Node server's process.
-            if (reported && typeof reported.then === 'function')
-                reported.then(undefined, () => { });
-        }
-        catch {
-            // A failing reporter must never take the process down with it.
-        }
-    };
-    /** Runs the callback for one verified event. True when the delivery is done, false when the callback threw. */
+    const report = reporter(opts.onError);
     const dispatch = async (event) => {
         let message;
         try {
@@ -147,44 +262,90 @@ export function purchaseAgentWebhook(secret, onMessage, opts = {}) {
             return false;
         }
     };
-    const handle = async (req, res) => {
-        let raw;
+    return nodeHandler((raw, signature) => answer(raw, signature, secret, verifyOpts, dispatch, report), report);
+}
+/** How many handled event ids the handler remembers, the oldest forgotten first. */
+const HANDLED_EVENTS_KEPT = 10_000;
+/**
+ * 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 function agentcardWebhook(opts) {
+    if (opts === null || typeof opts !== 'object')
+        throw new TypeError('Pass { secret, onMessage }.');
+    checkSecret(opts.secret);
+    if (typeof opts.onMessage !== 'function') {
+        throw new TypeError('Pass onMessage, the function that receives each message for a shopper.');
+    }
+    const secret = opts.secret;
+    const verifyOpts = { toleranceSeconds: toleranceOf(opts) };
+    const report = reporter(opts.onError);
+    // The events this process finished, and the ones it is running. A redelivery of a finished event
+    // runs nothing, and one that lands while the first delivery still runs waits for its answer.
+    const finished = new Set();
+    const running = new Map();
+    const finish = (eventId) => {
+        finished.add(eventId);
+        if (finished.size > HANDLED_EVENTS_KEPT)
+            finished.delete(finished.values().next().value);
+    };
+    /** Runs the callback for one event. True when the delivery is done, false when the callback threw. */
+    const run = async (event) => {
+        let message;
         try {
-            raw = await readRawBody(req);
+            message = readShopperMessage(event);
         }
         catch (error) {
-            if (error instanceof BodyTooLargeError)
-                return send(res, 413, { error: 'body_too_large' });
-            return send(res, 400, { error: 'unreadable_body' });
+            // A message the package cannot read reads the same way on every delivery, so it is not sent again.
+            report(error, event);
+            finish(event.id);
+            return true;
         }
-        if (raw === undefined) {
-            report(new Error(RAW_BODY_GONE), undefined);
-            return send(res, 500, { error: 'raw_body_unavailable' });
+        // A message whose link or window closed before it arrived reaches no callback, whichever one it would reach.
+        if (message && isStale(message)) {
+            finish(event.id);
+            return true;
         }
-        let event;
         try {
-            event = verifyAgentcardWebhook(raw, headerValue(req.headers['agentcard-signature']), secret, verifyOpts);
+            if (message?.externalUserId) {
+                await opts.onMessage(message.externalUserId, message, event);
+            }
+            else if (opts.onEvent) {
+                await opts.onEvent(event);
+            }
         }
         catch (error) {
-            if (error instanceof AgentcardSignatureError)
-                return send(res, 400, { error: 'invalid_signature', reason: error.reason });
-            if (error instanceof InvalidEventBodyError)
-                return send(res, 400, { error: 'invalid_body' });
-            report(error, undefined);
-            return send(res, 500, { error: 'verification_failed' });
+            // Not marked finished, so the next delivery of the event runs the callback again.
+            report(error, event);
+            return false;
         }
-        // The answer waits for the callback, so a callback that fails gets the event delivered again.
-        if (await dispatch(event))
-            return send(res, 200, { received: true });
-        return send(res, 500, { error: 'callback_failed' });
+        finish(event.id);
+        return true;
     };
-    // The handler never rejects: an unhandled rejection would end a plain Node server's process.
-    return async (req, res) => {
+    const dispatch = async (event) => {
+        if (finished.has(event.id))
+            return true;
+        const inFlight = running.get(event.id);
+        if (inFlight)
+            return inFlight;
+        const attempt = run(event);
+        running.set(event.id, attempt);
         try {
-            await handle(req, res);
+            return await attempt;
         }
-        catch (error) {
-            report(error, undefined);
+        finally {
+            running.delete(event.id);
         }
     };
+    const handleRaw = (raw, signature) => answer(raw, signature, secret, verifyOpts, dispatch, report);
+    const handler = nodeHandler(handleRaw, report);
+    handler.fetch = fetchHandler(handleRaw, report);
+    return handler;
 }

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatureReason, type AgentcardEvent, type VerifyOptions, } from './verify.js';
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
-export { purchaseAgentWebhook, type PurchaseAgentWebhookOptions, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, } from './client.js';
+export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
+export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, } from './buy-tool.js';
-export { forModel, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
+export { instantAck, ackFor, type AckForOptions } from './ack.js';
+export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
+export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
+export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';

package/dist/index.js

@@ -1,9 +1,13 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, } from './verify.js';
 export { readPurchaseMessage, } from './message.js';
-export { purchaseAgentWebhook, } from './handler.js';
+export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, } from './shopper-message.js';
+export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, } from './messages.js';
 export { buyTool, } from './buy-tool.js';
-export { forModel, stripLinks, } from './model-view.js';
+export { instantAck, ackFor } from './ack.js';
+export { forModel, forModelError, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
+export { listenToAgentcard, } from './listen.js';
+export { AGENTCARD_EVENT_TYPES, } from './events.js';

package/dist/listen.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Hear every Agentcard event without a webhook endpoint. Your server opens one connection to
+ * Agentcard with your company credentials, and Agentcard streams your company's events down it:
+ * no public URL, no webhook secret, no signature to check. Each event is the envelope a webhook
+ * endpoint would receive, with the same id.
+ *
+ * The listener reconnects on its own, resumes after the last event it handled, skips an event it
+ * already handled, and falls back to asking every few seconds when the stream is not available.
+ * Shopper messages go through the same reader as `agentcardWebhook` (`readShopperMessage`), so
+ * `onMessage` gets the same ready-to-send text.
+ */
+import { type AgentcardEvent } from './verify.js';
+import { type ShopperMessage } from './shopper-message.js';
+import { type AgentcardEventType } from './events.js';
+import { type AgentcardClient } from './client.js';
+/** Where the listener keeps the cursor of the last event it handled, so a restarted server resumes there. */
+export interface ListenCursorStore {
+    /** The cursor saved last, or null to start from now. */
+    load(): Promise<string | null> | string | null;
+    /** Called after each handled event, and at most once a minute while no event arrives. */
+    save(cursor: string): Promise<void> | void;
+}
+/** The fetch the listener streams with: the global fetch of Node 18 and later. */
+export type StreamFetch = (url: string, init: {
+    method: 'GET';
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+    ok: boolean;
+    headers: {
+        get(name: string): string | null;
+    };
+    body: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel(reason?: unknown): Promise<void>;
+        };
+    } | null;
+    text(): Promise<string>;
+}>;
+export interface ListenOptions {
+    /**
+     * Receives each event for one of your shoppers, under your own id for them, with the message
+     * ready to post into that shopper's chat: the same as `agentcardWebhook`'s `onMessage`. A message
+     * whose link or window closed before it arrived reaches no shopper: its event goes to `onEvent`.
+     */
+    onMessage?: (externalUserId: string, message: ShopperMessage, event: AgentcardEvent<AgentcardEventType>) => void | Promise<void>;
+    /** Receives every event `onMessage` does not take: every event, when you pass no `onMessage`. */
+    onEvent?: (event: AgentcardEvent<AgentcardEventType | (string & {})>) => void | Promise<void>;
+    /**
+     * Receives what went wrong: a callback that threw five times, after which the listener moves on,
+     * a lost connection it is about to retry, a cursor Agentcard no longer keeps. A reporter that
+     * throws is ignored. Default: `console.error`.
+     */
+    onError?: (error: unknown, event?: AgentcardEvent) => void | Promise<void>;
+    /** Only these events: event types, families such as `order.*`, or `*`. Default: every event. */
+    events?: string[];
+    /** Keeps the cursor across restarts. Default: in memory, so a new process starts from now. */
+    cursor?: ListenCursorStore;
+    /** `auto` streams and falls back to polling when the stream is not available. Default `auto`. */
+    transport?: 'auto' | 'stream' | 'poll';
+    /** How long polling waits between reads. Default 2000. */
+    pollIntervalMs?: number;
+    /** How long the stream may stay silent before the listener reconnects. Agentcard sends a heartbeat every 15 seconds. Default 45000. */
+    heartbeatTimeoutMs?: number;
+    /** How long one polling read may take before the listener gives up on it and reads again. Default 30000. */
+    pollTimeoutMs?: number;
+    /** The fetch to stream with. Default: the global fetch. */
+    fetch?: StreamFetch;
+}
+/** A running listener. */
+export interface AgentcardListener {
+    /** Resolves once the listener first reaches Agentcard, or once it closes. */
+    readonly ready: Promise<void>;
+    /** How the listener hears Agentcard right now. */
+    readonly transport: 'stream' | 'poll';
+    /** The cursor of the last event handled, or null before the first connection. */
+    readonly cursor: string | null;
+    /** Stops listening. Resolves once the callback that is running, if any, has returned. */
+    close(): Promise<void>;
+}
+/**
+ * Listen to every event Agentcard sends your company, over one connection your server opens.
+ * Build `agentcard` with your company's client credentials. Returns at once; `ready` resolves once
+ * the listener reaches Agentcard. Each event runs its callback once, in order, and the next event
+ * waits for it: a callback that throws runs again, up to five times, before the listener reports
+ * it and moves on. Run one listener per company and mode: two listeners each hear every event.
+ */
+export declare function listenToAgentcard(agentcard: AgentcardClient, opts: ListenOptions): AgentcardListener;