@agent-cards/commerce-sdk 0.11.0 → 0.13.0

package/README.md

@@ -39,7 +39,7 @@ agentcard.listen({
 });
 ```
 
-Once `onMessage` returns, the client keeps the message for that shopper's next `buy.turn`, and `turn.messages(history)` hands it to your model before the shopper's words, so the model knows the shopper saved a card or got an order. "Tell the model what Agentcard told the shopper" shows it.
+Once `onMessage` returns, the client keeps the message for that shopper's next `buy.turn`, and `turn.messages(history)` hands it to your model before the shopper's words, so the model knows the shopper saved a card or got an order. "Tell the model what Agentcard told the shopper" shows it. A message whose `advances` is true ends a step the shopper took outside the chat, such as saving a card: "Take the next step once the shopper finishes one outside the chat" shows how your agent moves on without waiting for their "ok".
 
 `listen` returns `{ ready, close }`: `ready` resolves once the listener reaches Agentcard, and `close()` stops it after the callback that is running returns. Run one listener per company and mode. Two listeners each hear every event, so with two, skip a `message.eventId` you already stored. Sandbox credentials hear sandbox events, live credentials live ones, and a shopper message is always live.
 
@@ -76,7 +76,7 @@ const answer = await new Anthropic().beta.messages.toolRunner({
 
 Build the client once and keep it. Every shopper's tool shares the client's access token, and the client renews the token a minute before it expires. Keep each shopper's tool as well. Agentcard keeps each purchase between calls, so a tool built for every message buys the same way, but it sends the same product links again each time Agentcard shows the same products.
 
-The model sends `ask`, `confirm`, `new_order`, `product_id` and `store_id`, and nothing else. 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.
+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.
 
 ## Use the tool in any framework
 
@@ -136,12 +136,48 @@ 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 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`, Agentcard's id for it 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. Each product gets its own link, so the three dishes a restaurant's reply offers are three cards, though they share the store's one page. A flight has no page at a store, so each flight a search finds is a `product` link whose `url` is null, with the airline, the route and its times in `title`: show it as a card with no link to open, and hand its `productId` back as the shopper's pick. The model reads `product_links_sent` and never a URL. The tool's description tells it that the shopper already sees those products as cards, so its reply never lists them again by name or price: it writes one short line, such as which one they want, and a shopper who asks for links hears that the links are there. When a later answer in the conversation only stands beside the same products, as a cart answer does, the tool sends none of their links again. When a later turn's reply presents them again, as the answer to a repeated ask does, the tool sends their links again, so every product the reply names arrives with its link. 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 eight 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`, or `from $10.69` for a product priced by a size or another choice the shopper makes, such as a burger whose patty count sets its price, Agentcard's id for it in `productId`, what taking it does in `action` (`reserve` for a restaurant table, `book` for a flight, room, class or ticket, `buy` for anything else, so a button can say Reserve instead of Buy this), its picture in `imageUrl`, or null when the store sent none, and every photo of the product in `images`, `imageUrl` first and at most eight, so a card can show the others as thumbnails that swap the main picture. `images` holds one entry for a product with one photo and none for a product with 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. Each product gets its own link, so the three dishes a restaurant's reply offers are three cards, though they share the store's one page. A flight has no page at a store, so each flight a search finds is a `product` link whose `url` is null, with the airline, the route and its times in `title`: show it as a card with no link to open, and hand its `productId` back as the shopper's pick. The model reads `product_links_sent` and never a URL. The tool's description tells it that the shopper already sees those products as cards, so its reply never lists them again by name or price: it writes one short line, such as which one they want, and a shopper who asks for links hears that the links are there. When a later answer in the conversation only stands beside the same products, as a cart answer does, the tool sends none of their links again. When a later turn's reply presents them again, as the answer to a repeated ask does, the tool sends their links again, so every product the reply names arrives with its link. A product link your `sendLink` throws on counts as not sent, and the call goes on.
 
 `productId` holds no link: it is the same `product_id` the model reads for that product, and the page is `url`. An answer that only adds a product the shopper picked lists that product alone, so it sends no card for a product nobody offered on that turn, and the pages the search already sent still count as sent on the answers after it.
 
 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.
 
+## Open each step in a pop-up, and close it when it is done
+
+A Vault, approval or store login link is a step the shopper takes outside the chat. Each one carries a stable `id`, such as `vault_1x9k2qd`: the same every time the same link is handed over, on your server and in the browser, with no part of the URL in it, so it is safe as a DOM key or in a log. `actionLinkId(link)` reads it from a link that has none.
+
+Each step ends with a shopper message: `actionLinkOutcome(link, message)` says how a message ended the step, or null when it left it open. `ACTION_LINK_ENDINGS` is the whole table:
+
+| Link | `completed` | `declined` | `failed` | `expired` |
+| --- | --- | --- | --- | --- |
+| `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` |
+
+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.
+
+In the browser, `actionWindows` from `@agent-cards/commerce-sdk/browser` opens each step in a pop-up window centered over the chat, so the shopper never leaves it, and closes the pop-up the moment the message that ends the step arrives. The browser entry imports no Node module, so any bundler takes it:
+
+```ts
+import { actionWindows } from '@agent-cards/commerce-sdk/browser';
+
+const windows = actionWindows({
+  onEnded: (step, outcome) => markStepDone(step.id, outcome),
+  onClosed: (step) => keepOfferingStep(step.id),
+});
+
+// The link's own click handler, so the browser counts the tap as the reason for the pop-up. When the
+// browser blocks it, `open` returns null and the link opens the way it would have, as a new tab.
+stepLink.addEventListener('click', (event) => {
+  if (windows.open(link)) event.preventDefault();
+});
+
+// Each shopper message your server forwards from `listen` or the webhook, with its `kind` and `facts`.
+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.
+
 ## 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:
