@agent-cards/commerce-sdk 0.5.0 → 0.9.0

package/dist/index.d.ts

@@ -2,10 +2,12 @@ export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatur
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.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 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 { 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, type BuyStoreChoice, type BuyStorePick, type BuyStores, } 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 { ackFor, type AckForOptions } from './ack.js';
-export { forModel, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
+export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolStore, } from './buy-tool.js';
+export { instantAck, ackFor, type AckForOptions } from './ack.js';
+export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } 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

@@ -6,6 +6,8 @@ export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_U
 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 { ackFor } from './ack.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;

package/dist/listen.js

@@ -0,0 +1,496 @@
+/**
+ * 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 { isRecord } from './verify.js';
+import { isStale, readShopperMessage } from './shopper-message.js';
+import { isEventPattern, matchesEventPattern } from './events.js';
+import { AgentcardApiError } from './client.js';
+/** How many handled event ids the listener remembers, the oldest forgotten first. */
+const HANDLED_EVENTS_KEPT = 10_000;
+/** Tries for one event's callback before the listener reports it and moves on. */
+const CALLBACK_ATTEMPTS = 5;
+const IDLE_SAVE_MS = 60_000;
+const MAX_BACKOFF_MS = 30_000;
+/**
+ * How far behind its cursor Agentcard hands events over again after a resume, in case one
+ * committed late, unless the stream says otherwise. The saved cursor carries the id of every event
+ * handled within this window and a margin, so a new process skips each of them.
+ */
+const DEFAULT_REPLAY_MS = 10_000;
+const REPLAY_MARGIN_MS = 5_000;
+/** The time in a cursor, `<ms>_<row>`, or null for a cursor of another shape. */
+const cursorTime = (cursor) => {
+    const m = cursor ? /^(\d{1,15})_/.exec(cursor) : null;
+    return m ? Number(m[1]) : null;
+};
+/** Streams in a row that answered but never said ready before `auto` polls instead: a proxy that buffers the stream, or closes it. */
+const STREAM_ATTEMPTS_BEFORE_POLLING = 3;
+/** Raised when the stream is not served here, so `auto` polls instead. */
+class StreamUnavailable extends Error {
+}
+/** Raised when the stream answered but closed, or went silent, before Agentcard said it was ready. */
+class StreamNotEstablished extends Error {
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted)
+        return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', done);
+        resolve();
+    }
+    signal.addEventListener('abort', done);
+});
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** An event envelope as Agentcard sends it, or null for anything else. */
+function eventOf(value) {
+    if (!isRecord(value) || typeof value.id !== 'string' || typeof value.type !== 'string' || !isRecord(value.data))
+        return null;
+    return {
+        id: value.id,
+        type: value.type,
+        created: typeof value.created === 'number' ? value.created : 0,
+        livemode: value.livemode === true,
+        data: value.data,
+    };
+}
+/** The Agentcard error a refused read answered with. */
+async function refusal(res) {
+    const body = parseJson(await res.text().catch(() => ''));
+    const error = isRecord(body) && isRecord(body.error) ? body.error : {};
+    const code = typeof error.code === 'string' ? error.code : `http_${res.status}`;
+    const message = typeof error.message === 'string' ? error.message : `Agentcard answered ${res.status}.`;
+    return new AgentcardApiError(res.status, code, message, isRecord(body) ? body : undefined);
+}
+/**
+ * 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 function listenToAgentcard(agentcard, opts) {
+    if (!agentcard || typeof agentcard.bearer !== 'function')
+        throw new TypeError('Pass the AgentcardClient built with your company credentials.');
+    if (!agentcard.company)
+        throw new TypeError('Listening takes your company credentials: build the client with clientId and clientSecret.');
+    if (opts === null || typeof opts !== 'object')
+        throw new TypeError('Pass { onMessage } or { onEvent }.');
+    if (opts.onMessage === undefined && opts.onEvent === undefined)
+        throw new TypeError('Pass onMessage, onEvent, or both.');
+    for (const name of ['onMessage', 'onEvent', 'onError']) {
+        if (opts[name] !== undefined && typeof opts[name] !== 'function')
+            throw new TypeError(`${name} must be a function.`);
+    }
+    const filter = opts.events === undefined ? null : [...opts.events];
+    if (filter !== null && (filter.length === 0 || filter.some((p) => typeof p !== 'string' || !isEventPattern(p)))) {
+        throw new TypeError('events lists event types Agentcard sends, families such as order.*, or *. Leave it out for every event.');
+    }
+    const transportOpt = opts.transport ?? 'auto';
+    if (!['auto', 'stream', 'poll'].includes(transportOpt))
+        throw new TypeError("transport is 'auto', 'stream' or 'poll'.");
+    const fetchFn = (opts.fetch ?? globalThis.fetch);
+    if (typeof fetchFn !== 'function')
+        throw new TypeError('Pass fetch: this runtime has no global fetch. Node 18 and later have one.');
+    const pollIntervalMs = opts.pollIntervalMs ?? 2_000;
+    const heartbeatTimeoutMs = opts.heartbeatTimeoutMs ?? 45_000;
+    const pollTimeoutMs = opts.pollTimeoutMs ?? 30_000;
+    const stop = new AbortController();
+    let transport = transportOpt === 'poll' ? 'poll' : 'stream';
+    let cursor = null;
+    let savedCursor = null;
+    let lastSave = 0;
+    let resolveReady;
+    const ready = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    const report = (error, event) => {
+        try {
+            const reported = opts.onError ? opts.onError(error, event) : console.error('Agentcard listener:', error);
+            if (reported && typeof reported.then === 'function')
+                reported.then(undefined, () => { });
+        }
+        catch {
+            // A failing reporter never stops the listener.
+        }
+    };
+    const finished = new Set();
+    /** The ids handled last, saved with the cursor, so a new process skips what Agentcard hands it again. */
+    /** Each handled id with the cursor time it came with, which is never earlier than the event's own place. */
+    const recent = [];
+    let replayMs = DEFAULT_REPLAY_MS;
+    const finishAt = (id, at) => {
+        finished.add(id);
+        if (finished.size > HANDLED_EVENTS_KEPT)
+            finished.delete(finished.values().next().value);
+        recent.push({ id, at: at ?? Date.now() });
+        if (recent.length > HANDLED_EVENTS_KEPT)
+            recent.shift();
+    };
+    /**
+     * What the store keeps: Agentcard's cursor, then the id of every event a resume from it could hand
+     * over again, as `<cursor>.<id>,<id>`. An id older than the replay window behind the cursor is dropped.
+     */
+    const stored = (next) => {
+        const at = cursorTime(next);
+        if (at !== null) {
+            const keepFrom = at - replayMs - REPLAY_MARGIN_MS;
+            while (recent.length > 0 && recent[0].at < keepFrom)
+                recent.shift();
+        }
+        return recent.length > 0 ? `${next}.${recent.map((r) => r.id).join(',')}` : next;
+    };
+    const save = async (next, force) => {
+        cursor = next;
+        const value = stored(next);
+        if (!opts.cursor || value === savedCursor)
+            return;
+        if (!force && Date.now() - lastSave < IDLE_SAVE_MS)
+            return;
+        try {
+            await opts.cursor.save(value);
+            savedCursor = value;
+            lastSave = Date.now();
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    /**
+     * Runs one event's callback, and tries again when it throws, up to five times in all. Answers
+     * false when the listener closed with the callback still failing: the event stays unfinished and
+     * nothing saves past it, so the next process runs it again.
+     */
+    const handle = async (event, at) => {
+        if (finished.has(event.id))
+            return true;
+        const finish = (id) => {
+            finishAt(id, at);
+            return true;
+        };
+        if (filter !== null && !filter.some((p) => matchesEventPattern(event.type, p)))
+            return finish(event.id);
+        let message = null;
+        try {
+            message = readShopperMessage(event);
+        }
+        catch (error) {
+            // A message the package cannot read reads the same way every time, so it is reported once.
+            report(error, event);
+        }
+        // A message whose link or window closed before it arrived reaches no shopper, and the event still reaches onEvent.
+        const forShopper = message && message.externalUserId !== null && !isStale(message) ? message : null;
+        for (let attempt = 1;; attempt++) {
+            try {
+                if (opts.onMessage && forShopper?.externalUserId)
+                    await opts.onMessage(forShopper.externalUserId, forShopper, event);
+                else if (opts.onEvent)
+                    await opts.onEvent(event);
+                return finish(event.id);
+            }
+            catch (error) {
+                if (attempt >= CALLBACK_ATTEMPTS) {
+                    report(error, event);
+                    return finish(event.id);
+                }
+                // Closing mid-failure leaves the event for the next process, which has the tries left.
+                if (stop.signal.aborted) {
+                    report(error, event);
+                    return false;
+                }
+                await sleep(1_000 * 2 ** (attempt - 1), stop.signal);
+            }
+        }
+    };
+    const query = (after, extra = {}) => {
+        const params = new URLSearchParams(extra);
+        if (after)
+            params.set('after', after);
+        if (filter)
+            params.set('types', filter.join(','));
+        const text = params.toString();
+        return text ? `?${text}` : '';
+    };
+    /** One authorized GET: a 401 renews the token once. */
+    const get = async (path, accept, signal) => {
+        let token = await agentcard.bearer();
+        for (let attempt = 0;; attempt++) {
+            const res = await fetchFn(`${agentcard.baseUrl}${path}`, { method: 'GET', headers: { authorization: `Bearer ${token}`, accept }, signal });
+            if (res.status !== 401 || attempt > 0)
+                return res;
+            await res.text().catch(() => '');
+            token = await agentcard.bearer(token);
+        }
+    };
+    /** A refused cursor: Agentcard no longer keeps it, so the listener reports it and starts from now. */
+    const dropCursor = async (error) => {
+        report(error);
+        cursor = null;
+    };
+    /** One stream connection, read to its end. Resolves when the server asks to reconnect or the connection drops. */
+    const streamOnce = async () => {
+        const conn = new AbortController();
+        const abort = () => conn.abort();
+        stop.signal.addEventListener('abort', abort);
+        let silence;
+        let wentSilent = false;
+        const arm = () => {
+            if (silence)
+                clearTimeout(silence);
+            silence = setTimeout(() => {
+                wentSilent = true;
+                abort();
+            }, heartbeatTimeoutMs);
+        };
+        let opened = false;
+        try {
+            arm();
+            let res;
+            try {
+                res = await get(`/api/v2/events/stream${query(cursor)}`, 'text/event-stream', conn.signal);
+            }
+            catch (error) {
+                // No answer within the heartbeat timeout is a stream held back on its way, not a lost network.
+                if (wentSilent && !stop.signal.aborted)
+                    throw new StreamNotEstablished('The event stream sent nothing before Agentcard said it was ready.');
+                throw error;
+            }
+            if (res.status === 400 || res.status === 410) {
+                const error = await refusal(res);
+                if (error.code === 'invalid_cursor' || error.code === 'cursor_expired') {
+                    await dropCursor(error);
+                    return 'reconnect';
+                }
+                throw error;
+            }
+            const type = res.headers.get('content-type') ?? '';
+            if (res.status === 404 || res.status === 405 || (res.ok && !type.includes('text/event-stream'))) {
+                await res.text().catch(() => '');
+                throw new StreamUnavailable(`Agentcard answered the stream with ${res.status} ${type || 'and no content type'}.`);
+            }
+            if (!res.ok || !res.body)
+                throw await refusal(res);
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            for (;;) {
+                let chunk;
+                try {
+                    chunk = await reader.read();
+                }
+                catch (error) {
+                    if (!opened && !stop.signal.aborted)
+                        throw new StreamNotEstablished('The event stream went silent before Agentcard said it was ready.');
+                    throw error;
+                }
+                const { done, value } = chunk;
+                // A connection that ends before Agentcard said it is ready counts as a failure, so it backs off.
+                if (done) {
+                    if (!opened)
+                        throw new StreamNotEstablished('The event stream closed before Agentcard said it was ready.');
+                    return 'dropped';
+                }
+                arm();
+                buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, '\n');
+                let cut;
+                while ((cut = buffer.indexOf('\n\n')) >= 0) {
+                    const block = buffer.slice(0, cut);
+                    buffer = buffer.slice(cut + 2);
+                    let id;
+                    let name = 'message';
+                    const data = [];
+                    for (const line of block.split('\n')) {
+                        if (line === '' || line.startsWith(':'))
+                            continue;
+                        const colon = line.indexOf(':');
+                        const field = colon < 0 ? line : line.slice(0, colon);
+                        const val = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+                        if (field === 'id')
+                            id = val;
+                        else if (field === 'event')
+                            name = val;
+                        else if (field === 'data')
+                            data.push(val);
+                    }
+                    if (name === 'ready') {
+                        opened = true;
+                        resolveReady();
+                        const announced = parseJson(data.join('\n'));
+                        if (isRecord(announced) && typeof announced.replay_seconds === 'number' && announced.replay_seconds > 0) {
+                            replayMs = Math.max(DEFAULT_REPLAY_MS, announced.replay_seconds * 1000);
+                        }
+                        if (id)
+                            await save(id, false);
+                    }
+                    else if (name === 'heartbeat') {
+                        if (id)
+                            await save(id, false);
+                    }
+                    else if (name === 'reconnect') {
+                        if (id)
+                            await save(id, false);
+                        await reader.cancel().catch(() => { });
+                        return 'reconnect';
+                    }
+                    else if (name === 'message' || name === 'replay') {
+                        // A replay is an event Agentcard hands over again after a resume, in case it committed late; an id already handled runs nothing.
+                        const event = eventOf(parseJson(data.join('\n')));
+                        if (event) {
+                            // A callback that runs long is not silence on the stream.
+                            if (silence)
+                                clearTimeout(silence);
+                            const handled = await handle(event, cursorTime(id));
+                            arm();
+                            // An event the shutdown left unfinished saves no cursor past it.
+                            if (!handled)
+                                return 'dropped';
+                        }
+                        if (id)
+                            await save(id, true);
+                    }
+                    if (stop.signal.aborted)
+                        return 'dropped';
+                }
+            }
+        }
+        finally {
+            if (silence)
+                clearTimeout(silence);
+            stop.signal.removeEventListener('abort', abort);
+            conn.abort();
+        }
+    };
+    /** One page of a polling read, given up after `pollTimeoutMs` so a stalled read never stops the listener. */
+    const readPage = async () => {
+        const conn = new AbortController();
+        const abort = () => conn.abort();
+        stop.signal.addEventListener('abort', abort);
+        const deadline = setTimeout(abort, pollTimeoutMs);
+        try {
+            const res = await get(`/api/v2/events${query(cursor, { limit: '100' })}`, 'application/json', conn.signal);
+            return { status: res.status, ok: res.ok, text: await res.text() };
+        }
+        finally {
+            clearTimeout(deadline);
+            stop.signal.removeEventListener('abort', abort);
+        }
+    };
+    /** One polling read, every page of it. */
+    const pollOnce = async () => {
+        for (;;) {
+            const res = await readPage();
+            if (!res.ok) {
+                const error = await refusal({ status: res.status, text: async () => res.text });
+                if (error.code === 'invalid_cursor' || error.code === 'cursor_expired')
+                    return dropCursor(error);
+                throw error;
+            }
+            const body = parseJson(res.text);
+            if (!isRecord(body) || !Array.isArray(body.data))
+                throw new AgentcardApiError(res.status, 'invalid_answer', 'Agentcard answered the event read with a body the listener cannot read.');
+            resolveReady();
+            for (const item of body.data) {
+                if (stop.signal.aborted)
+                    return;
+                const event = isRecord(item) ? eventOf(item.event) : null;
+                const itemCursor = isRecord(item) && typeof item.cursor === 'string' ? item.cursor : null;
+                // An event the shutdown left unfinished saves no cursor past it.
+                if (event && !(await handle(event, cursorTime(itemCursor))))
+                    return;
+                if (itemCursor)
+                    await save(itemCursor, true);
+            }
+            if (typeof body.cursor === 'string')
+                await save(body.cursor, body.data.length > 0);
+            if (body.has_more !== true)
+                return;
+        }
+    };
+    const loop = (async () => {
+        if (opts.cursor) {
+            try {
+                const loaded = await opts.cursor.load();
+                if (typeof loaded === 'string' && loaded !== '') {
+                    savedCursor = loaded;
+                    const dot = loaded.indexOf('.');
+                    cursor = dot < 0 ? loaded : loaded.slice(0, dot);
+                    for (const id of dot < 0 ? [] : loaded.slice(dot + 1).split(','))
+                        if (/^[A-Za-z0-9_]{1,64}$/.test(id))
+                            finishAt(id, cursorTime(cursor));
+                }
+            }
+            catch (error) {
+                report(error);
+            }
+        }
+        let failures = 0;
+        let unestablished = 0;
+        while (!stop.signal.aborted) {
+            try {
+                if (transport === 'stream') {
+                    const ended = await streamOnce();
+                    failures = 0;
+                    unestablished = 0;
+                    if (ended === 'reconnect')
+                        continue;
+                }
+                else {
+                    await pollOnce();
+                    failures = 0;
+                    await sleep(pollIntervalMs, stop.signal);
+                    continue;
+                }
+            }
+            catch (error) {
+                if (stop.signal.aborted)
+                    break;
+                if (error instanceof StreamUnavailable && transportOpt === 'auto') {
+                    transport = 'poll';
+                    continue;
+                }
+                failures++;
+                report(error);
+                if (error instanceof StreamNotEstablished && transportOpt === 'auto' && ++unestablished >= STREAM_ATTEMPTS_BEFORE_POLLING) {
+                    // Something between here and Agentcard holds the stream back; the same events come by polling, from the same cursor.
+                    transport = 'poll';
+                    continue;
+                }
+            }
+            if (stop.signal.aborted)
+                break;
+            // A dropped connection or a failed read waits a little longer each time, up to 30 seconds.
+            const backoff = Math.min(MAX_BACKOFF_MS, 1_000 * 2 ** Math.max(0, failures - 1));
+            await sleep(failures === 0 ? 250 : backoff * (0.5 + Math.random() / 2), stop.signal);
+        }
+        resolveReady();
+    })();
+    return {
+        ready,
+        get transport() {
+            return transport;
+        },
+        get cursor() {
+            return cursor;
+        },
+        async close() {
+            stop.abort();
+            await loop;
+        },
+    };
+}