@agent-cards/commerce-sdk 0.0.0-stage → 0.2.0

package/dist/handler.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+import { type AgentcardEvent, type VerifyOptions } from './verify.js';
+import { type PurchaseMessage } from './message.js';
+/** The parts of a Node or Express request the handler reads. */
+export interface WebhookRequest {
+    headers: Record<string, string | string[] | undefined>;
+    /** The bytes from `express.raw`, the text from `express.text`, or a body a JSON parser already parsed. */
+    body?: unknown;
+    /** The bytes a parser kept beside the parsed body: `express.json({ verify })`, NestJS and Firebase keep them here. */
+    rawBody?: unknown;
+    /** True once the request stream has been read to the end. */
+    readableEnded?: boolean;
+    on?(event: string, listener: (...args: any[]) => void): unknown;
+}
+/** The parts of a Node or Express response the handler writes. */
+export interface WebhookResponse {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(body?: string): unknown;
+}
+export interface PurchaseAgentWebhookOptions extends Pick<VerifyOptions, 'toleranceSeconds'> {
+    /** Receives every verified event that is not a purchase message, such as `merchant.connected`. */
+    onEvent?: (event: AgentcardEvent) => void | Promise<void>;
+    /**
+     * Receives what went wrong: an error thrown by `onMessage` or `onEvent`, whose
+     * delivery then answers 500, a purchase message the package cannot read, or a
+     * request whose raw body was already gone. The event is undefined when no
+     * event was read. A reporter that throws or rejects is ignored. Default:
+     * `console.error`.
+     */
+    onError?: (error: unknown, event: AgentcardEvent | undefined) => void | Promise<void>;
+}
+/**
+ * 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
+ * callback. A verified delivery runs `onMessage` for a purchase message, or
+ * `opts.onEvent` for any other event, and the handler answers when the
+ * 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.
+ */
+export declare function purchaseAgentWebhook(secret: string, onMessage: (message: PurchaseMessage, event: AgentcardEvent) => void | Promise<void>, opts?: PurchaseAgentWebhookOptions): (req: WebhookRequest, res: WebhookResponse) => Promise<void>;

package/dist/handler.js

