@agent-cards/commerce-sdk 0.18.2 → 0.18.4

package/README.md

@@ -178,6 +178,40 @@ onShopperMessage((message) => windows.settle(message));
 
 `markStepDone`, `keepOfferingStep` and `onShopperMessage` stand for your own code. `settle` closes each open pop-up whose step the message ends and returns `[{ step, outcome }]`. A pop-up the shopper closes before the step ends reaches `onClosed`, checked every 500 milliseconds (`pollMs`): the step is still open, so keep its link on screen, and a tap opens it again. Tapping a step whose pop-up is open brings that window to the front instead of opening a second one. A phone's browser opens the pop-up as a tab, and `settle` closes that tab the same way, since the chat opened it. The pop-up is 480 by 760 pixels by default (`width`, `height`), kept inside the screen. It keeps its opener on purpose: a window opened with `noopener` hands back no handle, so the chat could neither close it nor tell when the shopper closed it. `dispose()` stops watching and leaves every pop-up open, so a chat that remounts never shuts the page a shopper is typing a card into.
 
+## Keep the answer when the shopper's connection drops
+
+A phone that loses its connection while a reply streams back would show the shopper an error, though the turn finished on your server. Serve the turn with `turnStream` and read it in the browser with `streamTurn`, and the shopper gets the answer anyway. On your server:
+
+```ts
+import { readTurn, turnStream, isTurnId } from '@agent-cards/commerce-sdk';
+
+// POST /chat: the browser names the turn in `x-turn-id`.
+const turnId = request.headers.get('x-turn-id');
+if (!isTurnId(turnId)) return Response.json({ error: 'Name the turn.' }, { status: 400 });
+const { stream, finished } = turnStream({ store, key: `${shopperId}:${turnId}`, run: (send) => runTurn(send) });
+waitUntil(finished);
+return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });
+
+// GET /chat/turn?id=...: the turn's record, for the browser to pick up where its stream stopped.
+return Response.json(await readTurn(store, `${shopperId}:${id}`));
+```
+
+`store` is yours, such as Redis: `load(key)` and `save(key, record, ttlSeconds)`. `runTurn` stands for your agent's turn, and `send(event, data)` takes each event the chat shows, the last one included, such as `done`. The turn runs to its end after the browser leaves, and `finished` resolves once its record is saved: hand it to your host's `waitUntil`. The record is kept for ten minutes (`ttlSeconds`). Put your shopper's id in the key, so no shopper reads another's turn. When one turn at a time runs per shopper, answer a message sent during a turn with a 409 whose body names that turn, `{ "error": "...", "turn_id": "..." }`.
+
+In the browser:
+
+```ts
+import { streamTurn, readTurnResponse } from '@agent-cards/commerce-sdk/browser';
+
+const { refused } = await streamTurn({
+  start: (turnId) => fetch('/chat', { method: 'POST', headers: { 'x-turn-id': turnId }, body }),
+  read: (turnId) => fetch(`/chat/turn?id=${turnId}`).then(readTurnResponse),
+  onEvent: (event, data) => show(event, data),
+});
+```
+
+`onEvent` hears each event once, in order. When the stream drops, before its first event or after it, `streamTurn` reads the turn's record every 1.5 seconds (`pollMs`) and hands over the events the stream did not carry, until the turn's last one. A 409 that names a running turn waits for that turn's answer the same way. Any other refusal comes back in `refused`, the response, for you to show its error. A record that never appears within 15 seconds (`startWaitMs`) means the message never reached your server, and `streamTurn` throws the connection's error.
+
 ## Answer each shopper message in its own turn
 
 A shopper can send a second message before the first is answered. The `sendLink`, `onWorking` and `onResult` you pass to `buyTool` hear every call, whichever message the call answers, so a callback that hands each link to "the message running now" gives the first message's cards to the second. Open a turn for each message instead, and pass the turn to your model in place of the tool:
