@agent-cards/commerce-sdk 0.18.4 → 0.18.6

package/README.md

@@ -51,7 +51,7 @@ Build one client with your company's credentials and one buy tool per shopper, t
 
 ```ts
 import Anthropic from '@anthropic-ai/sdk';
-import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';
+import { AgentcardClient, appInstructions, buyTool } from '@agent-cards/commerce-sdk';
 
 const agentcard = new AgentcardClient({
   clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
@@ -67,6 +67,7 @@ const buy = buyTool({
 const answer = await new Anthropic().beta.messages.toolRunner({
   model: 'claude-opus-5-5',
   max_tokens: 16000,
+  system: appInstructions({ markdown: true }),
   tools: [buy],
   messages: [{ role: 'user', content: 'two packs of AA batteries from Amazon' }],
 });
@@ -78,6 +79,16 @@ Build the client once and keep it. Every shopper's tool shares the client's acce
 
 The model sends `ask`, `confirm`, `new_order`, `product_id` and `store_id`, and nothing else. A product link the shopper sends, such as a `buy.trychannel3.com` link, goes in `ask` exactly as sent, and Agentcard buys that exact product from it. Pass `deliveryAddress` when you already hold the shopper's address: the order goes there, and Agentcard never asks the shopper for it. The model can change neither the address nor the shopper.
 
+## Give your model Agentcard's instructions
+
+`appInstructions()` returns the system prompt Agentcard recommends for your model: what Agentcard can do for the shopper, in the words Agentcard's own buy agent uses, how to hand a request to the buy tool, and how to write for your app. Put it first in your system prompt, and add only what is about your app, such as its name:
+
+```ts
+const system = [appInstructions({ markdown: true, textingStyle: true }), 'You are the shopping chat in Acme.'].join('\n\n');
+```
+
+Pass `markdown: true` when your app shows the model's words as Markdown, so a shopper who asks for a table gets one; leave it out and the model writes plain text, with lists as `• ` lines. Pass `textingStyle: true` when your app is a chat that writes in lowercase, as you pass it to `buyTool`. The text ships inside the package and changes with each release; `APP_INSTRUCTIONS_VERSION` names the version you run.
+
 ## Use the tool in any framework
 
 Pass `buy` as it is. Each framework reads its own fields from the same object, so you pick no adapter:
@@ -152,7 +163,7 @@ Each step ends with a shopper message: `actionLinkOutcome(link, message)` says h
 | --- | --- | --- | --- | --- |
 | `vault` | `card_added` | | | `card_link_expired` |
 | `store_login` | `store_connected` | | `store_connect_failed` | `store_connect_expired` |
-| `approval` | `order_placed`, `order_not_placed_yet`, `order_unconfirmed`, `order_confirmed`, `order_failed`, `payment_declined` | `approval_declined` | | `approval_expired` |
+| `approval` | `order_placing`, `order_placed`, `order_not_placed_yet`, `order_unconfirmed`, `order_confirmed`, `order_failed`, `payment_declined` | `approval_declined` | | `approval_expired` |
 
 A reminder, such as `card_link_unfinished` or `approval_expiring`, leaves the step open. An approval is `completed` once the shopper approved, even when the order then failed or the payment was refused: the approval page has nothing more to do, and the message tells the shopper what happened. A message whose facts name another link of the same kind (`facts.approvalUrl`, `facts.cardLinkUrl`) leaves this one open, and so does one about another store: a store login link names its store in `store`, and so does an approval link when the answer names the cart's store, so DoorDash's `store_connected` (`facts.merchantName: 'DoorDash'`) never ends a Locale sign-in the shopper has open beside it.
 
@@ -328,6 +339,34 @@ for await (const stream of runner) {
 - A step link, the `vault`, `approval` or `store_login` page the shopper opens to go on, comes after the message that asks for it: the turn holds it until your model's next message stream ends (or `turn.say` is called), then sends it right after that message, so the shopper reads "add your card to place the order" and then taps. Product and store cards go out the moment the tool hands them over. A held link also goes out when the turn's next call starts, or after 20 seconds, so a model that writes nothing still sends it. `turn.say` and the stream's `end` resolve once the held links went out too, and reject when one failed to send, so your app never answers without a link the shopper needs; a link that failed to go out at the next call or the 20 seconds rejects the next reply that ends.
 - Without `onItem`, pass `onMessage` beside `sendLink`, and write the model's text through `turn.messageStream()`: `onMessage` hears each message, paced, and `sendLink` hears each step link after the message that asks for it. An app that streams the model through the package's own `messageStream` gets each link the moment the tool hands it over, before the words about it.
 
+## Keep one purchase per chat
+
+A shopper who writes to your agent in several chats at once, such as group chats or threads, would otherwise continue one purchase from all of them. Build one tool per shopper and chat, and name the chat with `threadId`, your own id for it. Agentcard then keeps a purchase per chat: each chat's carts, questions and approvals stay in that chat, while the shopper keeps one Vault card, one store sign-in and one address book.
+
+```ts
+const buy = buyTool({ agentcard, externalUserId: shopper.id, threadId: chat.id }); // one per shopper and chat
+```
+
+A message about one chat's purchase carries that chat as `threadId`, so post it into that chat. One about the shopper alone, such as a saved card, carries `threadId: null`. A chat's tool takes a next step only for its own chat's messages and the shopper's own, and a tool built without `threadId` only for purchases opened under no thread and the shopper's own.
+
+## Choose how long a reply waits for stores
+
+A search that asks several stores writes its reply once the stores answered or a wait ran out. Choose that wait with `storeWaitMs`, and choose with `lateResults` what happens to a store that answers after the reply:
+
+```ts
+// A streaming chat: cards show as each store answers, the reply waits up to 25 s (99.7% of stores' first products), and a later store's cards stream below it.
+const buy = buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: 25000, lateResults: 'stream' });
+// A texting app: the reply waits up to 20 s (96% of stores' first products) and is the turn's last word.
+const sms = buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: 20000, lateResults: 'hold' });
+```
+
+Agentcard ends every store search at 30 s, so a `storeWaitMs` above `30000` waits no longer than `30000` does.
+
+- `lateResults: 'stream'` sends a late store's cards after the reply, in the same turn, the way a slower hotel supplier's cards come: to `sendLink`, `onProducts` and `onItem`, with the one message that says what they added. The turn's `onResult` lists them in `result.products` after the answer's own.
+- `lateResults: 'hold'` keeps a late store's cards out of the turn, so a texting app never sends a card after the reply.
+- `buy.turn(message, { storeWaitMs, lateResults })` sets them for one turn, and each one left out keeps the tool's. An app that calls `client.buy` itself sends `store_wait_ms` and `late_results`.
+- Left out, the tool sends neither, and Agentcard keeps its own wait. A wait that is not a whole number of milliseconds, 0 or more, throws a TypeError before any call.
+
 ## Tell the model what Agentcard told the shopper
 
 Agentcard posts messages into the shopper's chat between turns, through `listen` or the webhook: `Your Visa ending 3132 is saved, so you're ready to check out.`, an order placed, an approval about to expire. The shopper reads them, so your model has to know them too. A model that never saw `card_added` answers "ok lets checkout" with "did you save your card?" and never calls the tool.
