@agent-cards/commerce-sdk 0.13.0 → 0.14.0

package/dist/client.js

@@ -10,6 +10,8 @@
  */
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
+/** The handlers that ask Agentcard to stream a turn. */
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -24,6 +26,37 @@ const DELIVERED_PER_SHOPPER = 20;
 const DELIVERED_SHOPPERS = 10_000;
 /** The event ids the client remembers taking in, so a message delivered twice reaches the model once. */
 const DELIVERED_IDS_KEPT = 10_000;
+/** `@opentelemetry/api`, loaded once, only when the app installed it: the package depends on nothing. */
+const OTEL_API = '@opentelemetry/api';
+let otelLoaded = null;
+function loadOtel() {
+    otelLoaded ??= import(/* webpackIgnore: true */ /* @vite-ignore */ OTEL_API).then((m) => (m.trace && m.propagation && m.context ? m : m.default?.trace ? m.default : null), () => null);
+    return otelLoaded;
+}
+/** The `traceparent` and `tracestate` headers for one call: the active span's, else the app's own, else none. */
+function traceHeaders(otel, own) {
+    const carrier = {};
+    if (otel) {
+        try {
+            otel.propagation.inject(otel.context.active(), carrier);
+        }
+        catch { /* A broken propagator never stops a purchase. */ }
+        if (str(carrier.traceparent))
+            return pickTrace(carrier);
+    }
+    let given;
+    try {
+        given = own?.();
+    }
+    catch { /* An app's own trace lookup that throws sends no trace. */ }
+    const ctx = typeof given === 'string' ? { traceparent: given } : given;
+    // Only a well-formed W3C traceparent goes out: anything else would break the header or the backend's parse.
+    return isRecord(ctx) && TRACEPARENT.test(String(ctx.traceparent)) ? pickTrace(ctx) : {};
+}
+const TRACEPARENT = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/;
+// A tracestate is printable ASCII of at most 512 characters (W3C); any other value is left off, so it can never stop a purchase.
+const TRACESTATE = /^[\x20-\x7e]{1,512}$/;
+const pickTrace = (c) => typeof c.tracestate === 'string' && TRACESTATE.test(c.tracestate) ? { traceparent: c.traceparent, tracestate: c.tracestate } : { traceparent: c.traceparent };
 const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'store_login', 'add_card', 'confirm', 'verification_code', 'approve']);
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
@@ -111,6 +144,13 @@ function feeLinesOf(v) {
     const lines = v.filter(isRecord).flatMap((f) => (str(f.label) && num(f.amountCents) !== null ? [{ label: f.label, amountCents: f.amountCents }] : []));
     return lines.length ? lines : null;
 }
+function feesOf(v) {
+    const amount = num(v.serviceFeesCents);
+    const status = v.merchantFeesPending === true || v.serviceFeesStatus === 'pending' ? 'pending'
+        : (v.serviceFeesStatus === undefined || v.serviceFeesStatus === 'known')
+            && amount !== null && Number.isSafeInteger(amount) && amount >= 0 ? 'known' : 'unknown';
+    return { serviceFeesCents: status === 'known' ? amount : null, serviceFeesStatus: status };
+}
 function cartOf(v) {
     if (!isRecord(v) || !str(v.hash) || !str(v.merchant))
         return null;
@@ -135,7 +175,7 @@ function cartOf(v) {
             };
         }) : [],
         subtotalCents: num(v.subtotalCents),
