@agent-cards/commerce-sdk 0.9.0 → 0.11.0

package/dist/buy-tool.d.ts

@@ -21,10 +21,21 @@
  * still finishing gets one 12-second pause and one read of the conversation.
  * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
  * to a minute, until the turn ends.
+ *
+ * `turn` binds the tool to one shopper message: the calls the model makes
+ * through it hand their links, answers and instant reply to that turn's own
+ * callbacks and lists, so a shopper who sends a second message before the
+ * first is answered never gets one message's cards beside the other's reply.
+ * Every turn of one tool still shares the shopper's conversation state, such
+ * as the store pages already sent. A turn with `onItem` hands the app its
+ * messages and links as one sequence, in the order they happened, and spaces
+ * the messages like someone texting.
  */
 import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type BuyToolModelView } from './model-view.js';
+import { type MessagePace, type MessageStream } from './messages.js';
+import type { ShopperMessage } from './shopper-message.js';
 /**
  * Where the purchase stands:
  * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
@@ -41,12 +52,17 @@ export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'pl
  * the page where they sign in to the store named in `store`, before Agentcard
  * can buy there. `product`: a product's page at its store, with its `title`,
  * `price`, `productId` and `imageUrl`. The page is `url`; `productId` holds no link.
+ * A flight option is a `product` link too, with a null `url`, since a flight has no page.
  * `store`: a store's page at the merchant, for a store the shopper can pick, with
- * its name in `title`, `storeId` and `etaMinutes`.
+ * its name in `title`, `storeId`, `etaMinutes` and `imageUrl`.
  */
 export interface BuyToolLink {
     kind: 'vault' | 'approval' | 'store_login' | 'product' | 'store';
-    url: string;
+    /**
+     * The page the link opens. Null only on a product link for a product with no page at a store, a
+     * flight option: show its card with no link to open, and let `productId` pick it.
+     */
+    url: string | null;
     /** When the link stops working, as an ISO 8601 timestamp, or null when Agentcard did not say. Always null on a product link. */
     expiresAt: string | null;
     /** On a store login link: the store's name, or null when Agentcard named none. */
@@ -61,7 +77,10 @@ export interface BuyToolLink {
      * can hand it back as the shopper's pick. Absent when Agentcard sent no such id, as an older API does.
      */
     productId?: string;
-    /** On a product link: the product's picture, or null when Agentcard sent none. Show it beside the title. */
+    /**
+     * On a product link: the product's picture. On a store link: the picture the store's card shows at
+     * the merchant. Null when Agentcard sent none. Show it beside the title.
+     */
     imageUrl?: string | null;
     /**
      * On a store link: Agentcard's id for the store, with no link in it. It is the `store_id` the model
@@ -81,6 +100,8 @@ export interface BuyToolStore {
     url: string | null;
     /** The delivery estimate in minutes, or null when the store showed none. */
     etaMinutes: number | null;
+    /** The picture the store's card shows at the merchant, or null when Agentcard sent none. */
+    imageUrl: string | null;
     /** True when the shopper holds this store's page: `sendLink` took it in this call or an earlier call of the same model turn. */
     linkSent: boolean;
 }
@@ -131,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;
@@ -152,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;
@@ -164,7 +194,9 @@ export interface BuyToolOptions {
      * holds the link before the model answers. A `sendLink` that throws on a
      * Vault or approval link makes the call throw too, and the model never
      * reads that a link went out. One that throws on a product link leaves
-     * that product's `linkSent` false, and the call goes on.
+     * that product's `linkSent` false, and the call goes on. It hears the links of every call, whatever
+     * shopper message the call answers: a chat app where a shopper can send a second message before the
+     * first is answered passes `sendLink` to `buy.turn` instead, so each link reaches the turn it belongs to.
      */
     sendLink?: (link: BuyToolLink) => void | Promise<void>;
     /** Where the orders go, when you already hold the shopper's address. The model never sets it. */
@@ -175,23 +207,43 @@ 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
-     * `ackDelayMs`, once for the calls the model makes in one turn, and never on a confirm, a pick or a
-     * reply such as `yes`, `2` or a code. The call waits for it before it returns, so the shopper reads
-     * it before any link or the model's answer. One that throws costs nothing but the instant reply.
+     * 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.
+     * The call waits for it before it returns, so the shopper reads it before any link or the model's
+     * 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
      * it, so your app can show the carts, the status, `next_action` or the order id without wrapping the
      * tool. A refusal the tool turns into an answer, such as a Vault link for a shopper with no card,
-     * counts; a call that throws calls nothing. One that throws costs nothing but the call to it.
+     * counts; a call that throws calls nothing. One that throws costs nothing but the call to it. Like
+     * `sendLink`, it hears every call; pass it to `buy.turn` to hear only the answers of one turn.
      */
     onResult?: (result: BuyToolResult) => void | Promise<void>;
     /**
@@ -258,14 +310,148 @@ export interface BuyTool {
      * The instant reply for a shopper's message, such as `on it, looking for usb-c cables under $20`, or
      * null for a message that starts no search: `yes`, `1`, `ok`, a code, `hi`, or the shopper's own
      * details, such as a name, a phone number or an address, and any message that answers a request for
-     * shipping or guest details or a code, and a pick of a product the shopper saw. Call it the moment the
+     * shipping or guest details or a code, and a pick of a product or a store the shopper saw, such as
+     * `Order from Tacos El Grullense` as a store card sends it. Call it the moment the
      * message arrives, before your model runs, and send the text it returns. 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`, so the shopper never hears it twice. When it returns null for a
      * 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
+     * turn's `sendLink` and keeps them in `turn.links`, hands its answer to this turn's `onResult` and
+     * 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
+     * `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;
 }
+/**
+ * One thing a turn hands the shopper: a message, such as the instant reply or a paragraph your model
+ * wrote, or a link, such as a product card. `buy.turn`'s `onItem` hears them in the order they happened.
+ */
+export type BuyToolTurnItem = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'link';
+    link: BuyToolLink;
+};
+/** The callbacks of one turn. Each one left out falls back to the option of the same name the tool was built with, except with `onItem`. */
+export interface BuyToolTurnOptions {
+    /**
+     * Hears everything the turn hands the shopper, one item at a time and in the order it happened: the
+     * instant reply and each message your model writes through `turn.messageStream()` or `turn.say()` as
+     * `text` items, and each link as a `link` item. Show each item below the one before it, and the chat
+     * reads in the order it happened: a search's cards, then the model's words about them. Each item
+     * waits for the one before it to settle. With `onItem`, the turn hands no link to a `sendLink` and
+     * no instant reply to an `onWorking`, the tool's included: pass `onItem`, or those, to the turn.
+     */
+    onItem?: (item: BuyToolTurnItem) => void | Promise<void>;
+    /**
+     * With `onItem`: spaces the turn's messages like someone texting. A message waits until
+     * `typingDelay` of it has passed since the item before it went out, so the shopper reads one message
+     * at a time. Time the model spent writing counts toward the pause. Links never wait. Default `true`;
+     * `false` hands each message over the moment it is ready, and a function returns the pause in
+     * milliseconds for a message.
+     */
+    pace?: MessagePace;
+    /** With `onItem`: hears `true` when the pause before a message starts and `false` the moment that message goes out, for a typing indicator. */
+    onTyping?: (typing: boolean) => void;
+    /**
+     * Delivers a link of this turn to the shopper, as the tool's `sendLink` does. Each call waits for it.
+     * Without one, `turn.links` still takes each link, and the model reads that it went out, so return
+     * `turn.links` beside the turn's reply.
+     */
+    sendLink?: (link: BuyToolLink) => void | Promise<void>;
+    /** 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>;
+    /** Called with each stage Agentcard reaches on a call this turn makes. */
+    onProgress?: (progress: BuyProgress) => void;
+}
+/**
+ * The buy tool for one shopper message, from `buy.turn`. It is the same tool, with the same name,
+ * schema and methods, so a framework takes it as it takes the tool, and the calls made through it
+ * 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' | '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
+     * `agentcardWebhook`'s `onMessage` returned from, on the client this tool was built with. Once
+     * `messages` ran, the ones it handed the model.
+     */
+    readonly agentcardMessages: ShopperMessage[];
+    /**
+     * What to send your model for this turn: `history`, then what Agentcard told the shopper that the
+     * history does not hold yet, as the assistant's words with every link taken out, then the shopper's
+     * message as a user message. Pass it as the model's `messages` and save what the model's run ends
+     * with as the next history, so the model reads that the shopper saved a card, approved or got an
+     * order before it answers them. A message the history already holds goes in no second time, and one
+     * a failed turn never saved goes in again. The Anthropic, OpenAI and Vercel AI SDK message lists all
+     * take it. Agentcard's words join the history's last assistant message when it is plain text, and
+     * come as an assistant message of their own otherwise. `history` is never changed.
+     */
+    messages<M extends object = BuyToolTurnMessage>(history?: readonly M[] | null): Array<M | BuyToolTurnMessage>;
+    /**
+     * Every link this 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. A link `sendLink` threw on is left out. Each read returns a new array.
+     */
+    readonly links: BuyToolLink[];
+    /** The whole answer of each call this turn made, in the order the calls returned. Each read returns a new array. */
+    readonly results: BuyToolResult[];
+    /**
+     * Every message and link the turn handed over, in the order they went out: the instant reply, each
+     * link, and each message written through `messageStream()` or `say()`. An item its send threw on is
+     * left out. Return it as the turn's answer, and an app renders it in order. Each read returns a new array.
+     */
+    readonly items: BuyToolTurnItem[];
+    /**
+     * A message stream whose messages become this turn's `text` items, after the items before them, as
+     * `messageStream` cuts them: push your model's text as it streams, then `end` it. Start one for each
+     * model message. With `onItem`, the turn spaces them by its `pace`.
+     */
+    messageStream(): MessageStream;
+    /** Cuts a whole text into messages, as `toMessages` does, and hands each one over as a `text` item. Resolves once every one went out. */
+    say(text: string): Promise<void>;
+}
+/** A message in the one shape the Anthropic, OpenAI and Vercel AI SDK message lists all take. */
+export type BuyToolTurnMessage = {
+    role: 'assistant';
+    content: string;
+} | {
+    role: 'user';
+    content: string;
+};
+/**
+ * The model's messages for a turn: the history, what Agentcard told the shopper, then the shopper's
+ * words. Agentcard's words join a last assistant message of plain text, a string or text parts only,
+ * so no provider reads two assistant messages in a row. After anything else, such as a tool result
+ * or an OpenAI Responses item, they come as an assistant message of their own.
+ */
+export declare function turnMessages<M extends object>(history: readonly M[] | null | undefined, told: readonly string[], shopperText: string): Array<M | BuyToolTurnMessage>;
 /** Shared with the merchant monitor so link eligibility uses the tool's product mapping. */
 export declare function productsOf(turn: BuyTurn): BuyToolProduct[];
 /**