@@ -175,6 +211,31 @@ A callback you leave out of `buy.turn` falls back to the one the tool was built
 
 A call made on `buy` itself still works as before: it belongs to the turn the tool reads from its timing, and its links go to the tool's `sendLink`.
 
+### Show Agentcard's reply as written
+
+Most answers only ask the shopper something: which product, which size, which store, or a yes to a cart's total. Agentcard's reply already says that, so a second model call that rewords it costs the shopper one more model round trip and changes nothing. Pass `replyAsWritten: true`, to `buyTool` for every turn or to `buy.turn` for one, and `turn.replyAsWritten` holds Agentcard's reply, with every link taken out, whenever the turn's last answer only asks. Show it and end the turn without calling your model again:
+
+```ts
+const turn = buy.turn(message, { replyAsWritten: true, onMessage: (text) => sendText(shopper.id, text) });
+const runner = new Anthropic().beta.messages.toolRunner({ model: 'claude-sonnet-5-5', max_tokens: 16000, tools: [turn], messages: turn.messages(history), stream: true });
+let written: string | null = null;
+for await (const stream of runner) {
+  written = turn.replyAsWritten;
+  if (written !== null) {
+    stream.abort(); // the reply says it already: no second model call
+    break;
+  }
+  const paragraphs = turn.messageStream();
+  stream.on('text', (delta) => paragraphs.push(delta));
+  await stream.done();
+  await paragraphs.end();
+}
+if (written !== null) await turn.say(written);
+history = written !== null ? [...runner.params.messages, { role: 'assistant', content: written }] : runner.params.messages;
+```
+
+Any other answer, such as an approval sent, an order placed or a refusal, leaves `turn.replyAsWritten` null, and your model words it. So does a line the tool writes itself for your model, such as the note that the cart changed or a `buy.nextStep` turn's ask for the shopper's yes: only a reply Agentcard sent goes out as written. `replyAsWritten(result)` applies the same rule to one answer, for a loop that reads `turn.results` itself. Leave the option off to have your model write every answer.
+
 ### Hand the app the turn in order
 
 A turn reaches the shopper as messages and links that interleave: the instant reply, the cards a search found, then your model's words about them. Pass `onItem` to `buy.turn`, and the turn hands your app all of them as one sequence, one item at a time, in the order they happened. Show each item below the one before it:
