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

package/LICENSE

@@ -0,0 +1,38 @@
+Copyright (c) 2026 Agentcard Corporation. All rights reserved.
+
+This software, including its source, compiled and minified code, models,
+word lists, recognizers and data files (the "Software"), is proprietary to
+Agentcard Corporation and is licensed, not sold.
+
+You may install and run the Software only to use Agentcard's services, under
+the terms you accepted when you signed up for them. If you integrate
+Agentcard into an application, you may include the Software, unmodified and
+as Agentcard publishes it, in that application and distribute the application
+to your end users so they can use Agentcard's services through it; this
+license binds every copy you distribute that way. Otherwise you may not, and
+may not help or allow anyone else to:
+
+1. copy, modify, translate or create derivative works of the Software, except
+   for copies made automatically when installing and running it or included
+   in an application as the paragraph above allows;
+2. reverse engineer, decompile, disassemble, deobfuscate or otherwise try to
+   derive the source, models, thresholds, word lists, recognizers or data of
+   the Software, except to the extent applicable law expressly permits it
+   despite this restriction;
+3. extract, scrape or reuse the Software's data, including its merchant,
+   processor and passphrase data, in any other product or service;
+4. use the Software, or anything learned from studying it, to build, train,
+   tune or benchmark a product or service that competes with Agentcard, or to
+   defeat or imitate its security checks;
+5. redistribute, sublicense, sell, rent or publish the Software apart from an
+   application as the paragraph above allows, or remove this notice from it.
+
+Agentcard keeps dated fingerprints of the Software's data. A match in
+another product or data set is evidence that it was copied from the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL AGENTCARD CORPORATION BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.
+
+Questions: legal@agentcard.sh

package/README.md

