@agent-cards/commerce-sdk 0.11.0 → 0.13.0

package/dist/browser.js

@@ -0,0 +1,118 @@
+/**
+ * `@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 { actionLinkId, actionLinkOutcome, isActionLink } from './action-links.js';
+export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';
+const DEFAULT_WIDTH = 480;
+const DEFAULT_HEIGHT = 760;
+const DEFAULT_POLL_MS = 500;
+/** `width=…,height=…,left=…,top=…` for a pop-up centered over the opener, kept on its screen. */
+function featuresFor(win, width, height) {
+    const availWidth = win.screen?.availWidth ?? width;
+    const availHeight = win.screen?.availHeight ?? height;
+    const w = Math.max(320, Math.min(width, availWidth));
+    const h = Math.max(400, Math.min(height, availHeight));
+    const left = Math.max(0, Math.round((win.screenX ?? 0) + ((win.outerWidth ?? w) - w) / 2));
+    const top = Math.max(0, Math.round((win.screenY ?? 0) + ((win.outerHeight ?? h) - h) / 2));
+    return `popup=yes,width=${w},height=${h},left=${left},top=${top}`;
+}
+const view = (t) => t.step;
+/**
+ * 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 function actionWindows(options = {}) {
+    const open = new Map();
+    let timer = null;
+    const win = () => options.window ?? (globalThis.window ?? null);
+    const stopIfIdle = () => {
+        if (open.size === 0 && timer !== null) {
+            win()?.clearInterval(timer);
+            timer = null;
+        }
+    };
+    const poll = () => {
+        for (const [id, tracked] of open) {
+            if (!tracked.popup.closed)
+                continue;
+            open.delete(id);
+            tracked.step.open = false;
+            options.onClosed?.(view(tracked));
+        }
+        stopIfIdle();
+    };
+    const idOf = (link) => link.id ?? actionLinkId(link);
+    return {
+        open(link) {
+            if (!isActionLink(link))
+                return null;
+            const w = win();
+            if (!w)
+                return null;
+            const id = idOf(link);
+            const known = open.get(id);
+            if (known && !known.popup.closed) {
+                known.popup.focus();
+                return view(known);
+            }
+            let popup = null;
+            try {
+                // A window named for the step: tapping the link again reaches the same window, never a second one.
+                popup = w.open(link.url, `agentcard_${id}`, featuresFor(w, options.width ?? DEFAULT_WIDTH, options.height ?? DEFAULT_HEIGHT));
+            }
+            catch {
+                popup = null;
+            }
+            if (!popup)
+                return null;
+            const tracked = { step: { id, kind: link.kind, url: link.url, store: link.store ?? null, open: true }, popup };
+            open.set(id, tracked);
+            try {
+                popup.focus();
+            }
+            catch {
+                /* a browser that refuses focus still shows the window */
+            }
+            timer ??= w.setInterval(poll, options.pollMs ?? DEFAULT_POLL_MS);
+            return view(tracked);
+        },
+        settle(message) {
+            const ended = [];
+            for (const [id, tracked] of open) {
+                const outcome = actionLinkOutcome(tracked.step, message);
+                if (!outcome)
+                    continue;
+                open.delete(id);
+                tracked.step.open = false;
+                try {
+                    tracked.popup.close();
+                }
+                catch {
+                    /* already gone */
+                }
+                ended.push({ step: view(tracked), outcome });
+            }
+            stopIfIdle();
+            for (const { step, outcome } of ended)
+                options.onEnded?.(step, outcome);
+            return ended;
+        },
+        get(link) {
+            if (!isActionLink(link))
+                return null;
+            const tracked = open.get(idOf(link));
+            return tracked && !tracked.popup.closed ? view(tracked) : null;
+        },
+        dispose() {
+            open.clear();
+            stopIfIdle();
+        },
+    };
+}

package/dist/buy-tool.d.ts