@@ -0,0 +1,190 @@
+/**
+ * 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.
+ */
+import { AgentcardSignatureError, InvalidEventBodyError, toleranceOf, verifyAgentcardWebhook, } from './verify.js';
+import { readPurchaseMessage } from './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. ' +
+    "Mount the route with express.raw({ type: 'application/json' }) before any express.json(), or keep the bytes with " +
+    'express.json({ verify: (req, _res, buf) => { Object.assign(req, { rawBody: buf }); } }).';
+class BodyTooLargeError extends Error {
+}
+function send(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify(body));
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value.join(',') : value;
+}
+function toBytes(chunk) {
+    if (chunk instanceof Uint8Array)
+        return chunk;
+    if (typeof chunk === 'string')
+        return new TextEncoder().encode(chunk);
+    throw new TypeError('The request stream yielded something other than bytes.');
+}
+/** Reads the request stream to its end. Past the size cap it keeps draining and keeps nothing. */
+function readStream(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let tooLarge = false;
+        let failed;
+        req.on('data', (chunk) => {
+            if (tooLarge || failed !== undefined)
+                return;
+            try {
+                const bytes = toBytes(chunk);
+                size += bytes.length;
+                if (size > MAX_BODY_BYTES) {
+                    tooLarge = true;
+                    chunks.length = 0;
+                    return;
+                }
+                chunks.push(bytes);
+            }
+            catch (err) {
+                failed = err;
+            }
+        });
+        req.on('end', () => {
+            if (failed !== undefined)
+                return reject(failed);
+            if (tooLarge)
+                return reject(new BodyTooLargeError());
+            const out = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                out.set(chunk, offset);
+                offset += chunk.length;
+            }
+            resolve(out);
+        });
+        req.on('error', reject);
+        // A client that disconnects mid-body ends the read; after 'end' this reject is a no-op.
+        req.on('close', () => reject(new Error('The request closed before its body ended.')));
+    });
+}
+function savedBody(req) {
+    if (typeof req.rawBody === 'string' || req.rawBody instanceof Uint8Array)
+        return req.rawBody;
+    if (typeof req.body === 'string' || req.body instanceof Uint8Array)
+        return req.body;
+    return undefined;
+}
+/**
+ * The raw body, wherever it is: bytes a parser kept, bytes or text from a raw
+ * or text parser, or the unread stream. Undefined when a JSON parser already
+ * consumed the stream and kept no bytes. Every source is held to the same
+ * size cap, text counted in UTF-8 bytes.
+ */
+async function readRawBody(req) {
+    const saved = savedBody(req);
+    if (saved !== undefined) {
+        const size = typeof saved === 'string' ? new TextEncoder().encode(saved).length : saved.length;
+        if (size > MAX_BODY_BYTES)
+            throw new BodyTooLargeError();
+        return saved;
+    }
+    if (req.readableEnded === true || typeof req.on !== 'function')
+        return undefined;
+    return readStream(req);
+}
+/**
+ * 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
+ * callback. A verified delivery runs `onMessage` for a purchase message, or
+ * `opts.onEvent` for any other event, and the handler answers when the
+ * 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.
+ */
+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.');
+    }
+    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 dispatch = async (event) => {
+        let message;
+        try {
+            message = readPurchaseMessage(event);
+        }
+        catch (error) {
+            // A purchase message the package cannot read reads the same way on every delivery, so it is not sent again.
+            report(error, event);
+            return true;
+        }
+        try {
+            if (message)
+                await onMessage(message, event);
+            else if (opts.onEvent)
+                await opts.onEvent(event);
+            return true;
+        }
+        catch (error) {
+            report(error, event);
+            return false;
+        }
+    };
+    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' });
+        }
+        let event;
+        try {
+            event = verifyAgentcardWebhook(raw, headerValue(req.headers['agentcard-signature']), secret, verifyOpts);
+        }
+        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' });
+        }
+        // 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' });
+    };
+    // The handler never rejects: an unhandled rejection would end a plain Node server's process.
+    return async (req, res) => {
+        try {
+            await handle(req, res);
+        }
+        catch (error) {
+            report(error, undefined);
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+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 { 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 { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { verifyAgentcardWebhook, AgentcardSignatureError, } from './verify.js';
+export { readPurchaseMessage, } from './message.js';
+export { 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 { toAnthropicTool, toOpenRouterTool, } from './adapters.js';

package/dist/message.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `purchase.message`: one event type for every moment of a purchase that a
+ * shopper should hear about. Each message carries the text to send as is, a
+ * note for the company's agent, and the same values as facts.
+ */
+import { type AgentcardEvent } from './verify.js';
+/**
+ * The moment a message is about:
+ * - `order_placed`: the shopper approved, and Agentcard placed the order.
+ * - `order_failed`: the order failed after the approval, and nothing more happens for that approval.
+ * - `order_not_placed_yet`: the shopper approved, and the order is not placed yet.
+ * - `approval_expiring`: the approval link expires soon; `text` carries the link.
+ * - `approval_expired`: the approval expired before the shopper answered, and nothing was charged.
+ * - `card_link_unfinished`: the shopper has not added a card from their card link; `text` carries the link again.
+ * - `card_link_expired`: the card link expired before the shopper added a card.
+ * - `cart_idle`: a cart sat without being sent for approval; `facts.nudgeNumber` counts the nudges.
+ */
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'approval_expiring' | 'approval_expired' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle';
+/** The message's values one by one, for a company that writes its own copy. A fact that does not apply is absent. */
+export interface PurchaseFacts {
+    merchantName?: string;
+    /** The total in the currency's minor unit: 2306 is $23.06. */
+    totalCents?: number;
+    /** The three-letter currency code. */
+    currency?: string;
+    cardBrand?: string;
+    cardLast4?: string;
+    orderId?: string;
+    /** Why an order failed or was not placed, in words. */
+    reason?: string;
+    approvalUrl?: string;
+    /** When the approval link stops working, as an ISO 8601 timestamp. */
+    approvalExpiresAt?: string;
+    cardLinkUrl?: string;
+    /** Until when the order is retried, as an ISO 8601 timestamp. */
+    retryUntil?: string;
+    /**
+     * Until when the message holds, as an ISO 8601 timestamp: the expiry of any link or window its text
+     * names. Absent when the message stays true. A message read after it is stale: drop it.
+     */
+    validUntil?: string;
+    /** 1 for a cart's first nudge, 2 for its second. */
+    nudgeNumber?: number;
+}
+/** A `purchase.message` event, read. */
+export interface PurchaseMessage {
+    /** The event id. Agentcard delivers at least once: handle each id once. */
+    eventId: string;
+    /**
+     * The moment the message is about: one of the kinds above, or a kind Agentcard adds later,
+     * read as its own name. Give a `switch` over it a default branch that sends `text`.
+     */
+    kind: PurchaseMessageKind | (string & {});
+    /** The shopper's Agentcard user id. */
+    userId: string;
+    /** Your own id for the shopper, when you gave Agentcard one. */
+    externalUserId: string | null;
+    /** Ready to send to the shopper as is. */
+    text: string;
+    /**
+     * For your agent: the facts of what happened, marked as written by the system and not typed by
+     * the shopper. Empty when the message carries no note; send `text` then.
+     */
+    note: string;
+    facts: PurchaseFacts;
+    /** The OAuth client id of the app the shopper connected through. */
+    clientId: string | null;
+    /** False for a sandbox event. */
+    livemode: boolean;
+    /** Unix seconds. */
+    created: number;
+}
+/**
+ * The message a `purchase.message` event carries, or null for any other event
+ * type. Pass the event `verifyAgentcardWebhook` returned. Throws a TypeError
+ * when a purchase message lacks its kind, user_id or text.
+ */
+export declare function readPurchaseMessage(event: AgentcardEvent): PurchaseMessage | null;

package/dist/message.js

@@ -0,0 +1,76 @@
+/**
+ * `purchase.message`: one event type for every moment of a purchase that a
+ * shopper should hear about. Each message carries the text to send as is, a
+ * note for the company's agent, and the same values as facts.
+ */
+import { isRecord } from './verify.js';
+/** The event type every purchase message arrives as. */
+const PURCHASE_MESSAGE_EVENT = 'purchase.message';
+const STRING_FACTS = [
+    ['merchant_name', 'merchantName'],
+    ['currency', 'currency'],
+    ['card_brand', 'cardBrand'],
+    ['card_last4', 'cardLast4'],
+    ['order_id', 'orderId'],
+    ['reason', 'reason'],
+    ['approval_url', 'approvalUrl'],
+    ['approval_expires_at', 'approvalExpiresAt'],
+    ['card_link_url', 'cardLinkUrl'],
+    ['retry_until', 'retryUntil'],
+    ['valid_until', 'validUntil'],
+];
+const NUMBER_FACTS = [
+    ['total_cents', 'totalCents'],
+    ['nudge_number', 'nudgeNumber'],
+];
+function readFacts(raw) {
+    const facts = {};
+    if (!isRecord(raw))
+        return facts;
+    for (const [wire, name] of STRING_FACTS) {
+        const value = raw[wire];
+        if (typeof value === 'string' && value !== '')
+            facts[name] = value;
+    }
+    for (const [wire, name] of NUMBER_FACTS) {
+        const value = raw[wire];
+        if (typeof value === 'number' && Number.isFinite(value))
+            facts[name] = value;
+    }
+    return facts;
+}
+function requiredString(data, field) {
+    const value = data[field];
+    if (typeof value !== 'string' || value === '') {
+        throw new TypeError(`The purchase.message event has no ${field}. Every purchase message carries kind, user_id and text.`);
+    }
+    return value;
+}
+/**
+ * The message a `purchase.message` event carries, or null for any other event
+ * type. Pass the event `verifyAgentcardWebhook` returned. Throws a TypeError
+ * when a purchase message lacks its kind, user_id or text.
+ */
+export function readPurchaseMessage(event) {
+    if (event.type !== PURCHASE_MESSAGE_EVENT)
+        return null;
+    const data = event.data;
+    const kind = requiredString(data, 'kind');
+    const userId = requiredString(data, 'user_id');
+    const text = requiredString(data, 'text');
+    // Without a note, the text alone still tells the shopper what happened.
+    const note = typeof data.note === 'string' ? data.note : '';
+    const connection = isRecord(data.connection) ? data.connection : {};
+    return {
+        eventId: event.id,
+        kind,
+        userId,
+        externalUserId: typeof data.external_user_id === 'string' && data.external_user_id !== '' ? data.external_user_id : null,
+        text,
+        note,
+        facts: readFacts(data.facts),
+        clientId: typeof connection.client_id === 'string' && connection.client_id !== '' ? connection.client_id : null,
+        livemode: event.livemode,
+        created: event.created,
+    };
+}

package/dist/messages.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Text cut into the messages a shopper reads one at a time. A chat app sends each paragraph as its
+ * own message, so a reply written as three paragraphs arrives as three texts. A blank line ends a
+ * paragraph, with two exceptions that keep a block whole: a fenced code block, and a list whose
+ * items a blank line separates.
+ */
+/**
+ * The text as separate messages, in order: one per paragraph, each trimmed, with empty ones left
+ * out. One or more blank lines end a paragraph. A fenced code block stays one message whatever blank
+ * lines it holds, and so does a list whose items blank lines separate.
+ *
+ * ```ts
+ * toMessages('Found two.\n\nWant the first one?'); // ['Found two.', 'Want the first one?']
+ * ```
+ */
+export declare function toMessages(text: string): string[];
+/** What `messageStream` hands back: push each piece of text as it arrives, then end once it stops. */
+export interface MessageStream {
+    /** Adds the next piece of text. Each message the piece completes goes to `onMessage` in order, after the one before it settled. */
+    push(delta: string): void;
+    /**
+     * The text is whole: the last message goes to `onMessage`. Resolves once every `onMessage` call
+     * settled, and rejects with the first error one threw or rejected with. A push after `end` throws.
+     */
+    end(): Promise<void>;
+}
+export interface MessageStreamOptions {
+    /**
+     * Hears each message, once and in order, as soon as the text after it ends it. A returned promise
+     * is awaited before the next message goes out, so an asynchronous send never delivers out of order.
+     * After a send fails, no later message is sent, and `end` rejects with the failure.
+     */
+    onMessage: (message: string) => void | Promise<void>;
+}
+/**
+ * Cuts streamed text into the messages `toMessages` finds, as it arrives. Each paragraph goes to
+ * `onMessage` the moment the blank line that ends it arrives, whatever the pieces split it into. A
+ * paragraph inside a list waits for the first characters of the line after the blank, which say
+ * whether the list goes on. `end` hands over the last message and waits for every send.
+ *
+ * ```ts
+ * const paragraphs = messageStream({ onMessage: (text) => sendToShopper(text) });
+ * stream.on('text', (delta) => paragraphs.push(delta));
+ * await stream.done();
+ * await paragraphs.end();
+ * ```
+ */
+export declare function messageStream(options: MessageStreamOptions): MessageStream;

package/dist/messages.js

@@ -0,0 +1,206 @@
+/**
+ * Text cut into the messages a shopper reads one at a time. A chat app sends each paragraph as its
+ * own message, so a reply written as three paragraphs arrives as three texts. A blank line ends a
+ * paragraph, with two exceptions that keep a block whole: a fenced code block, and a list whose
+ * items a blank line separates.
+ */
+/** A line holding nothing but spaces or tabs. */
+const BLANK = /^[ \t]*$/;
+/** A list item: `-`, `*` or `+`, or a number followed by `.` or `)`, then a space or the line's end. */
+const LIST_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/;
+/** A list item whose marker a space already follows, the only kind a line still being written is sure to stay. */
+const LIST_ITEM_SPACED = /^ {0,3}(?:[-*+]|\d{1,9}[.)])[ \t]/;
+/** A line indented under a list item: two spaces or a tab, then text. */
+const INDENTED = /^(?: {2,}|\t)\S/;
+/** The start of a line that can still grow into a list item or an indented line once more text arrives. */
+const MAYBE_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)]?)?$|^[ \t]*$/;
+/** A code fence: three or more backticks or tildes, indented by at most three spaces. */
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+/** How the line after a blank line inside a list reads: it continues the list, it ends it, or it is too short to tell. */
+function afterListBlank(line, complete) {
+    // `1.` alone is an item once the line ends there, and the start of `1.5 cups` while it is still arriving.
+    if ((complete ? LIST_ITEM : LIST_ITEM_SPACED).test(line) || INDENTED.test(line))
+        return 'continues';
+    if (!complete && MAYBE_ITEM.test(line))
+        return 'unknown';
+    return 'ends';
+}
+/** True when `line` closes the fence `open` opened: the same character, at least as many times, and nothing after. */
+function closesFence(line, open) {
+    const match = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+    return !!match && match[1][0] === open[0] && match[1].length >= open.length;
+}
+/**
+ * Reads text line by line and closes each message once nothing later can change it. It keeps only
+ * the message being built, so text fed in pieces costs what the text costs once.
+ */
+class Scanner {
+    onClose;
+    current = [];
+    fence = null;
+    inList = false;
+    blankInList = false;
+    constructor(onClose) {
+        this.onClose = onClose;
+    }
+    close() {
+        const message = this.current.join('\n').trim();
+        this.current = [];
+        this.inList = false;
+        this.blankInList = false;
+        if (message)
+            this.onClose(message);
+    }
+    /** One whole line. */
+    line(line) {
+        if (this.fence !== null) {
+            this.current.push(line);
+            if (closesFence(line, this.fence))
+                this.fence = null;
+            return;
+        }
+        if (BLANK.test(line)) {
+            if (this.current.length === 0)
+                return;
+            // A blank line ends the paragraph, unless it sits between two items of one list.
+            if (this.inList)
+                this.blankInList = true;
+            else
+                this.close();
+            return;
+        }
+        if (this.blankInList) {
+            if (afterListBlank(line, true) === 'ends')
+                this.close();
+            else
+                this.current.push('');
+            this.blankInList = false;
+        }
+        this.current.push(line);
+        if (LIST_ITEM.test(line))
+            this.inList = true;
+        else if (this.current.length === 1)
+            this.inList = false;
+        const open = FENCE.exec(line);
+        if (open)
+            this.fence = open[1];
+    }
+    /**
+     * The start of a line still being written. After a blank line inside a list, its first characters
+     * can already say the list ended, and the list goes out as soon as they do. Only the start counts:
+     * no marker, indent or number runs past 16 characters.
+     */
+    partial(start) {
+        if (this.fence === null && this.blankInList && afterListBlank(start.slice(0, 16), false) === 'ends')
+            this.close();
+    }
+    /** The text is whole: the message being built closes. */
+    end() {
+        this.close();
+    }
+}
+/**
+ * The text as separate messages, in order: one per paragraph, each trimmed, with empty ones left
+ * out. One or more blank lines end a paragraph. A fenced code block stays one message whatever blank
+ * lines it holds, and so does a list whose items blank lines separate.
+ *
+ * ```ts
+ * toMessages('Found two.\n\nWant the first one?'); // ['Found two.', 'Want the first one?']
+ * ```
+ */
+export function toMessages(text) {
+    const messages = [];
+    const scanner = new Scanner((message) => messages.push(message));
+    for (const line of String(text ?? '').replace(/\r\n?/g, '\n').split('\n'))
+        scanner.line(line);
+    scanner.end();
+    return messages;
+}
+/**
+ * Cuts streamed text into the messages `toMessages` finds, as it arrives. Each paragraph goes to
+ * `onMessage` the moment the blank line that ends it arrives, whatever the pieces split it into. A
+ * paragraph inside a list waits for the first characters of the line after the blank, which say
+ * whether the list goes on. `end` hands over the last message and waits for every send.
+ *
+ * ```ts
+ * const paragraphs = messageStream({ onMessage: (text) => sendToShopper(text) });
+ * stream.on('text', (delta) => paragraphs.push(delta));
+ * await stream.done();
+ * await paragraphs.end();
+ * ```
+ */
+export function messageStream(options) {
+    const onMessage = options?.onMessage;
+    if (typeof onMessage !== 'function')
+        throw new TypeError('Pass onMessage as a function that takes each message.');
+    // The line still being written. A trailing \r waits here too, in case its \n is in the next piece.
+    let open = '';
+    let ended = false;
+    let failure = null;
+    // Messages waiting for the send before them. A send that returns no promise goes out at once.
+    const queue = [];
+    let running = null;
+    const drain = () => {
+        while (queue.length > 0 && !failure) {
+            const message = queue.shift();
+            let sent;
+            try {
+                sent = onMessage(message);
+            }
+            catch (error) {
+                failure = { error };
+                break;
+            }
+            if (sent && typeof sent.then === 'function') {
+                return Promise.resolve(sent).then(() => drain() ?? undefined, (error) => {
+                    failure = { error };
+                });
+            }
+        }
+        return null;
+    };
+    const kick = () => {
+        if (running)
+            return;
+        const pending = drain();
+        if (pending) {
+            running = pending.then(() => {
+                running = null;
+                kick();
+            });
+        }
+    };
+    const scanner = new Scanner((message) => {
+        queue.push(message);
+        kick();
+    });
+    return {
+        push(delta) {
+            if (ended)
+                throw new Error('This message stream has ended. Start a new one for the next text.');
+            if (typeof delta !== 'string' || delta === '')
+                return;
+            const text = open + delta;
+            const cut = text.endsWith('\r') ? text.length - 1 : text.length;
+            const lines = text.slice(0, cut).replace(/\r\n?/g, '\n').split('\n');
+            open = (lines.pop() ?? '') + text.slice(cut);
+            for (const line of lines)
+                scanner.line(line);
+            // A held \r is a line ending still arriving, not text that could end a list.
+            scanner.partial(open.endsWith('\r') ? open.slice(0, -1) : open);
+        },
+        async end() {
+            if (!ended) {
+                ended = true;
+                for (const line of open.replace(/\r\n?/g, '\n').split('\n'))
+                    scanner.line(line);
+                open = '';
+                scanner.end();
+            }
+            while (running)
+                await running;
+            if (failure)
+                throw failure.error;
+        },
+    };
+}