@@ -1,3 +1,296 @@
-# Temporary Holding Version
+# @agent-cards/commerce-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give your agent one tool that buys for your shoppers at real stores, and tell each shopper what happened to their purchase in your agent's voice. The buy tool sends what the shopper says to Agentcard, and Agentcard finds the products, builds the cart and places the order once the shopper approves it. Agentcard then sends your webhook endpoint a signed `purchase.message` event at each moment a shopper should hear about, such as an order going through or an approval link about to expire. The package checks the signature and hands you the message.
+
+## Install
+
+```bash
+npm install @agent-cards/commerce-sdk
+```
+
+The package runs on Node 18 or later and has no dependencies.
+
+## Give your agent the buy tool
+
+Build one client with your company's credentials and one buy tool per shopper, then pass the tool to your agent as it is:
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';
+
+const agentcard = new AgentcardClient({
+  clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
+  clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '',
+});
+
+const buy = buyTool({
+  agentcard,
+  externalUserId: shopper.id, // your own id for the shopper
+  sendLink: (link) => textShopper(shopper.id, link.url),
+});
+
+const answer = await new Anthropic().beta.messages.toolRunner({
+  model: 'claude-opus-5-5',
+  max_tokens: 16000,
+  tools: [buy],
+  messages: [{ role: 'user', content: 'two packs of AA batteries from Amazon' }],
+});
+```
+
+`shopper` and `textShopper` stand for your own code. The model calls `buy` with the shopper's words, shows the shopper the cart, and confirms the cart only after the shopper says yes.
+
+Build the client once and keep it. Every shopper's tool shares the client's access token, and the client renews the token a minute before it expires. Keep each shopper's tool as well. Agentcard keeps each purchase between calls, so a tool built for every message buys the same way, but it sends the same product links again each time Agentcard shows the same products.
+
+The model sends `ask`, `confirm` and `new_order`, and nothing else. Pass `deliveryAddress` when you already hold the shopper's address: the order goes there, and Agentcard never asks the shopper for it. The model can change neither the address nor the shopper.
+
+## Use the tool in any framework
+
+Pass `buy` as it is. Each framework reads its own fields from the same object, so you pick no adapter:
+
+| Framework | Pass the tool | Who runs each call |
+|---|---|---|
+| Anthropic SDK, `client.beta.messages.toolRunner` | `tools: [buy]` | The tool runner. |
+| Vercel AI SDK 7 | `tools: { buy }` | The SDK. |
+| OpenAI SDK, OpenRouter's chat API, and any API that takes OpenAI's format | `tools: [buy.openai]` | Your loop, through `buy.handle`. |
+| OpenRouter's agent SDK, `callModel` | `tools: [toOpenRouterTool(buy, { tool, z })]` | The SDK. |
+
+In your own loop, hand each tool call to `buy.handle` and give the model what it returns. Here the OpenAI SDK talks to OpenRouter's chat API:
+
+```ts
+import OpenAI from 'openai';
+
+const openrouter = new OpenAI({ baseURL: 'https://openrouter.ai/api/v1', apiKey: process.env.OPENROUTER_API_KEY });
+const messages: OpenAI.ChatCompletionMessageParam[] = [{ role: 'user', content: 'two packs of AA batteries from Amazon' }];
+const send = async () => (await openrouter.chat.completions.create({ model: 'anthropic/claude-opus-5.5', messages, tools: [buy.openai] })).choices[0].message;
+
+let reply = await send();
+while (reply.tool_calls?.length) {
+  messages.push(reply);
+  for (const call of reply.tool_calls) {
+    if (call.type !== 'function') continue;
+    const content = await buy.handle(call.function.arguments).catch((error) => error.message);
+    messages.push({ role: 'tool', tool_call_id: call.id, content });
+  }
+  reply = await send();
+}
+console.log(reply.content); // the model's answer for the shopper
+```
+
+`buy.handle` takes the model's arguments as an object or as their JSON text, and returns the JSON text the model reads, with every link taken out. A call with input outside the schema rejects before anything reaches Agentcard. A call that fails rejects with a message that names no link, so the model reads `error.message` as it is.
+
+For a framework with its own tool format, declare `buy.definition`, which holds the name, the description and the input schema, and run the same three lines for each tool call.
+
+OpenRouter's agent SDK accepts only tools that its own `tool` builds from a zod schema, so that SDK keeps an adapter. Pass your own `tool` and `z`, and the package still installs no dependencies:
+
+```ts
+import { OpenRouter, tool } from '@openrouter/agent';
+import { z } from 'zod';
+import { toOpenRouterTool } from '@agent-cards/commerce-sdk';
+
+const result = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY }).callModel({
+  model: 'anthropic/claude-opus-5.5',
+  input: 'two packs of AA batteries from Amazon',
+  tools: [toOpenRouterTool(buy, { tool, z })],
+});
+console.log(await result.getText());
+```
+
+`toAnthropicTool(buy)` is no longer needed, and returns `buy` itself, so code that still calls it keeps working.
+
+## Send the shopper each link
+
+A purchase needs a link at three moments: the shopper approves the purchase on an approval page, a new shopper adds a card on a Vault page, and a shopper signs in to a store's own account on its login page before Agentcard can buy there. Each link's `kind` says which: `approval`, `vault` or `store_login`, and a `store_login` link names the store in `store`. The tool hands each link to `sendLink` and waits for it, so the shopper holds the link before the model answers. The model reads `link_sent: true` and never the link itself, because a tool runner puts each answer straight into the model's context, and a model that holds a link writes it into the chat.
+
+The tool also hands `sendLink` a `product` link for each product a search finds, up to twenty per answer. The link carries the product's page at its store in `url`, the product's name in `title`, its price in `price`, such as `$12.99`, and its id in `productId`. Every price the tool writes, in a link or in the model's view, uses the currency Agentcard names for the cart or the product, in that currency's own minor units: `1331` is `$13.31` in USD, `CA$13.31` in CAD and `¥1,331` in JPY. A price whose currency Agentcard does not name shows with no symbol. The link arrives beside the reply, and you decide how to show it: as a card, in a list, or as a text with the URL. The model reads `product_links_sent` and never a URL, so a shopper who asks for links hears that the links are there. When the next answer in the conversation shows the same products, the tool sends none of their links again. A product link your `sendLink` throws on counts as not sent, and the call goes on.
+
+Without `sendLink`, `result.links` still carries each Vault, approval and store login link for your code, each product in `result.products` carries its `url`, and the model still never reads one.
+
+## Sign up a new shopper
+
+A shopper who has not connected to your company yet gets a Vault link on their first call. The tool asks Agentcard for the link and hands it to `sendLink`, and the model reads `needs_card`. The shopper connects and adds a card on the Vault page, and the next call buys. Agentcard returns the same link while it has time left, so a shopper who asks twice gets one link.
+
+A shopper who is connected but has no card gets the add-card link Agentcard returned with its answer, and the model reads `needs_card` as well.
+
+## Wait for a placement
+
+An order takes a few seconds to go through after the shopper approves it. A call that lands while Agentcard is still placing the order pauses once for 12 seconds and reads the conversation, and the model reads `order_placed` with the order number, or `placing`. A call that finds the order already placed reads it at once, with no pause. An order the store cancelled, or one whose payment never confirmed, reads as `declined` with the reason.
+
+A request that takes Agentcard more than 110 seconds comes back before its cart is ready. The tool then reads the conversation every 5 seconds for up to a minute, and returns the cart once Agentcard finishes the request, so the shopper's first yes confirms that cart. If Agentcard is still working when the minute ends, the tool returns the cart Agentcard has built so far. When the shopper has carts at more than one store, the tool returns every cart and no `cart`, so the model asks the shopper which one to buy before it confirms. A confirm that takes that long returns the order it placed, sends the approval link it paused on, or reads `placing` while the order is still going through. Pass `wait` to replace the timer between reads, as the tests do.
+
+## Read what the model sees
+
+The model reads one object per call:
+
+```json
+{
+  "status": "needs_input",
+  "reply": "Here's an 8 pack of AA batteries at Amazon for $12.99, $13.31 with fees. Want me to order it?",
+  "cart": {
+    "store": "Amazon",
+    "items": [{ "name": "AA batteries, 8 pack", "qty": 1, "price": "$12.99" }],
+    "fees": "$0.32",
+    "tip": null,
+    "total": "$13.31"
+  },
+  "carts": [
+    { "store": "Amazon", "items": [{ "name": "AA batteries, 8 pack", "qty": 1, "price": "$12.99" }], "fees": "$0.32", "tip": null, "total": "$13.31" }
+  ],
+  "products": [],
+  "approval_expires_at": null,
+  "shopper_need_not_reply": false,
+  "link_sent": false,
+  "product_links_sent": 0
+}
+```
+
+`cart` is the newest cart, and `carts` lists every cart on the table, the newest last, so a shopper buying from more than one store hears each one.
+
+`status` says where the purchase stands:
+
+| `status` | What happened |
+|---|---|
+| `needs_input` | Agentcard asks the shopper something, or shows a cart. |
+| `needs_card` | The shopper adds a card from a link before Agentcard can buy. |
+| `approval_sent` | The shopper approves the purchase from a link. |
+| `placing` | The shopper approved, and the order is going through. |
+| `order_placed` | The order went through. |
+| `declined` | Agentcard did not buy, and `reply` says why. |
+
+A status Agentcard adds later reads as `needs_input`. `shopper_need_not_reply` is true when a `purchase.message` will tell the shopper how the order went.
+
+## Run the tool yourself
+
+`buy.answer(input)` sends the model's input and returns the whole answer for your code: the status, Agentcard's reply with its links, the cart and its hash, the products, the links, and the answer as it came in `envelope`. `buy.forModel(result)` returns what the model may read. Give the model the view, never the answer:
+
+```ts
+const result = await buy.answer({ ask: 'two packs of AA batteries', confirm: false, new_order: false });
+const view = buy.forModel(result); // the tool result your model reads
+```
+
+`buy.run`, `buy.execute` and `buy.handle` each return the same text, `JSON.stringify(buy.forModel(result))`: Anthropic's tool runner calls `buy.run`, the Vercel AI SDK calls `buy.execute`, and your own loop calls `buy.handle`.
+
+## Buy with a shopper's own token
+
+A tool that buys for one signed-in shopper takes that shopper's own Agentcard access token instead of a client, and names nobody:
+
+```ts
+const buy = buyTool({ accessToken: shopperAccessToken, sendLink });
+```
+
+## Try it in the sandbox
+
+Run the walkthrough with your sandbox credentials to watch one purchase from start to finish:
+
+```bash
+AGENTCARD_CLIENT_ID=... AGENTCARD_CLIENT_SECRET=... node node_modules/@agent-cards/commerce-sdk/examples/walkthrough.mjs
+```
+
+The walkthrough connects a test shopper with the sandbox code `111111`, asks for a restaurant table, picks one and confirms it. The sandbox refuses the booking itself, so the last answer is `declined` with `decline_code: sandbox_unavailable`, and nothing is booked or charged. Then a shopper nobody connected asks twice and gets the same Vault link both times. The walkthrough refuses live credentials before it connects anybody.
+
+`examples/anthropic.mjs` and `examples/openrouter.mjs` run the buy tool as a chat in your terminal, and each prints the links your app would send.
+
+## Read a refusal
+
+Five refusals still answer the shopper, so they come back as `needs_input` with the reason in `reply` and the code in `error_code`: a changed cart (`cart_changed`), a confirm with no cart (`nothing_to_confirm`), a confirm on a closed conversation (`conversation_closed`), a delivery address that changed since the cart was built (a code that starts with `delivery_address`), and a request Agentcard is still working on (`turn_in_progress`). Every other refusal throws an `AgentcardApiError`, and `error.code` says why:
+
+| `code` | What it means | What to do |
+|---|---|---|
+| `external_user_id_ambiguous` | Two of your shoppers share the `externalUserId` you passed. | Give each shopper their own id. |
+| `oauth_failed` | Agentcard refused your client credentials. | Check `clientId` and `clientSecret`. |
+| `unauthorized` | Agentcard refused the access token. | Sign the shopper in again when the token was their own. |
+| `timeout` | Agentcard did not answer in time, so whether the turn ran is unknown. A purchase turn waits 130 seconds. | Read the conversation with `agentcard.conversation(conversationId, { externalUserId })` when an earlier result gave you its `conversation_id`. Call the tool again only once that read shows the turn did not finish, because a second call sends a second turn. |
+| `unreachable` | No answer came back. The request can still have reached Agentcard. | As for `timeout`. |
+| `invalid_answer` | Agentcard answered with a body the client cannot read. | As for `timeout`. |
+
+The tool sends each purchase request once, because a purchase turn runs against live stores. Only a request Agentcard refused with a `401` goes again, once, with a renewed token.
+
+`buy.answer` throws the `AgentcardApiError` itself. `buy.run`, `buy.execute` and `buy.handle` throw the same message with every link taken out, and keep the original error on `error.cause` for your logs.
+
+## Mount the handler
+
+Subscribe your webhook endpoint to `purchase.message`, then mount the handler on its route with `express.raw`:
+
+```ts
+import express from 'express';
+import { purchaseAgentWebhook } from '@agent-cards/commerce-sdk';
+
+const app = express();
+const secret = process.env.AGENTCARD_WEBHOOK_SECRET ?? ''; // returned once, when you created the endpoint
+
+app.post('/agentcard/webhooks', express.raw({ type: 'application/json' }), purchaseAgentWebhook(secret, async (message) => {
+  // Past validUntil, the link or window the message names has closed: drop it, and the delivery still answers 200.
+  const until = message.facts.validUntil ? Date.parse(message.facts.validUntil) : Infinity;
+  if (until <= Date.now()) return;
+  // A link must arrive exactly as written, and a message without a note has only its text.
+  const sendAsIs = message.kind === 'approval_expiring' || message.kind === 'card_link_unfinished' || !message.note;
+  if (sendAsIs) return textShopper(message.userId, message.text);
+  try {
+    await runAgentTurn(message.userId, message.note, until);
+  } catch {
+    // The agent could not say it, so the shopper still hears what happened while it still holds.
+    if (until > Date.now()) await textShopper(message.userId, message.text);
+  }
+}));
+```
+
+`textShopper` and `runAgentTurn` stand for your own code. `runAgentTurn` gets the time the message stops holding, so it sends nothing after it. An empty secret throws when the server starts.
+
+Mount the route before any `app.use(express.json())`. The signature covers the exact bytes Agentcard sent, and a JSON parser that runs first throws those bytes away. If a JSON parser has to run first, keep the bytes for the handler:
+
+```ts
+app.use(express.json({ verify: (req, _res, buf) => { Object.assign(req, { rawBody: buf }); } }));
+```
+
+Without the raw bytes, the handler answers `500` and `onError` receives the fix.
+
+## Handle each delivery
+
+A delivery with a missing, malformed, stale or wrong signature gets a `400`, and your code never sees it. A verified delivery runs your callback, and the handler answers when the callback is done: `200` when it returns, `500` when it throws. After a `500`, Agentcard delivers the event again, so a shopper's update is not lost to a failed send.
+
+Agentcard waits 10 seconds for the answer. Keep the callback short: send the text, or save the agent turn to a queue that retries a failed job, then return. Without a queue, await the send, so a send that fails answers `500` and Agentcard delivers the event again.
+
+Agentcard delivers each event at least once, and again after any answer other than a `2xx`. Keep `message.eventId` and skip an id you already handled.
+
+Pass `onEvent` to receive every other event type, and `onError` to receive an error your callback throws. Without `onError`, the error goes to `console.error`. A purchase message the package cannot read also reaches `onError`, and gets a `200`, because a second delivery would read the same.
+
+## Read a message
+
+| Field | What it is for |
+|---|---|
+| `text` | The text to send the shopper as is. Send it when you have no agent, and for every message that carries a link, so the link arrives exactly as Agentcard wrote it. |
+| `note` | For your agent: what happened, marked as written by the system and not typed by the shopper. Give it to your agent as a turn, and the agent tells the shopper in its own voice. |
+| `facts` | The same values one by one, for a company that writes its own copy. A fact that does not apply to the message is absent. |
+
+When a message has no `note`, or your agent cannot run the turn, send `text` instead, and the shopper still hears what happened.
+
+The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`, `orderId`, `reason`, `approvalUrl`, `approvalExpiresAt`, `cardLinkUrl`, `retryUntil`, `nudgeNumber` and `validUntil`. `totalCents` is `2306` for `$23.06`.
+
+`validUntil` is when the message stops holding: the expiry of any link or window its text names. A message that arrives after it, or that you would send after it, is stale, so drop it instead of sending it. A message that stays true carries no `validUntil`.
+
+`userId` is the shopper's Agentcard user id, and `externalUserId` is your own id for them when you gave Agentcard one. `kind` says which moment the message is about:
+
+| `kind` | When it arrives |
+|---|---|
+| `order_placed` | The shopper approved, and Agentcard placed the order. |
+| `order_failed` | The order failed after the shopper approved. |
+| `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. |
+| `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. |
+
+Agentcard can add a kind later. A kind your code does not know still carries `text`, ready to send as is.
+
+## Verify without the handler
+
+```ts
+import { verifyAgentcardWebhook, readPurchaseMessage } from '@agent-cards/commerce-sdk';
+
+// Node types a header as a string or a list of strings; the check takes one string.
+const signature = req.headers['agentcard-signature'];
+const event = verifyAgentcardWebhook(rawBody, Array.isArray(signature) ? signature.join(',') : signature, secret);
+const message = readPurchaseMessage(event); // null for every other event type
+```
+
+`verifyAgentcardWebhook` throws `AgentcardSignatureError` when the delivery did not come from Agentcard, and `error.reason` says why: `missing_header`, `malformed_header`, `stale_timestamp` or `wrong_signature`. A delivery signed more than 300 seconds away from now is stale, and `toleranceSeconds` changes the limit.