@@ -31,11 +31,11 @@
  * 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 { AgentcardClient, type BuyCart, type BuyCartBuilding, 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';
+import { type ShopperMessage } from './shopper-message.js';
 /**
  * Where the purchase stands:
  * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
@@ -51,13 +51,21 @@ export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'pl
  * card. `approval`: the page where they approve this purchase. `store_login`:
  * 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.
+ * `price`, `productId`, `imageUrl` and `images`. 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`, `etaMinutes` and `imageUrl`.
  */
 export interface BuyToolLink {
     kind: 'vault' | 'approval' | 'store_login' | 'product' | 'store';
+    /**
+     * On a `vault`, `approval` or `store_login` link, a step the shopper takes outside the chat: a stable
+     * id for the link (`actionLinkId`), the same each time the same link is handed over, with no part of
+     * the URL in it. `actionLinkOutcome(link, message)` says whether a shopper message ended the step,
+     * and `actionWindows` from `@agent-cards/commerce-sdk/browser` opens it in a pop-up that closes then.
+     * Absent on product and store links.
+     */
+    id?: 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.
@@ -65,11 +73,19 @@ export interface BuyToolLink {
     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. */
+    /**
+     * On a store login link: the store's name, or null when Agentcard named none. On an approval link:
+     * the store whose cart it approves, when the answer names the cart.
+     */
     store?: string | null;
     /** On a product link: the product's name. */
     title?: string;
-    /** On a product link: the price as the shopper reads it, such as `$12.99`, or null when Agentcard named none. */
+    /**
+     * On a product link: what taking the product does, so a button can say it. `reserve` is a table the
+     * shopper reserves, `book` a flight, room, class or ticket they book, and `buy` anything they buy.
+     */
+    action?: BuyToolProductAction;
+    /** On a product link: the price as the shopper reads it, such as `$12.99`, or `from $10.69` for a product priced by a size or another required choice, or null when Agentcard named none. */
     price?: string | null;
     /**
      * On a product link: Agentcard's id for the product, with no link in it. It is the `product_id` the
@@ -82,6 +98,11 @@ export interface BuyToolLink {
      * the merchant. Null when Agentcard sent none. Show it beside the title.
      */
     imageUrl?: string | null;
+    /**
+     * On a product link: every photo of the product, `imageUrl` first, at most eight; one entry for a product
+     * with one photo and none for a product with none. Show the others as thumbnails that swap the main picture.
+     */
+    images?: string[];
     /**
      * On a store link: Agentcard's id for the store, with no link in it. It is the `store_id` the model
      * reads for the same store, and the tool takes it as `store_id`, so a "Order here" button can hand it
@@ -106,17 +127,27 @@ export interface BuyToolStore {
     linkSent: boolean;
 }
 /** A product the last search found. */
+/** What taking a product does: `reserve` a table, `book` a flight, room, class or ticket, `buy` anything else. */
+export type BuyToolProductAction = 'buy' | 'reserve' | 'book';
+/** The action a product of `merchant` takes (BuyToolProductAction). */
+export declare function productAction(merchant: string | null | undefined): BuyToolProductAction;
 export interface BuyToolProduct {
     flight?: BuyFlightItinerary;
+    /** What taking it does: `reserve` a table, `book` a flight, room, class or ticket, `buy` anything else. */
+    action: BuyToolProductAction;
     id: string;
     /** Agentcard's link-free id for the product, which the model passes as `product_id` when the shopper picks it; null from an older API. */
     ref: string | null;
     name: string;
     /** The price in the minor unit of `currency`. */
     priceCents: number | null;
+    /** True when `priceCents` is the lowest price of a product priced by a required choice, which reads `from $10.69`. */
+    priceFrom?: true;
     /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
     currency: string | null;
     imageUrl: string | null;
+    /** Every photo of the product, `imageUrl` first, at most eight; empty when it has none. */
+    images: string[];
     store: string | null;
     /** The product's page at its store, or null when Agentcard sent none. */
     url: string | null;
@@ -165,12 +196,17 @@ export interface BuyToolResult {
     next_action: BuyNextAction | null;
     /** The product the model's `product_id` picked, by its catalog id, and whether the cart now holds it; null when the call picked none. */
     pick: BuyPick | null;
-    /** The stores the reply presents to choose from, at most three, in the order the reply names them; empty when it presents none. */
+    /** The stores the reply presents to choose from, at most eight, in the order the reply names them; empty when it presents none. */
     stores: BuyToolStore[];
     /** The store the model's `store_id` picked, or the shopper's `the second one` did, and whether Agentcard selected it; null when none was picked. */
     store_pick: BuyStorePick | null;
     /** Every cart hash in this answer. */
     hashes: string[];
+    /**
+     * The cart the store's checkout is still building after this answer, or null: its cart and total reach the shopper as a
+     * message from Agentcard, and only the shopper's yes to that total confirms it.
+     */
+    cart_building?: BuyCartBuilding | null;
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
     envelope: Record<string, unknown>;
 }
@@ -265,6 +301,13 @@ export interface BuyToolOptions {
      * outside the first three.
      */
     earlyCards?: boolean;
+    /**
+     * `true` sets `turn.replyAsWritten` on every turn this tool opens, unless the turn says otherwise:
+     * Agentcard's reply, when an answer only asks the shopper something (`replyAsWritten`). Show it as
+     * the turn's answer and skip the model call that would reword it. Off by default, so your model
+     * writes every answer.
+     */
+    replyAsWritten?: boolean;
 }
 /**
  * The buy tool, in the shape every agent framework takes, because their field
@@ -338,6 +381,26 @@ export interface BuyTool {
      * built with.
      */
     turn(shopperText: string, options?: BuyToolTurnOptions): BuyToolTurn;
+    /**
+     * Opens the turn your agent takes on its own once the shopper finished a step outside the chat, such
+     * as saving a card or signing in to the store: a message whose `advances` is true. Pass it to your
+     * model as you pass `buy.turn`, with `turn.messages(history)` as the messages, and the model's answer
+     * is the shopper's next message, the step after the one they took, so they never have to say "ok"
+     * or "done" first. Post that answer in place of `message.text`, which the shopper then never reads.
+     *
+     * The turn moves the purchase only up to the shopper's own decision. Its calls never reach Agentcard
+     * with an ask, so nothing in it can place an order, confirm a cart or charge a card for the shopper.
+     * Each call reads where the purchase stands and answers with the next step: the card link, or the
+     * cart and the ask for the shopper's yes. The one exception is the yes the shopper already gave in the
+     * chat for this exact cart, when that confirm stopped for the step they just finished: it goes in for
+     * that cart's hash alone, and Agentcard refuses it if the cart changed.
+     *
+     * Returns null when there is no next step to take: a message whose `advances` is false, a message
+     * for another shopper or one whose link closed, a message this tool already took a turn for, and a
+     * message 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, as before.
+     */
+    nextStep(message: ShopperMessage, options?: BuyToolTurnOptions): BuyToolTurn | null;
 }
 /**
  * One thing a turn hands the shopper: a message, such as the instant reply or a paragraph your model
@@ -356,21 +419,34 @@ 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
+     * reads in the order it happened: a search's cards, then the model's words about them. A step link
+     * (`vault`, `approval`, `store_login`) is the one exception: it waits for the message that asks for
+     * it, and goes out right after that message, so the shopper reads the ask, then taps. 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.
+     * With `onItem` or `onMessage`: how the turn's messages are spaced. Default `false`: each message goes
+     * out the moment it is ready. `true` spaces them like someone texting: a message waits until
+     * `typingDelay` of it has passed since the item before it went out, and time the model spent writing
+     * counts toward the pause. A function returns the pause in milliseconds for a message. Links never wait.
      */
     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. */
+    /**
+     * `true` sets `turn.replyAsWritten` when an answer only asks the shopper something; `false` leaves it
+     * null, so your model rewords every answer. Default: the tool's `replyAsWritten`.
+     */
+    replyAsWritten?: boolean;
+    /** With `onItem` or `onMessage`: 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;
+    /**
+     * Without `onItem`: hears each message your model writes through `turn.messageStream()` or
+     * `turn.say()`, paced by `pace`, in the same order as the links `sendLink` hears. Write the model's
+     * text through the turn, and a step link (`vault`, `approval`, `store_login`) reaches `sendLink`
+     * after the message that asks for it, never before.
+     */
+    onMessage?: (message: string) => void | Promise<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
@@ -392,7 +468,15 @@ 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' | 'instantReaction' | 'turn'> {
+export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReaction' | 'turn' | 'nextStep'> {
+    /** For a turn `buy.nextStep` opened, the message whose step the shopper finished; null for a turn of a shopper message. */
+    readonly event: ShopperMessage | null;
+    /**
+     * For a turn `buy.nextStep` opened that your agent could not finish: call it before you post `message.text` instead.
+     * The message's text then reaches later turns as words the shopper read (`agentcard.delivered`), and a later
+     * `buy.nextStep` for the same event opens a turn again, as on a webhook's redelivery. Does nothing on another turn.
+     */
+    release(): void;
     /** 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. */
@@ -422,6 +506,15 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
     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[];
+    /**
+     * With `replyAsWritten` on: Agentcard's reply when the turn's last answer only asks the shopper
+     * something, such as a product list, a size or a cart's total and the ask for their yes, with every
+     * link taken out. Read it after the tool runs. When it is set, show it with `say()` and end the turn
+     * without calling your model again: the reply already says what the model would. Null when the option
+     * is off, before any call, after an answer your model has to word, and after a line the tool wrote
+     * itself for your model, such as the note that the cart changed or a `nextStep` turn's ask for the yes.
+     */
+    readonly replyAsWritten: string | null;
     /**
      * 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
@@ -431,10 +524,14 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
     /**
      * 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`.
+     * model message. With `onItem`, the turn spaces them by its `pace`. `end` resolves once the messages and the step links
+     * held for them went out, and rejects with the first that failed to send.
      */
     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. */
+    /**
+     * Cuts a whole text into messages, as `toMessages` does, and hands each one over as a `text` item. Resolves once every
+     * one, and every step link held for it, went out, and rejects with the first that failed to send.
+     */
     say(text: string): Promise<void>;
 }
 /** A message in the one shape the Anthropic, OpenAI and Vercel AI SDK message lists all take. */
@@ -452,6 +549,12 @@ export type BuyToolTurnMessage = {
  * 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>;
+/**
+ * The words a `nextStep` turn hands the model as the user's message: the event, marked as no one's
+ * typing, and the instruction to take the next step now in one short message, without the filler of
+ * a step announced and a question about what comes next.
+ */
+export declare function nextStepPrompt(message: ShopperMessage): string;
 /** Shared with the merchant monitor so link eligibility uses the tool's product mapping. */
 export declare function productsOf(turn: BuyTurn): BuyToolProduct[];
 /**