@agent-cards/commerce-sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -35,4 +35,4 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED. IN NO EVENT SHALL AGENTCARD CORPORATION BE LIABLE FOR ANY CLAIM,
 DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.
 
-Questions: legal@agentcard.sh
+Questions: legal@agentcard.com

package/README.md

@@ -101,10 +101,35 @@ console.log(await result.getText());
 
 A purchase needs a link at three moments: the shopper approves the purchase on an approval page, a new shopper adds a card on a Vault page, and a shopper signs in to a store's own account on its login page before Agentcard can buy there. Each link's `kind` says which: `approval`, `vault` or `store_login`, and a `store_login` link names the store in `store`. The tool hands each link to `sendLink` and waits for it, so the shopper holds the link before the model answers. The model reads `link_sent: true` and never the link itself, because a tool runner puts each answer straight into the model's context, and a model that holds a link writes it into the chat.
 
-The tool also hands `sendLink` a `product` link for each product a search finds, up to twenty per answer. The link carries the product's page at its store in `url`, the product's name in `title`, its price in `price`, such as `$12.99`, and its id in `productId`. Every price the tool writes, in a link or in the model's view, uses the currency Agentcard names for the cart or the product, in that currency's own minor units: `1331` is `$13.31` in USD, `CA$13.31` in CAD and `¥1,331` in JPY. A price whose currency Agentcard does not name shows with no symbol. The link arrives beside the reply, and you decide how to show it: as a card, in a list, or as a text with the URL. The model reads `product_links_sent` and never a URL, so a shopper who asks for links hears that the links are there. When the next answer in the conversation shows the same products, the tool sends none of their links again. A product link your `sendLink` throws on counts as not sent, and the call goes on.
+The tool also hands `sendLink` a `product` link for each product a search finds, up to three per answer. The link carries the product's page at its store in `url`, the product's name in `title`, its price in `price`, such as `$12.99`, its id in `productId`, and its picture in `imageUrl`, or null when the store sent none. Every price the tool writes, in a link or in the model's view, uses the currency Agentcard names for the cart or the product, in that currency's own minor units: `1331` is `$13.31` in USD, `CA$13.31` in CAD and `¥1,331` in JPY. A price whose currency Agentcard does not name shows with no symbol. The link arrives beside the reply, and you decide how to show it: as a card, in a list, or as a text with the URL. The model reads `product_links_sent` and never a URL, so a shopper who asks for links hears that the links are there. When the next answer in the conversation shows the same products, the tool sends none of their links again. A product link your `sendLink` throws on counts as not sent, and the call goes on.
 
 Without `sendLink`, `result.links` still carries each Vault, approval and store login link for your code, each product in `result.products` carries its `url`, and the model still never reads one.
 
+## Send each paragraph as its own message
+
+A chat app reads best when each paragraph arrives as its own message. `toMessages` cuts text at its blank lines, trims each message and leaves out the empty ones. A list whose items blank lines separate stays one message, and so does a fenced code block:
+
+```ts
+import { toMessages } from '@agent-cards/commerce-sdk';
+
+for (const text of toMessages(reply)) await textShopper(shopper.id, text);
+```
+
+`result.messages` from `buy.answer` holds Agentcard's own answer cut the same way, links included, so your code sends it without cutting it again.
+
+For a reply your model streams, `messageStream` hands over each paragraph the moment the blank line that ends it arrives, however the stream cuts the text. Push each piece of text, then call `end` for the last paragraph:
+
+```ts
+import { messageStream } from '@agent-cards/commerce-sdk';
+
+const paragraphs = messageStream({ onMessage: (text) => textShopper(shopper.id, text) });
+stream.on('text', (delta) => paragraphs.push(delta));
+await stream.done();
+await paragraphs.end();
+```
+
+`stream` stands for your model's streamed answer. When `onMessage` returns a promise, the stream waits for it before it sends the next paragraph, so the shopper reads them in order, and `end` resolves once every paragraph went out. After a send fails, no later paragraph goes out, and `end` rejects with that error. A paragraph inside a list waits for the first characters of the next line, which say whether the list goes on. Start a new `messageStream` for each model message, so one message never runs into the next.
+
 ## Sign up a new shopper
 
 A shopper who has not connected to your company yet gets a Vault link on their first call. The tool asks Agentcard for the link and hands it to `sendLink`, and the model reads `needs_card`. The shopper connects and adds a card on the Vault page, and the next call buys. Agentcard returns the same link while it has time left, so a shopper who asks twice gets one link.

package/dist/buy-tool.d.ts