package/dist/adapters.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The two adapters from before the buy tool fit every framework on its own.
+ * `toAnthropicTool` is no longer needed: pass the buy tool itself, and it
+ * returns that same object for one more release. `toOpenRouterTool` stays for
+ * OpenRouter's agent SDK, whose `callModel` takes only tools built with its
+ * own `tool` and a zod schema. The package imports no SDK: it calls the `tool`
+ * and `z` you pass, so it keeps no dependencies.
+ *
+ * Both hand the model the JSON text `buy.handle` returns, and a failed call
+ * as the error's message with every link taken out.
+ */
+import type { BuyTool } from './buy-tool.js';
+/** @deprecated The buy tool is Anthropic's runnable tool already. Kept for one release. */
+export type AnthropicBuyTool = BuyTool;
+/** @deprecated Pass the buy tool itself: `toolRunner({ tools: [buy] })`. Returns the same object, for one release. */
+export declare function toAnthropicTool(tool: BuyTool): BuyTool;
+/** The three zod builders the OpenRouter adapter calls; `z` from zod 3 or 4 has them. */
+export interface ZodLike {
+    object(shape: Record<string, unknown>): {
+        strict(): unknown;
+    };
+    string(): {
+        describe(description: string): unknown;
+    };
+    boolean(): {
+        describe(description: string): unknown;
+    };
+}
+/** What the OpenRouter adapter needs from you: `tool` from `@openrouter/agent`, and `z` from zod. */
+export interface OpenRouterToolkit<T> {
+    tool: (config: any) => T;
+    z: ZodLike;
+}
+/** The buy tool for OpenRouter's `callModel({ tools: [toOpenRouterTool(buy, { tool, z })] })`. */
+export declare function toOpenRouterTool<T>(buy: BuyTool, toolkit: OpenRouterToolkit<T>): T;