@@ -194,9 +255,11 @@ for await (const stream of runner) {
 ```
 
 - A `text` item is the instant reply, or a message your model wrote through `turn.messageStream()` or `turn.say(text)`. A `link` item is each link the tool hands over, with the fields `sendLink` would get.
-- Messages arrive one at a time, like someone texting. Each one waits until `typingDelay` of it has passed since the item before it went out: 300 ms, plus 12 ms a character, at most 1.5 seconds. Time your model spent writing counts toward the pause, so a slow model gets no added wait, and links never wait. `onTyping` hears `true` when a pause starts and `false` when its message goes out. Pass `pace: false` to send each message the moment it is ready, or a function that returns the pause in milliseconds.
+- Each message goes out the moment it is ready. Pass `pace: true` to space them like someone texting: each one then waits until `typingDelay` of it has passed since the item before it went out, 300 ms plus 12 ms a character, at most 1.5 seconds. Time your model spent writing counts toward the pause, so a slow model gets no added wait, and links never wait. `onTyping` hears `true` when a pause starts and `false` when its message goes out. A function returns your own pause in milliseconds.
 - With `onItem`, the turn sends no link to a `sendLink` and no instant reply to an `onWorking`, so a tool built with those for other turns sends nothing twice. Passing `onItem` beside `sendLink` or `onWorking` to the same turn throws.
 - `turn.items` holds every item that went out, in order, so an app that answers the whole turn at once returns it as is. A turn without `onItem` keeps `turn.items` as well, unpaced.
+- 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.
 
 ## Tell the model what Agentcard told the shopper
 
@@ -227,6 +290,57 @@ With a webhook, pass the client to the handler: `agentcardWebhook({ secret, agen
 
 The messages live in the client's memory, at most 20 per shopper. So the listener, or the webhook, and the turn have to run in one process on one client. When your listener runs in one process and your model in another, such as a serverless chat route, keep each message where your chat history lives as `onMessage` delivers it, as an assistant message, and the model reads it from the history.
 
+## Take the next step once the shopper finishes one outside the chat
+
+Some steps happen outside the chat: the shopper saves a card from the Vault link, signs in to DoorDash from the sign-in link, or declines the approval. Agentcard tells your server the moment each one ends, and its message reads like `Your Visa ending 4242 is saved, so you're ready to check out.`. Posted as is, it leaves the shopper to say "ok" or "done" before anything moves. Take the next step for them instead: when `message.advances` is true, open `buy.nextStep(message)` and run your model on it, and post the model's answer in place of `message.text`:
+
+```ts
+/** Each shopper's model runs, in order: the chat's own turns should wait on it too. */
+const runs = new Map<string, Promise<void>>();
+
+agentcard.listen({
+  onMessage: (shopperId, message) => {
+    const step = buyFor(shopperId).nextStep(message);
+    if (!step) return postToChat(shopperId, message.text);
+    // Run it without awaiting, so the listener moves on to the next event. One shopper's runs go in order, after
+    // their last one, so an older run never writes its history over a newer one.
+    // A turn that fails is released, so its text reaches later turns and a redelivery can take the step again.
+    const run = (runs.get(shopperId) ?? Promise.resolve()).then(() => runModel(shopperId, step)).catch(() => {
+      step.release();
+      agentcard.delivered(shopperId, message);
+      postToChat(shopperId, message.text);
+    });
+    runs.set(shopperId, run);
+  },
+});
+
+async function runModel(shopperId: string, turn: BuyToolTurn) {
+  const runner = anthropic.beta.messages.toolRunner({ model: 'claude-opus-5-5', max_tokens: 16000, tools: [turn], messages: turn.messages(histories.get(shopperId)) });
+  const answer = await runner;
+  histories.set(shopperId, runner.params.messages);
+  postToChat(shopperId, textOf(answer), turn.links);
+}
+```
+
+`buyFor` stands for the buy tool you keep for each shopper, and `textOf` for the text of the model's answer. The turn is a `buy.turn` in every way but one: no shopper wrote anything, so `turn.messages(history)` ends with the event, marked as written by the system, and the instruction to take the next step now in one short message, never "you're all set, what's next?". The shopper reads one message that does the next thing:
+
+| The shopper finished | The next message |
+| --- | --- |
+| Saving a card, after their yes stopped for it | The approval link: `i sent you a link to approve the payment for your chicken salad. it works for about 15 minutes, and the most you'll be charged is $19.02.` |
+| Saving a card, with no yes yet | The total and the ask for the yes: `your Souvla chicken salad comes to $17.43 with fees. should i go ahead and place the order?` |
+| Signing in to the store, with a card still to add | The add-card link: `next, add a card with the link i sent. it works for about 24 hours.` |
+| Signing in to the store, with a card on file | The total and the ask for the yes, or the approval link after a yes that stopped for the sign-in |
+| Declining the approval | `you declined the payment, so you haven't been charged. your chicken salad is still in the cart, so just say yes if you want a new approval link, or tell me what to change` |
+
+The turn moves the purchase only up to the shopper's own decision, and the tool holds it there whatever the model calls:
+
+- No call of the turn sends an ask to Agentcard, which could read the model's words as the shopper's go-ahead. Each call reads where the purchase stands and answers with the next step: the card link the sign-in held back, or the cart and the ask for the shopper's yes.
+- A confirm goes in only for the yes the shopper already gave in the chat, such as "lets place it", when that confirm stopped for the card or the sign-in they just finished. It goes in once, for that cart's hash, so Agentcard refuses it if the cart changed. A shopper message after the yes that is not a plain go-ahead, such as "wait, make it two", takes it back. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard.
+- The approval in the Vault is still the shopper's: the confirm sends the approval link, and the order goes in only once they approve it.
+- A shopper who was not connected yet when they asked gets their own first ask run, in their words, once their card is saved.
+
+`buy.nextStep` returns null when there is no step to take: a message whose `advances` is false, such as `order_placed`, whose `text` is already the whole message; a message for another shopper, or one whose link closed; a message it already took a turn for; and one that arrives while a call for the shopper's own message is still running, since that call's answer tells the model where the purchase stands. Post `message.text` then. `NEXT_STEP_KINDS` lists the kinds that advance: `card_added`, `store_connected` and `approval_declined`. Once `buy.nextStep` opens a turn, the client never hands the message's text to a later turn as words the shopper read, since they never read it. When your agent cannot finish the turn, call `step.release()` before you post `message.text`: the text then reaches later turns once `agentcard.delivered` records it, and a redelivery of the event opens a turn again.
+
 ## Add the exact product the shopper picks
 
 Each product in the model's view carries a `product_id`, Agentcard's id for it with no link in it. When the shopper picks one of those products, by its name, its place in the list or a tap on its card that sends its title, the model passes that `product_id`, and Agentcard adds exactly that product from the products it showed, with no new search. Your app sends no id of its own: a "Buy this" button that sends the shopper's words, such as `I'll take the KODAK AA Alkaline Batteries (24 Pack) ($13.49)`, is enough, because the model reads the `product_id` beside that name in its last result. Keep each tool result in the model's history, as a tool runner does, so the model still holds those ids on the shopper's next message. Your own code can pick too: a card's button can call `buy.answer` with the link's `productId` as `product_id`, and Agentcard adds that product.
@@ -235,7 +349,7 @@ Each product in the model's view carries a `product_id`, Agentcard's id for it w
 
 ## Show the stores the shopper picks from
 
-A delivery order often starts with a choice of store: the shopper asks for a taco, and Agentcard answers with the taquerias near them that deliver. Each store the reply names reaches `sendLink` as a `store` link, up to three per answer, in the order the reply names them. The link carries the store's page at the merchant in `url`, its name in `title`, Agentcard's id for it in `storeId`, the delivery estimate in minutes in `etaMinutes`, or null when the store showed none, and the picture the store's card shows at the merchant in `imageUrl`, or null when it shows none. Show it as a card with the picture and an "Order here" button. `result.stores` carries the same stores for your code, each with its `url` and `linkSent`.
+A delivery order often starts with a choice of store: the shopper asks for a taco, and Agentcard answers with the taquerias near them that deliver. Each store the reply names reaches `sendLink` as a `store` link, up to eight per answer, in the order the reply names them. The link carries the store's page at the merchant in `url`, its name in `title`, Agentcard's id for it in `storeId`, the delivery estimate in minutes in `etaMinutes`, or null when the store showed none, and the picture the store's card shows at the merchant in `imageUrl`, or null when it shows none. Show it as a card with the picture and an "Order here" button. `result.stores` carries the same stores for your code, each with its `url` and `linkSent`.
 
 The model reads each store in `stores` by its `store_id`, name and `eta_minutes`, never its page, and `store_links_sent` says how many store pages the shopper holds. When the shopper picks a store, by its name, its place in the list or a tap on its card, the model passes that `store_id`, and Agentcard selects exactly that store before its agent answers, so the products it finds next are from that store. A card's button can call `buy.answer` with the link's `storeId` as `store_id`. A shopper who answers only with a place in the list, such as `the second one` or `2`, picks the store at that place in the last answer's list, whether or not the model passed the id. A store pick starts no search, so it gets no instant reply: a card tap that sends `Order from Tacos El Grullense`, the store's name alone or with `please`, and `order here` or `this place` all read as a pick of a store the last answer listed. A dish beside the store's name, as in `order tacos from el farolito`, is a search.
 
@@ -342,7 +456,7 @@ await paragraphs.end();
 
 `stream` stands for your model's streamed answer. `toMessages` and `messageStream` keep nothing between two texts, so a shopper's overlapping messages never mix in them: the paragraphs of one model message go to the `onMessage` of its own stream, and the links of that turn's tool calls are in its `turn.links`. 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.
 
-A model often writes three paragraphs within 200 ms, and a shopper who gets them at once reads a wall, not a conversation. So `messageStream` spaces them like someone texting: the first goes out at once, and each one after it waits until `typingDelay` of it has passed since the one before, at most 1.5 seconds. Time the model spent writing counts toward the pause, so a slow model gets no added wait. Pass `onTyping` to show a typing indicator during each pause, `pace: false` to hand each paragraph over the moment it is cut, or `pace: (text) => ms` for your own pause. With `buy.turn`'s `onItem`, use `turn.messageStream()` instead, which spaces the model's messages after the cards and the instant reply too.
+Each paragraph goes out the moment it is cut. To space them like someone texting, pass `pace: true`: the first goes out at once, and each one after it waits until `typingDelay` of it has passed since the one before, at most 1.5 seconds. Time the model spent writing counts toward the pause, so a slow model gets no added wait. Pass `onTyping` to show a typing indicator during each pause, or `pace: (text) => ms` for your own pause. With `buy.turn`'s `onItem`, use `turn.messageStream()` instead, which keeps the model's messages after the cards and the instant reply too.
 
 ## Sign up a new shopper
 
@@ -601,6 +715,9 @@ The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`
 | `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. |
 | `store_connect_expired` | The sign-in link expired before the shopper finished signing in. `text` offers a new one. |
+| `cart_ready` | The store's checkout built the cart an answer named as still being built (`cart_building`). `text` gives the store's own total, and nothing is paid until the shopper says yes to it. |
+| `cart_needs_input` | That checkout asks the shopper something first, such as a size, a delivery address, a sign-in to the store or an approval of the most the order can cost. Their reply continues the cart. |
+| `cart_failed` | That checkout built no cart, and nothing was ordered or charged. |
 
 Agentcard can add a kind later. A kind your code does not know still carries `text`, ready to send as is.
 

package/dist/ack.d.ts

@@ -106,5 +106,17 @@ export declare const ACK_REACTION = "\uD83D\uDC40";
  * ```
  */
 export declare function instantReaction(shopperText: string, options?: AckForOptions): string | null;
+/**
+ * True when the shopper's words leave a yes they already gave standing: an acknowledgement such as
+ * `ok` or `sounds good`, a go-ahead such as `lets place it`, or a report that they took the step they
+ * were sent, such as `done` or `signed in`. False for anything else, `wait`, `no`, `cancel`, a
+ * question or a new request among them, which a yes given before it does not cover.
+ *
+ * ```ts
+ * keepsYes('ok done'); // true
+ * keepsYes('wait, make it two'); // false
+ * ```
+ */
+export declare function keepsYes(shopperText: string): boolean;
 /** The earlier name of `instantAck`, kept for apps that call it. */
 export declare function ackFor(text: string, options?: AckForOptions): string | null;

package/dist/ack.js

@@ -67,6 +67,13 @@ const CART_COMMAND = new RegExp('^(?:(?:ok|okay|so|actually|wait|and|um|uh)[\\s,
     ')\\b');
 /** Small talk that asks for nothing to be bought, after `please` and `thanks` come off. */
 const CHITCHAT = /^(?:(?:hi|hey|hello|yo|hiya|howdy|sup)(?: there| again)?|good (?:morning|afternoon|evening|night)|g(?:oo)?d ?night|how are (?:you|u)(?: doing)?(?: today)?|how'?s it going|what'?s up|whats up|wassup|who are (?:you|u)|what (?:can|do) (?:you|u) do|are (?:you|u) (?:a )?(?:bot|real|human|there)|you there|test(?:ing)?|bye|see (?:you|ya)|later|love (?:it|you|u)|awesome|amazing|wow|omg|ha(?:ha)+|lmao|:\)|ok cool|cool thanks|so much|very much|a lot)$/;
+/**
+ * A question about what the agent can buy or where it shops, such as `what stores can you buy from`,
+ * `where can you shop` or `which stores do you support`: the model answers it in a line or two, with no
+ * search, so no instant reply says it is looking. A question that names a product, such as `which stores
+ * can you buy aa batteries from`, is a search and keeps its reply.
+ */
+const CAPABILITY = /^(?:(?:ok|okay|so|and|but|hey|hi|um|uh|also|wait)[\s,]+)*(?:(?:what|which|where)(?: (?:kinds?|types?|sorts?) of)?(?: (?:other|else|all|the))?(?: (?:stores?|shops?|places?|sites?|websites?|merchants?|retailers?|restaurants?|brands?|products?|items?|things?|stuff))?(?: else)? (?:can|do|could|will|are) (?:you|u)(?: (?:able to|even|actually|also))? (?:buy|shop|order|get|purchase|do|use|support|work with|deliver|cover|access|sell|carry|offer|stock)(?: (?:from|at|on|in|with|for me|for us|to))?(?: for me)?|(?:what|which) (?:stores?|shops?|merchants?|retailers?|sites?) (?:are )?(?:supported|available|connected|on here)|(?:what|which) (?:stores?|shops?|merchants?|retailers?) do (?:you|u) (?:have|know|use|support|work with)|what (?:else )?(?:do|can) (?:you|u) (?:offer|sell|carry|get (?:me|us)|buy (?:me|us)|order (?:me|us)|find (?:me|us)))(?: (?:right now|here|today))?$/;
 /** Unit words a number names a product by, such as `10000 mah`, so it is never read as a zip code. */
 const UNIT = '(?:packs?|count|ct|pcs?|pieces?|oz|ml|l|g|kg|gb|tb|mb|mah|w|watts?|v|volts?|lumens?|lm|inch(?:es)?|in|ft|feet|mm|cm|lbs?|dollars?|bucks|rpm|dpi|btu|cal|calories|thread)';
 /**
@@ -237,7 +244,7 @@ export function isNewRequest(text) {
     const bare = words.replace(FILLER, '');
     if (bare === '' || ACKNOWLEDGED.test(bare) || CHECKOUT.test(bare))
         return false;
-    return !ANSWERS.test(words) && !STATUS.test(words) && !ABOUT.test(words) && !CART_COMMAND.test(words) && !CODE.test(words) && !CHITCHAT.test(words) && !isPick(line, words);
+    return !ANSWERS.test(words) && !STATUS.test(words) && !ABOUT.test(words) && !CART_COMMAND.test(words) && !CODE.test(words) && !CHITCHAT.test(words) && !CAPABILITY.test(words) && !isPick(line, words);
 }
 /** A short paraphrase of what the shopper asks for, safe to read back to them, or null when none is. */
 export function paraphrase(text) {
@@ -388,6 +395,27 @@ export const ACK_REACTION = '👀';
 export function instantReaction(shopperText, options = {}) {
     return instantAck(shopperText, options) === null ? null : ACK_REACTION;
 }
+/**
+ * True when the shopper's words leave a yes they already gave standing: an acknowledgement such as
+ * `ok` or `sounds good`, a go-ahead such as `lets place it`, or a report that they took the step they
+ * were sent, such as `done` or `signed in`. False for anything else, `wait`, `no`, `cancel`, a
+ * question or a new request among them, which a yes given before it does not cover.
+ *
+ * ```ts
+ * keepsYes('ok done'); // true
+ * keepsYes('wait, make it two'); // false
+ * ```
+ */
+export function keepsYes(shopperText) {
+    const words = plain(String(shopperText ?? '')).replace(/[!?.,;:]+/g, ' ').replace(/\b(?:please|pls|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim();
+    if (words === '')
+        return false;
+    const bare = words.replace(FILLER, '');
+    if (bare === '')
+        return true;
+    // A report after filler ("well signed in", "k connected") is read on its bare words too (review of #9220).
+    return ACKNOWLEDGED.test(bare) || CHECKOUT.test(bare) || STATUS.test(words) || STATUS.test(bare) || /^(?:done|added(?: it)?|i added(?: it| the card| a card)?)$/.test(bare);
+}
 /** The earlier name of `instantAck`, kept for apps that call it. */
 export function ackFor(text, options = {}) {
     return instantAck(text, options);

package/dist/action-links.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The steps a shopper takes outside the chat: adding a card (`vault`), signing in to a store
+ * (`store_login`) and approving a payment (`approval`). Each one is a link the buy tool hands over,
+ * and each one ends with a shopper message Agentcard sends: this file says which message ends which
+ * link, and how. It imports nothing, so a browser bundle can use it as well as a server.
+ */
+/** A link the shopper opens to do something outside the chat. */
+export type ActionLinkKind = 'vault' | 'store_login' | 'approval';
+/** The kinds of link that are a step outside the chat. */
+export declare const ACTION_LINK_KINDS: readonly ActionLinkKind[];
+/**
+ * How a step ended:
+ * - `completed`: the shopper finished it: a card saved, a store signed in to, a payment approved.
+ *   An approval stays `completed` when the order then failed or the payment was refused, since the
+ *   page has nothing more to do; the message itself tells the shopper what happened next.
+ * - `declined`: the shopper declined the payment on the approval page.
+ * - `failed`: the step did not go through, and its link no longer works (a store sign-in that failed).
+ * - `expired`: the link expired before the shopper finished.
+ */
+export type ActionLinkOutcome = 'completed' | 'declined' | 'failed' | 'expired';
+/**
+ * For each kind of step, the shopper message kinds that end it, and how. Every other message kind,
+ * such as `card_link_unfinished` or `approval_expiring`, leaves the step open.
+ */
+export declare const ACTION_LINK_ENDINGS: Readonly<Record<ActionLinkKind, Readonly<Record<string, ActionLinkOutcome>>>>;
+/** Whether a link is a step outside the chat: a `vault`, `store_login` or `approval` link with a page to open. */
+export declare function isActionLink<T extends {
+    kind: string;
+    url?: string | null;
+}>(link: T): link is T & {
+    kind: ActionLinkKind;
+    url: string;
+};
+/**
+ * A stable id for a step's link, such as `vault_1x9k2qd`: the same for the same link every time it is
+ * handed over, on the server and in the browser, and with no part of the URL in it, so it is safe in
+ * a log, a DOM key or a window name. The buy tool puts it on each step link as `id`.
+ */
+export declare function actionLinkId(link: {
+    kind: string;
+    url: string;
+}): string;
+/** What `actionLinkOutcome` reads of a shopper message: its kind, and the link URLs and the store its facts name, when they name them. */
+export interface ActionLinkMessage {
+    kind: string;
+    facts?: {
+        approvalUrl?: string;
+        cardLinkUrl?: string;
+        merchantName?: string;
+    } | null;
+}
+/**
+ * How `message` ends the step `link` is, or null when it leaves it open: a message about another
+ * kind of step, a reminder such as `card_link_unfinished`, a message whose facts name another link of
+ * the same kind (`facts.approvalUrl` or `facts.cardLinkUrl`), or one about another store: a store
+ * login or an approval link that names its `store` stays open when `facts.merchantName` names a
+ * different one, since a shopper can sign in to two stores, or approve two stores' carts, at once.
+ * A message whose facts name neither ends the shopper's open step of its kind.
+ */
+export declare function actionLinkOutcome(link: {
+    kind: string;
+    url?: string | null;
+    store?: string | null;
+}, message: ActionLinkMessage): ActionLinkOutcome | null;

package/dist/action-links.js

@@ -0,0 +1,77 @@
+/**
+ * The steps a shopper takes outside the chat: adding a card (`vault`), signing in to a store
+ * (`store_login`) and approving a payment (`approval`). Each one is a link the buy tool hands over,
+ * and each one ends with a shopper message Agentcard sends: this file says which message ends which
+ * link, and how. It imports nothing, so a browser bundle can use it as well as a server.
+ */
+/** The kinds of link that are a step outside the chat. */
+export const ACTION_LINK_KINDS = ['vault', 'store_login', 'approval'];
+/**
+ * For each kind of step, the shopper message kinds that end it, and how. Every other message kind,
+ * such as `card_link_unfinished` or `approval_expiring`, leaves the step open.
+ */
+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_placed: 'completed',
+        order_not_placed_yet: 'completed',
+        order_unconfirmed: 'completed',
+        order_confirmed: 'completed',
+        order_failed: 'completed',
+        payment_declined: 'completed',
+        approval_declined: 'declined',
+        approval_expired: 'expired',
+    },
+};
+/** Whether a link is a step outside the chat: a `vault`, `store_login` or `approval` link with a page to open. */
+export function isActionLink(link) {
+    return ACTION_LINK_KINDS.includes(link.kind) && typeof link.url === 'string' && link.url !== '';
+}
+/** FNV-1a, 32 bits, written out so the id reads the same in every runtime, with no crypto import. */
+function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+/**
+ * A stable id for a step's link, such as `vault_1x9k2qd`: the same for the same link every time it is
+ * handed over, on the server and in the browser, and with no part of the URL in it, so it is safe in
+ * a log, a DOM key or a window name. The buy tool puts it on each step link as `id`.
+ */
+export function actionLinkId(link) {
+    return `${link.kind}_${fnv1a(`${link.kind} ${link.url}`).toString(36)}`;
+}
+/** A store's name reduced to its letters and digits, so "Walmart" and "walmart.com" read alike. */
+const storeKey = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '');
+/** Whether two names are the same store: one reduced name holds the other. */
+function sameStore(a, b) {
+    const x = storeKey(a);
+    const y = storeKey(b);
+    return x === '' || y === '' || x.includes(y) || y.includes(x);
+}
+/**
+ * How `message` ends the step `link` is, or null when it leaves it open: a message about another
+ * kind of step, a reminder such as `card_link_unfinished`, a message whose facts name another link of
+ * the same kind (`facts.approvalUrl` or `facts.cardLinkUrl`), or one about another store: a store
+ * login or an approval link that names its `store` stays open when `facts.merchantName` names a
+ * different one, since a shopper can sign in to two stores, or approve two stores' carts, at once.
+ * A message whose facts name neither ends the shopper's open step of its kind.
+ */
+export function actionLinkOutcome(link, message) {
+    if (!isActionLink(link))
+        return null;
+    const outcome = ACTION_LINK_ENDINGS[link.kind][message.kind];
+    if (!outcome)
+        return null;
+    const named = link.kind === 'approval' ? message.facts?.approvalUrl : link.kind === 'vault' ? message.facts?.cardLinkUrl : undefined;
+    if (named && named !== link.url)
+        return null;
+    const store = message.facts?.merchantName;
+    if (link.store && store && !sameStore(link.store, store))
+        return null;
+    return outcome;
+}

package/dist/browser.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `@agent-cards/commerce-sdk/browser`: the part of the package that runs in the shopper's browser.
+ * It imports no Node module, so any bundler takes it.
+ *
+ * `actionWindows` opens each step the shopper takes outside the chat (adding a card, signing in to a
+ * store, approving a payment) in a pop-up window over the chat, and closes it the moment the shopper
+ * message that ends the step arrives. On a phone, where a browser opens the pop-up as a tab, it
+ * closes that tab the same way.
+ */
+import { type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome } from './action-links.js';
+export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';
+/** The part of a window `window.open` returns that `actionWindows` uses. */
+export interface PopupLike {
+    readonly closed: boolean;
+    close(): void;
+    focus(): void;
+}
+/** The part of the page's `window` that `actionWindows` uses. */
+export interface WindowLike {
+    open(url: string, target: string, features: string): PopupLike | null;
+    readonly screenX?: number;
+    readonly screenY?: number;
+    readonly outerWidth?: number;
+    readonly outerHeight?: number;
+    readonly screen?: {
+        readonly availWidth?: number;
+        readonly availHeight?: number;
+    };
+    setInterval(handler: () => void, ms: number): unknown;
+    clearInterval(id: unknown): void;
+}
+/** A step's link, as the buy tool hands it over (`BuyToolLink`) or as an app passes it on: its kind and its page. */
+export interface ActionLinkLike {
+    kind: string;
+    url?: string | null;
+    /** The store a store login or an approval is for, as the buy tool names it, so a message about another store leaves it open. */
+    store?: string | null;
+    /** The link's `actionLinkId`, when the buy tool put one on it. Read from the link when absent. */
+    id?: string;
+}
+/** A step open in a pop-up. */
+export interface ActionWindow {
+    /** The link's `actionLinkId`. */
+    readonly id: string;
+    readonly kind: ActionLinkKind;
+    readonly url: string;
+    /** The store the step is for, when the link named one. */
+    readonly store: string | null;
+    /** False once the window closed, by the shopper or by `actionWindows`. */
+    readonly open: boolean;
+}
+export interface ActionWindowsOptions {
+    /** The page's window. Defaults to `globalThis.window`; pass one to test with a fake. */
+    window?: WindowLike;
+    /** The pop-up's size in CSS pixels, kept inside the screen. Defaults to 480 by 760. */
+    width?: number;
+    height?: number;
+    /** How often to check whether the shopper closed a pop-up, in milliseconds. Defaults to 500. */
+    pollMs?: number;
+    /**
+     * Hears a step that ended while its pop-up was open, after `settle` closed the pop-up. Show the step
+     * as done here.
+     */
+    onEnded?: (step: ActionWindow, outcome: ActionLinkOutcome) => void;
+    /**
+     * Hears a pop-up the shopper closed before the step ended. The step is still open: keep offering
+     * its link, so the shopper can open it again.
+     */
+    onClosed?: (step: ActionWindow) => void;
+}
+export interface ActionWindows {
+    /**
+     * Opens the step's page in a pop-up centered over the chat, or brings its pop-up to the front when
+     * one is open already. Returns null when the link is not a step with a page, or when the browser
+     * blocked the pop-up: then let the link open the way it would have, as a new tab. Call it from the
+     * tap's click handler, so the browser counts the tap as the reason for the pop-up:
+     *
+     * ```js
+     * a.addEventListener('click', (event) => { if (windows.open(link)) event.preventDefault(); });
+     * ```
+     */
+    open(link: ActionLinkLike): ActionWindow | null;
+    /**
+     * Hands over a shopper message (`ShopperMessage`, or any object with its `kind` and `facts`, whose
+     * `merchantName` keeps one store's message from closing another store's step).
+     * Each open pop-up whose step the message ends closes, and `onEnded` hears it. Returns the steps it
+     * ended, with how each ended; an empty list when the message ends none.
+     */
+    settle(message: ActionLinkMessage): {
+        step: ActionWindow;
+        outcome: ActionLinkOutcome;
+    }[];
+    /** The open pop-up for the link, or null. */
+    get(link: ActionLinkLike): ActionWindow | null;
+    /**
+     * Stops watching every pop-up, and leaves each one as it is: a chat that reloads or remounts never
+     * shuts the page a shopper is typing a card into. Call it when the chat goes away.
+     */
+    dispose(): void;
+}
+/**
+ * Opens each step outside the chat in a pop-up and closes it when the step ends. One per chat page.
+ * The pop-up keeps its opener, deliberately: a window opened with `noopener` hands back no handle,
+ * so the chat could neither close it nor tell when the shopper closed it.
+ */
+export declare function actionWindows(options?: ActionWindowsOptions): ActionWindows;