@@ -22,7 +22,7 @@
  * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
  * to a minute, until the turn ends.
  */
-import { AgentcardClient, type BuyCart, type BuyDeliveryAddress, type FetchLike } from './client.js';
+import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type BuyToolModelView } from './model-view.js';
 /**
@@ -40,7 +40,7 @@ export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'pl
  * card. `approval`: the page where they approve this purchase. `store_login`:
  * the page where they sign in to the store named in `store`, before Agentcard
  * can buy there. `product`: a product's page at its store, with its `title`,
- * `price` and `productId`.
+ * `price`, `productId` and `imageUrl`.
  */
 export interface BuyToolLink {
     kind: 'vault' | 'approval' | 'store_login' | 'product';
@@ -55,9 +55,12 @@ export interface BuyToolLink {
     price?: string | null;
     /** On a product link: Agentcard's id for the product. */
     productId?: string;
+    /** On a product link: the product's picture, or null when Agentcard sent none. Show it beside the title. */
+    imageUrl?: string | null;
 }
 /** A product the last search found. */
 export interface BuyToolProduct {
+    flight?: BuyFlightItinerary;
     id: string;
     name: string;
     /** The price in the minor unit of `currency`. */
@@ -80,6 +83,12 @@ export interface BuyToolResult {
     status: BuyToolStatus;
     /** Agentcard's answer for the shopper, links included. */
     reply: string;
+    /**
+     * The same answer as the separate messages a shopper reads one at a time, links included: each
+     * message Agentcard sent (the purchase answer's `messages`), cut at its blank lines by `toMessages`.
+     * An answer the tool wrote itself, such as `placing`, is `reply` cut the same way.
+     */
+    messages: string[];
     /** The cart on the table, or null. */
     cart: BuyCart | null;
     /** Every cart on the table, oldest first. */
@@ -97,6 +106,8 @@ export interface BuyToolResult {
     order_id: string | null;
     decline_code: string | null;
     error_code: string | null;
+    /** The one step the shopper takes next, as Agentcard named it, or null. Only that step's link is in `links`. */
+    next_action: BuyNextAction | null;
     /** Every cart hash in this answer. */
     hashes: string[];
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */

package/dist/buy-tool.js

@@ -25,6 +25,7 @@
 import { AgentcardApiError, AgentcardClient, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
 import { forModel, forModelError, money, shownProducts } from './model-view.js';
+import { toMessages } from './messages.js';
 /** The pause before the one read that follows a placement Agentcard is still finishing. */
 const PLACEMENT_WAIT_MS = 12_000;
 /** After a turn that outlived Agentcard's budget: one read every 5 seconds, for at most a minute. */
@@ -63,6 +64,7 @@ function productsOf(turn) {
         priceCents: item.priceCents,
         currency: item.currency,
         imageUrl: item.image_url,
+        ...(item.flight ? { flight: item.flight } : {}),
         store: item.store?.name ?? item.store?.id ?? turn.catalog?.merchant_name ?? null,
         url: item.url ?? null,
         linkSent: false,
@@ -79,6 +81,7 @@ function answerOf(turn) {
     return {
         status: 'needs_input',
         reply: turn.reply,
+        messages: [],
         cart: turn.cart,
         carts: turn.carts,
         products: productsOf(turn),
@@ -90,13 +93,60 @@ function answerOf(turn) {
         order_id: turn.order_id,
         decline_code: turn.decline_code,
         error_code: turn.error_code,
+        next_action: turn.next_action,
         hashes: hashesOf(turn.cart, turn.carts),
         envelope: turn.raw,
     };
 }
+/**
+ * The answer that waits on the shopper's card, when the turn carries Agentcard's add-card link: a
+ * checkout refused on an empty vault (`vault_unavailable`), or the agent made the link while it
+ * asked. The status beside it does not decide: the link is the one way forward either way, and the
+ * reply has every link taken out. Null when the turn carries no link, or placed an order.
+ */
+function needsCardOf(turn, answer) {
+    // Agentcard named another step first: the card waits until that one is done.
+    if (turn.next_action && turn.next_action !== 'add_card')
+        return null;
+    if (!turn.add_card_url || turn.status === 'order_placed' || turn.status === 'partially_placed' || turn.status === 'needs_approval')
+        return null;
+    const refused = turn.status === 'declined';
+    // A refusal with another code is about something other than a card, and keeps its own status.
+    if (refused && turn.decline_code !== 'vault_unavailable')
+        return null;
+    if (!refused && turn.decline_code && turn.decline_code !== 'vault_unavailable')
+        return null;
+    return { ...answer, status: 'needs_card', links: [...answer.links, { kind: 'vault', url: turn.add_card_url, expiresAt: turn.add_card_expires_at }] };
+}
+/**
+ * The answer with only the link of the step the shopper takes now, when Agentcard names one
+ * (`next_action`): the Vault link waits for `add_card`, the approval link for `approve`. A store login
+ * link and product pages are not steps, so they stay. An answer that names no step keeps every link.
+ */
+function onlyNextStepLinks(result, next) {
+    if (!next)
+        return result;
+    const links = result.links.filter((link) => (link.kind === 'vault' ? next === 'add_card' : link.kind === 'approval' ? next === 'approve' : true));
+    return links.length === result.links.length ? result : { ...result, links };
+}
+/**
+ * The answer's `messages`, read once its `reply` is final: the messages Agentcard sent while the reply
+ * is still Agentcard's own, else the reply the tool wrote, each cut at its blank lines.
+ */
+function withMessages(result, turn) {
+    const sent = turn && result.reply === turn.reply && turn.messages.length > 0 ? turn.messages : [result.reply];
+    return { ...result, messages: sent.flatMap(toMessages) };
+}
 /** A purchase answer, read for its status. A status Agentcard adds later reads as `needs_input`. */
 function resultOfTurn(turn) {
+    return onlyNextStepLinks(resultOfStatus(turn), turn.next_action);
+}
+/** A purchase answer, read for its status, with every link the answer carries. */
+function resultOfStatus(turn) {
     const answer = answerOf(turn);
+    const card = needsCardOf(turn, answer);
+    if (card)
+        return card;
     switch (turn.status) {
         case 'order_placed':
         case 'partially_placed':
@@ -116,10 +166,6 @@ function resultOfTurn(turn) {
                     shopper_need_not_reply: turn.placement_announced === true,
                 };
             }
-            // A shopper with no card gets the add-card link checkout made. Every other reason for this code is not about a card.
-            if (turn.decline_code === 'vault_unavailable' && turn.add_card_url) {
-                return { ...answer, status: 'needs_card', links: [...answer.links, { kind: 'vault', url: turn.add_card_url, expiresAt: turn.add_card_expires_at }] };
-            }
             return { ...answer, status: 'declined' };
         default:
             return answer;
@@ -132,6 +178,7 @@ function resultOfRefusal(error) {
     const answer = (reply, carts) => ({
         status: 'needs_input',
         reply,
+        messages: [],
         cart: carts.at(-1) ?? null,
         carts,
         products: [],
@@ -143,6 +190,7 @@ function resultOfRefusal(error) {
         order_id: null,
         decline_code: null,
         error_code: error.code,
+        next_action: null,
         hashes: hashesOf(null, carts),
         envelope: error.body,
     });
@@ -161,6 +209,7 @@ function needsCard(link, body) {
     return {
         status: 'needs_card',
         reply: CARD_NEEDED,
+        messages: [],
         cart: null,
         carts: [],
         products: [],
@@ -172,6 +221,7 @@ function needsCard(link, body) {
         order_id: null,
         decline_code: null,
         error_code: 'user_not_connected',
+        next_action: 'add_card',
         hashes: [],
         envelope: body,
     };
@@ -267,6 +317,7 @@ export function buyTool(options) {
                 status: 'order_placed',
                 reply: `The ${order.merchant || 'store'} order went through, order number ${order.orderId}.`,
                 links: [],
+                next_action: null,
                 order_id: order.orderId,
                 conversation_id: conversationId,
             };
@@ -280,6 +331,7 @@ export function buyTool(options) {
             links: [],
             order_id: order.orderId,
             decline_code: `order_${order.status}`,
+            next_action: null,
             shopper_need_not_reply: false,
             conversation_id: conversationId,
         };
@@ -291,6 +343,7 @@ export function buyTool(options) {
         reply: refusal.message || `${NOT_PLACED} The ${refusal.merchant || 'store'} answered ${refusal.code}.`,
         links: [],
         decline_code: refusal.code,
+        next_action: null,
         shopper_need_not_reply: false,
     });
     /**
@@ -306,7 +359,7 @@ export function buyTool(options) {
         const refusal = conversation && checkoutRefusal(conversation);
         if (refusal)
             return refusedCheckout(base, refusal);
-        return { ...base, status: 'placing', reply: STILL_PLACING, links: [] };
+        return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null };
     };
     /**
      * What a finished turn's checkout left besides an order, which `placedOrderOf`
@@ -324,6 +377,7 @@ export function buyTool(options) {
                 reply: last.message || CARD_NEEDED,
                 links: [{ kind: 'vault', url: last.add_card_url, expiresAt: last.add_card_expires_at }],
                 decline_code: last.decline_code,
+                next_action: 'add_card',
                 shopper_need_not_reply: false,
                 envelope: conversation.raw,
             };
@@ -335,13 +389,14 @@ export function buyTool(options) {
         }
         const announced = last.placement_announced === true;
         if (last.approval_in_progress === true)
-            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], shopper_need_not_reply: announced };
+            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null, shopper_need_not_reply: announced };
         return {
             ...base,
             status: 'approval_sent',
             reply: APPROVAL_WAITING,
             links: [{ kind: 'approval', url: last.approval_url, expiresAt: last.approval_expires_at }],
             approval_expires_at: last.approval_expires_at,
+            next_action: 'approve',
             shopper_need_not_reply: announced,
             envelope: conversation.raw,
         };
@@ -399,6 +454,8 @@ export function buyTool(options) {
                     carts: conversation.carts,
                     hashes: conversation.carts.map((c) => c.hash),
                     error_code: newest ? null : base.error_code,
+                    // A read replaced the answer the step was named for, and names no step of its own: the reply asks.
+                    next_action: null,
                     envelope: conversation.raw,
                 };
                 if (!conversation.turn_in_progress)
@@ -408,7 +465,7 @@ export function buyTool(options) {
             }
         }
         if (placing)
-            return { ...base, status: 'placing', reply: STILL_PLACING, links: [] };
+            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null };
         // A minute that ends with the turn still running returns what the last read showed, a new cart as
         // ready although no read handed it back: nothing better exists by then, and a confirm that misses it
         // is refused, never placed on another cart.
@@ -479,7 +536,7 @@ export function buyTool(options) {
         for (const [url, product] of pages) {
             if (!before.has(url)) {
                 try {
-                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, expiresAt: null });
+                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, imageUrl: product.imageUrl, expiresAt: null });
                 }
                 catch {
                     continue;
@@ -530,7 +587,7 @@ export function buyTool(options) {
         catch (error) {
             refusal = error;
         }
-        return deliver(turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt));
+        return deliver(withMessages(turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt), turn));
     };
     /** Checks the model's input, with every link taken out of a refusal. */
     const parse = (input) => {

package/dist/client.d.ts

@@ -87,7 +87,19 @@ export interface BuyCart {
     hash: string;
 }
 /** A product a search found. `priceCents` is in the minor unit of `currency`, the store's ISO 4217 code. */
+/** Supplier facts only. Missing facts stay null; fare cabin does not establish segment cabins. */
+export interface BuyFlightItinerary {
+    fareCabinClass?: string | null;
+    legs: Array<{
+        origin: string | null;
+        destination: string | null;
+        departureAt: string | null;
+        arrivalAt: string | null;
+        cabinClasses: Array<string | null>;
+    }>;
+}
 export interface BuyCatalogItem {
+    flight?: BuyFlightItinerary;
     id: string;
     name: string | null;
     priceCents: number | null;
@@ -109,6 +121,14 @@ export interface BuyPaymentSource {
     brand: string | null;
     last4: string | null;
 }
+/**
+ * The one thing the shopper does next, as Agentcard names it, in the order a purchase asks for them:
+ * `shipping_details` (a shipping address and phone), `guest_details` (a name, email and phone for a
+ * booking), `add_card` (a card in their Vault), `confirm` (their yes to the cart), `verification_code`
+ * (the code a booking texted them), then `approve` (the approval link). A value this version does
+ * not know reads as null.
+ */
+export type BuyNextAction = 'shipping_details' | 'guest_details' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
 /** One turn's answer, every field read for its type; a field an older API does not send reads as null. */
 export interface BuyTurn {
     conversation_id: string;
@@ -133,6 +153,8 @@ export interface BuyTurn {
     placement_announced: boolean | null;
     approval_expires_at: string | null;
     approval_in_progress: boolean | null;
+    /** The one step the shopper takes next, or null when nothing waits on them or Agentcard named none. */
+    next_action: BuyNextAction | null;
     /** The page where the shopper signs in to a store's own account before Agentcard can buy there. */
     store_login_url: string | null;
     store_login_expires_at: string | null;

package/dist/client.js

@@ -16,6 +16,7 @@ export const BUY_TURN_TIMEOUT_MS = 130_000;
 const CALL_TIMEOUT_MS = 30_000;
 /** A token is renewed this long before it expires, so it never expires mid-call. */
 const RENEW_EARLY_MS = 60_000;
+const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'add_card', 'confirm', 'verification_code', 'approve']);
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
  * (`user_not_connected`, `external_user_id_ambiguous`, `turn_in_progress`,
@@ -97,18 +98,35 @@ function cartOf(v) {
 function cartsOf(v) {
     return Array.isArray(v) ? v.map(cartOf).filter((c) => c !== null) : [];
 }
+function flightOf(value) {
+    if (!isRecord(value) || !Array.isArray(value.legs))
+        return undefined;
+    return {
+        ...(Object.hasOwn(value, 'fareCabinClass') ? { fareCabinClass: str(value.fareCabinClass) } : {}),
+        legs: value.legs.map(value => {
+            const leg = isRecord(value) ? value : {};
+            return { origin: str(leg.origin), destination: str(leg.destination),
+                departureAt: str(leg.departureAt), arrivalAt: str(leg.arrivalAt),
+                cabinClasses: Array.isArray(leg.cabinClasses) ? leg.cabinClasses.map(str) : [] };
+        }),
+    };
+}
 function catalogOf(v) {
     if (!isRecord(v))
         return null;
-    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => ({
-        id: str(i.id) ?? '',
-        name: str(i.name),
-        priceCents: num(i.priceCents),
-        currency: str(i.currency),
-        image_url: str(i.image_url),
-        store: storeOf(i.store),
-        url: pageUrl(i.url),
-    })) : [];
+    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+        const flight = flightOf(i.flight);
+        return {
+            id: str(i.id) ?? '',
+            name: str(i.name),
+            priceCents: num(i.priceCents),
+            currency: str(i.currency),
+            image_url: str(i.image_url),
+            ...(flight ? { flight } : {}),
+            store: storeOf(i.store),
+            url: pageUrl(i.url),
+        };
+    }) : [];
     return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items };
 }
 function paymentSourceOf(v) {
@@ -142,6 +160,7 @@ export function turnOf(body) {
         store_login_url: str(body.store_login_url),
         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,
         raw: body,
     };
 }

package/dist/definition.js

@@ -11,6 +11,7 @@ export const BUY_TOOL_DESCRIPTION = [
     "Put the shopper's own words in `ask`.",
     'Tell the shopper what `reply` says, in your own voice.',
     '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.',
     'Never write a link.',
     'Each link reaches the shopper on its own.',

package/dist/index.d.ts

@@ -1,8 +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 BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, } from './client.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

@@ -3,6 +3,7 @@ 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/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;
+        },
+    };
+}

package/dist/model-view.d.ts

@@ -1,3 +1,12 @@
+/**
+ * What the model reads: the buy tool's answer with every link taken out. A
+ * tool runner puts a tool's result straight into the model's context, and a
+ * model that holds a link writes it into the chat. So a link never enters
+ * this view: `sendLink` delivers it, and the model reads `link_sent` for the
+ * Vault and approval links, and `link_sent` on each product and
+ * `product_links_sent` for the products' store pages.
+ */
+import type { BuyNextAction } from './client.js';
 import type { BuyToolProduct, BuyToolResult, BuyToolStatus } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
@@ -19,6 +28,8 @@ export interface BuyToolModelProduct {
 /** The buy tool's answer as the model reads it. */
 export interface BuyToolModelView {
     status: BuyToolStatus;
+    /** The one thing to ask the shopper for in this message, or null when nothing waits on them. Never ask for a later step. */
+    next_action: BuyNextAction | null;
     /** Agentcard's answer for the shopper, with every link taken out. */
     reply: string;
     /** The newest cart on the table. */

package/dist/model-view.js

@@ -1,5 +1,5 @@
 const MODEL_STATUSES = new Set(['needs_input', 'needs_card', 'approval_sent', 'placing', 'order_placed', 'declined']);
-/** The model sees the first twenty products the search found, the cap the backend's catalog keeps for a turn. */
+/** At most twenty products reach the model. Agentcard's /buy answer lists three, so this cap holds only for an older answer. */
 const MAX_PRODUCTS = 20;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const SCHEME_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`)\]]*/gi;
@@ -88,6 +88,7 @@ export function forModel(result) {
     const held = (product) => product.linkSent === true && typeof product.url === 'string' && product.url !== '';
     return {
         status,
+        next_action: result.next_action ?? null,
         reply: stripLinks(result.reply),
         cart: result.cart ? cartView(result.cart) : null,
         carts: (result.carts ?? []).map(cartView),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and hear what happened to each purchase from a signed webhook.",
   "type": "module",
   "main": "dist/index.js",