@agent-cards/commerce-sdk 0.10.0 → 0.11.0

package/README.md

@@ -150,7 +150,7 @@ A shopper can send a second message before the first is answered. The `sendLink`
 const buy = buyTool({ agentcard, externalUserId: shopper.id }); // one per shopper, kept
 
 async function onShopperMessage(message: string) {
-  const turn = buy.turn(message, { onWorking: (text) => textShopper(shopper.id, text) });
+  const turn = buy.turn(message, { onReaction: (emoji) => reactToShopperMessage(shopper.id, emoji) });
   const runner = new Anthropic().beta.messages.toolRunner({
     model: 'claude-opus-5-5',
     max_tokens: 16000,
@@ -167,11 +167,11 @@ async function onShopperMessage(message: string) {
 
 - `turn.links` holds each link the turn's calls handed over, in order: the Vault, approval and store login links, each product's store page, and each store card's page. The model reads that each one went out, so send them with the reply. Pass `sendLink` to `buy.turn` as well to send each one the moment the tool hands it over, such as down a server-sent event stream. A link your `sendLink` throws on stays out of `turn.links`.
 - `turn.results` holds the whole answer of each call, and an `onResult` passed to `buy.turn` hears each one as it arrives.
-- With `onWorking`, `buy.turn` sends the instant reply at once, before your model runs: the one `buy.instantAck` would return, or the one your `ack` function writes. You never call `instantAck` yourself. A slow call of the turn sends its reply to that `onWorking` too, and `turn.ack` holds the text the turn sent when it opened.
+- With `onReaction`, `buy.turn` puts a 👀 on a message that starts a search at once, before your model runs, and `turn.reaction` holds it. With only `onWorking`, it sends the text reply `buy.instantAck` would return, or the one your `ack` function writes, and `turn.ack` holds that text. You never call `instantReaction` or `instantAck` yourself. A slow call of the turn acknowledges through the same callback.
 - An `onProgress` passed to `buy.turn` hears only that turn's stages.
 - `turn.agentcardMessages` holds each message `agentcard.listen` or `agentcardWebhook` posted into this shopper's chat that the model has not read yet, and `turn.messages(history)` hands them to the model.
 
-A callback you leave out of `buy.turn` falls back to the one the tool was built with, so a tool whose `sendLink` texts the shopper keeps texting, and `turn.links` lists the same links. The turn is the tool, with the same name, schema and methods, so pass it to every framework the way you pass `buy`: `tools: [turn]`, `tools: { buy: turn }`, `tools: [turn.openai]` with `turn.handle`, or `toOpenRouterTool(turn, { tool, z })`. `turn.ack`, `turn.links` and `turn.results` stay out of the tool's JSON, so a tool runner sends the API the same fields. Build the tool once per shopper and open a turn from it for each message: the turns share the shopper's conversation, so a card a shopper already holds from an earlier turn is not sent again.
+A callback you leave out of `buy.turn` falls back to the one the tool was built with, so a tool whose `sendLink` texts the shopper keeps texting, and `turn.links` lists the same links. The turn is the tool, with the same name, schema and methods, so pass it to every framework the way you pass `buy`: `tools: [turn]`, `tools: { buy: turn }`, `tools: [turn.openai]` with `turn.handle`, or `toOpenRouterTool(turn, { tool, z })`. `turn.ack`, `turn.reaction`, `turn.links` and `turn.results` stay out of the tool's JSON, so a tool runner sends the API the same fields. Build the tool once per shopper and open a turn from it for each message: the turns share the shopper's conversation, so a card a shopper already holds from an earlier turn is not sent again.
 
 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`.
 
@@ -245,35 +245,62 @@ The tool sends each store page once for the calls the model makes in one turn. A
 
 ## Tell the shopper you are on it
 
-A first search can take Agentcard most of a minute. Pass `onWorking`, and the shopper reads an instant reply while Agentcard looks, such as `on it, looking for usb-c cables under $20` or `give me a sec, checking for a table for 2 in north beach`:
+A first search can take Agentcard most of a minute. Pass `onReaction`, and the shopper sees a 👀 on their own message while Agentcard looks, the way a friend reacts to a text before answering it. Show it as a tapback on the shopper's bubble:
 
 ```ts
 const buy = buyTool({
   agentcard,
   externalUserId: shopper.id,
   sendLink: (link) => textShopper(shopper.id, link.url),
+  onReaction: (emoji) => reactToShopperMessage(shopper.id, emoji), // emoji is always '👀'
+});
+```
+
+A reaction is the default acknowledgement. It names nothing the shopper said, so it never reads a request back wrong, and the chat holds only real answers. Each message gets at most one 👀:
+
+- A message that starts a search gets it the moment `buy.turn` opens, before your model runs.
+- A pick of a product or a store the shopper saw, an address or other details, an answer to a question such as `yes`, `2` or a code, a step toward checkout such as `ok lets checkout`, and an acknowledgement such as `its ok` get none when the turn opens, because Agentcard answers them fast.
+- A call that Agentcard has not answered within 1.5 seconds puts the 👀 on a message that has none yet: a slow `yes`, a pick, or a confirm that is still placing the order. It sends no text.
+- A turn that runs long, even past a minute, still gets no text line. A search often takes 10 to 40 seconds, so a line at any wait short enough to help would land on most searches and bring back the chatter the reaction replaces. To show a long wait, pass `onProgress` and show its stage, such as `checking_out`, as a status line or a typing indicator.
+
+With `onItem` on `buy.turn`, the 👀 still goes to `onReaction` and never joins the turn's items, because it sits on the shopper's bubble rather than in the agent's sequence. Without an `onReaction`, the text instant reply is the turn's first `text` item, as before.
+
+When the 👀 went out, the model reads `shopper_already_told_looking: true` in that turn's answers, and the tool's description tells it not to acknowledge the request again, so its reply opens with the answer or the question rather than `on it`. It reads false on a turn that reacted with nothing, and when `onReaction` threw. An `onReaction` that throws costs only the reaction.
+
+### Acknowledge in text, or not at all
+
+For SMS, or any chat that shows no reactions, acknowledge in text. Pass `onWorking` and no `onReaction`, or set `ack: 'text'`, and the shopper reads an instant reply instead, such as `on it, looking for usb-c cables under $20` or `give me a sec, checking for a table for 2 in north beach`:
+
+```ts
+const buy = buyTool({
+  agentcard,
+  externalUserId: shopper.id,
+  ack: 'text',
   onWorking: (text) => textShopper(shopper.id, text),
 });
 ```
 
-The tool sends the reply when Agentcard has not answered a new request within 1.5 seconds, 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 the shopper saw hears `adding it now`, a pick of a store or a place in a list, such as `the first one`, hears `got it, one moment`, and a confirm hears `on it, one moment`. 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.
+`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.
 
-When the instant reply went out, the model reads `shopper_already_told_looking: true` in that turn's answers, and the tool's description tells it not to acknowledge the request again, so its own reply opens with the answer or the question rather than a second `on it`. It reads false on a turn that sent none, and when `onWorking` threw.
+In text mode, the tool sends the reply when Agentcard has not answered a new request within 1.5 seconds, 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 the shopper saw hears `adding it now`, a pick of a store or a place in a list, such as `the first one`, hears `got it, one moment`, and a confirm hears `on it, one moment`. 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: false` to send none, `ack: (ask) => text` to write your own from the shopper's words, where an empty answer sends none, and `ackDelayMs` to change the 1.5 seconds.
+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.5 seconds for either mode.
 
-The model takes several seconds to call the tool after the shopper's message arrives. To answer sooner, call `buy.instantAck(message)` the moment the message arrives, before your model runs, and send the text it returns:
+The model takes several seconds to call the tool after the shopper's message arrives. Without `buy.turn`, react sooner by calling `buy.instantReaction(message)` the moment the message arrives, before your model runs, and put the emoji it returns on the message. In text mode, call `buy.instantAck(message)` and send the text it returns:
 
 ```ts
+const reaction = buy.instantReaction(message); // '👀' or null
+if (reaction) await reactToShopperMessage(shopper.id, reaction);
+// In text mode instead:
 const ack = buy.instantAck(message);
 if (ack) await textShopper(shopper.id, ack);
 ```
 
-With `buy.turn`, pass `onWorking` to the turn instead: it sends the same reply the moment the turn opens, and calls `instantAck` for you.
+With `buy.turn`, pass `onReaction` or `onWorking` to the turn instead: it acknowledges the moment the turn opens, and calls `instantReaction` or `instantAck` for you. When either returns a 👀 or a reply, the tool sends none of its own for that turn.
 
-`instantAck` returns null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a step toward paying for the cart such as `ok lets checkout`, `place the order` or `pay`, an acknowledgement such as `its ok`, `thats fine` or `sounds good`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a pick of a store, such as `order here` or a store card's `Order from Tacos El Grullense`, a code, small talk such as `hi` or `how are you`, a message that carries the shopper's own details, such as a name with a phone number, an email address, a street address, a bare house number and street such as `1801 wedemeyer`, or a zip code, any message that answers the last answer's request for an address, shipping or guest details or a code, and a short reply right after any other question the last answer asked, such as `im a 37` after `what size do you want?`, or `carne asada` after `which meat?`. A reply that opens a new request, such as `find me black running shoes`, or that runs past four words is still a search. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed, or names one of the stores its last answer listed and nothing else to buy, as a pick of it. A request for a store the shopper did not see, such as `order from chipotle`, reads back as `looking for chipotle`, never `looking for from chipotle`. When it returns a reply, the tool sends none of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still sends `onWorking` a reply that names nothing and never says it is looking for anything, such as `working on it` or `one moment`, and when it returns null for a pick, such a call sends `adding it now` or `got it, one moment`.
+`instantReaction` and `instantAck` return null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a step toward paying for the cart such as `ok lets checkout`, `place the order` or `pay`, an acknowledgement such as `its ok`, `thats fine` or `sounds good`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a pick of a store, such as `order here` or a store card's `Order from Tacos El Grullense`, a code, small talk such as `hi` or `how are you`, a message that carries the shopper's own details, such as a name with a phone number, an email address, a street address, a bare house number and street such as `1801 wedemeyer`, or a zip code, any message that answers the last answer's request for an address, shipping or guest details or a code, and a short reply right after any other question the last answer asked, such as `im a 37` after `what size do you want?`, or `carne asada` after `which meat?`. A reply that opens a new request, such as `find me black running shoes`, or that runs past four words is still a search. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed, or names one of the stores its last answer listed and nothing else to buy, as a pick of it. A request for a store the shopper did not see, such as `order from chipotle`, reads back as `looking for chipotle`, never `looking for from chipotle`. When it returns a reply, the tool sends none of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still acknowledges: with a 👀 in reaction mode, and in text mode with an `onWorking` reply that names nothing and never says it is looking for anything, such as `working on it` or `one moment`, and when it returns null for a pick, such a call sends `adding it now` or `got it, one moment`.
 
-Without a buy tool, `instantAck(message, { previous, nextAction, asked, stores })` from the package root decides the same way: `previous` is the reply you sent last, so the next one comes from another template, `nextAction` is the last answer's `next_action`, `asked` is the last message the shopper read, so an answer to its question for an address, a name or a code, or a short answer to any other question it asked, gets none, and `stores` holds the names of the stores the last answer listed, so a message that picks one gets none. Pass `ack: false` to the tool when you send it yourself. `ackFor` is the earlier name of the same function.
+Without a buy tool, `instantReaction(message, { nextAction, asked, stores })` and `instantAck(message, { previous, nextAction, asked, stores })` from the package root decide the same way, and `ACK_REACTION` is the `👀` `instantReaction` returns: `previous` is the reply you sent last, so the next one comes from another template, `nextAction` is the last answer's `next_action`, `asked` is the last message the shopper read, so an answer to its question for an address, a name or a code, or a short answer to any other question it asked, gets none, and `stores` holds the names of the stores the last answer listed, so a message that picks one gets none. Pass `ack: 'none'` to the tool when you acknowledge yourself. `ackFor` is the earlier name of the same function.
 
 ## Show what Agentcard is doing
 
@@ -470,12 +497,15 @@ Subscribe your endpoint to each event below by name. A catch-all `*` alone does
 | Event | `kind` | When it arrives | Who wrote `text` |
 |---|---|---|---|
 | `purchase.message` | `card_added` | The shopper saved a card from the card link your app sent, or picked one they keep. | Agentcard |
+| `purchase.message` | `store_connected` | The shopper signed in to their own account at the store from the sign-in link your app sent. | Agentcard |
 | `purchase.message` | `order_placed` | The shopper approved, and Agentcard placed the order. | Agentcard |
 | `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` | `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 |
+| `purchase.message` | `payment_declined` | The shopper approved, and the payment was refused before the order went in, such as a declined card. `facts.reason` says why. No charge went through. | Agentcard |
 | `purchase.message` | `card_link_unfinished` | The shopper has not added a card from their card link. `text` carries the link again. | Agentcard |
 | `purchase.message` | `card_link_expired` | The card link expired before the shopper added a card. | Agentcard |
 | `purchase.message` | `cart_idle` | A cart sat, and nobody sent it for approval. | Agentcard |
@@ -561,11 +591,16 @@ The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`
 | `order_not_placed_yet` | The shopper approved, and the order is not placed yet. |
 | `approval_expiring` | The approval link expires soon. `text` carries the link. |
 | `approval_expired` | The approval expired before the shopper answered, and no charge went through. |
+| `approval_declined` | The shopper declined the approval, and no charge went through. |
+| `payment_declined` | The shopper approved, and the payment was refused before the order went in. `facts.reason` says why. |
 | `card_link_unfinished` | The shopper has not added a card from their card link. `text` carries the link again. |
 | `card_link_expired` | The card link expired before the shopper added a card. |
 | `cart_idle` | A cart sat, and nobody sent it for approval. |
 | `order_unconfirmed` | The store's reply to the order was lost, and Agentcard is confirming it. |
 | `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. |
+| `store_connect_expired` | The sign-in link expired before the shopper finished signing in. `text` offers a new one. |
 
 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

@@ -89,5 +89,22 @@ export declare function answersQuestion(text: string, asked: string | null | und
  * ```
  */
 export declare function instantAck(shopperText: string, options?: AckForOptions): string | null;
+/**
+ * The reaction the tool puts on a shopper's message to say it is on it: 👀, as a chat app shows a
+ * tapback on the shopper's own bubble. It names nothing the shopper said, so it can never read a
+ * request back wrong.
+ */
+export declare const ACK_REACTION = "\uD83D\uDC40";
+/**
+ * The reaction for a shopper's message, `👀`, or null for a message that starts no search. It reads the
+ * message exactly as `instantAck` does, so a pick, an address, an answer to a question, a step toward
+ * checkout or an acknowledgement such as `its ok` gets none.
+ *
+ * ```ts
+ * instantReaction('can you find me usb-c cables under $20'); // '👀'
+ * instantReaction('yes'); // null
+ * ```
+ */
+export declare function instantReaction(shopperText: string, options?: AckForOptions): string | null;
 /** 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

@@ -369,6 +369,25 @@ export function instantAck(shopperText, options = {}) {
         return null;
     return ackAt(nextTemplate(templateOf(options?.previous)), shopperText);
 }
+/**
+ * The reaction the tool puts on a shopper's message to say it is on it: 👀, as a chat app shows a
+ * tapback on the shopper's own bubble. It names nothing the shopper said, so it can never read a
+ * request back wrong.
+ */
+export const ACK_REACTION = '👀';
+/**
+ * The reaction for a shopper's message, `👀`, or null for a message that starts no search. It reads the
+ * message exactly as `instantAck` does, so a pick, an address, an answer to a question, a step toward
+ * checkout or an acknowledgement such as `its ok` gets none.
+ *
+ * ```ts
+ * instantReaction('can you find me usb-c cables under $20'); // '👀'
+ * instantReaction('yes'); // null
+ * ```
+ */
+export function instantReaction(shopperText, options = {}) {
+    return instantAck(shopperText, options) === null ? null : ACK_REACTION;
+}
 /** The earlier name of `instantAck`, kept for apps that call it. */
 export function ackFor(text, options = {}) {
     return instantAck(text, options);

package/dist/buy-tool.d.ts

@@ -152,8 +152,9 @@ export interface BuyToolResult {
     /** True when Agentcard tells the shopper how the order went, so the shopper need not reply. */
     shopper_need_not_reply: boolean;
     /**
-     * True when `onWorking` delivered this turn's instant reply, such as `got it, finding a taco`, so the
-     * shopper already heard that the request is being worked on. Absent or false when none went out.
+     * True when this turn's acknowledgement reached the shopper: the 👀 `onReaction` put on their message,
+     * or the instant reply `onWorking` sent, such as `got it, finding a taco`. The shopper already knows
+     * the request is being worked on. Absent or false when none went out.
      */
     shopper_already_told_looking?: boolean;
     conversation_id: string | null;
@@ -173,6 +174,14 @@ export interface BuyToolResult {
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
     envelope: Record<string, unknown>;
 }
+/**
+ * How the tool acknowledges a shopper's message while Agentcard works on it:
+ * - `reaction`, the default: a 👀 on the shopper's own message, through `onReaction`. No text goes out.
+ * - `text`: an instant reply, such as `on it, looking for usb-c cables under $20`, through `onWorking`,
+ *   for SMS, or any chat that shows no reactions.
+ * - `none`: nothing.
+ */
+export type BuyAckMode = 'reaction' | 'text' | 'none';
 export interface BuyToolOptions {
     /** A client built with your company's credentials. Build it once and share it across every shopper's tool. */
     agentcard?: AgentcardClient;
@@ -198,9 +207,19 @@ export interface BuyToolOptions {
     fetch?: FetchLike;
     /** The pause between two reads of the conversation. Default: a timer. */
     wait?: (ms: number) => Promise<void>;
+    /**
+     * Reacts to the shopper's message with `emoji`, always `👀`, to say the tool is on it: show it on the
+     * shopper's own bubble, as a tapback. It fires once per message: the moment `buy.turn` opens on a
+     * search, or, for a message that got none, such as `yes`, once a call passes `ackDelayMs`. Never on a
+     * pick, an address, an answer to a question or a step toward checkout when the turn opens. With it,
+     * the tool sends no text acknowledgement at all, unless `ack` is `'text'`. One that throws costs
+     * nothing but the reaction.
+     */
+    onReaction?: (emoji: string) => void | Promise<void>;
     /**
      * Sends the shopper an instant reply, such as `on it, looking for usb-c cables under $20`, while
-     * Agentcard works on a new request. It goes out when Agentcard has not answered within
+     * Agentcard works on a new request, when the tool acknowledges in text: with `ack: 'text'`, or with
+     * no `onReaction`. It goes out when Agentcard has not answered within
      * `ackDelayMs`, once for the calls the model makes in one turn. A slow pick gets `adding it now`
      * for a product or `got it, one moment` for a store or a place in a list. A slow confirm gets
      * `on it, one moment`. These replies name nothing the shopper said. A code gets no reply.
@@ -208,9 +227,16 @@ export interface BuyToolOptions {
      * answer. One that throws costs nothing but the instant reply.
      */
     onWorking?: (message: string) => void | Promise<void>;
-    /** `false` sends no instant reply. A function writes it from the shopper's words instead, and an empty answer sends none. A turn whose message `instantAck` sent nothing for gets the built-in reply that names nothing. */
-    ack?: false | ((ask: string) => string | null | undefined);
-    /** How long Agentcard has to answer before the instant reply goes out. Default 1500. */
+    /**
+     * How the tool acknowledges a message (`BuyAckMode`). Left out, it reacts through `onReaction` when
+     * the tool or the turn has one, and otherwise sends text through `onWorking`, as 0.9 did. `'text'`
+     * sends text even with an `onReaction`, and `'none'`, or `false`, sends nothing. A function is
+     * `'text'` with your own words: it writes the instant reply from the shopper's words, and an empty
+     * answer sends none. A turn whose message `instantAck` sent nothing for gets the built-in reply that
+     * names nothing.
+     */
+    ack?: BuyAckMode | false | ((ask: string) => string | null | undefined);
+    /** How long Agentcard has to answer before the instant reply or the reaction goes out. Default 1500. */
     ackDelayMs?: number;
     /**
      * Called with the whole answer once per call, after its links went out and before the model reads
@@ -292,6 +318,14 @@ export interface BuyTool {
      * message that picks nothing, such as `yes`, a slow call still sends `onWorking` a reply that names nothing.
      */
     instantAck(shopperText: string): string | null;
+    /**
+     * The reaction for a shopper's message, `👀`, or null for one that starts no search, read as
+     * `instantAck` reads it. Call it the moment the message arrives, before your model runs, and put the
+     * emoji it returns on the shopper's message. When it returns one, the tool sends no reaction or text of
+     * its own for that turn, and the model reads `shopper_already_told_looking`. With `buy.turn` and
+     * `onReaction`, the turn does this for you.
+     */
+    instantReaction(shopperText: string): string | null;
     /**
      * Opens the turn of one shopper message and returns the tool for that turn: pass it to your model in
      * place of the tool, as `tools: [turn]`. Each call the model makes through it hands its links to this
@@ -299,8 +333,9 @@ export interface BuyTool {
      * keeps it in `turn.results`, and sends this turn's instant reply to its `onWorking`. A shopper who
      * sends a second message while the first still runs gets a second turn, and no link, cart or reply
      * of one reaches the other. Call it the moment the message arrives, before your model runs: with an
-     * `onWorking`, the instant reply `instantAck` would return goes out at once. An option left out falls
-     * back to the one the tool was built with.
+     * `onReaction`, a search gets its 👀 at once, and with only an `onWorking`, the instant reply
+     * `instantAck` would return goes out at once. An option left out falls back to the one the tool was
+     * built with.
      */
     turn(shopperText: string, options?: BuyToolTurnOptions): BuyToolTurn;
 }
@@ -342,7 +377,9 @@ export interface BuyToolTurnOptions {
      * `turn.links` beside the turn's reply.
      */
     sendLink?: (link: BuyToolLink) => void | Promise<void>;
-    /** Sends this turn's instant reply: at once when `turn` opens on a new request, or once a slow call passes `ackDelayMs`. */
+    /** Reacts 👀 to this turn's message: at once when `turn` opens on a new request, or once a slow call passes `ackDelayMs`. */
+    onReaction?: (emoji: string) => void | Promise<void>;
+    /** Sends this turn's instant reply in text, when the tool acknowledges in text: at once when `turn` opens on a new request, or once a slow call passes `ackDelayMs`. */
     onWorking?: (message: string) => void | Promise<void>;
     /** Called with the whole answer of each call this turn makes, after its links went out and before the model reads it. */
     onResult?: (result: BuyToolResult) => void | Promise<void>;
@@ -355,9 +392,11 @@ export interface BuyToolTurnOptions {
  * belong to this turn alone. `ack`, `links` and `results` are read-only, and JSON leaves them out, so a
  * tool runner that sends the tool to its API sends the same fields as before.
  */
-export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'turn'> {
-    /** The instant reply this turn sent to `onWorking` when it opened, or null when it sent none. */
+export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReaction' | 'turn'> {
+    /** 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. */
+    readonly reaction: string | null;
     /**
      * The messages Agentcard posted into this shopper's chat that the model has not read yet, oldest
      * first, such as `card_added` once they saved a card: each one `agentcard.listen`'s or

package/dist/buy-tool.js

@@ -35,7 +35,7 @@ import { AgentcardApiError, AgentcardClient, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
 import { forModel, forModelError, money, pickId, productCardKey, shownProducts, shownStores, stripLinks } from './model-view.js';
 import { messageStream, paceOf, sleep, toMessages, typingHook } from './messages.js';
-import { ackAt, answersQuestion, instantAck as instantAckOf, isNewRequest, isPickText, namesStore, nextTemplate, slowStepLine, waitAt } from './ack.js';
+import { ACK_REACTION, ackAt, answersQuestion, instantAck as instantAckOf, isNewRequest, isPickText, namesStore, nextTemplate, slowStepLine, waitAt } from './ack.js';
 const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * The model's messages for a turn: the history, what Agentcard told the shopper, then the shopper's
@@ -535,13 +535,31 @@ export function buyTool(options) {
     const who = client.company ? { externalUserId } : {};
     if (o.onWorking !== undefined && typeof o.onWorking !== 'function')
         throw new TypeError('Pass onWorking as a function that sends the shopper a message.');
-    if (o.ack !== undefined && o.ack !== false && typeof o.ack !== 'function')
-        throw new TypeError('Pass ack as false, or as a function that writes the instant reply from the ask.');
+    if (o.onReaction !== undefined && typeof o.onReaction !== 'function')
+        throw new TypeError('Pass onReaction as a function that puts the emoji on the shopper\'s message.');
+    if (o.ack !== undefined && o.ack !== false && o.ack !== 'reaction' && o.ack !== 'text' && o.ack !== 'none' && typeof o.ack !== 'function') {
+        throw new TypeError("Pass ack as 'reaction', 'text' or 'none', as false, or as a function that writes the instant reply from the ask.");
+    }
     const ackDelayMs = o.ackDelayMs ?? ACK_DELAY_MS;
     if (typeof ackDelayMs !== 'number' || !Number.isFinite(ackDelayMs) || ackDelayMs < 0)
         throw new TypeError('Pass ackDelayMs as a number of milliseconds, 0 or more.');
-    const onWorking = o.ack === false ? undefined : o.onWorking;
     const writeAck = typeof o.ack === 'function' ? o.ack : null;
+    /** The mode `ack` names, or null when it names none and the callbacks a turn holds decide. */
+    const ackMode = o.ack === undefined ? null : o.ack === false || o.ack === 'none' ? 'none' : o.ack === 'reaction' ? 'reaction' : 'text';
+    /**
+     * Where a turn acknowledges, from the callbacks it holds: a reaction when it can react and `ack` asks
+     * for no text, else text. At most one of the two comes back, so a shopper never gets a 👀 and a line.
+     */
+    const ackRoutes = (working, reacting) => {
+        if (ackMode === 'none')
+            return { onWorking: undefined, onReaction: undefined };
+        if (ackMode === 'text')
+            return { onWorking: working, onReaction: undefined };
+        if (ackMode === 'reaction' || reacting)
+            return { onWorking: undefined, onReaction: reacting };
+        return { onWorking: working, onReaction: undefined };
+    };
+    const { onWorking, onReaction } = ackRoutes(o.onWorking, o.onReaction);
     /** Calls running now, when the last one ended, and the template the instant reply used last. */
     let running = 0;
     let lastEndedAt = Number.NEGATIVE_INFINITY;
@@ -556,8 +574,10 @@ export function buyTool(options) {
         picked: null,
         ackOut: null,
         ackDelivered: false,
+        reaction: null,
         sendLink,
         onWorking,
+        onReaction,
         onResult,
         onProgress,
         links: null,
@@ -609,25 +629,53 @@ export function buyTool(options) {
         appAck = { at: Date.now(), said: text !== null, picked };
         return text;
     };
+    /** The app's own reaction: the turn its message opens sends no reaction or reply of its own. */
+    const instantReaction = (shopperText) => (instantAck(shopperText) === null ? null : ACK_REACTION);
+    /**
+     * Puts the 👀 on the turn's message. Every call of the turn waits for it before it hands over a link,
+     * and one that throws costs only the reaction: `turn.reaction` goes back to null, and the model reads
+     * that the shopper was not told.
+     */
+    const react = (t, reacting) => {
+        t.acked = true;
+        t.reaction = ACK_REACTION;
+        let sent;
+        try {
+            sent = reacting(ACK_REACTION);
+        }
+        catch (error) {
+            sent = Promise.reject(error);
+        }
+        t.ackOut = Promise.resolve(sent).then(() => { t.ackDelivered = true; }, () => { t.reaction = null; });
+    };
     /**
      * Holds the instant reply for a new request until `ackDelayMs` passes. `cancel` stops one that has
      * not gone out, and frees the turn's reply for a later call.
      */
     const holdAck = (ask, t, step = null) => {
         const onWorking = t.onWorking;
-        if (!onWorking || t.acked)
+        const reacting = t.onReaction;
+        if ((!onWorking && !reacting) || t.acked)
             return null;
         // A confirm, or a pick of what the shopper saw, gets fixed words that never say `looking for`.
         const slow = step ?? t.picked ?? (!t.neutral && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
         // A short answer to the question the last reply asked, such as `medium` after `what size?`, is no
         // search: like `yes`, a slow call still tells the shopper, in words that look for nothing.
         const neutral = t.neutral || answersQuestion(ask, lastReply);
-        if (!slow && !neutral && !isNewRequest(ask))
+        // A slow call of any message may get the 👀, which reads nothing back; only a text reply needs one of these.
+        if (!reacting && !slow && !neutral && !isNewRequest(ask))
             return null;
         t.acked = true;
         let held = true;
         const timer = setTimeout(() => {
             held = false;
+            // With reactions, a slow call puts the message's one 👀 on it, and never adds a line of text.
+            if (reacting) {
+                react(t, reacting);
+                return;
+            }
+            if (!onWorking)
+                return;
             let text;
             if (slow) {
                 text = slowStepLine(slow);
@@ -1149,7 +1197,7 @@ export function buyTool(options) {
         const own = options ?? {};
         if (typeof own !== 'object')
             throw new TypeError('Pass the turn options as an object, or leave them out.');
-        for (const key of ['sendLink', 'onWorking', 'onResult', 'onProgress', 'onItem']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onItem']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -1168,7 +1216,8 @@ export function buyTool(options) {
         const state = {
             ...toolTurn(++modelTurn),
             sendLink: (link) => feed.push({ kind: 'link', link }, () => (onItem ? onItem({ kind: 'link', link: { ...link } }) : baseSendLink?.(link))),
-            onWorking: acks ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
+            // A reaction goes to onReaction even with onItem: it sits on the shopper's bubble, not in the turn's sequence.
+            ...ackRoutes(acks ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined, own.onReaction ?? o.onReaction),
             onResult: own.onResult ?? onResult,
             onProgress: own.onProgress ?? onProgress,
             links: [],
@@ -1178,11 +1227,12 @@ export function buyTool(options) {
         const text = (message, skip) => feed.push({ kind: 'text', text: message }, () => onItem?.({ kind: 'text', text: message }), skip);
         let ack = null;
         const working = state.onWorking;
-        if (working) {
+        const reacting = state.onReaction;
+        if (working || reacting) {
             const message = String(shopperText ?? '');
             const read = ackOfMessage(message);
             let text = read.text;
-            if (text !== null && writeAck) {
+            if (text !== null && writeAck && working) {
                 try {
                     text = writeAck(message) ?? null;
                 }
@@ -1199,7 +1249,11 @@ export function buyTool(options) {
                 // A message that starts no search, such as `yes`: a slow call still tells the shopper, in words that name nothing.
                 state.neutral = true;
             }
-            else if (text !== null) {
+            else if (reacting) {
+                // A search gets its 👀 the moment the turn opens, and no text: the reaction reads nothing back.
+                react(state, reacting);
+            }
+            else if (text !== null && working) {
                 ack = text;
                 state.acked = true;
                 let sent;
@@ -1258,6 +1312,7 @@ export function buyTool(options) {
             agentcardMessages: { get: () => [...(handed ?? kept)], enumerable: false },
             messages: { value: messagesFor, enumerable: false },
             ack: { value: ack, enumerable: false },
+            reaction: { get: () => state.reaction, enumerable: false },
             links: { get: () => [...links], enumerable: false },
             results: { get: () => [...results], enumerable: false },
             items: { get: () => feed.items.map((item) => (item.kind === 'link' ? { kind: 'link', link: { ...item.link } } : { ...item })), enumerable: false },
@@ -1274,5 +1329,5 @@ export function buyTool(options) {
             },
         });
     };
-    return toolOf(answer, { instantAck, turn }, {});
+    return toolOf(answer, { instantAck, instantReaction, turn }, {});
 }

package/dist/definition.js

@@ -11,7 +11,7 @@ export const BUY_TOOL_DESCRIPTION = [
     'Buy what this shopper asks for at real stores.',
     "Put the shopper's own words in `ask`.",
     'Tell the shopper what `reply` says, in your own voice, except the products and stores it lists that reach the shopper as cards.',
-    "When `shopper_already_told_looking` is true, the shopper was already told you are working on their request, so never acknowledge it again: open with the answer or the question.",
+    "When `shopper_already_told_looking` is true, the shopper already knows you are working on their request, from a reply or a 👀 on their message, so never acknowledge it again: open with the answer or the question.",
     'Show the shopper the cart before you confirm it.',
     'Ask the shopper for exactly one thing per message: the step `next_action` names, even when `reply` lists more. Never mention a later step, and never ask for the next one until the shopper has done this one.',
     'When `next_action` is null and `reply` is about something other than a cart, ask for no checkout step: a cart from an earlier request gets one short line at most, after the answer to what the shopper just asked, and never a question about confirming or placing it.',
@@ -32,6 +32,12 @@ export const BUY_TOOL_DESCRIPTION = [
     'Store links reach the shopper on their own, as cards that show each store\'s name and delivery time. When `store_links_sent` is above zero, never list those stores again: ask which one in one short line.',
     'When `store_links_sent` is 0 and you offer the `stores`, name each one by its `name`, never only "their links are there".',
     'When `pick.in_cart` is false, the product the shopper picked is not in the cart: tell the shopper what `reply` says, and never ask them to confirm the cart.',
+    "Talk to the shopper only about their order, in their terms: what is in the cart, what was found and what they can do next. Leave out how it was done, even when `reply` says it: never mention this tool, `reply`, a field, a system, \"my end\" or what you can or can't see, the searches run, the stores checked or not, a timeout, account setup, or a link that did not go out. When parts of the result disagree, say what you are sure of and ask, never which part said what.",
+    'Say as fact only what the result shows: never promise what a store will do later, such as confirm a size when the order goes through.',
+    'Never tell the shopper to remove, delete or replace a card or to change a setting, even when `reply` says to.',
+    'Name each link by what it is for, from `next_action`: the link to add a card, to sign in to the store, or to approve the payment.',
+    'Within a step, ask for one detail per message, such as the delivery address before the name for the label.',
+    'Write every sentence in your own style, casing included, even where `reply` is written another way.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {

package/dist/index.d.ts

@@ -5,8 +5,8 @@ export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, t
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, 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, } 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, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, } from './buy-tool.js';
-export { instantAck, ackFor, type AckForOptions } from './ack.js';
+export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
+export { instantAck, instantReaction, ackFor, ACK_REACTION, type AckForOptions } from './ack.js';
 export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';

package/dist/index.js

@@ -6,7 +6,7 @@ export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_U
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, typingDelay, } from './messages.js';
 export { buyTool, } from './buy-tool.js';
-export { instantAck, ackFor } from './ack.js';
+export { instantAck, instantReaction, ackFor, ACK_REACTION } from './ack.js';
 export { forModel, forModelError, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.js';

package/dist/message.d.ts

@@ -12,12 +12,17 @@ import { type AgentcardEvent } from './verify.js';
  * - `order_unconfirmed`: the store's reply to the order was lost, so the order may exist; Agentcard is confirming it.
  * - `approval_expiring`: the approval link expires soon; `text` carries the link.
  * - `approval_expired`: the approval expired before the shopper answered, and nothing was charged.
+ * - `approval_declined`: the shopper declined the approval, and nothing was charged.
+ * - `payment_declined`: the shopper approved, and the payment was refused before the order went in; `facts.reason` says why. Nothing was charged.
  * - `card_link_unfinished`: the shopper has not added a card from their card link; `text` carries the link again.
  * - `card_link_expired`: the card link expired before the shopper added a card.
  * - `cart_idle`: a cart sat without being sent for approval; `facts.nudgeNumber` counts the nudges.
  * - `card_added`: the shopper saved a card from the card link your app sent, and can check out with it.
+ * - `store_connected`: the shopper signed in to their own account at the store from the sign-in link your app sent, 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.
+ * - `store_connect_expired`: the sign-in link expired before the shopper finished signing in.
  */
-export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added';
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'approval_declined' | 'payment_declined' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added' | 'store_connected' | 'store_connect_failed' | 'store_connect_expired';
 /** The message's values one by one, for a company that writes its own copy. A fact that does not apply is absent. */
 export interface PurchaseFacts {
     merchantName?: string;
@@ -28,7 +33,7 @@ export interface PurchaseFacts {
     cardBrand?: string;
     cardLast4?: string;
     orderId?: string;
-    /** Why an order failed or was not placed, in words. */
+    /** Why an order failed or was not placed, or a payment was declined, in words. */
     reason?: string;
     approvalUrl?: string;
     /** When the approval link stops working, as an ISO 8601 timestamp. */

package/dist/model-view.d.ts

@@ -66,6 +66,12 @@ export interface BuyToolModelView {
     shopper_already_told_looking: boolean;
     /** True when the shopper already has the link this answer needed. */
     link_sent: boolean;
+    /**
+     * Which links went out with this answer: `store_login` is the store's own login page (the shopper
+     * logs in to their account there), `vault` is the page where they add a card, `approval` the page
+     * where they approve the payment. Name the link by what it is: a store login is never a card link.
+     */
+    links_sent: Array<'vault' | 'approval' | 'store_login'>;
     /** How many of the products above the shopper holds as cards, each with its name, price and picture; 0 when none went out. */
     product_links_sent: number;
     /** The product this call's `product_id` picked, and whether the cart now holds it; null when the call picked none. */

package/dist/model-view.js

@@ -4,8 +4,14 @@ const MAX_PRODUCTS = 20;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const SCHEME_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`)\]]*/gi;
 const WWW_URL = /\bwww\.[^\s<>"'`)\]]*/gi;
-/** A host followed by a path, a query or a fragment: `vault.agentcard.sh/a/1`, `vault.agentcard.sh?token=abc`. */
-const HOST_PATH = /\b(?:[a-z0-9-]+\.)+[a-z]{2,}[/?#][^\s<>"'`)\]]*/gi;
+/**
+ * A host followed by a path, a query or a fragment: `vault.agentcard.sh/a/1`, `vault.agentcard.sh?token=abc`. A `?` that
+ * only punctuation follows before a space, a closing bracket or quote, or the end starts no query: in "at glossier.com?
+ * Say yes" it is the question's mark, and the host reads as its site's name (BARE_HOST). A `?` that more of an address
+ * follows starts one, punctuation or not (`glossier.com?.ref=x`), and a `#` always starts a fragment
+ * (`glossier.com#:~:text=Balm`).
+ */
+const HOST_PATH = /\b(?:[a-z0-9-]+\.)+[a-z]{2,}(?:[/#]|\?(?![.,;:!?]*(?:[\s<>"'`)\]]|$)))[^\s<>"'`)\]]*/gi;
 /**
  * A bare host on a common top-level domain, such as `agentcard.sh` or `amazon.com`, which a chat app
  * turns into a link. The list keeps words with a dot, such as `Node.js`, and an email address's host.
@@ -163,6 +169,9 @@ export function forModel(result) {
         shopper_need_not_reply: result.shopper_need_not_reply === true,
         shopper_already_told_looking: result.shopper_already_told_looking === true,
         link_sent: result.link_sent === true,
+        links_sent: result.link_sent === true
+            ? [...new Set((result.links ?? []).map((link) => link.kind).filter((kind) => kind === 'vault' || kind === 'approval' || kind === 'store_login'))]
+            : [],
         // A card per product, so two dishes on a restaurant's one page are two cards.
         product_links_sent: new Set(products.filter(held).map(productCardKey)).size,
         // The id the model sent, never the catalog id, which is a store page for a retail product.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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.",
   "type": "module",
   "main": "dist/index.js",