@agent-cards/commerce-sdk 0.5.0 → 0.9.0

package/dist/model-view.d.ts

@@ -4,10 +4,11 @@
  * model that holds a link writes it into the chat. So a link never enters
  * this view: `sendLink` delivers it, and the model reads `link_sent` for the
  * Vault and approval links, and `link_sent` on each product and
- * `product_links_sent` for the products' store pages.
+ * `product_links_sent` for the products' store pages, and `link_sent` on each
+ * store and `store_links_sent` for the pages of the stores to pick from.
  */
 import type { BuyNextAction } from './client.js';
-import type { BuyToolProduct, BuyToolResult, BuyToolStatus } from './buy-tool.js';
+import type { BuyToolProduct, BuyToolResult, BuyToolStatus, BuyToolStore } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
     items: Array<{
@@ -23,10 +24,21 @@ export interface BuyToolModelProduct {
     /** What the model passes as `product_id` when the shopper picks this product: Agentcard's ref, never a link. Null when there is none. */
     product_id: string | null;
     name: string;
+    /** The store that sells it, by name, never a link: a product with no store is not shown to the model. */
+    store: string;
     price: string | null;
     /** True when the shopper holds this product's store page, which `sendLink` delivered beside the reply. */
     link_sent: boolean;
 }
+export interface BuyToolModelStore {
+    /** What the model passes as `store_id` when the shopper picks this store: Agentcard's id, never a link. */
+    store_id: string;
+    name: string;
+    /** The delivery estimate in minutes, or null when the store showed none. */
+    eta_minutes: number | null;
+    /** True when the shopper holds this store's page, which `sendLink` delivered beside the reply. */
+    link_sent: boolean;
+}
 /** The buy tool's answer as the model reads it. */
 export interface BuyToolModelView {
     status: BuyToolStatus;
@@ -41,6 +53,8 @@ export interface BuyToolModelView {
     products: BuyToolModelProduct[];
     approval_expires_at: string | null;
     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 has the link this answer needed. */
     link_sent: boolean;
     /** How many store pages of the products above the shopper holds, 0 when none went out. */
@@ -50,8 +64,20 @@ export interface BuyToolModelView {
         product_id: string | null;
         in_cart: boolean;
     } | null;
+    /** The stores the reply presents to choose from, in the order it names them. */
+    stores: BuyToolModelStore[];
+    /** How many store pages of the stores above the shopper holds, 0 when none went out. */
+    store_links_sent: number;
+    /** The store this call's `store_id` (or an answer such as `the second one`) picked, and whether Agentcard selected it; null when none was picked. */
+    store_pick: {
+        store_id: string;
+        selected: boolean;
+    } | null;
 }
-/** The text with every link taken out: a Markdown link keeps its label, and a bare address goes entirely. */
+/**
+ * The text with every link taken out: a Markdown link keeps its label, an address with a path or a scheme goes
+ * entirely, and a bare address reads as the site's name (siteName), so the store a reply names stays in it.
+ */
 export declare function stripLinks(text: string): string;
 /**
  * An amount in its currency's minor unit, as the model reads it: the currency's own minor units place the
@@ -60,11 +86,17 @@ export declare function stripLinks(text: string): string;
  */
 export declare function money(minor: number | null | undefined, currency: string | null | undefined): string | null;
 /**
- * The products the model reads: the first twenty that keep a name once links
- * are taken out. The tool sends store pages for these same twenty, so the shopper
- * never holds a product link the model cannot name.
+ * The products the model reads: the first twenty that keep a name and a store
+ * once links are taken out, so the model never offers a product without saying
+ * where it is sold. The tool sends store pages for these same twenty, so the
+ * shopper never holds a product link the model cannot name.
  */
 export declare function shownProducts(products: readonly BuyToolProduct[] | null | undefined): BuyToolProduct[];
+/**
+ * The stores the model reads: each one whose id and name hold no link, so the model never reads a
+ * link and never offers a store without its name. The tool sends pages for these same stores.
+ */
+export declare function shownStores(stores: readonly BuyToolStore[] | null | undefined): BuyToolStore[];
 /**
  * The id the model passes back for a product: Agentcard's link-free ref, else the product's own id when
  * it holds no link, else null. A retail product's id is its store page, and a link never reaches the model.

package/dist/model-view.js

@@ -10,15 +10,40 @@ const HOST_PATH = /\b(?:[a-z0-9-]+\.)+[a-z]{2,}[/?#][^\s<>"'`)\]]*/gi;
  * A bare host on a common top-level domain, such as `agentcard.sh` or `amazon.com`, which a chat app
  * turns into a link. The list keeps words with a dot, such as `Node.js`, and an email address's host.
  */
-const BARE_HOST = /(?<![@\w.-])(?:[a-z0-9-]+\.)+(?:com|net|org|io|co|sh|ai|app|dev|me|us|uk|ca|de|fr|es|it|nl|eu|au|in|jp|br|mx|info|biz|shop|store|site|online|link|page|xyz|ly|gg|to|tv|fm|so)(?![\w-])/gi;
-/** The text with every link taken out: a Markdown link keeps its label, and a bare address goes entirely. */
+const BARE_HOST = /(?<![@\w.-])(?:[a-z0-9-]+\.)+(?:com|net|org|io|co|sh|ai|app|dev|me|us|uk|ca|de|fr|es|it|nl|eu|au|in|jp|br|mx|info|biz|shop|store|site|online|link|page|xyz|ly|gg|to|tv|fm|so)(?:\.[a-z]{2})?(?![\w-])/gi;
+/** The labels of a domain ending under a country's (amazon.co.uk), which name no store. */
+const SECOND_LEVEL = new Set(['co', 'com', 'org', 'net', 'ac', 'gov', 'edu']);
+/** Labels before a store's own that name a part of its site: shop.nike.com is Nike's, ca.mavi.com is Mavi's. */
+const SITE_PART = new Set(['www', 'shop', 'store', 'stores', 'm', 'mobile', 'en', 'us', 'ca', 'uk']);
+/**
+ * The name a bare address stands for, as the model reads a store in `reply`: walmart.com reads Walmart, shop.nike.com
+ * Nike, amazon.co.uk Amazon. Agentcard names a store by its domain, and a removed domain left the model with "Buy it at
+ * for $54.00" and no store to tell the shopper.
+ */
+function siteName(host) {
+    const labels = host.toLowerCase().split('.').filter(Boolean);
+    labels.pop();
+    if (labels.length > 1 && SECOND_LEVEL.has(labels[labels.length - 1]))
+        labels.pop();
+    const name = labels.find((label, i) => i === labels.length - 1 || !(SITE_PART.has(label) || label.length <= 2)) ?? '';
+    return name ? name[0].toUpperCase() + name.slice(1) : '';
+}
+/** A www address: the site's name when it is bare (the closing mark it ends a sentence with stays), nothing when it carries a path. */
+function wwwName(address) {
+    const [, host, closing] = /^(.*?)([.,;:!?]*)$/.exec(address) ?? [];
+    return host && !/[/?#]/.test(host) ? siteName(host) + (closing ?? '') : '';
+}
+/**
+ * The text with every link taken out: a Markdown link keeps its label, an address with a path or a scheme goes
+ * entirely, and a bare address reads as the site's name (siteName), so the store a reply names stays in it.
+ */
 export function stripLinks(text) {
     return String(text ?? '')
         .replace(MARKDOWN_LINK, '$1')
         .replace(SCHEME_URL, '')
-        .replace(WWW_URL, '')
+        .replace(WWW_URL, wwwName)
         .replace(HOST_PATH, '')
-        .replace(BARE_HOST, '')
+        .replace(BARE_HOST, siteName)
         .replace(/\(\s*\)|\[\s*\]|<\s*>/g, '')
         .replace(/[ \t]+([.,;:!?])/g, '$1')
         .replace(/[ \t]{2,}/g, ' ')
@@ -60,12 +85,20 @@ export function money(minor, currency) {
     return format.format(minor / 10 ** minorUnits(format));
 }
 /**
- * The products the model reads: the first twenty that keep a name once links
- * are taken out. The tool sends store pages for these same twenty, so the shopper
- * never holds a product link the model cannot name.
+ * The products the model reads: the first twenty that keep a name and a store
+ * once links are taken out, so the model never offers a product without saying
+ * where it is sold. The tool sends store pages for these same twenty, so the
+ * shopper never holds a product link the model cannot name.
  */
 export function shownProducts(products) {
-    return (products ?? []).filter((product) => stripLinks(product.name) !== '').slice(0, MAX_PRODUCTS);
+    return (products ?? []).filter((product) => stripLinks(product.name) !== '' && stripLinks(product.store ?? '') !== '').slice(0, MAX_PRODUCTS);
+}
+/**
+ * The stores the model reads: each one whose id and name hold no link, so the model never reads a
+ * link and never offers a store without its name. The tool sends pages for these same stores.
+ */
+export function shownStores(stores) {
+    return (stores ?? []).filter((store) => store.id !== '' && stripLinks(store.id) === store.id && stripLinks(store.name) !== '');
 }
 /**
  * The id the model passes back for a product: Agentcard's link-free ref, else the product's own id when
@@ -95,20 +128,29 @@ export function forModel(result) {
     const status = typeof result.status === 'string' && MODEL_STATUSES.has(result.status) ? result.status : 'needs_input';
     const products = shownProducts(result.products);
     const held = (product) => product.linkSent === true && typeof product.url === 'string' && product.url !== '';
+    const stores = shownStores(result.stores);
+    const heldStore = (store) => store.linkSent === true && typeof store.url === 'string' && store.url !== '';
     return {
         status,
         next_action: result.next_action ?? null,
         reply: stripLinks(result.reply),
         cart: result.cart ? cartView(result.cart) : null,
         carts: (result.carts ?? []).map(cartView),
-        products: products.map((product) => ({ product_id: pickId(product), name: stripLinks(product.name), price: money(product.priceCents, product.currency), link_sent: held(product) })),
+        products: products.map((product) => ({ product_id: pickId(product), name: stripLinks(product.name), store: stripLinks(product.store ?? ''), price: money(product.priceCents, product.currency), link_sent: held(product) })),
         approval_expires_at: typeof result.approval_expires_at === 'string' ? stripLinks(result.approval_expires_at) || null : null,
         shopper_need_not_reply: result.shopper_need_not_reply === true,
+        shopper_already_told_looking: result.shopper_already_told_looking === true,
         link_sent: result.link_sent === true,
         // Two products on one page share one link, so the count is of pages.
         product_links_sent: new Set(products.filter(held).map((product) => product.url)).size,
         // The id the model sent, never the catalog id, which is a store page for a retail product.
         pick: result.pick ? { product_id: pickId({ id: result.pick.product_id, ref: result.pick.ref }), in_cart: result.pick.in_cart === true } : null,
+        stores: stores.map((store) => ({ store_id: store.id, name: stripLinks(store.name), eta_minutes: store.etaMinutes, link_sent: heldStore(store) })),
+        store_links_sent: new Set(stores.filter(heldStore).map((store) => store.url)).size,
+        // A store id with a link in it is never read back to the model.
+        store_pick: result.store_pick && stripLinks(result.store_pick.store_id) === result.store_pick.store_id
+            ? { store_id: result.store_pick.store_id, selected: result.store_pick.selected === true }
+            : null,
     };
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.5.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.",
+  "version": "0.9.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",
   "types": "dist/index.d.ts",