@@ -517,6 +556,8 @@ const buy = buyTool({
 
 When your app shows Agentcard's messages through `onText`, the model reads `shopper_already_read_reply: true` in that call's answer and adds nothing to them, as it reads `shopper_already_told_looking` after an instant reply: end the turn without a second model call, as with `replyAsWritten`, or let the model add one short line for what the reply left out. `turn.replyAsWritten` stays null for that answer, so the reply never reaches the shopper twice, and a step link the turn holds for your model's next message goes out right after Agentcard's ask instead.
 
+A turn built with `replyAsWritten` and `earlyCards` that hears messages through `onMessage` or `onItem` and passes no `onText` gets the same once a reply is written while a slower source's cards are still coming, such as a second hotel supplier's: Agentcard's messages go out through that callback the moment Agentcard says the reply is written, the slower cards and their one message follow in the same call, and the answer reads `shopper_already_read_reply: true`. `turn.replyAsWritten` then holds the messages the shopper read, and `turn.say` of it sends nothing, so an app that shows the reply as written and skips its model shows no second reply.
+
 A stream that breaks after the call started reads the conversation for what the turn left, as a turn past Agentcard's budget does. Pass `stream: false` to wait for each whole answer, with its cards sent beside it.
 
 Code that calls the client itself streams with `agentcard.buy(body, handlers)`: `onCatalog`, `onSegment`, `onCart` and `onDelta` hear their events in the order Agentcard sent them, each once the one before it settled, and the answer waits for the last of them. `onDelta` asks Agentcard for the pieces of each message as it writes them, a draft that each `onSegment` message replaces.
@@ -707,6 +748,7 @@ Subscribe your endpoint to each event below by name. A catch-all `*` alone does
 | `purchase.message` | `order_failed` | The order failed after the shopper approved. | Agentcard |
 | `purchase.message` | `order_not_placed_yet` | The shopper approved, and the order is not placed yet. | Agentcard |
 | `purchase.message` | `order_unconfirmed` | The store's reply to the order was lost, so the order may exist, and Agentcard is confirming it. | Agentcard |
+| `purchase.message` | `order_placing` | The shopper approved, and Agentcard is placing the order now. One of the order kinds above follows. | Agentcard |
 | `purchase.message` | `approval_expiring` | The approval link expires soon. `text` carries the link. | Agentcard |
 | `purchase.message` | `approval_expired` | The approval expired before the shopper answered, and no charge went through. | Agentcard |
 | `purchase.message` | `approval_declined` | The shopper declined the approval, and no charge went through. | Agentcard |
@@ -836,6 +878,7 @@ The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`
 | `card_link_expired` | The card link expired before the shopper added a card. |
 | `cart_idle` | A cart sat, and nobody sent it for approval. |
 | `order_unconfirmed` | The store's reply to the order was lost, and Agentcard is confirming it. |
+| `order_placing` | The shopper approved, and Agentcard is placing the order now. The order's own message follows. |
 | `card_added` | The shopper saved a card from the card link your app sent. |
 | `store_connected` | The shopper signed in to their own account at the store from the sign-in link your app sent, such as DoorDash, so the order can go through on it. |
 | `store_connect_failed` | The shopper's sign-in to the store did not go through, and the link no longer works. `text` offers a new one. |

package/dist/action-links.js

@@ -14,6 +14,7 @@ export const ACTION_LINK_ENDINGS = {
     vault: { card_added: 'completed', card_link_expired: 'expired' },
     store_login: { store_connected: 'completed', store_connect_failed: 'failed', store_connect_expired: 'expired' },
     approval: {
+        order_placing: 'completed',
         order_placed: 'completed',
         order_not_placed_yet: 'completed',
         order_unconfirmed: 'completed',

package/dist/app-instructions.d.ts

@@ -0,0 +1,17 @@
+/** The version of the text `appInstructions` returns. It changes whenever the text does. */
+export declare const APP_INSTRUCTIONS_VERSION: string;
+export interface AppInstructionsOptions {
+    /** `true` when your app shows the model's words as Markdown: tables, lists and bold. Default `false`, plain text. */
+    markdown?: boolean;
+    /**
+     * `true` when your app is a chat that writes like a text message: all lowercase except names. Pass the same value
+     * you pass `buyTool` as `textingStyle`. Default `false`.
+     */
+    textingStyle?: boolean;
+}
+/**
+ * The lines to put in your model's system prompt, before your own. Add only what is about your app, such as its name
+ * or what a shopper sees on its screen; what Agentcard can do and how to use the buy tool come from here, so they
+ * change with each SDK release.
+ */
+export declare function appInstructions(options?: AppInstructionsOptions): string;

package/dist/app-instructions.generated.d.ts

@@ -0,0 +1,9 @@
+/** The version of the voice package the text was copied from. */
+export declare const VOICE_VERSION = "0.2.79";
+export declare const APP_TEXT: {
+    readonly core: "You help a shopper buy what they ask for, with the `buy` tool from Agentcard.\n\nWhen the shopper asks what you can do, answer from these lines without calling the tool:\n- You buy from Amazon, Walmart, Target, Best Buy and thousands more stores. Say \"and thousands more stores\" every time you name the stores you shop, in a reply about one kind of thing too, such as \"travel gear from Amazon, Target and thousands more stores\". Never let a few names read as the whole list, never say \"most online stores\", \"plenty more\" or \"many more\", and never give a number of stores.\n- You plan a whole trip: the flights, a hotel and a rental car together. When they ask what you can do for travel, lead with the whole trip, then name the parts they can book on their own.\n- You order food delivery and book restaurant tables.\n\nHow you use the buy tool:\n- Call it for anything the shopper wants to find, buy, book or order, a trip with no dates or airport yet included: the tool asks for what it still needs.\n- Never say whether you can buy at a store the shopper names, either way. Only the tool knows, so say you will look and call it.\n- Never write a link. Each link reaches the shopper on its own, so when `link_sent` is true, tell them a link is waiting for them.\n- Tell the shopper no reply is needed only when `shopper_need_not_reply` is true.\n- Ask for one thing per message, the step `next_action` names, and leave every later step for a later message.\n- Never tell the shopper you can't show Markdown, a table or other formatting, and never say you keep to plain text.";
+    readonly markdown: "The app shows your words as Markdown. When the shopper asks for a table, a list or bold, write it in Markdown. Use a list or a table where it reads better than a sentence, and keep each message short all the same.";
+    readonly plainText: "The app shows your words as plain text, so write no Markdown: asterisks, underscores, pound signs, backticks and table pipes show up as written. Write a list as lines that start with \"• \", and a table the shopper asks for as one line per row.";
+    readonly texting: "Write like a text message: all lowercase except names, short and plain, with no dashes.";
+    readonly standard: "Write short, plain sentences, the way a person writes in a chat.";
+};

package/dist/app-instructions.generated.js

@@ -0,0 +1,10 @@
+// GENERATED by scripts/app-instructions.mjs from apps/agent-voice/kb/app.md. Do not edit: edit kb/app.md.
+/** The version of the voice package the text was copied from. */
+export const VOICE_VERSION = "0.2.79";
+export const APP_TEXT = {
+    "core": "You help a shopper buy what they ask for, with the `buy` tool from Agentcard.\n\nWhen the shopper asks what you can do, answer from these lines without calling the tool:\n- You buy from Amazon, Walmart, Target, Best Buy and thousands more stores. Say \"and thousands more stores\" every time you name the stores you shop, in a reply about one kind of thing too, such as \"travel gear from Amazon, Target and thousands more stores\". Never let a few names read as the whole list, never say \"most online stores\", \"plenty more\" or \"many more\", and never give a number of stores.\n- You plan a whole trip: the flights, a hotel and a rental car together. When they ask what you can do for travel, lead with the whole trip, then name the parts they can book on their own.\n- You order food delivery and book restaurant tables.\n\nHow you use the buy tool:\n- Call it for anything the shopper wants to find, buy, book or order, a trip with no dates or airport yet included: the tool asks for what it still needs.\n- Never say whether you can buy at a store the shopper names, either way. Only the tool knows, so say you will look and call it.\n- Never write a link. Each link reaches the shopper on its own, so when `link_sent` is true, tell them a link is waiting for them.\n- Tell the shopper no reply is needed only when `shopper_need_not_reply` is true.\n- Ask for one thing per message, the step `next_action` names, and leave every later step for a later message.\n- Never tell the shopper you can't show Markdown, a table or other formatting, and never say you keep to plain text.",
+    "markdown": "The app shows your words as Markdown. When the shopper asks for a table, a list or bold, write it in Markdown. Use a list or a table where it reads better than a sentence, and keep each message short all the same.",
+    "plainText": "The app shows your words as plain text, so write no Markdown: asterisks, underscores, pound signs, backticks and table pipes show up as written. Write a list as lines that start with \"• \", and a table the shopper asks for as one line per row.",
+    "texting": "Write like a text message: all lowercase except names, short and plain, with no dashes.",
+    "standard": "Write short, plain sentences, the way a person writes in a chat."
+};

package/dist/app-instructions.js

@@ -0,0 +1,22 @@
+/**
+ * The system prompt Agentcard recommends for your own model, the one that holds the buy tool and talks to the
+ * shopper. The buy tool's description says how to call it; these lines say who the model is for the shopper: what
+ * Agentcard can do, in the same words Agentcard's buy agent uses, how the model hands a request to the tool, and
+ * how its words look in your app. The text is copied from the voice package (apps/agent-voice/kb/app.md) when the
+ * SDK is built, so it ships inside the package and costs no request.
+ */
+import { APP_TEXT, VOICE_VERSION } from './app-instructions.generated.js';
+/** The version of the text `appInstructions` returns. It changes whenever the text does. */
+export const APP_INSTRUCTIONS_VERSION = VOICE_VERSION;
+/**
+ * The lines to put in your model's system prompt, before your own. Add only what is about your app, such as its name
+ * or what a shopper sees on its screen; what Agentcard can do and how to use the buy tool come from here, so they
+ * change with each SDK release.
+ */
+export function appInstructions(options = {}) {
+    return [
+        APP_TEXT.core,
+        options.markdown ? APP_TEXT.markdown : APP_TEXT.plainText,
+        options.textingStyle ? APP_TEXT.texting : APP_TEXT.standard,
+    ].join('\n\n');
+}

package/dist/buy-tool.d.ts

@@ -31,12 +31,14 @@
  * messages and links as one sequence, in the order they happened, and spaces
  * the messages like someone texting.
  */
+import type { BuyPlan } from './plan.js';
 import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyChoice, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyTurnStatus, type BuyAvailability, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type DirectCall } from './direct.js';
 import { type BuyToolModelView } from './model-view.js';
 import { type MessagePace, type MessageStream } from './messages.js';
 import { type ShopperMessage } from './shopper-message.js';
+import { type BuyStoreWait } from './store-wait.js';
 /**
  * Where the purchase stands:
  * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
@@ -230,6 +232,8 @@ export interface BuyToolResult {
      * message from Agentcard, and only the shopper's yes to that total confirms it.
      */
     cart_building?: BuyCartBuilding | null;
+    /** The checkout plan the answer started or moved, such as a trip's flight, hotel and car with each one's state; null when none. */
+    plan?: BuyPlan | null;
     /**
      * True when this call sent Agentcard a confirm: the shopper's yes, or the yes the tool carried past a step the shopper
      * finished outside the chat. Absent when the call sent the shopper's words or read the conversation.
@@ -289,13 +293,20 @@ export interface BuyToolFound {
     found: number;
     more: BuyToolLink[];
 }
-export interface BuyToolOptions {
+export interface BuyToolOptions extends BuyStoreWait {
     /** A client built with your company's credentials. Build it once and share it across every shopper's tool. */
     agentcard?: AgentcardClient;
     /** Or one shopper's own Agentcard access token, for a tool that buys only for them. */
     accessToken?: string;
     /** Your own id for the shopper. Required with a company client, and left out with a shopper's own token. */
     externalUserId?: string;
+    /**
+     * Your own id for the chat or thread this tool answers in, such as a group chat's id. Agentcard keeps one open purchase
+     * per thread for the shopper, so two chats never share a cart, a question or an approval, and the tool reads only the
+     * messages about this thread's purchase and those about the shopper alone, such as a saved card. Build one tool per
+     * shopper and thread. Leave it out for an app with one chat per shopper.
+     */
+    threadId?: string;
     /**
      * Delivers a link to the shopper. Each call waits for it, so the shopper
      * holds the link before the model answers. A `sendLink` that throws on a
@@ -550,7 +561,7 @@ export type BuyToolTurnItem = {
     link: BuyToolLink;
 };
 /** The callbacks of one turn. Each one left out falls back to the option of the same name the tool was built with, except with `onItem`. */
-export interface BuyToolTurnOptions {
+export interface BuyToolTurnOptions extends BuyStoreWait {
     /**
      * Hears everything the turn hands the shopper, one item at a time and in the order it happened: the
      * instant reply and each message your model writes through `turn.messageStream()` or `turn.say()` as
@@ -615,6 +626,14 @@ export interface BuyToolTurnOptions {
     onText?: BuyToolOptions['onText'];
     /** Hears the carts each time a call of this turn builds or changes one, as the tool's `onCart` does. */
     onCart?: BuyToolOptions['onCart'];
+    /**
+     * The card the shopper tapped to open this turn, by the `productId` its link carried, whatever answer showed it. With `direct`
+     * on, the turn's call goes straight to Agentcard as a pick of exactly that card (`turn.direct`, reason `pick`), and Agentcard
+     * carts it, so a tap on a card two answers back carts that card. Send the tap's words as the turn's message too.
+     */
+    tapped?: {
+        productId: string;
+    };
 }
 /**
  * The buy tool for one shopper message, from `buy.turn`. It is the same tool, with the same name,