@agent-cards/commerce-sdk 0.18.0 → 0.18.2

package/README.md

@@ -136,7 +136,7 @@ console.log(await result.getText());
 
 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 eight 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`, or `from $10.69` for a product priced by a size or another choice the shopper makes, such as a burger whose patty count sets its price, Agentcard's id for it in `productId`, what taking it does in `action` (`reserve` for a restaurant table, `book` for a flight, room, class or ticket, `buy` for anything else, so a button can say Reserve instead of Buy this), its picture in `imageUrl`, or null when the store sent none, and every photo of the product in `images`, `imageUrl` first and at most eight, so a card can show the others as thumbnails that swap the main picture. `images` holds one entry for a product with one photo and none for a product with none. 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. Each product gets its own link, so the three dishes a restaurant's reply offers are three cards, though they share the store's one page. A flight has no page at a store, so each flight a search finds is a `product` link whose `url` is null, with the airline, the route and its times in `title`: show it as a card with no link to open, and hand its `productId` back as the shopper's pick. The model reads `product_links_sent` and never a URL. The tool's description tells it that the shopper already sees those products as cards, so its reply never lists them again by name or price: it writes one short line, such as which one they want, and a shopper who asks for links hears that the links are there. When a later answer in the conversation only stands beside the same products, as a cart answer does, the tool sends none of their links again. When a later turn's reply presents them again, as the answer to a repeated ask does, the tool sends their links again, so every product the reply names arrives with its link. A product link your `sendLink` throws on counts as not sent, and the call goes on.
+The tool also hands `sendLink` a `product` link for each product a search finds, up to eight 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`, or `from $10.69` for a product priced by a size or another choice the shopper makes, such as a burger whose patty count sets its price, Agentcard's id for it in `productId`, what taking it does in `action` (`reserve` for a restaurant table, `book` for a flight, room, class or ticket, `buy` for anything else, so a button can say Reserve instead of Buy this), its picture in `imageUrl`, or null when the store sent none, and every photo of the product in `images`, `imageUrl` first and at most eight, so a card can show the others as thumbnails that swap the main picture. `images` holds one entry for a product with one photo and none for a product with none. The link names the store that sells the product in `store`, such as `Walmart`, and the store's own website in `storeDomain`, such as `walmart.com` or `jadeyoga.com`, or null when Agentcard knows none, such as a restaurant's: show `storeDomain` on the card as where the product comes from, never the host of `url`, which can be a tracking link. 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. Each product gets its own link, so the three dishes a restaurant's reply offers are three cards, though they share the store's one page. A flight has no page at a store, so each flight a search finds is a `product` link whose `url` is null, with the airline, the route and its times in `title`: show it as a card with no link to open, and hand its `productId` back as the shopper's pick. The model reads `product_links_sent` and never a URL. The tool's description tells it that the shopper already sees those products as cards, so its reply never lists them again by name or price: it writes one short line, such as which one they want, and a shopper who asks for links hears that the links are there. When a later answer in the conversation only stands beside the same products, as a cart answer does, the tool sends none of their links again. When a later turn's reply presents them again, as the answer to a repeated ask does, the tool sends their links again, so every product the reply names arrives with its link. A product link your `sendLink` throws on counts as not sent, and the call goes on.
 
 `productId` holds no link: it is the same `product_id` the model reads for that product, and the page is `url`. An answer that only adds a product the shopper picked lists that product alone, so it sends no card for a product nobody offered on that turn, and the pages the search already sent still count as sent on the answers after it.
 