package/dist/adapters.js

@@ -0,0 +1,23 @@
+/** @deprecated Pass the buy tool itself: `toolRunner({ tools: [buy] })`. Returns the same object, for one release. */
+export function toAnthropicTool(tool) {
+    return tool;
+}
+/** The buy tool for OpenRouter's `callModel({ tools: [toOpenRouterTool(buy, { tool, z })] })`. */
+export function toOpenRouterTool(buy, toolkit) {
+    const { tool, z } = toolkit ?? {};
+    if (typeof tool !== 'function' || !z || typeof z.object !== 'function') {
+        throw new TypeError("Pass { tool, z }: tool from '@openrouter/agent' and z from 'zod'.");
+    }
+    const { properties } = buy.definition.input_schema;
+    return tool({
+        name: buy.definition.name,
+        description: buy.definition.description,
+        inputSchema: z.object({
+            ask: z.string().describe(properties.ask.description),
+            confirm: z.boolean().describe(properties.confirm.description),
+            new_order: z.boolean().describe(properties.new_order.description),
+        }).strict(),
+        // OpenRouter's SDK encodes what execute returns as JSON, so the view goes back as an object and reaches the model as the same text.
+        execute: async (input) => JSON.parse(await buy.execute(input)),
+    });
+}

package/dist/buy-tool.d.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 { AgentcardClient, type BuyCart, type BuyDeliveryAddress, 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';
+/**
+ * Where the purchase stands:
+ * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
+ * - `needs_card`: the shopper connects and adds a card first, from a link.
+ * - `approval_sent`: the shopper approves the purchase from a link.
+ * - `placing`: the shopper approved, and the order is going through.
+ * - `order_placed`: the order went through.
+ * - `declined`: Agentcard did not buy, and `reply` says why.
+ */
+export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'placing' | 'order_placed' | 'declined';
+/**
+ * A link for the shopper. `vault`: the page where they connect and add a
+ * 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` and `productId`.
+ */
+export interface BuyToolLink {
+    kind: 'vault' | 'approval' | 'store_login' | 'product';
+    url: string;
+    /** 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. */
+    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. */
+    price?: string | null;
+    /** On a product link: Agentcard's id for the product. */
+    productId?: string;
+}
+/** A product the last search found. */
+export interface BuyToolProduct {
+    id: string;
+    name: string;
+    /** The price in the minor unit of `currency`. */
+    priceCents: number | null;
+    /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
+    currency: string | null;
+    imageUrl: string | null;
+    store: string | null;
+    /** The product's page at its store, or null when Agentcard sent none. */
+    url: string | null;
+    /**
+     * True when the shopper holds this product's store page: `sendLink` took it
+     * in this call, or in the last call that sent store pages in the same
+     * conversation.
+     */
+    linkSent: boolean;
+}
+/** One answer of the buy tool, whole, for your code. Hand it to `forModel` before a model reads it. */
+export interface BuyToolResult {
+    status: BuyToolStatus;
+    /** Agentcard's answer for the shopper, links included. */
+    reply: string;
+    /** The cart on the table, or null. */
+    cart: BuyCart | null;
+    /** Every cart on the table, oldest first. */
+    carts: BuyCart[];
+    products: BuyToolProduct[];
+    /** The Vault or approval link this answer needs, each one handed to `sendLink` before the call returned. A product's store page is its `url`. */
+    links: BuyToolLink[];
+    /** True when `sendLink` took every link in `links`. */
+    link_sent: boolean;
+    /** When the approval link stops working, as an ISO 8601 timestamp. */
+    approval_expires_at: string | null;
+    /** True when Agentcard tells the shopper how the order went, so the shopper need not reply. */
+    shopper_need_not_reply: boolean;
+    conversation_id: string | null;
+    order_id: string | null;
+    decline_code: string | null;
+    error_code: string | null;
+    /** Every cart hash in this answer. */
+    hashes: string[];
+    /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
+    envelope: Record<string, unknown>;
+}
+export interface BuyToolOptions {
+    /** A client built with your company's credentials. Build it once and share it across every shopper's tool. */
+    agentcard?: AgentcardClient;
+    /** Or one shopper's own Agentcard access token, for a tool that buys only for them. */
+    accessToken?: string;
+    /** Your own id for the shopper. Required with a company client, and left out with a shopper's own token. */
+    externalUserId?: string;
+    /**
+     * Delivers a link to the shopper. Each call waits for it, so the shopper
+     * 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.
+     */
+    sendLink?: (link: BuyToolLink) => void | Promise<void>;
+    /** Where the orders go, when you already hold the shopper's address. The model never sets it. */
+    deliveryAddress?: BuyDeliveryAddress;
+    /** With `accessToken`: where Agentcard answers. Default `https://api.agentcard.sh`. */
+    baseUrl?: string;
+    /** With `accessToken`: the fetch to call Agentcard with. Default: the global fetch. */
+    fetch?: FetchLike;
+    /** The pause between two reads of the conversation. Default: a timer. */
+    wait?: (ms: number) => Promise<void>;
+}
+/**
+ * The buy tool, in the shape every agent framework takes, because their field
+ * names do not collide:
+ * - Anthropic's tool runner sends `name`, `description`, `input_schema` and
+ *   `strict` to the API, the only fields JSON carries, and calls `parse` and `run`.
+ * - The Vercel AI SDK reads `description`, `inputSchema` and `strict`, and calls `execute`.
+ * - The OpenAI SDK, and every API that takes OpenAI's format, takes `openai`,
+ *   and your loop hands each call to `handle`.
+ * The tool carries no `type`: Anthropic's API takes `custom` or none, and the
+ * Vercel AI SDK throws on `custom`. `run`, `execute` and `handle` are one
+ * function, so every framework hands the model the same JSON, with every
+ * link taken out.
+ */
+export interface BuyTool {
+    /** The tool's name, `buy`. */
+    readonly name: string;
+    /** What the model reads before it calls the tool. */
+    readonly description: string;
+    /** The JSON Schema of the model's input, under Anthropic's field name. */
+    readonly input_schema: BuyToolInputSchema;
+    /** Asks the model API for input that always fits the schema. */
+    readonly strict: true;
+    /** The same schema, as the Vercel AI SDK reads it. */
+    readonly inputSchema: BuyToolStandardSchema;
+    /** The tool in OpenAI's function-calling format, for `tools: [buy.openai]`. */
+    readonly openai: OpenAIBuyTool;
+    /** The name, description and input schema to give the model. */
+    readonly definition: BuyToolDefinition;
+    /** Checks the model's input against the schema, and throws a message the model can act on. */
+    parse(input: unknown): BuyToolInput;
+    /** Runs one call and returns what the model reads, as JSON text. Anthropic's tool runner calls it. */
+    run(input: BuyToolInput): Promise<string>;
+    /** The same call, for the Vercel AI SDK. */
+    execute(input: BuyToolInput): Promise<string>;
+    /** The same call, for your own loop: takes the model's arguments as an object or as their JSON text. */
+    handle(args: unknown): Promise<string>;
+    /** Sends the model's input to Agentcard and returns the whole answer, links included, for your code. Never hand it to the model. */
+    answer(input: BuyToolInput): Promise<BuyToolResult>;
+    /** The answer as the model may read it, with every link taken out. */
+    forModel(result: BuyToolResult): BuyToolModelView;
+}
+/**
+ * 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 declare function buyTool(options: BuyToolOptions): BuyTool;