@agent-cards/commerce-sdk 0.13.0 → 0.14.0

package/dist/index.js

@@ -7,7 +7,8 @@ export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInp
 export { toMessages, messageStream, typingDelay, } from './messages.js';
 export { buyTool, nextStepPrompt, productAction, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION } from './ack.js';
-export { forModel, forModelError, replyAsWritten, stripLinks, } from './model-view.js';
+export { directCall, isProductAsk } from './direct.js';
+export { forModel, forModelError, replyAsWritten, withoutCardList, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';

package/dist/model-view.d.ts

@@ -26,6 +26,7 @@ export interface BuyToolModelCart {
         variant: string | null;
     }>;
     fees: string | null;
+    fees_status?: 'known' | 'pending' | 'unknown';
     /** The store's own fee and tax lines inside `fees`, by the store's labels. Empty when it itemized none. */
     fee_lines: Array<{
         label: string;
@@ -89,6 +90,8 @@ export interface BuyToolModelView {
     shopper_need_not_reply: boolean;
     /** True when the shopper already got a message this turn saying their request is being worked on, so the reply opens with no acknowledgement of its own. */
     shopper_already_told_looking: boolean;
+    /** True when the shopper already read `reply`, every message of it, as Agentcard wrote it, so the answer adds only what it leaves out. */
+    shopper_already_read_reply: boolean;
     /** True when the shopper already has the link this answer needed. */
     link_sent: boolean;
     /**
@@ -179,12 +182,26 @@ export declare function forModel(result: BuyToolResult): BuyToolModelView;
  * Null for any other answer, which your model puts in its own words, and for a line the tool wrote
  * itself for your model, such as the note that the cart changed or a `nextStep` turn's ask for the
  * shopper's yes: only the reply Agentcard sent, as `envelope` holds it, is written for the shopper.
+ * Null as well once the shopper read the reply through `onText` (`shopper_already_read_reply`).
  *
  * ```ts
  * replyAsWritten(result); // 'found two at Amazon. want the first one?'
  * ```
  */
 export declare function replyAsWritten(result: BuyToolResult): string | null;
+/**
+ * Agentcard's reply without the list its cards already show the shopper: each list line that names a product or
+ * store whose card went out, the line that led into that list (`here are a few:`, `other choices:`), a sentence that
+ * points at a number the list gave (`the dishwand in #8`), and, past the one or two products a reply recommends in
+ * words, each further sentence that names another card. What is left is the reply around the list, such as `found
+ * these at amazon.` and `which one do you want?`. A reply whose cards went out names none of them twice over.
+ *
+ * ```ts
+ * withoutCardList('Two I'd suggest:\n- Duracell AA, 24 pack, $20.78\n\nWhich one?', ['Duracell AA Batteries, 24 Count']);
+ * // 'Which one?'
+ * ```
+ */
+export declare function withoutCardList(reply: string, cardNames: readonly string[]): string;
 /**
  * A thrown error as the model may read it: the same message with every link
  * taken out, and the original error on `cause` for your logs. A TypeError

package/dist/model-view.js

@@ -159,7 +159,8 @@ function cartView(cart) {
             options: (line.options ?? []).map(stripLinks).filter((o) => o !== ''),
             variant: line.variant ? stripLinks(line.variant) || null : null,
         })),
-        fees: cart.serviceFeesCents > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
+        fees: cart.serviceFeesCents !== null && cart.serviceFeesCents > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
+        fees_status: cart.serviceFeesStatus,
         fee_lines: (cart.merchantFeeLines ?? []).map((line) => ({ label: stripLinks(line.label), amount: money(line.amountCents, cart.currency) })),
         tip: cart.tipCents > 0 ? money(cart.tipCents, cart.currency) : null,
         total: money(cart.totalCents, cart.currency) ?? money(0, cart.currency),
@@ -226,6 +227,7 @@ export function forModel(result) {
         // A step's ask is one short line: an approval Agentcard places on its own needs no "no need to reply" beside it.
         shopper_need_not_reply: result.shopper_need_not_reply === true && !STEP_ACTIONS.has(result.next_action ?? ''),
         shopper_already_told_looking: result.shopper_already_told_looking === true,
+        shopper_already_read_reply: result.shopper_already_read_reply === true,
         link_sent: result.link_sent === true,
         links_sent: result.link_sent === true
             ? [...new Set((result.links ?? []).map((link) => link.kind).filter((kind) => kind === 'vault' || kind === 'approval' || kind === 'store_login'))]
@@ -249,17 +251,140 @@ export function forModel(result) {
  * Null for any other answer, which your model puts in its own words, and for a line the tool wrote
  * itself for your model, such as the note that the cart changed or a `nextStep` turn's ask for the
  * shopper's yes: only the reply Agentcard sent, as `envelope` holds it, is written for the shopper.
+ * Null as well once the shopper read the reply through `onText` (`shopper_already_read_reply`).
  *
  * ```ts
  * replyAsWritten(result); // 'found two at Amazon. want the first one?'
  * ```
  */
 export function replyAsWritten(result) {
+    // The shopper already read every message of it through onText: handing it out again would say it twice.
+    if (result.shopper_already_read_reply === true)
+        return null;
     // The tool's own lines tell the model what to say, so only Agentcard's reply, unchanged, goes out as is.
     const agentcards = typeof result.envelope?.reply === 'string' && result.envelope.reply === result.reply;
     const view = forModel(result);
     const reply = view.reply.trim();
-    return agentcards && view.status === 'needs_input' && reply !== '' ? reply : null;
+    if (!agentcards || view.status !== 'needs_input' || reply === '')
+        return null;
+    const cards = [...view.products.filter((product) => product.link_sent).map((product) => product.name), ...view.stores.filter((store) => store.link_sent).map((store) => store.name)];
+    // A reply with nothing left once the cards' list comes out is your model's to word.
+    return withoutCardList(reply, cards) || null;
+}
+/** A line that opens a list: `- `, `* `, `• `, `1. ` or `1) `. */
+const LIST_ITEM = /^\s*(?:[-*•]|\d{1,2}[.)])\s+/;
+/** A price, in any of the currencies a store writes one in. */
+const PRICE = /[$£€]\s?\d/;
+/** The place a sentence points at in a numbered list, such as `#8` or `number 3`, where `a #2 Phillips head` names a kind of thing. */
+const LIST_NUMBER = /(?<!\ba )(?<!\ban )(?:#(\d{1,2})\b|\bnumber (\d{1,2})\b)/i;
+/** A unit a size or a count is written in, so `10 ft`, `10-ft` and `10ft` read as one word. */
+const UNIT = /(\d)[\s-]+(ft|feet|foot|inch|inches|oz|fl|ml|l|g|kg|lb|lbs|gb|tb|mb|w|mah|v|cm|mm|m|pack|pk|ct|count|pcs|pieces)\b/gi;
+/**
+ * A size one text spells one way and a card's name another, so `24 pack` reads as the card's `24 Count`. Inches lose
+ * their unit, so `41 in black` reads as the card's `41` and `10 in` as its `10in`: `in` is a word as often as a unit.
+ */
+const SAME_UNIT = new Map([['feet', 'ft'], ['foot', 'ft'], ['in', ''], ['inch', ''], ['inches', ''], ['pk', 'pack'], ['ct', 'pack'], ['count', 'pack'], ['pcs', 'pack'], ['pieces', 'pack'], ['lbs', 'lb']]);
+/** A size or a count written as one word, such as `24pack` or `10ft`. */
+const SIZE = /^(\d+)(\p{L}+)$/u;
+/** A text's words, lowercased, letters and digits only, with markdown's bold marks gone and a size written as one word. */
+function wordsOf(text) {
+    return text
+        .toLowerCase()
+        .replace(UNIT, '$1$2')
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((word) => word !== '')
+        .map((word) => word.replace(SIZE, (whole, count, unit) => `${count}${SAME_UNIT.get(unit) ?? unit}`));
+}
+/**
+ * The card a text names, by the first six words of the card's name: at least two of them, and most of them, in the
+ * text. Null when it names none. A name of one word never counts in prose, where a generic word such as `soap` would.
+ * A size or a count among those words has to be in the text too, so the 3ft cable's line never reads as the 10ft card.
+ */
+function cardNamed(text, cards, inList) {
+    const said = new Set(wordsOf(text));
+    for (const [index, name] of cards.entries()) {
+        const head = name.slice(0, 6);
+        if (!head.every((word) => !/\d/.test(word) || said.has(word)))
+            continue;
+        const hits = head.filter((word) => said.has(word)).length;
+        if (head.length === 1 ? inList && hits === 1 : hits >= Math.max(2, Math.ceil(head.length * 0.6)))
+            return index;
+    }
+    return null;
+}
+/**
+ * Agentcard's reply without the list its cards already show the shopper: each list line that names a product or
+ * store whose card went out, the line that led into that list (`here are a few:`, `other choices:`), a sentence that
+ * points at a number the list gave (`the dishwand in #8`), and, past the one or two products a reply recommends in
+ * words, each further sentence that names another card. What is left is the reply around the list, such as `found
+ * these at amazon.` and `which one do you want?`. A reply whose cards went out names none of them twice over.
+ *
+ * ```ts
+ * withoutCardList('Two I'd suggest:\n- Duracell AA, 24 pack, $20.78\n\nWhich one?', ['Duracell AA Batteries, 24 Count']);
+ * // 'Which one?'
+ * ```
+ */
+export function withoutCardList(reply, cardNames) {
+    const cards = cardNames.map(wordsOf).filter((name) => name.length > 0);
+    if (cards.length === 0)
+        return reply.trim();
+    // A text that opens with a card's name and gives its price is a list line, as a reply writes one without a bullet.
+    const opensCard = (text) => {
+        const words = wordsOf(text);
+        return PRICE.test(text) && cards.some((name) => name.length >= 2 && name.slice(0, 3).every((word, i) => words[i] === word));
+    };
+    const lines = reply.split('\n');
+    const kind = lines.map((line) => {
+        if (LIST_ITEM.test(line))
+            return cardNamed(line.replace(LIST_ITEM, ''), cards, true) !== null ? 'item' : 'kept';
+        return opensCard(line) ? 'named' : 'kept';
+    });
+    const dropped = kind.map((of) => of !== 'kept');
+    // The numbers the dropped list gave, so a number of a product's own, `a #2 Phillips head`, keeps its sentence.
+    const numbers = new Set(lines.flatMap((line, i) => (dropped[i] ? [Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1])] : [])).filter((number) => Number.isInteger(number)));
+    // The list a line leads into: the lines from the next one with words on it to the first that is not a list line, so a
+    // question on the line after the last item, `Which one?`, is no part of the list.
+    const listAfter = (line) => {
+        const start = lines.findIndex((after, j) => j > line && after.trim() !== '');
+        if (start === -1)
+            return [];
+        let end = start;
+        while (end < lines.length && (LIST_ITEM.test(lines[end]) || kind[end] === 'named'))
+            end += 1;
+        return dropped.slice(start, end);
+    };
+    const named = new Set();
+    const kept = [];
+    lines.forEach((line, i) => {
+        if (kind[i] === 'item')
+            return;
+        let text = line;
+        // The line that leads into a list whose every line went loses the sentence that leads in: `Two I'd suggest:` or
+        // `Other choices:`. A list that keeps a line, for a product no card shows, keeps its lead too.
+        const list = listAfter(i);
+        if (text.trim().endsWith(':') && list.length > 0 && list.every(Boolean))
+            text = text.trim().replace(/(?:^|(?<=[.!?])\s+)[^.!?]*:$/, '');
+        const sentences = text.split(/(?<=[.!?])\s+/).filter((sentence) => {
+            const place = LIST_NUMBER.exec(sentence);
+            if (place && numbers.has(Number(place[1] ?? place[2])))
+                return false;
+            const card = cardNamed(sentence, cards, false);
+            // A list line written without a bullet keeps the sentences its card does not say, such as the question after it.
+            if (kind[i] === 'named')
+                return card === null && !opensCard(sentence);
+            if (card === null || named.has(card))
+                return true;
+            // A reply recommends one or two products in words; a sentence that names a third is the list again.
+            if (named.size >= 2)
+                return false;
+            named.add(card);
+            return true;
+        });
+        if (kind[i] === 'named' && sentences.length === 0)
+            return;
+        kept.push(sentences.join(' ').trimEnd());
+    });
+    return kept.join('\n').replace(/\n{3,}/g, '\n\n').trim();
 }
 /**
  * A thrown error as the model may read it: the same message with every link

package/dist/shopper-message.d.ts

@@ -9,7 +9,7 @@ import { type PurchaseFacts, type PurchaseMessageKind } from './message.js';
  * The event types that carry a message for a shopper. Subscribe your endpoint to each by name:
  * a catch-all `*` alone does not turn `purchase.message` on.
  */
-export declare const SHOPPER_EVENT_TYPES: readonly ["purchase.message", "order.confirmed", "order.updated"];
+export declare const SHOPPER_EVENT_TYPES: readonly ['purchase.message', 'order.confirmed', 'order.updated'];
 /** One of the event types that carry a message for a shopper. */
 export type ShopperEventType = (typeof SHOPPER_EVENT_TYPES)[number];
 /**
@@ -18,7 +18,7 @@ export type ShopperEventType = (typeof SHOPPER_EVENT_TYPES)[number];
  * to the store (`store_connected`), or declined the approval (`approval_declined`), outside the chat.
  * `buy.nextStep(message)` opens that turn. Every other kind's `text` is the whole message: post it as is.
  */
-export declare const NEXT_STEP_KINDS: readonly ["card_added", "store_connected", "approval_declined"];
+export declare const NEXT_STEP_KINDS: readonly ['card_added', 'store_connected', 'approval_declined'];
 /** A kind after which the agent takes the next step on its own. */
 export type NextStepKind = (typeof NEXT_STEP_KINDS)[number];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
   "type": "module",
   "main": "dist/index.js",
@@ -40,6 +40,14 @@
     "webhooks",
     "purchases"
   ],
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18"
   },