@@ -251,6 +285,8 @@ const turn = buy.turn(message, {
   onItem: (item) => (item.kind === 'text' ? sendText(shopper.id, item.text) : sendCard(shopper.id, item.link)), // your code
 });
 if (await turn.handled()) {
+  // A newer message from the shopper stopped this turn: that message's turn answers and keeps the exchange.
+  if (turn.stopped) return;
   // Agentcard answered the shopper: keep the exchange, so your model reads it on the next message.
   const said = turn.items.flatMap((item) => (item.kind === 'text' ? [item.text] : [])).join('\n\n');
   history = [...turn.messages(history), { role: 'assistant', content: said }];
@@ -432,7 +468,7 @@ const buy = buyTool({
 
 `ack` takes `'reaction'`, `'text'` or `'none'`. Left out, the tool reacts when the tool or the turn has an `onReaction`, and sends text through `onWorking` otherwise, so an app built on 0.9 with only `onWorking` keeps its text replies. With both callbacks, the shopper gets the 👀 and never the text too. `'none'`, or `false`, sends nothing.
 
-In text mode, a streamed search's reply is Agentcard's own line, written from the conversation while it searches, such as `one sec, checking target for la croix`, and it reaches `onWorking` before the cards or not at all. A search `buy.turn` sends straight that has shown the shopper nothing by twice `ackDelayMs`, because Agentcard wrote no line or its line was dropped, sends `one moment` once, and a line of Agentcard's that comes after it is dropped. When your model's run fails before it wrote or called anything, call `turn.end()` before you show your error, so no wait line follows it. With `stream: false`, the tool sends its own reply when Agentcard has not answered a new request within `ackDelayMs`, 1 second by default, so a quick answer arrives alone. It sends one for the calls the model makes in one turn, where a call that starts within 15 seconds of the last one ending counts as the same turn. A slow confirm or pick never hears `looking for`: a pick, of a product, a store or a place in a list such as `the first one`, hears `got it, one moment`, a confirm hears `on it, one moment`, and any other answer hears `one moment`. A turn opened with `buy.turn` that has shown the shopper nothing, no line and no card, after the delay sends that line once. None of them names anything the shopper said, and a code hears nothing. The words rotate through six templates, and one tool never sends the same template twice in a row. A short paraphrase of the request goes in when the tool can read one: it stops before any link, email address, phone number, street address or long number, and a request that starts with one gets a reply that names nothing, such as `looking for that now`. The call waits for `onWorking`, so the shopper reads the reply before any link and before the model answers. An `onWorking` that throws costs only the instant reply.
+In text mode, a streamed search's reply is Agentcard's own line, written from the conversation while it searches, such as `one sec, checking target for la croix`, and it reaches `onWorking` before the cards or not at all. A search `buy.turn` sends straight that has shown the shopper nothing by twice `ackDelayMs`, because Agentcard wrote no line or its line was dropped, sends `one moment` once, and a line of Agentcard's that comes after it is dropped. When your model's run fails before it wrote or called anything, call `turn.end()` before you show your error, so no wait line follows it. When `turn.stopped` is true after a call, the shopper sent a new message while this turn ran and Agentcard stopped the turn for it: end the turn there, with no model call, no error and no saved history, because the new message's turn answers. With `stream: false`, the tool sends its own reply when Agentcard has not answered a new request within `ackDelayMs`, 1 second by default, so a quick answer arrives alone. It sends one for the calls the model makes in one turn, where a call that starts within 15 seconds of the last one ending counts as the same turn. A slow confirm or pick never hears `looking for`: a pick, of a product, a store or a place in a list such as `the first one`, hears `got it, one moment`, a confirm hears `on it, one moment`, and any other answer hears `one moment`. A turn opened with `buy.turn` that has shown the shopper nothing, no line and no card, after the delay sends that line once. None of them names anything the shopper said, and a code hears nothing. The words rotate through six templates, and one tool never sends the same template twice in a row. A short paraphrase of the request goes in when the tool can read one: it stops before any link, email address, phone number, street address or long number, and a request that starts with one gets a reply that names nothing, such as `looking for that now`. The call waits for `onWorking`, so the shopper reads the reply before any link and before the model answers. An `onWorking` that throws costs only the instant reply.
 
 Pass `ack: (ask) => text` to write your own text from the shopper's words, where an empty answer sends none, and `ackDelayMs` to change the 1 second for either mode.
 

package/dist/ack.js

@@ -15,6 +15,7 @@
  * store the shopper saw, such as `order here`, or `Order from Tacos El Grullense` as a store card sends it.
  */
 import { SENTENCE_END } from './sentences.js';
+import { withoutTripVerb } from './trip-ask.js';
 /** Each template twice: with the paraphrase in place of `{x}`, and without one. */
 const TEMPLATES = [
     ['on it, looking for {x}', 'on it, looking for that now'],
@@ -301,7 +302,7 @@ export function paraphrase(text) {
     }
     for (let before = ''; before !== rest;) {
         before = rest;
-        rest = rest.replace(LEAD, '');
+        rest = withoutTripVerb(rest.replace(LEAD, ''));
     }
     // `order from tacos el grullense` names the store, never `from tacos el grullense`.
     rest = rest.replace(/^(?:from|at)\s+/, '').replace(/[\s,]+(?:please|pls|thanks|thank you|thx|ty)$/, '').replace(/[\s,.:!?]+$/, '');

package/dist/browser.d.ts

@@ -105,3 +105,5 @@ export interface ActionWindows {
  * so the chat could neither close it nor tell when the shopper closed it.
  */
 export declare function actionWindows(options?: ActionWindowsOptions): ActionWindows;
+export { streamTurn, readTurnResponse, type StreamTurnOptions, type StreamTurnResult, type TurnResponseLike } from './turn-reader.js';
+export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord } from './turn-record.js';

package/dist/browser.js

@@ -118,3 +118,6 @@ export function actionWindows(options = {}) {
         },
     };
 }
+// A chat turn read in the browser: a dropped connection reads the turn's answer back by the turn's id.
+export { streamTurn, readTurnResponse } from './turn-reader.js';
+export { TURN_RECOVERY_ON, isTurnId } from './turn-record.js';

package/dist/buy-tool.d.ts

@@ -638,6 +638,14 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
      * again does nothing.
      */
     end(): void;
+    /**
+     * True once a call of this turn answered `turn_stopped`: the shopper sent a newer message, and Agentcard stopped this
+     * turn for it. The newer message's turn answers the shopper, so this one is over. Do not call your model again, show
+     * no error and save no history for it: the cards it already showed stay with the shopper. The call returns to your
+     * model as any other, so check `stopped` after each call. The stopped answer goes to no `onResult` and changes nothing
+     * a later turn reads, and no wait line or 👀 follows it.
+     */
+    readonly stopped: boolean;
     /** The instant reply this turn sent to `onWorking` when it opened, or null when it sent none, as with a reaction. */
     readonly ack: string | null;
     /** The reaction this turn put on the shopper's message, `👀`, when it opened or once a call ran slow, or null while it put none or when `onReaction` threw. */

package/dist/buy-tool.js

@@ -130,6 +130,8 @@ const APP_TURN_MS = 120_000;
 const STEP_LINK_KINDS = new Set(['vault', 'approval', 'store_login']);
 /** The longest a step link waits for its message: an app that never writes one still sends the link. */
 const STEP_LINK_HOLD_MS = 20_000;
+/** The `error_code` of an answer whose turn a newer message from the same shopper stopped: that message's turn answers instead. */
+const TURN_STOPPED = 'turn_stopped';
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
 const STILL_BUILDING = "The store is still building the cart for the shopper's last request. Its cart and total reach the shopper in a message from Agentcard: once that message has arrived, call this tool again with the shopper's words.";
 const CART_NOT_READY = 'The store is still building the cart, so it has no total yet, and nothing was confirmed. Its cart and total reach the shopper in a message from Agentcard: confirm it only after the shopper says yes to that total.';
@@ -735,6 +737,15 @@ function checkoutRefusal(conversation) {
         return null;
     return { code, merchant: last.merchant_name, message: last.message };
 }
+/** Ends a turn (`turn.end()`, or a call it made that a newer message stopped): no wait line and no 👀 go out after it. */
+function endTurn(state) {
+    state.ended = true;
+    state.dropWaitLine?.();
+    // The acknowledgement a call still running holds, a 👀 or a line for a slow pick, confirm or answer, is cancelled too.
+    for (const cancel of state.holds ?? [])
+        cancel();
+    state.holds?.clear();
+}
 /**
  * A buy tool for one shopper. With a company client, name the shopper with
  * `externalUserId`; with a shopper's own `accessToken`, the token names them.
@@ -2005,6 +2016,15 @@ export function buyTool(options) {
             ack?.cancel();
             const settled = plan && 'local' in plan ? plan.local : turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirmSent, startedAt);
             await t.ackOut;
+            // A newer message from the shopper stopped this turn, and its own turn answers: this one ends here and says nothing
+            // more. Its empty answer holds no cart and lists no product, so it leaves what the shopper last read, the carts and
+            // the last ask as they were, and the app's onResult never hears it, so no cart panel empties.
+            if (turn?.error_code === TURN_STOPPED) {
+                endTurn(t);
+                t.stopped = true;
+                t.results?.push(settled);
+                return settled;
+            }
             // The streamed messages that waited for the answer go out in order: each the answer kept as written, and a card ask or
             // a link the answer replaced gives way to its ask for the step Agentcard named, once, after them. All of them go out
             // before any link of the answer.
@@ -2565,7 +2585,8 @@ export function buyTool(options) {
                     return false;
                 throw error;
             }
-            if (result.shopper_already_read_reply === true)
+            // A newer message stopped this turn, and that message's turn answers the shopper: nothing is left for the app's model.
+            if (result.shopper_already_read_reply === true || state.stopped)
                 return true;
             const reply = replyAsWritten(result, { textingStyle: texting });
             // The reply goes out where the app hears the turn's messages: onItem or onMessage, else onText. With none of them, the
@@ -2597,14 +2618,7 @@ export function buyTool(options) {
                 enumerable: false,
             },
             end: {
-                value: () => {
-                    state.ended = true;
-                    state.dropWaitLine?.();
-                    // The acknowledgement a call still running holds, a 👀 or a line for a slow pick, confirm or answer, is cancelled too.
-                    for (const cancel of state.holds ?? [])
-                        cancel();
-                    state.holds?.clear();
-                },
+                value: () => endTurn(state),
                 enumerable: false,
             },
             messages: { value: messagesFor, enumerable: false },
@@ -2613,7 +2627,8 @@ export function buyTool(options) {
             links: { get: () => [...links], enumerable: false },
             results: { get: () => [...results], enumerable: false },
             direct: { value: direct, enumerable: false },
-            replyAsWritten: { get: () => (written && results.length > 0 ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
+            stopped: { get: () => state.stopped === true, enumerable: false },
+            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
             items: { get: () => feed.items.map((item) => (item.kind === 'link' ? { kind: 'link', link: { ...item.link } } : { ...item })), enumerable: false },
             // Each message joins the feed the moment it is cut, so a link the tool hands over during a pause never overtakes text already written.
             // A step link held for this message goes out right after its last paragraph, once the stream ends.

package/dist/client.d.ts

@@ -50,6 +50,11 @@ export interface BuyCatalogUpdate {
     found: number | null;
     /** The products found past the cards, in the order they were found, to show on "show more" with no new search. */
     more: BuyCatalog['items'];
+    /**
+     * False while a search of the turn is still out, such as a second flight source: more cards may join these, and a card
+     * already shown may come again with a lower price under the same `id`. True once every source answered.
+     */
+    final: boolean;
 }
 /**
  * Whether a place a card shows has room at the time the shopper asked for: `checking` while Agentcard's live search runs,
@@ -424,6 +429,19 @@ export interface BuyChoiceOption {
     label: string;
     /** What choosing it adds to the price, in cents: 0 when free, null when the store does not say. */
     price_delta_cents: number | null;
+    /** On a `recipe_delivery` choice: the grocery store, when it arrives and what this way costs. Absent on every other choice. */
+    delivery?: BuyChoiceDelivery;
+}
+/**
+ * One way a recipe's groceries can come: the DoorDash grocery store, its street when DoorDash names one, its delivery estimate in
+ * minutes (null when DoorDash shows none), the total with DoorDash's fees, and the part of that total that ships from Walmart or Amazon.
+ */
+export interface BuyChoiceDelivery {
+    store: string;
+    store_address: string | null;
+    eta_minutes: number | null;
+    total_cents: number;
+    shipped_cents: number;
 }
 /** One group of values, such as a sandwich's bread or a shirt's size. `min` and `max` count the values picked; `max` null for no limit. */
 export interface BuyChoiceGroup {
@@ -436,7 +454,8 @@ export interface BuyChoiceGroup {
 /**
  * The choice an answer's reply asks the shopper to make, as data: the question, the item it is about, where the values come
  * from (`menu_item`: a restaurant item's options, `store_checkout`: a store's own size or colour question, `catalog_variant`:
- * a product's sizes or colours in stock), and every group with its values.
+ * a product's sizes or colours in stock, `recipe_delivery`: the ways a recipe's groceries can come, each option with its
+ * `delivery`), and every group with its values.
  */
 export interface BuyChoice {
     question: string | null;

package/dist/client.js

@@ -309,11 +309,17 @@ export function choiceOf(value) {
     if (!isRecord(value) || !Array.isArray(value.groups))
         return null;
     const groups = value.groups.filter(isRecord).flatMap((g) => {
-        const options = (Array.isArray(g.options) ? g.options : []).filter(isRecord).flatMap((o) => str(o.label) ? [{ id: str(o.id), label: o.label.trim(), price_delta_cents: num(o.price_delta_cents) }] : []);
+        const options = (Array.isArray(g.options) ? g.options : []).filter(isRecord).flatMap((o) => str(o.label) ? [{ id: str(o.id), label: o.label.trim(), price_delta_cents: num(o.price_delta_cents), ...deliveryOf(o.delivery) }] : []);
         return options.length ? [{ name: str(g.name) ?? '', required: g.required === true, min: num(g.min) ?? 0, max: num(g.max), options }] : [];
     });
     return groups.length ? { question: str(value.question), item: str(value.item), source: str(value.source) ?? '', groups } : null;
 }
+/** A recipe option's `delivery`, as `{ delivery }` when it names a store and a total, else nothing. */
+function deliveryOf(value) {
+    if (!isRecord(value) || !str(value.store) || num(value.total_cents) === null)
+        return {};
+    return { delivery: { store: value.store, store_address: str(value.store_address), eta_minutes: num(value.eta_minutes), total_cents: num(value.total_cents), shipped_cents: num(value.shipped_cents) ?? 0 } };
+}
 /** A cart being built, as an answer, a refusal or the conversation read names it. */
 export function cartBuildingOf(value) {
     return isRecord(value) && str(value.store) ? { store: value.store, started_at: str(value.started_at) ?? '' } : null;
@@ -512,7 +518,7 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                 const asOf = str(block.as_of);
                 const shown = countOf(block.shown);
                 const found = countOf(block.found);
-                const update = { conversationId: data.conversation_id, catalog, asOf, shown, found, more: catalogItemsOf(block.more) };
+                const update = { conversationId: data.conversation_id, catalog, asOf, shown, found, more: catalogItemsOf(block.more), final: block.final !== false };
                 // The count follows the cards it counts, so an app never shows "8 of 23" above no cards, and it settles before the
                 // next event, so a later count never lands before an earlier one. A card display that throws never costs the count.
                 deliver(async () => {

package/dist/definition.d.ts

@@ -7,6 +7,8 @@
  */
 export declare const BUY_TOOL_NAME = "buy";
 /** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
+export declare const BUY_TOOL_RULES: string;
+/** The rules as the model reads them, with travel named when src/trip-ask.ts says so. */
 export declare const BUY_TOOL_DESCRIPTION: string;
 /**
  * What the model sends: `ask`, `confirm` and `new_order` every time, `product_id`, null unless the

package/dist/definition.js

@@ -5,9 +5,10 @@
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
+import { withTravel } from './trip-ask.js';
 export const BUY_TOOL_NAME = 'buy';
 /** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
-export const BUY_TOOL_DESCRIPTION = [
+export const BUY_TOOL_RULES = [
     'Buy what this shopper asks for at real stores.',
     "Put the shopper's own words in `ask`.",
     'When the shopper sends a link to a product, such as a buy.trychannel3.com link, put the whole link in `ask` exactly as they sent it, query string included, with their words beside it: Agentcard buys that exact product from the link, so never describe the link in words instead.',
@@ -65,6 +66,8 @@ export const BUY_TOOL_DESCRIPTION = [
     'Ask the shopper to "let me know", never "text me", unless your app is a text-message chat.',
     'Name only the stores and products that reach the shopper as cards in this result, never others in passing, such as "five guys and mcdonald\'s deliver there too", even when `reply` names them: to offer more, ask "want other options?". This is for what you suggest: when you show the cart or ask for a yes to it, name what is in it.',
 ].join(' ');
+/** The rules as the model reads them, with travel named when src/trip-ask.ts says so. */
+export const BUY_TOOL_DESCRIPTION = withTravel(BUY_TOOL_RULES);
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {
     return {

package/dist/direct.js

@@ -28,6 +28,7 @@
  * the 188 labelled messages in `test/fixtures/direct-messages.json`, it sends none it should not.
  */
 import { ABOUT, ACKNOWLEDGED, CAPABILITY, CART_COMMAND, CHECKOUT, CHITCHAT, FILLER, asksForDetails, asksForSimilar, isNewRequest, isPickText, namesStore, plain } from './ack.js';
+import { tripAskGoesStraight } from './trip-ask.js';
 /**
  * A price limit put on what was just shown: `under $20`, `under 20`, `less than 15 bucks`, `between 10 and 20`, `$20 or
  * less`, `over $50`, `cheaper ones`, `menos de 20`. Only whether the message states one: Agentcard reads the limit itself.
@@ -107,6 +108,8 @@ export function isProductAsk(text) {
         return !QUESTION_START.test(bare) && !NOT_SHOPPING.test(words.replace(/\S*https?:\/\/\S+|\S*www\.\S+/g, ''));
     if (!isNewRequest(raw) || CAPABILITY.test(words) || NOT_SHOPPING.test(words) || PAST.test(words) || CORRECTION.test(words) || REFERS.test(words) || COMPLAINT.test(words))
         return false;
+    if (tripAskGoesStraight(raw, bare))
+        return true;
     // A question goes to the model, unless it asks Agentcard to get something: `can you find me usb-c cables?`.
     const framed = SHOP_FRAME.exec(bare);
     if (/\?/.test(raw) && !(framed && /^(?:can|could|would|will) (?:you|u)\b/.test(bare)))

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, ty
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.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 AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, 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, type BuyChoice, type BuyChoiceGroup, type BuyChoiceOption, } from './client.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, 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, type BuyChoice, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } 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, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
@@ -15,3 +15,5 @@ export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRout
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';
+export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS, type TurnStream, type TurnStreamOptions } from './turn-stream.js';
+export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord, type TurnRecordStore } from './turn-record.js';

package/dist/index.js

@@ -15,3 +15,5 @@ export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, } from './events.js';
+export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS } from './turn-stream.js';
+export { TURN_RECOVERY_ON, isTurnId } from './turn-record.js';

package/dist/trip-ask.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Trip asks and the tool's travel wording, kept out of direct.ts, ack.ts and definition.ts, which each call in here once.
+ *
+ * On 2026-10-28 on chat.opencommerce.sh, "help me plan a trip to Loreto" never reached Agentcard: `directCall` read no
+ * shopping verb, and the app's model, whose capability rule named stores and restaurants and no travel, answered "i can't
+ * plan itineraries" and offered no flight or hotel. Both switches below ship off and change nothing until a later change
+ * turns them on; a test turns them on by setting the field.
+ */
+/**
+ * `goStraight` on: a trip, flights or a hotel with the place they are for, `help me plan a trip to Loreto`, `flights to
+ * Loreto`, `flights and hotels in loreto` or `a hotel in Chicago next week`, goes straight to Agentcard, which asks for the
+ * airport and the dates it needs, and the instant reply reads the trip back without the verb (`a trip to loreto`). Off: such
+ * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
+ *
+ * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
+ * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * description is the text it was before, word for word.
+ */
+export declare const TRAVEL: {
+    goStraight: boolean;
+    inCapabilities: boolean;
+};
+/** True when the message's words, openings taken off, ask for a trip, flights or a hotel and name the place. */
+export declare function isTripAsk(bare: string): boolean;
+/**
+ * Whether a message that passed `isProductAsk`'s checks for small talk, the account and a story of what happened goes straight
+ * as a trip ask: a question goes only when it asks Agentcard to plan it (`can you help me plan a trip to italy?`).
+ */
+export declare function tripAskGoesStraight(raw: string, bare: string): boolean;
+/** The read-back without the verb that asked for the trip: `plan a trip to loreto` reads back `a trip to loreto`. Any other words, `plan b emergency contraception` too, read back as they are. */
+export declare function withoutTripVerb(text: string): string;
+/** The tool's description with travel named, when `inCapabilities` is on (or `on` says so); the description as given when off. */
+export declare function withTravel(description: string, on?: boolean): string;

package/dist/trip-ask.js

@@ -0,0 +1,63 @@
+/**
+ * Trip asks and the tool's travel wording, kept out of direct.ts, ack.ts and definition.ts, which each call in here once.
+ *
+ * On 2026-10-28 on chat.opencommerce.sh, "help me plan a trip to Loreto" never reached Agentcard: `directCall` read no
+ * shopping verb, and the app's model, whose capability rule named stores and restaurants and no travel, answered "i can't
+ * plan itineraries" and offered no flight or hotel. Both switches below ship off and change nothing until a later change
+ * turns them on; a test turns them on by setting the field.
+ */
+/**
+ * `goStraight` on: a trip, flights or a hotel with the place they are for, `help me plan a trip to Loreto`, `flights to
+ * Loreto`, `flights and hotels in loreto` or `a hotel in Chicago next week`, goes straight to Agentcard, which asks for the
+ * airport and the dates it needs, and the instant reply reads the trip back without the verb (`a trip to loreto`). Off: such
+ * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
+ *
+ * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
+ * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * description is the text it was before, word for word.
+ */
+export const TRAVEL = { goStraight: true, inCapabilities: true };
+/** What a trip ask opens with before the trip: `can you help me plan`, `i want to book`, `let's plan`, `plan`. */
+const TRIP_LEAD = "(?:(?:(?:can|could|would|will) (?:you|u) |please |i'?d like (?:you )?to |i want to |i need to |we want to |we need to |let'?s |lets )?(?:help (?:me|us) )?(?:plan|book|organi[sz]e|arrange|find|search for|look for)(?: (?:me|us))? )?";
+/** The trip itself: a trip, a vacation, flights, a hotel, or flights and a hotel together. */
+const TRIP_THING = '(?:(?:a|an|some|the|cheap|cheapest|good) )?(?:(?:(?:weekend|family|beach|ski|honeymoon|birthday|anniversary|business|work|quick|short|long|girls|guys) )?(?:trip|vacation|getaway|holiday)|(?:flights?|hotels?|hotel rooms?|places? to stay)(?: (?:and|&|\\+) (?:a |some )?(?:flights?|hotels?|hotel rooms?|places? to stay))?)';
+/** When the trip is, after its place: `next week`, `this weekend`, `in december`, `on nov 3`, `for 5 days`. */
+const MONTH = '(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|june?|july?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)';
+const NUMBER = '(?:a|an|one|two|three|four|five|six|seven|eight|nine|ten|\\d{1,2})';
+const WHEN = `(?: (?:next|this) (?:week|weekend|month|year|summer|winter|spring|fall)| tomorrow| tonight| in ${MONTH}| in ${NUMBER} (?:days?|weeks?|months?)| on ${MONTH} \\d{1,2}(?:st|nd|rd|th)?| ${MONTH} \\d{1,2}(?:st|nd|rd|th)?(?: ?- ?\\d{1,2})?| for ${NUMBER} (?:days?|nights?|weeks?)| over (?:thanksgiving|christmas|new year'?s|the holidays|spring break))*`;
+/** A trip with where it goes: one to three words of place, then only words of when. */
+const TRIP_ASK = new RegExp(`^${TRIP_LEAD}${TRIP_THING} (?:to|in|at|near|for|around) (\\p{L}[\\p{L}'.-]*(?: \\p{L}[\\p{L}'.-]*){0,2}?)${WHEN}$`, 'u');
+/** Words that make the place a sentence about a trip already booked or a price: `my flight to jfk is delayed`, `flights to cancun cost a fortune`. */
+const TRIP_TOLD = /\b(?:is|are|was|were|be|been|got|gets|get|delayed|cancell?ed|booked|landed|left|leaves|leaving|late|cheaper|cheap|expensive|pricey|cost|costs|price|prices|worth|good|bad|ok|okay|fine|over|done|sucks?|suck|lol|sounds?|seems?|looks?)\b/;
+/** Places close to home that a trip word can name and no flight or hotel goes to: `a trip to the store`, `a trip to walmart`, `a trip to target.com`. */
+const NOT_A_TRIP_PLACE = /^(?:the (?:store|shop|mall|grocery store|supermarket|gym|doctor|dentist|bank|vet|post office|office|pharmacy|market)|work|school|bed|me|us|you|my|our|it|this|that|walmart|target|costco|best ?buy|home depot|lowe'?s|trader joe'?s|whole foods|safeway|kroger|cvs|walgreens|ikea|aldi|publix|sam'?s club|amazon)\b|\.(?:com|co|net|org|shop|store|us|uk|ca|io)\b/;
+/** The verb a trip ask opens with, read off before the trip reads back. */
+const TRIP_VERB = /^(?:plan|organi[sz]e|arrange)\b[\s,]*/;
+/** True when the message's words, openings taken off, ask for a trip, flights or a hotel and name the place. */
+export function isTripAsk(bare) {
+    const match = TRIP_ASK.exec(bare.replace(/\s*\?+$/, ''));
+    return match !== null && !TRIP_TOLD.test(match[1]) && !NOT_A_TRIP_PLACE.test(match[1]);
+}
+/**
+ * Whether a message that passed `isProductAsk`'s checks for small talk, the account and a story of what happened goes straight
+ * as a trip ask: a question goes only when it asks Agentcard to plan it (`can you help me plan a trip to italy?`).
+ */
+export function tripAskGoesStraight(raw, bare) {
+    if (!TRAVEL.goStraight || !isTripAsk(bare))
+        return false;
+    return !/\?/.test(raw) || /^(?:can|could|would|will) (?:you|u)\b/.test(bare);
+}
+/** The read-back without the verb that asked for the trip: `plan a trip to loreto` reads back `a trip to loreto`. Any other words, `plan b emergency contraception` too, read back as they are. */
+export function withoutTripVerb(text) {
+    return TRAVEL.goStraight && isTripAsk(text) ? text.replace(TRIP_VERB, '') : text;
+}
+const OPENING_LINE = 'Buy what this shopper asks for at real stores.';
+const TRAVEL_LINES = 'You also plan and book trips: flights and hotels. When the shopper asks to plan a trip, or for flights or a hotel, such as "help me plan a trip to Loreto" or "flights and hotels in loreto", call this tool with their words, even when they name no dates and no place they leave from: Agentcard asks them for what it needs.';
+const CAPABILITY_END = 'so name those, and no other store unless a result showed it.';
+const CAPABILITY_TRAVEL = 'Name flights and hotels for a trip among the kinds of things you can do.';
+/** The tool's description with travel named, when `inCapabilities` is on (or `on` says so); the description as given when off. */
+export function withTravel(description, on = TRAVEL.inCapabilities) {
+    if (!on)
+        return description;
+    return description.replace(OPENING_LINE, `${OPENING_LINE} ${TRAVEL_LINES}`).replace(CAPABILITY_END, `${CAPABILITY_END} ${CAPABILITY_TRAVEL}`);
+}

package/dist/turn-reader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `streamTurn` sends the shopper's message and reads the turn's server-sent events in the browser. When the connection
+ * drops before the turn's last event, or before the first one, it reads the turn's record by its id from your server
+ * (`readTurn` behind a route of yours) and hands over each event the stream did not, so the shopper gets the answer.
+ * A 409 that names the turn already running for this shopper (`turn_id`) waits for that turn's answer the same way.
+ */
+import { type TurnRecord } from './turn-record.js';
+/** The part of a fetch `Response` the reader uses. */
+export interface TurnResponseLike {
+    ok: boolean;
+    status: number;
+    body: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+export interface StreamTurnOptions {
+    /** Sends the shopper's message with the turn's id, such as in an `x-turn-id` header, and returns the response. */
+    start(turnId: string): Promise<TurnResponseLike>;
+    /** Reads the turn's record from your server, or null while it has none. `readTurn` answers it there. */
+    read(turnId: string): Promise<TurnRecord | null>;
+    /** Hears each event once, in the order the turn sent them, whether the stream or the record carried it. */
+    onEvent(event: string, data: unknown): void;
+    /** The turn's id. Defaults to a new random one. */
+    turnId?: string;
+    /** How often the record is read after a drop, in milliseconds. Defaults to 1,500. */
+    pollMs?: number;
+    /** How long a record that never appears is waited for before the drop counts as the error, in milliseconds. Defaults to 15,000. */
+    startWaitMs?: number;
+    /** How long a turn's record is read before giving up, in milliseconds. Defaults to 300,000. */
+    waitMs?: number;
+    /** Whether a drop reads the record. Defaults to `TURN_RECOVERY_ON`. */
+    recover?: boolean;
+    /** Stops reading the record once it aborts, as the abort of your own fetch stops the stream. */
+    signal?: AbortSignal;
+}
+export interface StreamTurnResult {
+    /** The id of the turn whose events were heard: the running turn's after a 409 that named one. */
+    turnId: string;
+    /** True when some of the events came from the record, after a drop or a 409. */
+    recovered: boolean;
+    /** The response, when the server refused the message and no turn's answer was waited for: read its error from it. */
+    refused?: TurnResponseLike;
+}
+export declare function streamTurn(options: StreamTurnOptions): Promise<StreamTurnResult>;
+/** The record your server's route answers, read back: a helper for `read`, such as `(id) => fetch(...).then(readTurnResponse)`. */
+export declare function readTurnResponse(response: TurnResponseLike): Promise<TurnRecord | null>;

package/dist/turn-reader.js

@@ -0,0 +1,148 @@
+/**
+ * `streamTurn` sends the shopper's message and reads the turn's server-sent events in the browser. When the connection
+ * drops before the turn's last event, or before the first one, it reads the turn's record by its id from your server
+ * (`readTurn` behind a route of yours) and hands over each event the stream did not, so the shopper gets the answer.
+ * A 409 that names the turn already running for this shopper (`turn_id`) waits for that turn's answer the same way.
+ */
+import { TURN_RECOVERY_ON, isTurnId, parseTurnRecord } from './turn-record.js';
+const TERMINAL = new Set(['done', 'error']);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function newTurnId() {
+    const c = globalThis.crypto;
+    return c?.randomUUID?.() ?? `turn_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+}
+export async function streamTurn(options) {
+    const recover = options.recover ?? TURN_RECOVERY_ON;
+    let turnId = options.turnId ?? newTurnId();
+    let heard = 0;
+    let ended = false;
+    // An error your `onEvent` throws is yours: it ends the read, and the record is not read in its place.
+    let appFailed = null;
+    const hear = (event, data) => {
+        heard++;
+        if (TERMINAL.has(event))
+            ended = true;
+        try {
+            options.onEvent(event, data);
+        }
+        catch (error) {
+            appFailed = { error };
+            throw error;
+        }
+    };
+    // A drop reads the record unless recovery is off, the turn already ended, the app's own code threw or the app aborted.
+    const recovers = (error) => recover && !ended && !appFailed && !options.signal?.aborted && error?.name !== 'AbortError';
+    // Reads the record until it holds the turn's last event, handing over what the stream had not.
+    const fromRecord = async (cause) => {
+        const startWaitMs = options.startWaitMs ?? 15_000;
+        const waitMs = options.waitMs ?? 300_000;
+        const began = Date.now();
+        let seen = false;
+        const stopIfAborted = () => {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? cause;
+        };
+        for (;;) {
+            stopIfAborted();
+            // A read that hangs counts as no record once the limit it waits under passes.
+            const left = Math.max(0, (seen ? waitMs : Math.min(startWaitMs, waitMs)) - (Date.now() - began));
+            const record = await withDeadline(Promise.resolve().then(() => options.read(turnId)), left, options.signal);
+            stopIfAborted();
+            if (record) {
+                seen = true;
+                for (const { event, data } of record.events.slice(heard))
+                    hear(event, data);
+                if (record.done || ended)
+                    return { turnId, recovered: true };
+            }
+            const waited = Date.now() - began;
+            if ((!seen && waited >= startWaitMs) || waited >= waitMs)
+                throw cause;
+            await sleep(options.pollMs ?? 1_500);
+        }
+    };
+    let response;
+    try {
+        response = await options.start(turnId);
+    }
+    catch (error) {
+        if (!recovers(error))
+            throw error;
+        return fromRecord(error);
+    }
+    if (!response.ok || !response.body) {
+        if (recover && response.status === 409) {
+            const text = await response.text().catch(() => '');
+            const running = parseJson(text)?.turn_id;
+            if (isTurnId(running)) {
+                turnId = running;
+                return fromRecord(new Error(`The chat answered ${response.status}.`));
+            }
+            return { turnId, recovered: false, refused: { ok: response.ok, status: response.status, body: null, text: async () => text } };
+        }
+        return { turnId, recovered: false, refused: response };
+    }
+    try {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let end;
+            while ((end = buffer.indexOf('\n\n')) !== -1) {
+                const frame = buffer.slice(0, end);
+                buffer = buffer.slice(end + 2);
+                const event = /^event: (.*)$/m.exec(frame)?.[1];
+                const data = /^data: (.*)$/m.exec(frame)?.[1];
+                if (event && data !== undefined)
+                    hear(event, JSON.parse(data));
+            }
+        }
+        if (ended || !recover)
+            return { turnId, recovered: false };
+        return fromRecord(new Error('The chat stream ended before the turn did.'));
+    }
+    catch (error) {
+        if (ended && !appFailed)
+            return { turnId, recovered: false };
+        if (!recovers(error))
+            throw error;
+        return fromRecord(error);
+    }
+}
+/** The read's record, or null when it fails, has not answered within `ms`, or the app aborts first. */
+function withDeadline(read, ms, signal) {
+    let timer;
+    let stop;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), ms);
+        stop = () => resolve(null);
+        if (signal?.aborted)
+            resolve(null);
+        else
+            signal?.addEventListener('abort', stop, { once: true });
+    });
+    return Promise.race([read.catch(() => null), late]).finally(() => {
+        clearTimeout(timer);
+        if (stop)
+            signal?.removeEventListener('abort', stop);
+    });
+}
+/** A JSON body read leniently: null when it is not JSON. */
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** The record your server's route answers, read back: a helper for `read`, such as `(id) => fetch(...).then(readTurnResponse)`. */
+export async function readTurnResponse(response) {
+    if (!response.ok)
+        return null;
+    return parseTurnRecord(await response.text());
+}

package/dist/turn-record.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A turn's record: every event a chat turn sent the shopper's browser, in order, kept under the turn's id in a store
+ * the app provides, so a browser whose connection dropped reads the turn's answer back instead of losing it.
+ * This file imports nothing, so the server helper (`turnStream`) and the browser reader (`streamTurn`) share it.
+ */
+/**
+ * Whether a turn keeps its record and a dropped stream reads it back. Off until the pull request that turns it on:
+ * while it is off, `turnStream` streams without saving and `streamTurn` reports a drop as the error it was.
+ */
+export declare const TURN_RECOVERY_ON: boolean;
+/** One event of a turn, as its server-sent frame carries it: `event: <event>` and `data: <JSON of data>`. */
+export interface TurnEvent {
+    event: string;
+    data: unknown;
+}
+/** What a turn sent so far, and whether it ended: `done` is true once the turn's last event is in `events`. */
+export interface TurnRecord {
+    events: TurnEvent[];
+    done: boolean;
+}
+/** Where a turn's record lives between instances, such as Redis: the same shape as the listener's cursor store. */
+export interface TurnRecordStore {
+    /** The record saved last under `key`, or null when none was saved or it expired. */
+    load(key: string): Promise<string | null> | string | null;
+    /** Saves the record under `key`, to be kept for `ttlSeconds`. */
+    save(key: string, record: string, ttlSeconds: number): Promise<void> | void;
+}
+/** A turn id the browser makes up front: 8 to 64 letters, digits, `-` or `_`. Check one before using it in a key. */
+export declare function isTurnId(value: unknown): value is string;
+/** A stored record read back, or null when the text is not one. */
+export declare function parseTurnRecord(text: string | null | undefined): TurnRecord | null;

package/dist/turn-record.js

@@ -0,0 +1,26 @@
+/**
+ * A turn's record: every event a chat turn sent the shopper's browser, in order, kept under the turn's id in a store
+ * the app provides, so a browser whose connection dropped reads the turn's answer back instead of losing it.
+ * This file imports nothing, so the server helper (`turnStream`) and the browser reader (`streamTurn`) share it.
+ */
+/**
+ * Whether a turn keeps its record and a dropped stream reads it back. Off until the pull request that turns it on:
+ * while it is off, `turnStream` streams without saving and `streamTurn` reports a drop as the error it was.
+ */
+export const TURN_RECOVERY_ON = false;
+/** A turn id the browser makes up front: 8 to 64 letters, digits, `-` or `_`. Check one before using it in a key. */
+export function isTurnId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(value);
+}
+/** A stored record read back, or null when the text is not one. */
+export function parseTurnRecord(text) {
+    if (typeof text !== 'string')
+        return null;
+    try {
+        const record = JSON.parse(text);
+        return Array.isArray(record.events) ? { events: record.events, done: record.done === true } : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/turn-stream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `turnStream` serves one chat turn to the shopper's browser as server-sent events and keeps every event it sends in the
+ * app's store under the turn's id. The turn runs to its end whether or not the browser is still there: an event the
+ * stream can no longer carry still goes in the record, and `finished` resolves once the record holds the turn's last
+ * event. Hand `finished` to your host's `waitUntil` so a serverless function is not stopped before then.
+ * `readTurn` hands the record back to the browser's reader (`streamTurn` in `@agent-cards/commerce-sdk/browser`).
+ */
+import { type TurnRecord, type TurnRecordStore } from './turn-record.js';
+/** How long a record is kept by default: ten minutes, past the longest turn a chat waits on. */
+export declare const TURN_RECORD_TTL_SECONDS = 600;
+export interface TurnStreamOptions {
+    /** Where the record lives. */
+    store: TurnRecordStore;
+    /** The record's key: the turn's id together with your shopper's id, so one shopper never reads another's turn. */
+    key: string;
+    /**
+     * Runs the turn. Call `send` for each event the browser shows, the last one included (such as `done` or `error`).
+     * A turn that throws ends with an `error` event carrying the message in `failedText`.
+     */
+    run(send: (event: string, data: unknown) => void): Promise<void>;
+    /** How long the record is kept, in seconds. Defaults to `TURN_RECORD_TTL_SECONDS`. */
+    ttlSeconds?: number;
+    /** The text of the `error` event a turn that throws ends with. */
+    failedText?: string;
+    /** Whether to keep the record. Defaults to `TURN_RECOVERY_ON`. */
+    recover?: boolean;
+    /** Hears each save the store refused: the record then misses events until a later save lands. Log it here. */
+    onSaveError?: (error: unknown) => void;
+}
+export interface TurnStream {
+    /** The body of the response: `text/event-stream`. */
+    stream: ReadableStream<Uint8Array>;
+    /** Resolves once the turn ended and its record is saved. It never rejects. */
+    finished: Promise<void>;
+}
+export declare function turnStream(options: TurnStreamOptions): TurnStream;
+/** The turn's record under `key`, or null when the store has none, for the browser's reader to pick up where its stream stopped. */
+export declare function readTurn(store: TurnRecordStore, key: string): Promise<TurnRecord | null>;

package/dist/turn-stream.js

@@ -0,0 +1,91 @@
+/**
+ * `turnStream` serves one chat turn to the shopper's browser as server-sent events and keeps every event it sends in the
+ * app's store under the turn's id. The turn runs to its end whether or not the browser is still there: an event the
+ * stream can no longer carry still goes in the record, and `finished` resolves once the record holds the turn's last
+ * event. Hand `finished` to your host's `waitUntil` so a serverless function is not stopped before then.
+ * `readTurn` hands the record back to the browser's reader (`streamTurn` in `@agent-cards/commerce-sdk/browser`).
+ */
+import { TURN_RECOVERY_ON, parseTurnRecord } from './turn-record.js';
+/** How long a record is kept by default: ten minutes, past the longest turn a chat waits on. */
+export const TURN_RECORD_TTL_SECONDS = 600;
+export function turnStream(options) {
+    const recover = options.recover ?? TURN_RECOVERY_ON;
+    const ttl = options.ttlSeconds ?? TURN_RECORD_TTL_SECONDS;
+    const encoder = new TextEncoder();
+    const record = { events: [], done: false };
+    let controller = null;
+    let gone = false;
+    // Saves run one after another, so a slow early save never lands over a later one.
+    let saving = Promise.resolve();
+    const save = () => {
+        if (!recover)
+            return;
+        const text = JSON.stringify(record);
+        saving = saving
+            .then(() => options.store.save(options.key, text, ttl))
+            .catch((error) => {
+            try {
+                options.onSaveError?.(error);
+            }
+            catch {
+                /* the app's logging failing never stops the turn */
+            }
+        });
+    };
+    // Each event is written to JSON once, before it is kept: a value JSON cannot hold throws here, to the turn, and the
+    // record keeps a copy, so a later change to the caller's object never rewrites what the shopper was sent.
+    const send = (event, data) => {
+        if (record.done)
+            return;
+        const json = JSON.stringify(data) ?? 'null';
+        const entry = { event, data: JSON.parse(json) };
+        record.events.push(entry);
+        save();
+        if (gone || !controller)
+            return;
+        try {
+            controller.enqueue(encoder.encode(`event: ${event}\ndata: ${json}\n\n`));
+        }
+        catch {
+            // The browser left: the record still takes every event.
+            gone = true;
+        }
+    };
+    let started;
+    const ready = new Promise((resolve) => (started = resolve));
+    const stream = new ReadableStream({
+        start(c) {
+            controller = c;
+            started();
+        },
+        cancel() {
+            gone = true;
+        },
+    });
+    const finished = (async () => {
+        await ready;
+        save();
+        try {
+            await options.run(send);
+        }
+        catch {
+            send('error', { error: options.failedText ?? 'The turn could not finish.' });
+        }
+        record.done = true;
+        save();
+        await saving;
+        if (!gone) {
+            try {
+                controller?.close();
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    })();
+    return { stream, finished };
+}
+/** The turn's record under `key`, or null when the store has none, for the browser's reader to pick up where its stream stopped. */
+export async function readTurn(store, key) {
+    return parseTurnRecord(await store.load(key));
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
+  "homepage": "https://opencommerce.sh",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",