-        serviceFeesCents: num(v.serviceFeesCents) ?? 0,
+        ...feesOf(v),
         merchantFeeLines: feeLinesOf(v.merchantFeeLines),
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
@@ -164,7 +204,12 @@ function flightOf(value) {
 function catalogOf(v) {
     if (!isRecord(v))
         return null;
-    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+    const items = catalogItemsOf(v.items);
+    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+}
+/** A catalog block's products, as `items` or `more` lists them. */
+function catalogItemsOf(v) {
+    return Array.isArray(v) ? v.filter(isRecord).map((i) => {
         const flight = flightOf(i.flight);
         return {
             id: str(i.id) ?? '',
@@ -180,7 +225,10 @@ function catalogOf(v) {
             url: pageUrl(i.url),
         };
     }) : [];
-    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+}
+/** A count Agentcard sent: a whole number, never negative. Null otherwise. */
+function countOf(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null;
 }
 /** The stores an answer presents: each one with an id and a name, and no block when none has both. */
 function storesOf(v) {
@@ -376,14 +424,21 @@ async function eachEvent(res, onEvent) {
 }
 /**
  * A streamed purchase turn, read to its `envelope`: the same answer a JSON turn returns, with its
- * status in `http_status`. Each `progress` and `catalog` goes to its handler on the way. A stream that
- * breaks or ends before its envelope, once it named the conversation, reads as a turn past its budget
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment` and `cart` goes to its handler
+ * on the way, and any other event, such as a `ping` or a `tool`, is read past. A stream that breaks or
+ * ends before its envelope, once it named the conversation, reads as a turn past its budget
  * (`turn_timeout`), so the tool reads the conversation for what the turn left instead of losing it.
  */
 async function readStreamedTurn(res, stream, timeoutMs) {
     let envelope = null;
     let conversationId = null;
-    const delivering = [];
+    // The catalog, segment, cart and delta handlers run one after another, in the order their events arrived, so an app
+    // never shows a message above the cards it names, nor a piece of the next message before the message ahead of it. The
+    // stream is read on meanwhile, and the answer waits for the last one. A handler that throws costs only itself.
+    let delivering = Promise.resolve();
+    const deliver = (hand) => {
+        delivering = delivering.then(() => hand()).catch(() => { });
+    };
     let failure = null;
     try {
         await eachEvent(res, (event, text) => {
@@ -391,6 +446,8 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             if (!data)
                 return;
             conversationId = str(data.conversation_id) ?? conversationId;
+            // The conversation this event belongs to: its own, or the one an earlier event of the same turn named.
+            const named = conversationId;
             if (event === 'envelope') {
                 envelope = data;
                 return true;
@@ -403,19 +460,59 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                     // The app's display failing never fails the turn.
                 }
             }
-            else if (event === 'catalog' && stream.onCatalog && str(data.conversation_id)) {
+            else if (event === 'status' && typeof data.text === 'string' && data.text.trim() !== '' && typeof data.step === 'string' && stream.onStatus) {
+                try {
+                    stream.onStatus({ conversationId: named, step: data.step, text: data.text });
+                }
+                catch {
+                    // The app's display failing never fails the turn.
+                }
+            }
+            else if (event === 'delta' && typeof data.text === 'string' && data.text !== '' && stream.onDelta) {
+                deliver(() => stream.onDelta({ conversationId: named, text: data.text }));
+            }
+            else if (event === 'catalog' && (stream.onCatalog || stream.onFound) && str(data.conversation_id)) {
                 const catalog = catalogOf(data.catalog);
                 if (!catalog || catalog.items.length === 0)
                     return;
-                const asOf = isRecord(data.catalog) ? str(data.catalog.as_of) : null;
-                delivering.push(Promise.resolve().then(() => stream.onCatalog({ conversationId: data.conversation_id, catalog, asOf })).catch(() => { }));
+                const block = data.catalog;
+                const asOf = str(block.as_of);
+                const shown = countOf(block.shown);
+                const found = countOf(block.found);
+                const update = { conversationId: data.conversation_id, catalog, asOf, shown, found, more: catalogItemsOf(block.more) };
+                // The count follows the cards it counts, so an app never shows "8 of 23" above no cards, and it settles before the
+                // next event, so a later count never lands before an earlier one. A card display that throws never costs the count.
+                deliver(async () => {
+                    try {
+                        await stream.onCatalog?.(update);
+                    }
+                    catch {
+                        // The app's display failing never fails the turn.
+                    }
+                    if (shown !== null && found !== null && found >= shown)
+                        await stream.onFound?.({ conversationId: update.conversationId, shown, found });
+                });
+            }
+            else if (event === 'find' && stream.onFound && str(data.conversation_id)) {
+                // Find mode's count from the product index: the cards it shows of the products it found.
+                const shown = countOf(data.shown);
+                const found = countOf(data.found);
+                if (shown !== null && found !== null && found >= shown)
+                    deliver(() => stream.onFound({ conversationId: data.conversation_id, shown, found }));
+            }
+            else if (event === 'segment' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onSegment) {
+                deliver(() => stream.onSegment({ conversationId: named, text: data.text }));
+            }
+            else if (event === 'cart' && stream.onCart && str(data.conversation_id)) {
+                const update = { conversationId: data.conversation_id, cart: cartOf(data.cart), carts: cartsOf(data.carts) };
+                deliver(() => stream.onCart(update));
             }
         });
     }
     catch (error) {
         failure = error;
     }
-    await Promise.all(delivering);
+    await delivering;
     const answered = envelope;
     if (answered) {
         const { http_status: httpStatus, ...body } = answered;
@@ -439,6 +536,7 @@ export class AgentcardClient {
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     inbox = new Map();
     deliveredIds = new Set();
+    trace;
     constructor(options) {
         const o = (options ?? {});
         const hasCredentials = o.clientId !== undefined || o.clientSecret !== undefined;
@@ -457,6 +555,7 @@ export class AgentcardClient {
         this.baseUrl = (str(o.baseUrl) ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.credentials = hasCredentials ? { clientId: o.clientId, clientSecret: o.clientSecret } : null;
         this.shopperToken = hasCredentials ? null : o.accessToken;
+        this.trace = isRecord(o.trace) ? o.trace : {};
     }
     /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
     get company() {
@@ -491,10 +590,39 @@ export class AgentcardClient {
         if (!isRecord(body))
             throw new TypeError('Pass the purchase request as an object, such as { ask: "two AA battery packs" }.');
         this.checkShopper({ externalUserId: body.external_user_id, userId: body.user_id });
-        const streamed = !!stream && (typeof stream.onProgress === 'function' || typeof stream.onCatalog === 'function');
-        // A streamed turn keeps the soft budget a JSON turn has, so it answers within BUY_TURN_TIMEOUT_MS too.
-        const path = streamed ? '/buy?stream=1&soft_timeout=1' : '/buy';
-        return turnOf(await this.call('POST', path, body, BUY_TURN_TIMEOUT_MS, streamed ? stream : undefined));
+        const streamed = !!stream && STREAM_HANDLERS.some((name) => typeof stream[name] === 'function');
+        // A streamed turn keeps the soft budget a JSON turn has, so it answers within BUY_TURN_TIMEOUT_MS too. The pieces of
+        // each message go out only to a caller that asks for them.
+        const path = !streamed ? '/buy' : typeof stream.onDelta === 'function' ? '/buy?stream=deltas&soft_timeout=1' : '/buy?stream=1&soft_timeout=1';
+        const otel = this.trace.otel === false ? null : this.trace.otel ?? await loadOtel();
+        const run = async () => {
+            const headers = traceHeaders(otel, this.trace.traceContext);
+            return turnOf(await this.call('POST', path, body, BUY_TURN_TIMEOUT_MS, streamed ? stream : undefined, headers));
+        };
+        if (!otel)
+            return run();
+        // One `sdk.buy` span per call, a client span (kind 2) the backend's `buy.request` hangs under. It names the
+        // conversation and how the call ended, never what the shopper said.
+        const attributes = { 'agentcard.streamed': streamed };
+        const conversationId = str(body.conversation_id);
+        if (conversationId)
+            attributes['agentcard.conversation_id'] = conversationId;
+        return otel.trace.getTracer('commerce-sdk').startActiveSpan('sdk.buy', { kind: 2, attributes }, async (span) => {
+            try {
+                const turn = await run();
+                if (turn.conversation_id)
+                    span.setAttribute('agentcard.conversation_id', turn.conversation_id);
+                span.setAttribute('agentcard.buy_status', turn.status);
+                return turn;
+            }
+            catch (error) {
+                span.setStatus({ code: 2, message: error instanceof AgentcardApiError ? error.code : 'error' });
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
     async conversation(conversationId, who = {}) {
@@ -618,10 +746,10 @@ export class AgentcardClient {
             throw new TypeError('Name the shopper once: externalUserId, your own id for them, or userId, the Agentcard user id.');
         }
     }
-    async call(method, path, body, timeoutMs, stream) {
+    async call(method, path, body, timeoutMs, stream, extra = {}) {
         let token = await this.bearer();
         for (let attempt = 0;; attempt++) {
-            const answer = await this.send(method, path, token, body, timeoutMs, stream);
+            const answer = await this.send(method, path, token, body, timeoutMs, stream, extra);
             if (answer.status === 401 && attempt === 0 && this.credentials) {
                 token = await this.renewAfter(token);
                 continue;
@@ -639,12 +767,13 @@ export class AgentcardClient {
             throw errorOf(answer.status, answer.body);
         }
     }
-    async send(method, path, token, body, timeoutMs, stream) {
+    async send(method, path, token, body, timeoutMs, stream, extra = {}) {
         let res;
         try {
             res = await this.fetchFn(`${this.baseUrl}${path}`, {
                 method,
                 headers: {
+                    ...extra,
                     authorization: `Bearer ${token}`,
                     accept: stream ? 'text/event-stream, application/json' : 'application/json',
                     ...(body !== undefined ? { 'content-type': 'application/json' } : {}),

package/dist/definition.js

@@ -13,6 +13,7 @@ export const BUY_TOOL_DESCRIPTION = [
     'When the shopper sends a link to a product, such as a buy.trychannel3.com link, put the whole link in `ask` exactly as they sent it, query string included, with their words beside it: Agentcard buys that exact product from the link, so never describe the link in words instead.',
     'Tell the shopper what `reply` says, in your own voice, except the products and stores it lists that reach the shopper as cards.',
     "When `shopper_already_told_looking` is true, the shopper already knows you are working on their request, from a reply or a 👀 on their message, so never acknowledge it again: open with the answer or the question.",
+    'When `shopper_already_read_reply` is true, the shopper already read `reply` as Agentcard wrote it, so never say it again in any words: answer with only what `reply` leaves out, in one short line, or with nothing.',
     'Show the shopper the cart before you confirm it.',
     'When `cart_building` is set, the store is still building that cart: tell the shopper in one short line that its total is on its way, never ask them to confirm it, and confirm it only after they say yes to the total in the message Agentcard sends next.',
     'Ask the shopper for exactly one thing per message: the step `next_action` names, even when `reply` lists more. Never mention a later step, and never ask for the next one until the shopper has done this one.',

package/dist/direct.d.ts

@@ -0,0 +1,50 @@
+import type { BuyNextAction } from './client.js';
+import type { BuyToolInput } from './definition.js';
+/** Why a message goes straight to Agentcard. */
+export type DirectReason = 'product_ask' | 'pick' | 'answer' | 'confirm';
+/** The buy call for a message that goes straight to Agentcard, and why it does. */
+export interface DirectCall {
+    input: BuyToolInput;
+    reason: DirectReason;
+}
+/** What Agentcard last told the shopper, which decides whether a pick or an answer goes straight. */
+export interface DirectContext {
+    /**
+     * True when the shopper's last turn ended on an answer from Agentcard: its last call returned, and
+     * no turn since ran without one. False or left out, only a request to buy goes straight.
+     */
+    answered?: boolean;
+    /** The step Agentcard's last answer asked for, its `next_action`. */
+    nextAction?: BuyNextAction | null;
+    /** Agentcard's last reply, the question a short answer answers. */
+    asked?: string | null;
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. */
+    products?: ReadonlyArray<{
+        productId: string | null;
+        name: string;
+    }>;
+    /** The stores Agentcard's last answer showed, with the `store_id` a pick sends. */
+    stores?: ReadonlyArray<{
+        storeId: string;
+        name: string;
+    }>;
+}
+/**
+ * True when the message asks to buy or book something, read with no context: a shopping verb with what
+ * to get, a product link, a product at a named store, or a table. A question, small talk, a pick or an
+ * answer, a command to the cart, the shopper's own details and anything about the account read false.
+ */
+export declare function isProductAsk(text: string): boolean;
+/**
+ * The call a shopper's message makes straight to Agentcard, with no model deciding it, or null when
+ * your model decides: see the top of this file for what goes straight. `ask` carries the shopper's
+ * words as they sent them, a confirm goes in only for a plain yes to the total Agentcard asked them to
+ * confirm, and a pick names its `product_id` or `store_id` only when the message names one exactly.
+ *
+ * ```ts
+ * directCall('find me usb-c cables under $20'); // { input: { ask: 'find me usb-c cables under $20', confirm: false, ... }, reason: 'product_ask' }
+ * directCall('what time is it'); // null
+ * directCall('yes', { answered: true, nextAction: 'confirm' }); // { input: { ask: 'yes', confirm: true, ... }, reason: 'confirm' }
+ * ```
+ */
+export declare function directCall(shopperText: string, context?: DirectContext): DirectCall | null;

package/dist/direct.js

@@ -0,0 +1,237 @@
+/**
+ * The buy call a shopper's message makes with no model deciding it: `directCall` reads the message, and
+ * what Agentcard last asked the shopper, and returns the call your app sends straight to Agentcard, or
+ * null when your model decides. Only three kinds of message go straight:
+ *
+ * - a request to buy or book something: a shopping verb with what to get (`find me usb-c cables under
+ *   $20`, `i need a gift for my dad`, `add a toothbrush from walmart to my cart`), a product link, a
+ *   product at a named store (`aa batteries on amazon`), or a table (`a table for 2 tonight at 7`);
+ * - a pick of what Agentcard just showed, by a card's tap (`I'll take the KODAK AA (24 Pack) ($13.49)`,
+ *   `Order from Shake Shack`), its place (`the first one`, `#2`, `1 and 3`) or a reference (`that one`);
+ * - the answer to the question Agentcard just asked: the address, name or code it asked for, a short
+ *   answer such as `medium` or `size 9`, or a plain yes to the total it asked the shopper to confirm.
+ *
+ * Everything else goes to the model: a question, small talk, a change of mind (`no`, `wait`, `cancel`),
+ * a command to the cart, and anything about the account, an order or how the chat works. A pick or an
+ * answer goes straight only while the shopper's last turn ended on Agentcard's answer, so a reply to
+ * something your model said reaches your model.
+ *
+ * The rule is tuned for precision over recall: a message that reaches Agentcard by mistake gets a
+ * purchase reply to small talk, while one the model reads by mistake costs only the model's call. On
+ * the 188 labelled messages in `test/fixtures/direct-messages.json`, it sends none it should not.
+ */
+import { ABOUT, ACKNOWLEDGED, CAPABILITY, CART_COMMAND, CHECKOUT, CHITCHAT, FILLER, asksForDetails, isNewRequest, isPickText, namesStore, plain } from './ack.js';
+/** The longest message that goes straight: a long one is read by the model. */
+const MAX_CHARS = 500;
+/** The steps a shopper answers with their own details or a code. */
+const DETAIL_STEPS = new Set(['shipping_details', 'guest_details', 'verification_code']);
+/** The words of a message: plain, with punctuation, `please` and `thanks` taken out. */
+function wordsOf(text) {
+    return plain(text).replace(/[^\p{L}\p{N}\s$'&+./#-]+/gu, ' ').replace(/[!?.,;:]+(?=\s|$)/g, ' ').replace(/[!?,;:]+/g, ' ').replace(/\b(?:please|pls|plz|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/** Words a message opens with before it says anything: a greeting or filler. */
+const OPENING = /^(?:(?:hey+|hi+|hello+|yo|hiya|howdy|good (?:morning|afternoon|evening)|ok|okay|so|um|uh|also|and|alright|cool|great)(?: there)?\s+)+/;
+/** A change of mind, a refusal or a stall: never an answer to send on. */
+const TAKEBACK = /^(?:i'?ll think|let me think|thinking|i'?m thinking|let me check|i'?ll check|i'?ll let you know|no|nope|nah|not (?:yet|now|really|sure)|cancel|stop|wait|hold on|hang on|never ?mind|nvm|forget (?:it|that|about it)|start over|nothing|none|neither|later|maybe|idk|i don'?t know|dunno|not sure|hmm+|um+|uh+|lol|lmao|haha+|ok|okay|k|kk|thanks?|ty|cool|nice|great|wow|oh|ah)\b/;
+/** Words that say the message is about something other than buying, wherever they sit. */
+const NOT_SHOPPING = new RegExp([
+    'joke', 'weather', 'forecast', 'news', 'poem', 'riddle', 'lyrics', 'translate', 'homework', 'essay', 'coding', 'python', 'javascript',
+    'bug', 'error', 'crash(?:ed|es)?', 'broken', 'not working', "doesn'?t work", 'refund', 'return policy', 'password', 'log ?in', 'sign ?in',
+    'account', 'api', 'support', 'customer service', 'agent ?card', 'what time', 'time is it', "today'?s date", 'human', 'real person',
+    'cancel', 'track(?:ing)?', "where'?s my", 'status', 'receipt', 'invoice', 'unsubscribe', 'privacy', 'kyc', 'identity', 'verify',
+    'promo', 'coupon', 'discount code', 'charged', 'charge me', 'balance', 'wallet', 'approve', 'approval', 'link',
+    '(?:my|a|the|new|your|payment|credit|debit|virtual|bank|visa|mastercard) card', 'card (?:number|details|on file)',
+]
+    .map((word) => `\\b${word}\\b`)
+    .join('|'));
+/** A message that opens as a question: the model reads it, unless it asks Agentcard to get something (`can you find me ...`). */
+const QUESTION_START = /^(?:what|whats|what'?s|where|wheres|where'?s|when|why|how|who|whose|which|is|are|was|were|do|does|did|should|shall|will|would|have|has|tell me|explain|any idea|wanna|you)\b/;
+/** A shopping verb and what follows it, after any opening such as `can you`. */
+const SHOP_FRAME = new RegExp('^(?:(?:can|could|would|will) (?:you|u) (?:please )?|please |i\'?d like (?:you )?to |help me )?' +
+    '(?:find(?: me| us)?|search(?: for)?|look(?:ing)? for|look up|show me|shop for|buy(?: me)?|order(?: me)?|purchase|get me|get us|grab(?: me)?|pick up|book(?: me)?|reserve|add|' +
+    "i want|i need|we need|we want|i'?d like|id like|i would like|i'?m looking for|im looking for|we'?re looking for|i'?m after|im after|" +
+    'need|want|can i get|could i get|can i have|could i have|i\'?ll have|send me|get)\\s+(.+)$');
+/** What a shopping verb takes that names nothing to buy: help, a person, a pronoun, the cart, a question. */
+const NOT_AN_ITEM = /^(?:(?:stuff|things|anything|items|products|everything)(?: (?:on|from|at|in|here|there|online)\b.*)?$|help|some help|assistance|someone|somebody|a human|a person|an agent|to (?!(?:buy|order|get|find|book|reserve|purchase|shop|grab|try)\b)\w+|info|information|advice|more info|you|u|me|it|this|that|these|those|them|nothing|out|lost|more|again|a (?:moment|minute|sec|second|break|nap|hug|vacation|friend)|how|what|where|why|when|who|(?:the |my |our )?(?:cart|basket|order|orders|total|purchases?|history|address)|my)\b/;
+/** A verb that needs an object word after it before it names a thing: `add` alone, or `get` with one word, says too little. */
+const MIN_ITEM_CHARS = 3;
+/** Stores a shopper names by brand, so `aa batteries amazon` reads as a product at a store. */
+const STORES = "amazon|walmart|target|best ?buy|costco|home depot|lowe'?s|ebay|etsy|doordash|door dash|uber ?eats|instacart|cvs|walgreens|nike|adidas|sephora|ulta|macy'?s|nordstrom|ikea|wayfair|chewy|whole foods|trader joe'?s|safeway|kroger|old navy|uniqlo|zara|h&m|rei|staples|office depot|barnes (?:&|and) noble|petco|petsmart|aldi|publix|sam'?s club|shein|temu|newegg|lululemon|patagonia|allbirds|glossier|shake shack|chipotle|starbucks|mcdonald'?s|taco bell|five guys|souvla|opentable|resy|1-800-flowers|zappos|kohl'?s|ace hardware|hollister|abercrombie|gap|apple store|dick'?s sporting goods";
+/** A store's own address, such as `livlyclothing.com`. */
+const DOMAIN = '[a-z0-9][a-z0-9-]*\\.(?:com|co|net|org|shop|store|us|uk|ca|io|co\\.uk)';
+/** A thing at a named store: `aa batteries from amazon`, `bows at livlyclothing.com`, `aa batteries amazon`, `tacos near me`. */
+const AT_STORE = new RegExp(`^(?:a |an |some |\\d+ )?[\\p{L}\\p{N}$'&+./-]+(?: [\\p{L}\\p{N}$'&+./-]+){0,9} (?:(?:(?:from|at|on|off) (?:the )?(?:${STORES}|${DOMAIN}))(?: [\\p{L}\\p{N}$'&+./-]+){0,6}|(?:${STORES})|near me)$`, 'u');
+/** Words a thing never opens with: a pronoun or a verb of the chat. */
+const NOT_A_THING = /^(?:i|i'?m|im|i'?ll|ill|i'?ve|ive|we|we'?re|you|u|your|it|its|it'?s|this|that|these|those|they|he|she|my|our|let|lets|let'?s|thank|thanks|just|still|so|not|no|yes|cool|nice|great|love|like|hate|wish|hope|think|guess|really|very|too)\b/;
+/** A table, or a reservation, for a number of people. */
+const TABLE = /^(?:(?:a |an |book (?:a |me a |us a )?)?(?:\w+ )?)?(?:table|reservation|res|booking) for (?:\d{1,2}|one|two|three|four|five|six|seven|eight|ten|twelve)\b/;
+/** A count or size a product is named by: `81 ct`, `30 rolls`, `160ct`, `6 pack`, `12 oz`. */
+const COUNTED = /\b\d+(?:\.\d+)? ?(?:ct|count|pk|pack|packs|rolls?|pcs|pieces|oz|fl oz|ml|lb|lbs|kg|g|gb|tb|mah|inch|in|ft|qt|quart|gallon|gal|capsules|tablets|caplets|gels|bars|cans|bottles)\b/;
+/** Words that tell of something that already happened, not something to get: `returned 3 bottles`, `the 12 pack never came`. */
+const HAPPENED = /\b(?:returned|bought|ordered|got|received|have|had|has|was|were|is|are|did|never|came|arrived|missing|broke|broken|delivered|shipped|yesterday|last)\b/;
+/** A purchase that already happened, which the shopper tells of rather than asks for: `returned my nike shoes yesterday`. */
+const PAST = /\b(?:returned|bought|ordered|received|arrived|came|never|yesterday|last (?:week|time|month|night)|already|refund(?:ed)?|expired)\b/;
+/** A correction of what came before, such as `actually i need AAA not AA`: the model reads it with what it corrects. */
+const CORRECTION = /^(?:actually|instead|no|nah|nope|wait|oh wait|hmm|oops|sorry|i meant|meant)\b|\bnot\b|\binstead\b/;
+/** Words that point at something only the shopper knows, such as `the usual` or `my home address`, or at a step to repeat. */
+const REFERS = /\b(?:whatever|anything|up to you|you pick|you choose|your call|surprise me|dealer'?s choice|usual|same as|as before|like before|like last time|my (?:home|work|office|regular|normal)\b|code|again)\b/;
+/** A complaint or a joke at a price or a store, which asks for nothing: `another $9.99 delivery fee on doordash`, `duracell is a ripoff`. */
+const COMPLAINT = /\b(?:fees?|ripoff|rip off|scam|overpriced|ugh|smh|annoying|terrible|worst|sucks|hate|love that|tbh|lol|lmao|wtf|seriously|bruh)\b/;
+const LINK = /\bhttps?:\/\/\S+|\bwww\.\S+/i;
+/**
+ * True when the message asks to buy or book something, read with no context: a shopping verb with what
+ * to get, a product link, a product at a named store, or a table. A question, small talk, a pick or an
+ * answer, a command to the cart, the shopper's own details and anything about the account read false.
+ */
+export function isProductAsk(text) {
+    const raw = String(text ?? '');
+    if (raw.length > MAX_CHARS)
+        return false;
+    const words = wordsOf(raw);
+    if (!/[\p{L}]/u.test(words))
+        return false;
+    const bare = words.replace(OPENING, '');
+    if (LINK.test(raw))
+        return !QUESTION_START.test(bare) && !NOT_SHOPPING.test(words.replace(/\S*https?:\/\/\S+|\S*www\.\S+/g, ''));
+    if (!isNewRequest(raw) || CAPABILITY.test(words) || NOT_SHOPPING.test(words) || PAST.test(words) || CORRECTION.test(words) || REFERS.test(words) || COMPLAINT.test(words))
+        return false;
+    // A question goes to the model, unless it asks Agentcard to get something: `can you find me usb-c cables?`.
+    const framed = SHOP_FRAME.exec(bare);
+    if (/\?/.test(raw) && !(framed && /^(?:can|could|would|will) (?:you|u)\b/.test(bare)))
+        return false;
+    if (QUESTION_START.test(bare))
+        return false;
+    if (framed) {
+        const item = framed[1].trim();
+        return item.length >= MIN_ITEM_CHARS && !NOT_AN_ITEM.test(item);
+    }
+    if (TABLE.test(bare))
+        return true;
+    // A product named with its count or size, such as `tide pods 81 ct` or `kirkland toilet paper 30 rolls`, with no verb.
+    if (COUNTED.test(bare) && !NOT_A_THING.test(bare) && !HAPPENED.test(bare) && bare.split(' ').length <= 10)
+        return true;
+    return AT_STORE.test(bare) && !NOT_A_THING.test(bare);
+}
+/** A plain yes: to a total, the go-ahead that confirms it. */
+const YES = /^(?:y|ya|yes+|yeah|yea|yep|yup|sure|confirm(?:ed)?|sounds good|looks good|perfect|yes (?:please|place it|go ahead|do it|confirm|that'?s right|correct))$/;
+function isYes(words) {
+    if (YES.test(words) || CHECKOUT.test(words))
+        return true;
+    // A yes, then the go-ahead in other words: `yep go ahead`, `ok do it`, `yes, place the order`, `sure, sounds good`.
+    const rest = words.replace(FILLER, '');
+    return rest !== words && (rest === '' || YES.test(rest) || CHECKOUT.test(rest));
+}
+/** Words that open a new request or a question rather than a short answer. */
+const REQUEST_START = /^(?:find|search|look|show|get|order|buy|book|can|could|would|will|what|which|how|is|are|do|does|did|i want|i need|please)\b/;
+/** Words that open an objection to giving details: the model answers it. */
+const OBJECTION = /\b(?:expired|wrong|invalid|another|new code|resend|lol|don'?t|do not|won'?t|didn'?t|did not|haven'?t|not|never|no|rather not|why|what|where|how|privacy|safe|secure|instead|different|change)\b/;
+/** Words that weigh a product rather than pick it: `duracell is too expensive`, `energizer instead of these`. */
+const DOUBT = /\b(?:far|close|closest|open|hours|distance|minutes|rating|reviews|not|no|too|expensive|cheaper|pricey|better|worse|than|instead|vs|versus|or|compare|difference|why|isn'?t|aren'?t|don'?t|doesn'?t|hate|meh)\b/;
+const ORDINALS = { first: 1, second: 2, third: 3, fourth: 4, fifth: 5, sixth: 6, seventh: 7, eighth: 8 };
+/** The places in a list a message names, such as `1 and 3` or `the second one`, in order: empty when it names none. */
+function placesOf(bare, count) {
+    const said = bare.replace(/^(?:i'?ll take|i'?ll do|i'?ll go with|go with|let'?s do|lets do|i want|give me|get me|add|the|both|option|options|number|numbers|item|#)\s*/g, ' ');
+    const tokens = said.match(/#?\d{1,2}(?:st|nd|rd|th)?|first|second|third|fourth|fifth|sixth|seventh|eighth|last/g) ?? [];
+    // The places stand alone, joined by `and` or a comma, with only `the`, `one`, `ones`, `option` or `#` around them.
+    const rest = said.replace(/#?\d{1,2}(?:st|nd|rd|th)?|first|second|third|fourth|fifth|sixth|seventh|eighth|last|\band\b|&|\+|,|\bthe\b|\bones?\b|\boptions?\b|\bnumbers?\b|\bitems?\b|#|\bplease\b/g, ' ').trim();
+    if (tokens.length === 0 || rest !== '')
+        return null;
+    const places = tokens.map((token) => (token === 'last' ? count : ORDINALS[token] ?? Number(token.replace(/\D/g, ''))));
+    return places.every((place) => place >= 1 && place <= count) ? places : null;
+}
+/** Text as lowercase words with single spaces, as the tool compares a product's name with a tap. */
+function nameWords(text) {
+    return String(text ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+}
+/** The pick a message makes of what Agentcard just showed, null when it picks nothing, or false when it counts past the list. */
+function pickOf(raw, bare, context) {
+    const products = context.products ?? [];
+    const stores = context.stores ?? [];
+    const call = (fields) => ({ input: { ask: raw, confirm: false, new_order: false, product_id: null, store_id: null, ...fields }, reason: 'pick' });
+    if (stores.length > 0) {
+        const said = ` ${nameWords(raw)} `;
+        // A store's card names it whole; a store named with the dishes to order from it (`five guys, bacon cheeseburger`) picks it too.
+        const named = stores.filter((store) => namesStore(raw, [store.name]) || (nameWords(store.name).length >= 5 && said.includes(` ${nameWords(store.name)} `)));
+        if (named.length === 1 && !QUESTION_START.test(bare) && !DOUBT.test(said))
+            return call({ store_id: named[0].storeId });
+        if (named.length > 0 && (QUESTION_START.test(bare) || DOUBT.test(said)))
+            return false;
+        if (named.length > 1)
+            return call({});
+    }
+    if (products.length > 0) {
+        // A card's tap names the product whole: `I'll take the KODAK AA Alkaline Batteries (24 Pack) ($13.49)`.
+        const said = nameWords(raw);
+        const named = products.filter((product) => nameWords(product.name).length >= 12 && said.includes(nameWords(product.name)));
+        if (named.length === 1)
+            return call({ product_id: named[0].productId });
+        if (named.length > 1)
+            return call({});
+        // A word only one product's name holds, such as its brand: `lets do the coppertop ones`, `duracell 24 count is fine`.
+        const words = new Set(said.split(' '));
+        const owners = (word) => products.filter((product) => nameWords(product.name).split(' ').includes(word));
+        const marked = products.filter((product) => nameWords(product.name).split(' ').some((word) => word.length >= 4 && !/^\d/.test(word) && words.has(word) && owners(word).length === 1));
+        if (marked.length === 1 && said.split(' ').length <= 10 && !QUESTION_START.test(bare) && !DOUBT.test(said))
+            return call({ product_id: marked[0].productId });
+        const places = placesOf(bare, products.length);
+        if (places)
+            return call(places.length === 1 ? { product_id: products[places[0] - 1].productId } : {});
+        // A place past the end of the list picks nothing the shopper saw.
+        if (placesOf(bare, Number.MAX_SAFE_INTEGER))
+            return false;
+        if (/^(?:both|all|all of them|both of them|all three|all 3)$/.test(bare))
+            return call({});
+    }
+    if ((products.length > 0 || stores.length > 0) && isPickText(raw))
+        return call({});
+    return null;
+}
+/**
+ * The call a shopper's message makes straight to Agentcard, with no model deciding it, or null when
+ * your model decides: see the top of this file for what goes straight. `ask` carries the shopper's
+ * words as they sent them, a confirm goes in only for a plain yes to the total Agentcard asked them to
+ * confirm, and a pick names its `product_id` or `store_id` only when the message names one exactly.
+ *
+ * ```ts
+ * directCall('find me usb-c cables under $20'); // { input: { ask: 'find me usb-c cables under $20', confirm: false, ... }, reason: 'product_ask' }
+ * directCall('what time is it'); // null
+ * directCall('yes', { answered: true, nextAction: 'confirm' }); // { input: { ask: 'yes', confirm: true, ... }, reason: 'confirm' }
+ * ```
+ */
+export function directCall(shopperText, context = {}) {
+    const raw = String(shopperText ?? '').trim();
+    if (raw === '' || raw.length > MAX_CHARS)
+        return null;
+    const ctx = context ?? {};
+    const words = wordsOf(raw);
+    if (!/[\p{L}\p{N}]/u.test(words))
+        return null;
+    const bare = words.replace(OPENING, '') || words;
+    const plainCall = (reason, confirm = false) => ({ input: { ask: raw, confirm, new_order: false, product_id: null, store_id: null }, reason });
+    if (ctx.answered === true && !/\?/.test(raw)) {
+        const told = CHITCHAT.test(words) || ABOUT.test(words) || CART_COMMAND.test(words) || CAPABILITY.test(words);
+        if (ctx.nextAction === 'confirm' && isYes(words))
+            return plainCall('confirm', true);
+        // A question, a story of what happened, an objection or a change of mind is the model's to answer, whatever came before.
+        const aside = QUESTION_START.test(bare) || REFERS.test(words) || COMPLAINT.test(words) || PAST.test(words) || NOT_SHOPPING.test(words) || OBJECTION.test(words) || CORRECTION.test(words);
+        if (!told && !aside && !TAKEBACK.test(words)) {
+            const pick = pickOf(raw, bare, ctx);
+            if (pick === false)
+                return null;
+            if (pick)
+                return pick;
+            // The address, name or code Agentcard asked for: what the shopper sends is the answer, unless it objects.
+            const details = (typeof ctx.nextAction === 'string' && DETAIL_STEPS.has(ctx.nextAction)) || asksForDetails(ctx.asked);
+            if (details && !OBJECTION.test(words) && !REQUEST_START.test(bare) && !QUESTION_START.test(bare) && !PAST.test(words) && !/\b(?:same as|on file|you have|the usual|ur|your)\b/.test(words) && !/^(?:resend|send|again|still)\b/.test(bare) && !NOT_SHOPPING.test(words) && words.split(' ').length <= 40)
+                return plainCall('answer');
+            // A short answer to Agentcard's question, such as `medium` after `what size?`, or a yes to `want me to check amazon?`.
+            if (/\?/.test(String(ctx.asked ?? '')) && ctx.nextAction !== 'confirm' && !NOT_SHOPPING.test(words)) {
+                if (isYes(words))
+                    return plainCall('answer');
+                if (!ACKNOWLEDGED.test(words) && words.split(' ').length <= 4 && !REQUEST_START.test(bare))
+                    return plainCall('answer');
+            }
+        }
+    }
+    return isProductAsk(raw) ? plainCall('product_ask') : null;
+}

package/dist/events.d.ts

@@ -3,7 +3,7 @@
  * name. The stream (`agentcard.listen`) and a webhook endpoint carry the same types, with the same
  * envelope and the same ids. A test holds this list to the backend's catalog.
  */
-export declare const AGENTCARD_EVENT_TYPES: readonly ["card.created", "card.updated", "card.closed", "cardholder.created", "cardholder.updated", "transaction.authorized", "transaction.declined", "transaction.cleared", "transaction.voided", "balance.low", "cardholder_onboarding_session.completed", "platform_connect_session.completed", "merchant.connected", "order.placed", "order.confirmed", "order.failed", "order.updated", "purchase.message", "connection.created", "connected_card.updated", "vault.card_stored", "vault.session_linked", "vault.session_card_picked", "vault.payment_permission.updated", "action.confirmed", "action.done", "checkout_authorization.approved", "checkout_authorization.submitted", "checkout_authorization.declined", "checkout_authorization.cancelled", "checkout_authorization.expired", "checkout_authorization.duplicate_charge", "checkout_authorization.refused", "checkout_authorization.watched", "checkout_authorization.amount_mismatch", "checkout_authorization.settled", "checkout_authorization.settlement_unconfirmed", "checkout_authorization.outcome_reported", "card_flow.started", "card_flow.failed", "transfer.approved", "transfer.initiated", "transfer.completed", "transfer.failed", "transfer.released", "wallet.funded", "user_wallet.funding_detected", "user_wallet.funded", "wallet.balance.low", "recovery.requested", "recovery.completed", "recovery.rejected", "wallet.withdrawal.initiated", "wallet.withdrawal.completed", "wallet.withdrawal.failed", "identity.verification.updated", "approval.requested", "reward.earned", "reward.reversed", "wallet_link.opened"];
+export declare const AGENTCARD_EVENT_TYPES: readonly ['card.created', 'card.updated', 'card.closed', 'cardholder.created', 'cardholder.updated', 'transaction.authorized', 'transaction.declined', 'transaction.cleared', 'transaction.voided', 'balance.low', 'cardholder_onboarding_session.completed', 'platform_connect_session.completed', 'merchant.connected', 'order.placed', 'order.confirmed', 'order.failed', 'order.updated', 'purchase.message', 'connection.created', 'connected_card.updated', 'vault.card_stored', 'vault.session_linked', 'vault.session_card_picked', 'vault.payment_permission.updated', 'action.confirmed', 'action.done', 'checkout_authorization.approved', 'checkout_authorization.submitted', 'checkout_authorization.declined', 'checkout_authorization.cancelled', 'checkout_authorization.expired', 'checkout_authorization.duplicate_charge', 'checkout_authorization.refused', 'checkout_authorization.watched', 'checkout_authorization.amount_mismatch', 'checkout_authorization.settled', 'checkout_authorization.settlement_unconfirmed', 'checkout_authorization.outcome_reported', 'card_flow.started', 'card_flow.failed', 'transfer.approved', 'transfer.initiated', 'transfer.completed', 'transfer.failed', 'transfer.released', 'wallet.funded', 'user_wallet.funding_detected', 'user_wallet.funded', 'wallet.balance.low', 'recovery.requested', 'recovery.completed', 'recovery.rejected', 'wallet.withdrawal.initiated', 'wallet.withdrawal.completed', 'wallet.withdrawal.failed', 'identity.verification.updated', 'approval.requested', 'reward.earned', 'reward.reversed', 'wallet_link.opened'];
 /** One event type Agentcard sends. A type Agentcard adds later still reads as its own name. */
 export type AgentcardEventType = (typeof AGENTCARD_EVENT_TYPES)[number];
 /** Whether a filter entry names something Agentcard sends: an event type, a family such as `order.*`, or `*`. */

package/dist/index.d.ts

@@ -2,12 +2,13 @@ export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatur
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, } from './client.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
-export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
+export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION, type AckForOptions } from './ack.js';
-export { forModel, forModelError, replyAsWritten, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
+export { directCall, isProductAsk, type DirectCall, type DirectContext, type DirectReason } from './direct.js';
+export { forModel, forModelError, replyAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';