@agent-cards/commerce-sdk 0.0.0-stage → 0.2.0

package/dist/buy-tool.js

@@ -0,0 +1,619 @@
+/**
+ * The buy tool: one call that buys for one shopper, in one object that every
+ * agent framework takes. `answer` sends the model's input to Agentcard and
+ * returns the whole answer for your code, with the status, Agentcard's
+ * reply, the cart and its hash, the products and the links. `forModel` turns
+ * that answer into what the model may read, with every link taken out, and
+ * `run`, `execute` and `handle` return that view as JSON text. A link
+ * reaches the shopper through `sendLink`, and each call waits for it before
+ * it returns: the Vault and approval links, then the store page of each
+ * product the model reads.
+ *
+ * Agentcard keeps the conversation: every call continues the shopper's open
+ * purchase (`resume: true`), and a confirm places the cart Agentcard last
+ * showed (`confirm: true`). The tool keeps one thing between calls: the store
+ * pages it sent last. Agentcard repeats the last search in each answer for a
+ * while, so a list it shows again in the same conversation does not reach
+ * the shopper twice. A tool built for each message buys the same way, and
+ * sends such a list again.
+ *
+ * Two answers make the tool wait before it returns. A placement Agentcard is
+ * 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.
+ */
+import { AgentcardApiError, AgentcardClient, } from './client.js';
+import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
+import { forModel, forModelError, money, shownProducts } from './model-view.js';
+import { toMessages } from './messages.js';
+/** The pause before the one read that follows a placement Agentcard is still finishing. */
+const PLACEMENT_WAIT_MS = 12_000;
+/** After a turn that outlived Agentcard's budget: one read every 5 seconds, for at most a minute. */
+const TURN_READ_EVERY_MS = 5_000;
+const TURN_READS = 12;
+/**
+ * How long before an `in_progress` checkout the order it waits on may have been placed: the
+ * approval's own resume can place the order a moment before a second attempt records that the
+ * placement is still running.
+ */
+const RESUME_SKEW_MS = 2 * 60_000;
+/** Ledger states of an order that stopped after it was placed: its payment never confirmed, or the store cancelled it. */
+const STOPPED_ORDER = new Set(['failed', 'cancelled']);
+/** The refusals a confirm gets once the order took the cart, or while the placement still runs. */
+const AFTER_PLACEMENT = new Set(['nothing_to_confirm', 'conversation_closed', 'turn_in_progress']);
+const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
+const CARD_NEEDED = 'The shopper adds a card from a Vault link before Agentcard can buy for them.';
+const STILL_PLACING = 'The shopper approved, and the order is still going through.';
+const NOT_PLACED = 'The order did not go through.';
+const CART_READY = 'The cart is ready. Show the shopper the cart before you confirm it.';
+const CHOOSE_CART = 'The shopper has carts at more than one store. Ask the shopper which cart they want, and send their answer in ask before you confirm.';
+const APPROVAL_WAITING = 'The purchase waits for the shopper to approve it from the approval link.';
+const ANSWER_LATE = "Agentcard's answer took too long to come back. Call this tool again with the shopper's last words.";
+const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shopper the cart as it stands now.';
+const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper what they want.';
+const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
+function hashesOf(cart, carts) {
+    return [...new Set([cart?.hash, ...carts.map((c) => c.hash)].filter((h) => typeof h === 'string' && h !== ''))];
+}
+function productsOf(turn) {
+    return (turn.catalog?.items ?? [])
+        .filter((item) => item.name)
+        .map((item) => ({
+        id: item.id,
+        name: item.name,
+        priceCents: item.priceCents,
+        currency: item.currency,
+        imageUrl: item.image_url,
+        ...(item.flight ? { flight: item.flight } : {}),
+        store: item.store?.name ?? item.store?.id ?? turn.catalog?.merchant_name ?? null,
+        url: item.url ?? null,
+        linkSent: false,
+    }));
+}
+/** The store login link an answer carries, read from its own fields: a link in `reply` is never pulled out. */
+function storeLoginOf(turn) {
+    if (!turn.store_login_url)
+        return [];
+    return [{ kind: 'store_login', url: turn.store_login_url, expiresAt: turn.store_login_expires_at, store: turn.store_login_merchant_name }];
+}
+/** The answer before its status is read: every field the purchase answer carries. */
+function answerOf(turn) {
+    return {
+        status: 'needs_input',
+        reply: turn.reply,
+        messages: [],
+        cart: turn.cart,
+        carts: turn.carts,
+        products: productsOf(turn),
+        links: storeLoginOf(turn),
+        link_sent: false,
+        approval_expires_at: turn.approval_expires_at,
+        shopper_need_not_reply: false,
+        conversation_id: turn.conversation_id || null,
+        order_id: turn.order_id,
+        decline_code: turn.decline_code,
+        error_code: turn.error_code,
+        next_action: turn.next_action,
+        hashes: hashesOf(turn.cart, turn.carts),
+        envelope: turn.raw,
+    };
+}
+/**
+ * The answer that waits on the shopper's card, when the turn carries Agentcard's add-card link: a
+ * checkout refused on an empty vault (`vault_unavailable`), or the agent made the link while it
+ * asked. The status beside it does not decide: the link is the one way forward either way, and the
+ * reply has every link taken out. Null when the turn carries no link, or placed an order.
+ */
+function needsCardOf(turn, answer) {
+    // Agentcard named another step first: the card waits until that one is done.
+    if (turn.next_action && turn.next_action !== 'add_card')
+        return null;
+    if (!turn.add_card_url || turn.status === 'order_placed' || turn.status === 'partially_placed' || turn.status === 'needs_approval')
+        return null;
+    const refused = turn.status === 'declined';
+    // A refusal with another code is about something other than a card, and keeps its own status.
+    if (refused && turn.decline_code !== 'vault_unavailable')
+        return null;
+    if (!refused && turn.decline_code && turn.decline_code !== 'vault_unavailable')
+        return null;
+    return { ...answer, status: 'needs_card', links: [...answer.links, { kind: 'vault', url: turn.add_card_url, expiresAt: turn.add_card_expires_at }] };
+}
+/**
+ * The answer with only the link of the step the shopper takes now, when Agentcard names one
+ * (`next_action`): the Vault link waits for `add_card`, the approval link for `approve`. A store login
+ * link and product pages are not steps, so they stay. An answer that names no step keeps every link.
+ */
+function onlyNextStepLinks(result, next) {
+    if (!next)
+        return result;
+    const links = result.links.filter((link) => (link.kind === 'vault' ? next === 'add_card' : link.kind === 'approval' ? next === 'approve' : true));
+    return links.length === result.links.length ? result : { ...result, links };
+}
+/**
+ * The answer's `messages`, read once its `reply` is final: the messages Agentcard sent while the reply
+ * is still Agentcard's own, else the reply the tool wrote, each cut at its blank lines.
+ */
+function withMessages(result, turn) {
+    const sent = turn && result.reply === turn.reply && turn.messages.length > 0 ? turn.messages : [result.reply];
+    return { ...result, messages: sent.flatMap(toMessages) };
+}
+/** A purchase answer, read for its status. A status Agentcard adds later reads as `needs_input`. */
+function resultOfTurn(turn) {
+    return onlyNextStepLinks(resultOfStatus(turn), turn.next_action);
+}
+/** A purchase answer, read for its status, with every link the answer carries. */
+function resultOfStatus(turn) {
+    const answer = answerOf(turn);
+    const card = needsCardOf(turn, answer);
+    if (card)
+        return card;
+    switch (turn.status) {
+        case 'order_placed':
+        case 'partially_placed':
+            return { ...answer, status: 'order_placed' };
+        case 'needs_approval':
+            return { ...answer, status: 'approval_sent' };
+        case 'declined':
+            if (turn.decline_code === 'vault_approval_required') {
+                // The shopper already opened the approval and checkout is placing: a second link would ask for a second approval.
+                if (turn.approval_in_progress === true) {
+                    return { ...answer, status: 'placing', reply: turn.reply || STILL_PLACING, shopper_need_not_reply: turn.placement_announced === true };
+                }
+                return {
+                    ...answer,
+                    status: 'approval_sent',
+                    links: [...answer.links, ...(turn.approval_url ? [{ kind: 'approval', url: turn.approval_url, expiresAt: turn.approval_expires_at }] : [])],
+                    shopper_need_not_reply: turn.placement_announced === true,
+                };
+            }
+            return { ...answer, status: 'declined' };
+        default:
+            return answer;
+    }
+}
+/** A refusal that still answers the shopper: a changed cart, nothing to confirm, a turn still running. Null for every other error. */
+function resultOfRefusal(error) {
+    if (!(error instanceof AgentcardApiError) || error.status !== 409)
+        return null;
+    const answer = (reply, carts) => ({
+        status: 'needs_input',
+        reply,
+        messages: [],
+        cart: carts.at(-1) ?? null,
+        carts,
+        products: [],
+        links: [],
+        link_sent: false,
+        approval_expires_at: null,
+        shopper_need_not_reply: false,
+        conversation_id: error.conversationId,
+        order_id: null,
+        decline_code: null,
+        error_code: error.code,
+        next_action: null,
+        hashes: hashesOf(null, carts),
+        envelope: error.body,
+    });
+    if (error.code.startsWith('delivery_address'))
+        return answer(ADDRESS_CHANGED, []);
+    if (error.code === 'cart_changed')
+        return answer(CART_CHANGED, error.carts);
+    if (error.code === 'nothing_to_confirm' || error.code === 'conversation_closed')
+        return answer(NOTHING_TO_CONFIRM, []);
+    if (error.code === 'turn_in_progress')
+        return answer(STILL_WORKING, []);
+    return null;
+}
+/** A shopper Agentcard has not connected to this company yet: the Vault link where they connect and add a card. */
+function needsCard(link, body) {
+    return {
+        status: 'needs_card',
+        reply: CARD_NEEDED,
+        messages: [],
+        cart: null,
+        carts: [],
+        products: [],
+        links: [{ kind: 'vault', url: link.url, expiresAt: link.expiresAt }],
+        link_sent: false,
+        approval_expires_at: null,
+        shopper_need_not_reply: false,
+        conversation_id: null,
+        order_id: null,
+        decline_code: null,
+        error_code: 'user_not_connected',
+        next_action: 'add_card',
+        hashes: [],
+        envelope: body,
+    };
+}
+/**
+ * The order this purchase's checkout produced: the last checkout's own order, or the newest order
+ * placed since the last checkout, one that did not stop first. Agentcard clears the last checkout when
+ * a turn starts, so an order older than it came from an earlier cart. With no last checkout, only an
+ * order placed since `since`, the moment this call started, counts. The ledger's state wins over the
+ * checkout's, because the store can cancel an order after checkout placed it.
+ */
+function placedOrderOf(conversation, since) {
+    const last = conversation.last_checkout;
+    if (last?.order_id) {
+        // Two stores can use the same order number, so the store has to match as well.
+        const ledger = conversation.orders.find((order) => order.order_id === last.order_id && order.merchant === last.merchant);
+        return { orderId: last.order_id, merchant: last.merchant_name, status: ledger?.status ?? '' };
+    }
+    const stampedAt = last?.at ? Date.parse(last.at) : Number.NaN;
+    const from = Number.isFinite(stampedAt) ? stampedAt - (placementRunning(conversation) ? RESUME_SKEW_MS : 0) : since;
+    const current = conversation.orders.filter((order) => {
+        // An order from another store is another purchase, however close in time.
+        if (!order.order_id || (last && order.merchant !== last.merchant))
+            return false;
+        const placedAt = order.placed_at ? Date.parse(order.placed_at) : Number.NaN;
+        return Number.isFinite(placedAt) && placedAt >= from;
+    });
+    const newest = current.filter((order) => !STOPPED_ORDER.has(order.status)).at(-1) ?? current.at(-1);
+    return newest ? { orderId: newest.order_id, merchant: newest.merchant_name, status: newest.status } : null;
+}
+/** True when the last checkout is a placement Agentcard is still finishing. */
+function placementRunning(conversation) {
+    const last = conversation.last_checkout;
+    return last?.code === 'in_progress' || last?.decline_code === 'in_progress' || last?.status === 'pending';
+}
+/**
+ * Why a finished checkout placed nothing, or null while it can still place: an order, a placement
+ * still running, a turn still running, or an approval waiting for the shopper are not refusals.
+ */
+function checkoutRefusal(conversation) {
+    const last = conversation.last_checkout;
+    if (!last || last.order_id || conversation.turn_in_progress || placementRunning(conversation))
+        return null;
+    const code = last.decline_code ?? last.code;
+    if (!code || code === 'vault_approval_required')
+        return null;
+    return { code, merchant: last.merchant_name, message: last.message };
+}
+/**
+ * A buy tool for one shopper. With a company client, name the shopper with
+ * `externalUserId`; with a shopper's own `accessToken`, the token names them.
+ * Throws a TypeError for options that cannot work, before any call.
+ */
+export function buyTool(options) {
+    const o = options ?? {};
+    if ((o.agentcard === undefined) === (o.accessToken === undefined)) {
+        throw new TypeError("Pass agentcard, a client built with your company credentials, or accessToken, the shopper's own token, and not both.");
+    }
+    if (o.agentcard !== undefined && typeof o.agentcard.buy !== 'function') {
+        throw new TypeError('Pass agentcard as an AgentcardClient.');
+    }
+    const client = o.agentcard ?? new AgentcardClient({ accessToken: o.accessToken, baseUrl: o.baseUrl, fetch: o.fetch });
+    const externalUserId = o.externalUserId;
+    if (client.company && (typeof externalUserId !== 'string' || externalUserId.trim() === '')) {
+        throw new TypeError('Pass externalUserId: your own id for this shopper. A company client buys for many shoppers, so each tool names its own.');
+    }
+    if (!client.company && externalUserId !== undefined) {
+        throw new TypeError("A shopper's own access token already names the shopper. Leave externalUserId out.");
+    }
+    if (o.sendLink !== undefined && typeof o.sendLink !== 'function') {
+        throw new TypeError('Pass sendLink as a function that delivers a link to the shopper.');
+    }
+    const sendLink = o.sendLink;
+    const wait = o.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    if (typeof wait !== 'function')
+        throw new TypeError('Pass wait as a function of milliseconds that resolves after the pause.');
+    const who = client.company ? { externalUserId } : {};
+    /** One read of the conversation, or null when it fails: a read only ever improves an answer the tool already has. */
+    const read = async (conversationId) => {
+        try {
+            return await client.conversation(conversationId, who);
+        }
+        catch {
+            return null;
+        }
+    };
+    /** The order this purchase placed, or the reason it stopped when the ledger says it did. */
+    const placed = (base, order, conversation) => {
+        const conversationId = conversation.conversation_id || base.conversation_id;
+        if (!STOPPED_ORDER.has(order.status)) {
+            return {
+                ...base,
+                status: 'order_placed',
+                reply: `The ${order.merchant || 'store'} order went through, order number ${order.orderId}.`,
+                links: [],
+                next_action: null,
+                order_id: order.orderId,
+                conversation_id: conversationId,
+            };
+        }
+        return {
+            ...base,
+            status: 'declined',
+            reply: order.status === 'cancelled'
+                ? `${order.merchant || 'The store'} cancelled order ${order.orderId}.`
+                : `${NOT_PLACED} The ${order.merchant || 'store'} order ${order.orderId} stopped because its payment never confirmed.`,
+            links: [],
+            order_id: order.orderId,
+            decline_code: `order_${order.status}`,
+            next_action: null,
+            shopper_need_not_reply: false,
+            conversation_id: conversationId,
+        };
+    };
+    /** A checkout that finished without an order: the reason it gave, for the shopper to hear. */
+    const refusedCheckout = (base, refusal) => ({
+        ...base,
+        status: 'declined',
+        reply: refusal.message || `${NOT_PLACED} The ${refusal.merchant || 'store'} answered ${refusal.code}.`,
+        links: [],
+        decline_code: refusal.code,
+        next_action: null,
+        shopper_need_not_reply: false,
+    });
+    /**
+     * Placing after the tap: one 12-second pause, one read, then the order, the refusal the checkout
+     * finished with, or `placing`. `since` is when this call started, for `placedOrderOf`.
+     */
+    const awaitPlacement = async (base, conversationId, since) => {
+        await wait(PLACEMENT_WAIT_MS);
+        const conversation = await read(conversationId);
+        const order = conversation && placedOrderOf(conversation, since);
+        if (conversation && order)
+            return placed(base, order, conversation);
+        const refusal = conversation && checkoutRefusal(conversation);
+        if (refusal)
+            return refusedCheckout(base, refusal);
+        return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null };
+    };
+    /**
+     * What a finished turn's checkout left besides an order, which `placedOrderOf`
+     * reads first: the refusal it ended with, or the approval it paused on.
+     * Agentcard clears the last checkout when a turn starts, so a checkout read
+     * here belongs to the turn that just ended.
+     */
+    const checkoutOf = (base, conversation) => {
+        const last = conversation.last_checkout;
+        // A checkout that found no card made an add-card link: the shopper gets it, as from a turn that ended the same way.
+        if (last?.decline_code === 'vault_unavailable' && last.add_card_url) {
+            return {
+                ...base,
+                status: 'needs_card',
+                reply: last.message || CARD_NEEDED,
+                links: [{ kind: 'vault', url: last.add_card_url, expiresAt: last.add_card_expires_at }],
+                decline_code: last.decline_code,
+                next_action: 'add_card',
+                shopper_need_not_reply: false,
+                envelope: conversation.raw,
+            };
+        }
+        if (last?.decline_code !== 'vault_approval_required' || !last.approval_url) {
+            // A checkout that ended refused keeps its cart on the table; the refusal is the answer, not the cart.
+            const refusal = checkoutRefusal(conversation);
+            return refusal ? refusedCheckout(base, refusal) : null;
+        }
+        const announced = last.placement_announced === true;
+        if (last.approval_in_progress === true)
+            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null, shopper_need_not_reply: announced };
+        return {
+            ...base,
+            status: 'approval_sent',
+            reply: APPROVAL_WAITING,
+            links: [{ kind: 'approval', url: last.approval_url, expiresAt: last.approval_expires_at }],
+            approval_expires_at: last.approval_expires_at,
+            next_action: 'approve',
+            shopper_need_not_reply: announced,
+            envelope: conversation.raw,
+        };
+    };
+    /**
+     * A turn past Agentcard's budget: a read every 5 seconds for up to a minute,
+     * counted in elapsed time, so slow reads end the reading sooner. A turn that
+     * ends returns the order it placed, the refusal or the approval it ended on,
+     * the cart it left, or none. A new cart waits for the read that shows the
+     * turn ended: the running turn holds the conversation, and only a read that
+     * gets the conversation hands its one cart back as the cart `confirm: true`
+     * places. Carts at two stores return with no cart to confirm, so the shopper
+     * picks one first. A placement another attempt is still finishing keeps the
+     * reading going and ends as `placing`, never as the cart. A minute without
+     * any of them returns Agentcard's own answer, or what the last read showed
+     * while the turn still ran.
+     */
+    const awaitCart = async (base, conversationId, since) => {
+        const shown = new Set(base.hashes);
+        const deadline = Date.now() + TURN_READS * TURN_READ_EVERY_MS;
+        let placing = false;
+        // What the last read showed while the turn still ran, when it showed a new cart.
+        let early = null;
+        for (let i = 0; i < TURN_READS && Date.now() < deadline; i++) {
+            await wait(TURN_READ_EVERY_MS);
+            const conversation = await read(conversationId);
+            // A failed read loses nothing: the next one, while the minute lasts, can still find the cart.
+            if (!conversation)
+                continue;
+            placing = false;
+            early = null;
+            if (!conversation.turn_in_progress) {
+                const order = placedOrderOf(conversation, since);
+                if (order)
+                    return placed(base, order, conversation);
+                const finished = checkoutOf(base, conversation);
+                if (finished)
+                    return finished;
+                // The cart is being placed: its order is what the shopper waits for, not the cart again.
+                if (placementRunning(conversation)) {
+                    placing = true;
+                    continue;
+                }
+            }
+            const newest = conversation.carts.at(-1) ?? null;
+            if ((newest && !shown.has(newest.hash)) || !conversation.turn_in_progress) {
+                // A read hands its cart back, as the one `confirm: true` places, only when no turn holds the
+                // conversation and it shows one cart. With carts at two stores `confirm: true` still names the
+                // cart an earlier answer showed, so none is offered: the shopper's pick goes out as an ask.
+                const one = conversation.carts.length === 1 ? newest : null;
+                const answer = {
+                    ...base,
+                    reply: one ? CART_READY : newest ? CHOOSE_CART : ANSWER_LATE,
+                    cart: one,
+                    carts: conversation.carts,
+                    hashes: conversation.carts.map((c) => c.hash),
+                    error_code: newest ? null : base.error_code,
+                    // A read replaced the answer the step was named for, and names no step of its own: the reply asks.
+                    next_action: null,
+                    envelope: conversation.raw,
+                };
+                if (!conversation.turn_in_progress)
+                    return answer;
+                // The running turn holds the conversation, so this read handed nothing back: read on until it ends.
+                early = answer;
+            }
+        }
+        if (placing)
+            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null };
+        // A minute that ends with the turn still running returns what the last read showed, a new cart as
+        // ready although no read handed it back: nothing better exists by then, and a confirm that misses it
+        // is refused, never placed on another cart.
+        return early ?? base;
+    };
+    const settleTurn = async (turn, startedAt) => {
+        const result = resultOfTurn(turn);
+        if (!turn.conversation_id)
+            return result;
+        // Checkout reports a placement another attempt is finishing as `in_progress`, under any status.
+        if (turn.decline_code === 'in_progress') {
+            return awaitPlacement({ ...result, shopper_need_not_reply: turn.placement_announced === true }, turn.conversation_id, startedAt);
+        }
+        if (result.status === 'needs_input' && turn.error_code === 'turn_timeout')
+            return awaitCart(result, turn.conversation_id, startedAt);
+        return result;
+    };
+    /**
+     * A refusal, settled: a shopper not connected yet gets the Vault link; a
+     * confirm refused because the order already took the cart, or because the
+     * placement is still running, reads the conversation for the order.
+     */
+    const settleRefusal = async (error, confirm, startedAt) => {
+        if (error instanceof AgentcardApiError && error.status === 403 && error.code === 'user_not_connected' && client.company) {
+            return needsCard(await client.mintVaultLink({ externalUserId: externalUserId }), error.body);
+        }
+        const refused = resultOfRefusal(error);
+        if (!refused)
+            throw error;
+        if (!confirm || !(error instanceof AgentcardApiError) || !error.conversationId || !AFTER_PLACEMENT.has(error.code))
+            return refused;
+        const conversationId = error.conversationId;
+        const conversation = await read(conversationId);
+        if (!conversation)
+            return refused;
+        // Only this purchase's order counts: the last checkout's, or one placed after it.
+        const order = placedOrderOf(conversation, startedAt);
+        if (order)
+            return placed(refused, order, conversation);
+        const placing = placementRunning(conversation);
+        if (!placing && !(error.code === 'turn_in_progress' && conversation.turn_in_progress))
+            return refused;
+        const settled = await awaitPlacement(refused, conversationId, startedAt);
+        // A running turn that placed nothing may be a search rather than a placement, so the shopper hears it is still working.
+        return settled.status === 'placing' && !placing ? refused : settled;
+    };
+    /** The store pages this tool sent last, with their conversation. */
+    let lastPages = null;
+    /**
+     * The store page of each product the model reads, sent once per page. A
+     * page the last batch in this conversation already sent stays with the
+     * shopper and goes out no second time. A page whose `sendLink` throws
+     * stays unsent, and the call goes on, so the next answer tries it again.
+     */
+    const deliverPages = async (result) => {
+        if (!sendLink)
+            return result;
+        const pages = new Map();
+        for (const product of shownProducts(result.products)) {
+            if (product.url && !pages.has(product.url))
+                pages.set(product.url, product);
+        }
+        // An answer with no store page leaves the last batch as it was.
+        if (pages.size === 0)
+            return result;
+        const before = lastPages?.conversationId === result.conversation_id ? lastPages.urls : new Set();
+        const held = new Set();
+        for (const [url, product] of pages) {
+            if (!before.has(url)) {
+                try {
+                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, imageUrl: product.imageUrl, expiresAt: null });
+                }
+                catch {
+                    continue;
+                }
+            }
+            held.add(url);
+        }
+        lastPages = { conversationId: result.conversation_id, urls: held };
+        return { ...result, products: result.products.map((product) => (product.url && held.has(product.url) ? { ...product, linkSent: true } : product)) };
+    };
+    /** One batch of pages at a time: a call that overlaps another reads the pages that one sent. */
+    let pagesInTurn = Promise.resolve();
+    const deliverPagesInTurn = (result) => {
+        const batch = pagesInTurn.then(() => deliverPages(result));
+        pagesInTurn = batch.catch(() => { });
+        return batch;
+    };
+    /** The Vault or approval link first, because the purchase waits on it, then the store pages. */
+    const deliver = async (result) => {
+        let delivered = result;
+        if (result.links.length > 0 && sendLink) {
+            for (const link of result.links)
+                await sendLink({ ...link });
+            delivered = { ...result, link_sent: true };
+        }
+        return deliverPagesInTurn(delivered);
+    };
+    const answer = async (raw) => {
+        const startedAt = Date.now();
+        const input = parseBuyToolInput(raw);
+        // A new order is never a confirm: a model that sets both drops the cart and places nothing.
+        const confirm = input.confirm && !input.new_order;
+        const ask = input.ask.trim();
+        if (!confirm && ask === '')
+            throw new TypeError("Put the shopper's words in ask.");
+        const body = {
+            resume: true,
+            ...(confirm ? { confirm: true, payment_source: 'vault' } : { ask }),
+            ...(input.new_order ? { new_order: true } : {}),
+            ...(o.deliveryAddress ? { delivery_address: o.deliveryAddress } : {}),
+            ...(client.company ? { external_user_id: externalUserId } : {}),
+        };
+        let turn = null;
+        let refusal;
+        try {
+            turn = await client.buy(body);
+        }
+        catch (error) {
+            refusal = error;
+        }
+        return deliver(withMessages(turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt), turn));
+    };
+    /** Checks the model's input, with every link taken out of a refusal. */
+    const parse = (input) => {
+        try {
+            return parseBuyToolInput(input);
+        }
+        catch (error) {
+            throw forModelError(error);
+        }
+    };
+    /** Every call a framework makes: the model's input, checked, then the model's view of the answer as JSON text. */
+    const handle = async (args) => {
+        try {
+            return JSON.stringify(forModel(await answer(parseBuyToolInput(args))));
+        }
+        catch (error) {
+            throw forModelError(error);
+        }
+    };
+    const { name, description, input_schema } = buyToolDefinition();
+    const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer, forModel };
+    // JSON skips these three, so a runner that sends the tool to its API as is sends Anthropic's fields and nothing else.
+    const unsent = (value) => ({ value, enumerable: false, writable: true, configurable: true });
+    return Object.defineProperties(tool, {
+        definition: unsent(buyToolDefinition()),
+        inputSchema: unsent(buyToolStandardSchema((error) => forModelError(error).message)),
+        openai: unsent(openAIBuyTool()),
+    });
+}