@@ -362,7 +362,7 @@ async function runModel(shopperId: string, turn: BuyToolTurn) {
 | Saving a card, with no yes and no pick standing | The total and the ask for the yes: `your Souvla chicken salad comes to $17.43 with fees. should i go ahead and place the order?` |
 | Signing in to the store, with a card still to add | The add-card link: `next, add a card with the link i sent. it works for about 24 hours.` |
 | Signing in to the store, with a card on file | The total and the ask for the yes, or the approval link after a yes that stopped for the sign-in |
-| Signing in or saving a card, after a yes, when the store priced its fees and tax in since | The new total, then the next link: `it's $17.89 with fees and tax now. approve the payment to place your order (up to $17.89)` |
+| Signing in or saving a card, after a yes, when the store priced its fees and tax in since | The new total and the ask for the yes, with no link: `The cart changed after your yes: it comes to $17.89 with tax and shipping now. Nothing was paid. Say yes to pay $17.89.` |
 | Declining the approval | `you declined the payment, so you haven't been charged. your chicken salad is still in the cart, so just say yes if you want a new approval link, or tell me what to change` |
 
 With `direct` and `replyAsWritten` on the tool, a step needs no model when its answer is a link: send `step.run(step.direct.input)` first, and when `step.replyAsWritten` is set, post it, with `step.links`, in place of the model's answer. When it is null, as for the ask for a yes, run your model as above.
@@ -370,8 +370,8 @@ With `direct` and `replyAsWritten` on the tool, a step needs no model when its a
 The turn moves the purchase only up to the shopper's own decision, and the tool holds it there whatever the model calls:
 
 - No call of the turn sends an ask to Agentcard, which could read the model's words as the shopper's go-ahead. Each call reads where the purchase stands and answers with the next step: the card link the sign-in held back, or the cart and the ask for the shopper's yes.
-- A confirm goes in only for the yes the shopper already gave in the chat, such as "lets place it", when that confirm stopped for the card or the sign-in they just finished, and the shopper is never asked for that yes again. It goes on past each step, the sign-in and then the card, as long as the cart holds the same items, in the same quantities and at the same prices, at the same store: a total that moved only because the store priced its fees, tax or delivery in keeps the yes, and the next ask says the new total (`yes_carried` on the answer). Each confirm names the cart's hash as it stands, so Agentcard refuses it if the cart changed. A cart whose items, quantities or store changed, a shopper message after the yes that is not a plain go-ahead, such as "wait, make it two", and a declined approval each take the yes back, and the shopper is asked again. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard.
-- A shopper who picked what is in the cart, by tapping a product's card or asking to buy it, and since answered only the checkout's questions (an address, a phone number, a name, an email, a yes to an address read back to them) or said a plain go-ahead, gave the same go-ahead: saving the card or signing in to the store confirms that cart by its hash as it stands, with no ask for a yes (`yes_carried.picked`). A cart whose items, quantities, item prices or store changed since the pick, any other message, such as "actually wait" or a question, and a declined approval take it back.
+- A confirm goes in only for the yes the shopper already gave in the chat, such as "lets place it", when that confirm stopped for the card or the sign-in they just finished, and the shopper is never asked for that yes again. It goes on past each step, the sign-in and then the card, as long as the cart holds the same items, in the same quantities and at the same prices, at the same store. Each confirm names the cart's hash as it stands, and in `carried` the hash of the cart the shopper said yes to: Agentcard pays only that cart, so a total that moved because the store priced its fees, tax or delivery in comes back with the new total and the ask for the shopper's yes, and nothing is paid. A cart whose items, quantities or store changed, a shopper message after the yes that is not a plain go-ahead, such as "wait, make it two", and a declined approval each take the yes back, and the shopper is asked again. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard.
+- A shopper who picked what is in the cart, by tapping a product's card or asking to buy it, and since answered only the checkout's questions (an address, a phone number, a name, an email, a yes to an address read back to them) or said a plain go-ahead, gave the same go-ahead: saving the card or signing in to the store confirms that cart by its hash as it stands, with no ask for a yes (`yes_carried.picked`). The confirm names in `carried` the cart the chat showed, and a cart the store priced again since comes back with its total and the ask for a yes. A cart whose items, quantities, item prices or store changed since the pick, any other message, such as "actually wait" or a question, and a declined approval take it back.
 - The approval in the Vault is still the shopper's: the confirm sends the approval link, which names the most they can be charged, and the order goes in only once they approve it.
 - A shopper who was not connected yet when they asked gets their own first ask run, in their words, once their card is saved.
 

package/dist/ack.d.ts

@@ -20,6 +20,13 @@ export declare const CHITCHAT: RegExp;
  * can you buy aa batteries from`, is a search and keeps its reply.
  */
 export declare const CAPABILITY: RegExp;
+/**
+ * True when the shopper's words ask for other products like one they saw, such as `More like the KODAK AA Alkaline Batteries (60
+ * Pack)`, `something similar to the first one`, `alternatives to the Duracell` or `cheaper than the KODAK one`: a new search,
+ * never a pick of the product it names. `names` are the products the shopper saw: their words are read out first, so a product
+ * whose own name says `alternative` or `similar` is still picked by its tap.
+ */
+export declare function asksForSimilar(text: string, names?: readonly string[]): boolean;
 /**
  * True when the message names one of these stores and nothing else to buy: the store's whole name, or
  * two words of it in a row, such as `el grullense` for `Tacos El Grullense`, alone or after a frame such

package/dist/ack.js

@@ -140,6 +140,45 @@ const PLACE = '(?:first|second|third|fourth|fifth|sixth|last|other|\\d{1,2}(?:st
 const PICK_REF = new RegExp(`^(?:(?:the|that|this) (?:[\\w'$.-]+ ){0,3}one\\b|(?:that|this|those|these|both|it)(?: ones?)?$|the ${PLACE}(?: (?:one|option|item|product|choice|result))?$|${PLACE}(?: (?:one|option|item|product|choice|result)\\b|$)|(?:option|number|item|choice|#) ?#?\\d{1,2}\\b|\\d{1,2}$)`);
 /** A budget word in front of a price, so `under $13.49` stays a search. */
 const BUDGET = /(?:under|below|than|max|maximum|around|about|to|budget|within|over|above|for|most)\s*$/;
+/** What a request for other products opens with before `more like`: `show me more like the KODAK one`, `any more like it`. */
+const MORE_LIKE_LEAD = "(?:(?:ok|okay|hey|hi|so|um|uh|also|and|cool|great|nice|hmm|actually|yes|yeah|can you|could you|can i|could i|i'?d like to|i want to|please)\\s+)*(?:(?:show|find|get|give|send)(?: me| us)?\\s+|(?:i want|i'?d like|i would like|i need|i'?m looking for|im looking for|looking for|search for|look for|do you have|got|have you got|are there|is there|see)\\s+)?(?:some\\s+|any\\s+)?";
+/**
+ * Words that ask for other products like one the shopper saw, never for that product: `more like the KODAK AA (60 Pack)`,
+ * `something similar`, `alternatives to the Duracell`, `cheaper than the KODAK one`, `like the first one but in blue`, and in
+ * Spanish `algo parecido al KODAK`, `más como este`. A number or a price after the words is a correction (`more like $20`,
+ * `something like 2`), and stays out.
+ */
+const SIMILAR = [
+    new RegExp(`^${MORE_LIKE_LEAD}more (?:like|similar)\\b(?!\\s*(?:\\$|\\d))`),
+    /\bmore like (?:the|this|that|these|those|it|them|one|ones)\b/,
+    /\b(?:something|anything|stuff|things|ones|others|other ones|other options|options|products|items|other products|other items|more)(?: else)? (?:like|similar to)\b(?!\s*(?:\$|\d))/,
+    /\bsimilar (?:to|ones?|items?|products?|options?|stuff|things|styles?|kinds?|types?|brands?|models?)\b|\b(?:something|anything|more|some|any|show me|find|see|got|have|want|need|others?) similar\b|^similar\b/,
+    /\b(?:an?|some|any|other|cheaper|good|better|similar) alternatives?\b|\balternatives? (?:to|for|like)\b|^alternatives?\b/,
+    /\b(?:cheaper|less expensive|more affordable|lower[- ]priced|lower cost) than\b(?!\s*(?:\$|\d|(?:that|this|my|the) (?:price|budget)))/,
+    /\blike (?:the|this|that|these|those|it)\b.*\bbut\b|\bbut (?:cheaper|less expensive|more affordable)\b/,
+    /\b(?:anything|something|others?|options?|ones?|products?|items?)(?: else)? (?:other than|besides|apart from)\b/,
+    /\bparecid[oa]s?\b|\bsimilar(?:es)? a[ls]?\b|\balgo (?:como|parecido|similar|as[ií])\b(?!\s*(?:\$|\d))|\bm[aá]s (?:como|del estilo)\b|\botr[oa]s? (?:opciones |cosas |productos |marcas )?(?:como|parecid[oa]s?|similares)\b|\balternativas?\b|\bm[aá]s barat[oa]s? que\b|\bcomo (?:el|la|los|las|este|esta|estos|estas|ese|esa)\b.*\bpero\b/,
+];
+/** Text as lowercase words with single spaces, accents kept, as `asksForSimilar` reads it. */
+function similarWords(text) {
+    return plain(String(text ?? '')).replace(/[^\p{L}\p{N}\s$#'-]+/gu, ' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * True when the shopper's words ask for other products like one they saw, such as `More like the KODAK AA Alkaline Batteries (60
+ * Pack)`, `something similar to the first one`, `alternatives to the Duracell` or `cheaper than the KODAK one`: a new search,
+ * never a pick of the product it names. `names` are the products the shopper saw: their words are read out first, so a product
+ * whose own name says `alternative` or `similar` is still picked by its tap.
+ */
+export function asksForSimilar(text, names = []) {
+    let said = ` ${similarWords(text)} `;
+    for (const name of names) {
+        const own = similarWords(name);
+        if (own.length >= 3)
+            said = said.split(` ${own} `).join(' ');
+    }
+    said = said.replace(/\s+/g, ' ').trim();
+    return said !== '' && SIMILAR.some((pattern) => pattern.test(said));
+}
 /**
  * True for a pick of a product the shopper already saw: a frame such as `i'll take` or `i want the`, a
  * reference such as `that one`, `the second` or `#2`, or a product title with its price, as a product
@@ -147,6 +186,9 @@ const BUDGET = /(?:under|below|than|max|maximum|around|about|to|budget|within|ov
  * gets no instant reply.
  */
 function isPick(line, words) {
+    // `More like the KODAK AA (60 Pack) ($26.05)` names a card to search for others like it: a new search, with its instant reply.
+    if (asksForSimilar(line))
+        return false;
     if (/\(\s*\$\s*\d[\d,]*(?:\.\d{2})?\s*\)/.test(line))
         return true;
     const price = line.match(/\$\s*\d[\d,]*\.\d{2}\s*$/);

package/dist/buy-tool.d.ts

@@ -76,9 +76,16 @@ export interface BuyToolLink {
     expiresAt: string | null;
     /**
      * On a store login link: the store's name, or null when Agentcard named none. On an approval link:
-     * the store whose cart it approves, when the answer names the cart.
+     * the store whose cart it approves, when the answer names the cart. On a product link: the name of
+     * the store that sells it, such as `Walmart` or `jadeyoga.com`, or null when Agentcard named none.
      */
     store?: string | null;
+    /**
+     * On a product link: the website of the store that sells it, such as `walmart.com` or `jadeyoga.com`, to show on the card
+     * as where the product comes from. It is never the host of `url`, which can be a tracking link that names no store. Null
+     * when Agentcard knows no website for the store, such as a restaurant, a venue or an airline.
+     */
+    storeDomain?: string | null;
     /** On a product link: the product's name. */
     title?: string;
     /**
@@ -156,6 +163,8 @@ export interface BuyToolProduct {
     /** Every photo of the product, `imageUrl` first, at most eight; empty when it has none. */
     images: string[];
     store: string | null;
+    /** The website of the store that sells it, such as `walmart.com`, or null when Agentcard knows none. */
+    storeDomain?: string | null;
     /** The product's page at its store, or null when Agentcard sent none. */
     url: string | null;
     /**

package/dist/buy-tool.js

@@ -39,7 +39,7 @@ import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, repl
 import { joinLeadIns, leadInJoiner, messageStream, paceOf, paragraphsOf, sleep, toMessages, typingHook } from './messages.js';
 import { isStale } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
-import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
+import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, asksForSimilar, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
 /** The action a product of `merchant` takes (BuyToolProductAction). */
 export function productAction(merchant) {
     if (merchant === 'reservations')
@@ -210,7 +210,7 @@ function yesAfter(result, yes) {
     const seen = yes.shown ?? stopped;
     if (!seen || (yes.shown && stopped && !sameOrder(yes.shown, stopped)))
         return null;
-    return { conversationId: result.conversation_id, cart: stopped ?? seen, totalCents: seen.totalCents };
+    return { conversationId: result.conversation_id, cart: stopped ?? seen, totalCents: seen.totalCents, consentedHash: seen.hash };
 }
 /** The words of the call a `nextStep` turn's `direct` makes. They never reach Agentcard: the turn's calls send no ask. */
 const NEXT_STEP_ASK = 'take the next step';
@@ -270,7 +270,22 @@ export function productsOf(turn) {
 /** A product's card as `sendLink` hears it: the id the model reads and a pick takes, never the store page, which is `url`. A flight option has no page at a store: its card carries no url, and its productId picks it. */
 function productLink(product) {
     const productId = pickId(product);
-    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
+    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), store: product.store ?? null, storeDomain: product.storeDomain ?? null, expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
+}
+/** A host name: dot-separated labels of letters, digits and hyphens, ending in a letters-only top-level label. */
+const STORE_HOST = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+/**
+ * The website of the store a catalog item is at: the `domain` Agentcard sent, else, from an older API that sends none, the
+ * store's id when the id is itself a website (`jadeyoga.com`). Never Channel3's tracking host (buy.trychannel3.com). Null
+ * when neither names one: a store id such as `walmart` names no website by itself.
+ */
+function storeDomainOf(store) {
+    for (const raw of [store?.domain, store?.id]) {
+        const host = typeof raw === 'string' ? raw.trim().toLowerCase().replace(/^www\./, '').replace(/\.$/, '') : '';
+        if (STORE_HOST.test(host) && host !== 'trychannel3.com' && !host.endsWith('.trychannel3.com'))
+            return host;
+    }
+    return null;
 }
 function productsOfCatalog(catalog) {
     return (catalog.items ?? [])
@@ -286,6 +301,7 @@ function productsOfCatalog(catalog) {
         images: item.image_urls ?? (item.image_url ? [item.image_url] : []),
         ...(item.flight ? { flight: item.flight } : {}),
         store: item.store?.name ?? item.store?.id ?? catalog.merchant_name ?? null,
+        storeDomain: storeDomainOf(item.store),
         url: item.url ?? null,
         action: productAction(catalog.merchant),
         linkSent: false,
@@ -915,8 +931,10 @@ export function buyTool(options) {
     let shownStoreNames = [];
     /** True for a pick of a product or a store the shopper saw, by its name. */
     const namesShown = (text) => namesShownProduct(text) || namesStore(text, shownStoreNames);
+    /** Whether a message asks for other products like one shown (`More like the <card's name>`): a new search, never a pick. */
+    const asksLikeShown = (text) => asksForSimilar(text, [...lastTappable, ...lastAnswerProducts].map((product) => product.name));
     /** What a message picks: a product it names (`product`), a store or a place in a list (`pick`), or nothing (null). */
-    const pickOf = (text) => namesStore(text, shownStoreNames) ? 'pick' : namesShownProduct(text) ? 'product' : isPickText(text) ? 'pick' : null;
+    const pickOf = (text) => asksLikeShown(text) ? null : namesStore(text, shownStoreNames) ? 'pick' : namesShownProduct(text) ? 'product' : isPickText(text) ? 'pick' : null;
     /** How the shopper's message reads for the instant reply: what it picks, and the reply it gets, or null. */
     const ackOfMessage = (shopperText) => {
         const text = String(shopperText ?? '');
@@ -1020,7 +1038,7 @@ export function buyTool(options) {
             };
         }
         // A confirm, or a pick of what the shopper saw, gets fixed words that never say `looking for`.
-        const slow = step ?? t.picked ?? (!t.neutral && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
+        const slow = step ?? t.picked ?? (!t.neutral && !asksLikeShown(ask) && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
         // A short answer to the question the last reply asked, such as `medium` after `what size?`, is no
         // search: like `yes`, a slow call still tells the shopper, in words that look for nothing.
         const neutral = t.neutral || answersQuestion(ask, lastReply);
@@ -1585,7 +1603,7 @@ export function buyTool(options) {
         const inPurchase = (at) => at === null || at === conversationId;
         if (yes && one && conversationId && inPurchase(yes.conversationId) && sameOrder(one, yes.cart)) {
             carriedYes = null;
-            return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who }, yes: { ...yes, cart: one, conversationId } };
+            return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', carried: { from: yes.picked ? 'pick' : 'yes', cart_hash: yes.consentedHash }, ...who }, yes: { ...yes, cart: one, conversationId } };
         }
         // The shopper picked what is in the cart and finished the step outside the chat: finishing it is their go-ahead for the
         // same order, confirmed by the cart's hash as it stands now, and the approval link stays their consent to the payment
@@ -1597,7 +1615,7 @@ export function buyTool(options) {
         if (picked?.cart && one && conversationId && inPurchase(picked.conversationId) && (event.kind === 'card_added' || event.kind === 'store_connected')) {
             pickedOrder = null;
             if (sameOrder(one, picked.cart)) {
-                return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who }, yes: { conversationId, cart: one, totalCents: picked.cart.totalCents, picked: true } };
+                return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', carried: { from: 'pick', cart_hash: picked.cart.hash }, ...who }, yes: { conversationId, cart: one, totalCents: picked.cart.totalCents, consentedHash: picked.cart.hash, picked: true } };
             }
         }
         // A checkout the shopper already moved past their yes (an approval link waiting, or the order going through) is reported as
@@ -1640,7 +1658,9 @@ export function buyTool(options) {
         if (!confirm && ask === '')
             throw new TypeError("Put the shopper's words in ask.");
         // A pick chooses from the products or stores this conversation showed: never on a confirm, and never on a new order, which shows none yet.
-        const picks = !confirm && !newOrder;
+        // A request for other products like one shown is a new search: a `product_id` or `store_id` the model sent beside it would
+        // put that product in the cart (2026-10-27, "More like <a card's whole title>" on 0.18.0), so none goes.
+        const picks = !confirm && !newOrder && !asksLikeShown(ask);
         const pick = picks && input.product_id ? { product_id: input.product_id } : picks && input.store_id ? { store_id: input.store_id } : null;
         const body = {
             resume: true,

package/dist/client.d.ts

@@ -250,6 +250,15 @@ export interface BuyRequest {
     hand_back?: true;
     /** With `hand_back`: what Agentcard's last answer showed and asked, which decides whether a pick or an answer is shopping. */
     last_answer?: BuyLastAnswer;
+    /**
+     * On a confirm the app sends on its own after a step outside the chat (a saved card, a store sign-in): the go-ahead it
+     * carries, a `yes` to a cart or the `pick` of what is in it, and `cart_hash`, the cart it was given for. Agentcard pays
+     * only that cart; a cart that changed since is answered with its total and `next_action: 'confirm'`, and nothing is paid.
+     */
+    carried?: {
+        from: 'yes' | 'pick';
+        cart_hash: string;
+    };
 }
 /** What the shopper's last answer from Agentcard showed and asked, sent with `hand_back`. */
 export interface BuyLastAnswer {
@@ -267,9 +276,14 @@ export interface BuyLastAnswer {
     }>;
 }
 export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
+/**
+ * The store a product or a cart is at. `domain` is the store's own website, such as `walmart.com` or `jadeyoga.com`: on a
+ * catalog item, null when Agentcard knows none (a restaurant, a venue, an airline), and absent from an older API and on a cart.
+ */
 export interface BuyStore {
     id: string;
     name?: string;
+    domain?: string | null;
 }
 export interface BuyCartLine {
     name: string;

package/dist/client.js

@@ -136,7 +136,7 @@ function imagesOf(main, list) {
 function storeOf(v) {
     if (!isRecord(v) || !str(v.id))
         return null;
-    return { id: v.id, ...(str(v.name) ? { name: v.name } : {}) };
+    return { id: v.id, ...(str(v.name) ? { name: v.name } : {}), ...(Object.hasOwn(v, 'domain') ? { domain: str(v.domain) } : {}) };
 }
 function feeLinesOf(v) {
     if (!Array.isArray(v))

package/dist/direct.js

@@ -12,7 +12,11 @@
  *   answer such as `medium` or `size 9`, or a plain yes to the total it asked the shopper to confirm;
  * - a price limit for the products Agentcard just showed: `only options under $20`, `under 20`, `cheaper ones`.
  *   Agentcard holds its cards to the limit and shows the ones inside it again as cards; your model, answering
- *   from the list it saw, named two products with no card to tap (2026-10-27).
+ *   from the list it saw, named two products with no card to tap (2026-10-27);
+ * - a request for other products like one Agentcard just showed: `More like the KODAK AA Alkaline Batteries (60 Pack)`,
+ *   `something similar to the first one`, `cheaper than the KODAK one`. It goes as a new search with no `product_id`:
+ *   on 2026-10-27 (the playground chat on 0.18.0, production /buy) "More like <a card's whole title>" went as a pick of
+ *   that card, and Agentcard put it in the cart and asked for the shipping address.
  *
  * 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
@@ -23,7 +27,7 @@
  * 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';
+import { ABOUT, ACKNOWLEDGED, CAPABILITY, CART_COMMAND, CHECKOUT, CHITCHAT, FILLER, asksForDetails, asksForSimilar, isNewRequest, isPickText, namesStore, plain } from './ack.js';
 /**
  * A price limit put on what was just shown: `under $20`, `under 20`, `less than 15 bucks`, `between 10 and 20`, `$20 or
  * less`, `over $50`, `cheaper ones`, `menos de 20`. Only whether the message states one: Agentcard reads the limit itself.
@@ -164,6 +168,9 @@ function pickOf(raw, bare, context) {
     const byName = context.tappable?.length ? context.tappable : 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' });
+    // `More like the <card's whole name>` names a card to find others like it: it picks nothing.
+    if (asksForSimilar(raw, [...byName, ...products].map((product) => product.name)))
+        return null;
     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.
@@ -236,6 +243,12 @@ export function directCall(shopperText, context = {}) {
         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 request for other products like one just shown is a new search, never a pick of the one it names: it goes with no
+        // `product_id`, and Agentcard searches for products like it and leaves it out.
+        const shown = [...(ctx.tappable ?? []), ...(ctx.products ?? [])];
+        if (!told && (shown.length > 0 || (ctx.stores ?? []).length > 0) && asksForSimilar(raw, shown.map((product) => product.name))) {
+            return NOT_SHOPPING.test(words) || TAKEBACK.test(words) ? null : plainCall('product_ask');
+        }
         // 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)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "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",