@agent-cards/commerce-sdk 0.2.0 → 0.8.0

package/dist/listen.js

@@ -0,0 +1,496 @@
+/**
+ * Hear every Agentcard event without a webhook endpoint. Your server opens one connection to
+ * Agentcard with your company credentials, and Agentcard streams your company's events down it:
+ * no public URL, no webhook secret, no signature to check. Each event is the envelope a webhook
+ * endpoint would receive, with the same id.
+ *
+ * The listener reconnects on its own, resumes after the last event it handled, skips an event it
+ * already handled, and falls back to asking every few seconds when the stream is not available.
+ * Shopper messages go through the same reader as `agentcardWebhook` (`readShopperMessage`), so
+ * `onMessage` gets the same ready-to-send text.
+ */
+import { isRecord } from './verify.js';
+import { isStale, readShopperMessage } from './shopper-message.js';
+import { isEventPattern, matchesEventPattern } from './events.js';
+import { AgentcardApiError } from './client.js';
+/** How many handled event ids the listener remembers, the oldest forgotten first. */
+const HANDLED_EVENTS_KEPT = 10_000;
+/** Tries for one event's callback before the listener reports it and moves on. */
+const CALLBACK_ATTEMPTS = 5;
+const IDLE_SAVE_MS = 60_000;
+const MAX_BACKOFF_MS = 30_000;
+/**
+ * How far behind its cursor Agentcard hands events over again after a resume, in case one
+ * committed late, unless the stream says otherwise. The saved cursor carries the id of every event
+ * handled within this window and a margin, so a new process skips each of them.
+ */
+const DEFAULT_REPLAY_MS = 10_000;
+const REPLAY_MARGIN_MS = 5_000;
+/** The time in a cursor, `<ms>_<row>`, or null for a cursor of another shape. */
+const cursorTime = (cursor) => {
+    const m = cursor ? /^(\d{1,15})_/.exec(cursor) : null;
+    return m ? Number(m[1]) : null;
+};
+/** Streams in a row that answered but never said ready before `auto` polls instead: a proxy that buffers the stream, or closes it. */
+const STREAM_ATTEMPTS_BEFORE_POLLING = 3;
+/** Raised when the stream is not served here, so `auto` polls instead. */
+class StreamUnavailable extends Error {
+}
+/** Raised when the stream answered but closed, or went silent, before Agentcard said it was ready. */
+class StreamNotEstablished extends Error {
+}
+const sleep = (ms, signal) => new Promise((resolve) => {
+    if (signal.aborted)
+        return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', done);
+        resolve();
+    }
+    signal.addEventListener('abort', done);
+});
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** An event envelope as Agentcard sends it, or null for anything else. */
+function eventOf(value) {
+    if (!isRecord(value) || typeof value.id !== 'string' || typeof value.type !== 'string' || !isRecord(value.data))
+        return null;
+    return {
+        id: value.id,
+        type: value.type,
+        created: typeof value.created === 'number' ? value.created : 0,
+        livemode: value.livemode === true,
+        data: value.data,
+    };
+}
+/** The Agentcard error a refused read answered with. */
+async function refusal(res) {
+    const body = parseJson(await res.text().catch(() => ''));
+    const error = isRecord(body) && isRecord(body.error) ? body.error : {};
+    const code = typeof error.code === 'string' ? error.code : `http_${res.status}`;
+    const message = typeof error.message === 'string' ? error.message : `Agentcard answered ${res.status}.`;
+    return new AgentcardApiError(res.status, code, message, isRecord(body) ? body : undefined);
+}
+/**
+ * Listen to every event Agentcard sends your company, over one connection your server opens.
+ * Build `agentcard` with your company's client credentials. Returns at once; `ready` resolves once
+ * the listener reaches Agentcard. Each event runs its callback once, in order, and the next event
+ * waits for it: a callback that throws runs again, up to five times, before the listener reports
+ * it and moves on. Run one listener per company and mode: two listeners each hear every event.
+ */
+export function listenToAgentcard(agentcard, opts) {
+    if (!agentcard || typeof agentcard.bearer !== 'function')
+        throw new TypeError('Pass the AgentcardClient built with your company credentials.');
+    if (!agentcard.company)
+        throw new TypeError('Listening takes your company credentials: build the client with clientId and clientSecret.');
+    if (opts === null || typeof opts !== 'object')
+        throw new TypeError('Pass { onMessage } or { onEvent }.');
+    if (opts.onMessage === undefined && opts.onEvent === undefined)
+        throw new TypeError('Pass onMessage, onEvent, or both.');
+    for (const name of ['onMessage', 'onEvent', 'onError']) {
+        if (opts[name] !== undefined && typeof opts[name] !== 'function')
+            throw new TypeError(`${name} must be a function.`);
+    }
+    const filter = opts.events === undefined ? null : [...opts.events];
+    if (filter !== null && (filter.length === 0 || filter.some((p) => typeof p !== 'string' || !isEventPattern(p)))) {
+        throw new TypeError('events lists event types Agentcard sends, families such as order.*, or *. Leave it out for every event.');
+    }
+    const transportOpt = opts.transport ?? 'auto';
+    if (!['auto', 'stream', 'poll'].includes(transportOpt))
+        throw new TypeError("transport is 'auto', 'stream' or 'poll'.");
+    const fetchFn = (opts.fetch ?? globalThis.fetch);
+    if (typeof fetchFn !== 'function')
+        throw new TypeError('Pass fetch: this runtime has no global fetch. Node 18 and later have one.');
+    const pollIntervalMs = opts.pollIntervalMs ?? 2_000;
+    const heartbeatTimeoutMs = opts.heartbeatTimeoutMs ?? 45_000;
+    const pollTimeoutMs = opts.pollTimeoutMs ?? 30_000;
+    const stop = new AbortController();
+    let transport = transportOpt === 'poll' ? 'poll' : 'stream';
+    let cursor = null;
+    let savedCursor = null;
+    let lastSave = 0;
+    let resolveReady;
+    const ready = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    const report = (error, event) => {
+        try {
+            const reported = opts.onError ? opts.onError(error, event) : console.error('Agentcard listener:', error);
+            if (reported && typeof reported.then === 'function')
+                reported.then(undefined, () => { });
+        }
+        catch {
+            // A failing reporter never stops the listener.
+        }
+    };
+    const finished = new Set();
+    /** The ids handled last, saved with the cursor, so a new process skips what Agentcard hands it again. */
+    /** Each handled id with the cursor time it came with, which is never earlier than the event's own place. */
+    const recent = [];
+    let replayMs = DEFAULT_REPLAY_MS;
+    const finishAt = (id, at) => {
+        finished.add(id);
+        if (finished.size > HANDLED_EVENTS_KEPT)
+            finished.delete(finished.values().next().value);
+        recent.push({ id, at: at ?? Date.now() });
+        if (recent.length > HANDLED_EVENTS_KEPT)
+            recent.shift();
+    };
+    /**
+     * What the store keeps: Agentcard's cursor, then the id of every event a resume from it could hand
+     * over again, as `<cursor>.<id>,<id>`. An id older than the replay window behind the cursor is dropped.
+     */
+    const stored = (next) => {
+        const at = cursorTime(next);
+        if (at !== null) {
+            const keepFrom = at - replayMs - REPLAY_MARGIN_MS;
+            while (recent.length > 0 && recent[0].at < keepFrom)
+                recent.shift();
+        }
+        return recent.length > 0 ? `${next}.${recent.map((r) => r.id).join(',')}` : next;
+    };
+    const save = async (next, force) => {
+        cursor = next;
+        const value = stored(next);
+        if (!opts.cursor || value === savedCursor)
+            return;
+        if (!force && Date.now() - lastSave < IDLE_SAVE_MS)
+            return;
+        try {
+            await opts.cursor.save(value);
+            savedCursor = value;
+            lastSave = Date.now();
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    /**
+     * Runs one event's callback, and tries again when it throws, up to five times in all. Answers
+     * false when the listener closed with the callback still failing: the event stays unfinished and
+     * nothing saves past it, so the next process runs it again.
+     */
+    const handle = async (event, at) => {
+        if (finished.has(event.id))
+            return true;
+        const finish = (id) => {
+            finishAt(id, at);
+            return true;
+        };
+        if (filter !== null && !filter.some((p) => matchesEventPattern(event.type, p)))
+            return finish(event.id);
+        let message = null;
+        try {
+            message = readShopperMessage(event);
+        }
+        catch (error) {
+            // A message the package cannot read reads the same way every time, so it is reported once.
+            report(error, event);
+        }
+        // A message whose link or window closed before it arrived reaches no shopper, and the event still reaches onEvent.
+        const forShopper = message && message.externalUserId !== null && !isStale(message) ? message : null;
+        for (let attempt = 1;; attempt++) {
+            try {
+                if (opts.onMessage && forShopper?.externalUserId)
+                    await opts.onMessage(forShopper.externalUserId, forShopper, event);
+                else if (opts.onEvent)
+                    await opts.onEvent(event);
+                return finish(event.id);
+            }
+            catch (error) {
+                if (attempt >= CALLBACK_ATTEMPTS) {
+                    report(error, event);
+                    return finish(event.id);
+                }
+                // Closing mid-failure leaves the event for the next process, which has the tries left.
+                if (stop.signal.aborted) {
+                    report(error, event);
+                    return false;
+                }
+                await sleep(1_000 * 2 ** (attempt - 1), stop.signal);
+            }
+        }
+    };
+    const query = (after, extra = {}) => {
+        const params = new URLSearchParams(extra);
+        if (after)
+            params.set('after', after);
+        if (filter)
+            params.set('types', filter.join(','));
+        const text = params.toString();
+        return text ? `?${text}` : '';
+    };
+    /** One authorized GET: a 401 renews the token once. */
+    const get = async (path, accept, signal) => {
+        let token = await agentcard.bearer();
+        for (let attempt = 0;; attempt++) {
+            const res = await fetchFn(`${agentcard.baseUrl}${path}`, { method: 'GET', headers: { authorization: `Bearer ${token}`, accept }, signal });
+            if (res.status !== 401 || attempt > 0)
+                return res;
+            await res.text().catch(() => '');
+            token = await agentcard.bearer(token);
+        }
+    };
+    /** A refused cursor: Agentcard no longer keeps it, so the listener reports it and starts from now. */
+    const dropCursor = async (error) => {
+        report(error);
+        cursor = null;
+    };
+    /** One stream connection, read to its end. Resolves when the server asks to reconnect or the connection drops. */
+    const streamOnce = async () => {
+        const conn = new AbortController();
+        const abort = () => conn.abort();
+        stop.signal.addEventListener('abort', abort);
+        let silence;
+        let wentSilent = false;
+        const arm = () => {
+            if (silence)
+                clearTimeout(silence);
+            silence = setTimeout(() => {
+                wentSilent = true;
+                abort();
+            }, heartbeatTimeoutMs);
+        };
+        let opened = false;
+        try {
+            arm();
+            let res;
+            try {
+                res = await get(`/api/v2/events/stream${query(cursor)}`, 'text/event-stream', conn.signal);
+            }
+            catch (error) {
+                // No answer within the heartbeat timeout is a stream held back on its way, not a lost network.
+                if (wentSilent && !stop.signal.aborted)
+                    throw new StreamNotEstablished('The event stream sent nothing before Agentcard said it was ready.');
+                throw error;
+            }
+            if (res.status === 400 || res.status === 410) {
+                const error = await refusal(res);
+                if (error.code === 'invalid_cursor' || error.code === 'cursor_expired') {
+                    await dropCursor(error);
+                    return 'reconnect';
+                }
+                throw error;
+            }
+            const type = res.headers.get('content-type') ?? '';
+            if (res.status === 404 || res.status === 405 || (res.ok && !type.includes('text/event-stream'))) {
+                await res.text().catch(() => '');
+                throw new StreamUnavailable(`Agentcard answered the stream with ${res.status} ${type || 'and no content type'}.`);
+            }
+            if (!res.ok || !res.body)
+                throw await refusal(res);
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = '';
+            for (;;) {
+                let chunk;
+                try {
+                    chunk = await reader.read();
+                }
+                catch (error) {
+                    if (!opened && !stop.signal.aborted)
+                        throw new StreamNotEstablished('The event stream went silent before Agentcard said it was ready.');
+                    throw error;
+                }
+                const { done, value } = chunk;
+                // A connection that ends before Agentcard said it is ready counts as a failure, so it backs off.
+                if (done) {
+                    if (!opened)
+                        throw new StreamNotEstablished('The event stream closed before Agentcard said it was ready.');
+                    return 'dropped';
+                }
+                arm();
+                buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, '\n');
+                let cut;
+                while ((cut = buffer.indexOf('\n\n')) >= 0) {
+                    const block = buffer.slice(0, cut);
+                    buffer = buffer.slice(cut + 2);
+                    let id;
+                    let name = 'message';
+                    const data = [];
+                    for (const line of block.split('\n')) {
+                        if (line === '' || line.startsWith(':'))
+                            continue;
+                        const colon = line.indexOf(':');
+                        const field = colon < 0 ? line : line.slice(0, colon);
+                        const val = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+                        if (field === 'id')
+                            id = val;
+                        else if (field === 'event')
+                            name = val;
+                        else if (field === 'data')
+                            data.push(val);
+                    }
+                    if (name === 'ready') {
+                        opened = true;
+                        resolveReady();
+                        const announced = parseJson(data.join('\n'));
+                        if (isRecord(announced) && typeof announced.replay_seconds === 'number' && announced.replay_seconds > 0) {
+                            replayMs = Math.max(DEFAULT_REPLAY_MS, announced.replay_seconds * 1000);
+                        }
+                        if (id)
+                            await save(id, false);
+                    }
+                    else if (name === 'heartbeat') {
+                        if (id)
+                            await save(id, false);
+                    }
+                    else if (name === 'reconnect') {
+                        if (id)
+                            await save(id, false);
+                        await reader.cancel().catch(() => { });
+                        return 'reconnect';
+                    }
+                    else if (name === 'message' || name === 'replay') {
+                        // A replay is an event Agentcard hands over again after a resume, in case it committed late; an id already handled runs nothing.
+                        const event = eventOf(parseJson(data.join('\n')));
+                        if (event) {
+                            // A callback that runs long is not silence on the stream.
+                            if (silence)
+                                clearTimeout(silence);
+                            const handled = await handle(event, cursorTime(id));
+                            arm();
+                            // An event the shutdown left unfinished saves no cursor past it.
+                            if (!handled)
+                                return 'dropped';
+                        }
+                        if (id)
+                            await save(id, true);
+                    }
+                    if (stop.signal.aborted)
+                        return 'dropped';
+                }
+            }
+        }
+        finally {
+            if (silence)
+                clearTimeout(silence);
+            stop.signal.removeEventListener('abort', abort);
+            conn.abort();
+        }
+    };
+    /** One page of a polling read, given up after `pollTimeoutMs` so a stalled read never stops the listener. */
+    const readPage = async () => {
+        const conn = new AbortController();
+        const abort = () => conn.abort();
+        stop.signal.addEventListener('abort', abort);
+        const deadline = setTimeout(abort, pollTimeoutMs);
+        try {
+            const res = await get(`/api/v2/events${query(cursor, { limit: '100' })}`, 'application/json', conn.signal);
+            return { status: res.status, ok: res.ok, text: await res.text() };
+        }
+        finally {
+            clearTimeout(deadline);
+            stop.signal.removeEventListener('abort', abort);
+        }
+    };
+    /** One polling read, every page of it. */
+    const pollOnce = async () => {
+        for (;;) {
+            const res = await readPage();
+            if (!res.ok) {
+                const error = await refusal({ status: res.status, text: async () => res.text });
+                if (error.code === 'invalid_cursor' || error.code === 'cursor_expired')
+                    return dropCursor(error);
+                throw error;
+            }
+            const body = parseJson(res.text);
+            if (!isRecord(body) || !Array.isArray(body.data))
+                throw new AgentcardApiError(res.status, 'invalid_answer', 'Agentcard answered the event read with a body the listener cannot read.');
+            resolveReady();
+            for (const item of body.data) {
+                if (stop.signal.aborted)
+                    return;
+                const event = isRecord(item) ? eventOf(item.event) : null;
+                const itemCursor = isRecord(item) && typeof item.cursor === 'string' ? item.cursor : null;
+                // An event the shutdown left unfinished saves no cursor past it.
+                if (event && !(await handle(event, cursorTime(itemCursor))))
+                    return;
+                if (itemCursor)
+                    await save(itemCursor, true);
+            }
+            if (typeof body.cursor === 'string')
+                await save(body.cursor, body.data.length > 0);
+            if (body.has_more !== true)
+                return;
+        }
+    };
+    const loop = (async () => {
+        if (opts.cursor) {
+            try {
+                const loaded = await opts.cursor.load();
+                if (typeof loaded === 'string' && loaded !== '') {
+                    savedCursor = loaded;
+                    const dot = loaded.indexOf('.');
+                    cursor = dot < 0 ? loaded : loaded.slice(0, dot);
+                    for (const id of dot < 0 ? [] : loaded.slice(dot + 1).split(','))
+                        if (/^[A-Za-z0-9_]{1,64}$/.test(id))
+                            finishAt(id, cursorTime(cursor));
+                }
+            }
+            catch (error) {
+                report(error);
+            }
+        }
+        let failures = 0;
+        let unestablished = 0;
+        while (!stop.signal.aborted) {
+            try {
+                if (transport === 'stream') {
+                    const ended = await streamOnce();
+                    failures = 0;
+                    unestablished = 0;
+                    if (ended === 'reconnect')
+                        continue;
+                }
+                else {
+                    await pollOnce();
+                    failures = 0;
+                    await sleep(pollIntervalMs, stop.signal);
+                    continue;
+                }
+            }
+            catch (error) {
+                if (stop.signal.aborted)
+                    break;
+                if (error instanceof StreamUnavailable && transportOpt === 'auto') {
+                    transport = 'poll';
+                    continue;
+                }
+                failures++;
+                report(error);
+                if (error instanceof StreamNotEstablished && transportOpt === 'auto' && ++unestablished >= STREAM_ATTEMPTS_BEFORE_POLLING) {
+                    // Something between here and Agentcard holds the stream back; the same events come by polling, from the same cursor.
+                    transport = 'poll';
+                    continue;
+                }
+            }
+            if (stop.signal.aborted)
+                break;
+            // A dropped connection or a failed read waits a little longer each time, up to 30 seconds.
+            const backoff = Math.min(MAX_BACKOFF_MS, 1_000 * 2 ** Math.max(0, failures - 1));
+            await sleep(failures === 0 ? 250 : backoff * (0.5 + Math.random() / 2), stop.signal);
+        }
+        resolveReady();
+    })();
+    return {
+        ready,
+        get transport() {
+            return transport;
+        },
+        get cursor() {
+            return cursor;
+        },
+        async close() {
+            stop.abort();
+            await loop;
+        },
+    };
+}

package/dist/message.d.ts

@@ -9,13 +9,15 @@ import { type AgentcardEvent } from './verify.js';
  * - `order_placed`: the shopper approved, and Agentcard placed the order.
  * - `order_failed`: the order failed after the approval, and nothing more happens for that approval.
  * - `order_not_placed_yet`: the shopper approved, and the order is not placed yet.
+ * - `order_unconfirmed`: the store's reply to the order was lost, so the order may exist; Agentcard is confirming it.
  * - `approval_expiring`: the approval link expires soon; `text` carries the link.
  * - `approval_expired`: the approval expired before the shopper answered, and nothing was charged.
  * - `card_link_unfinished`: the shopper has not added a card from their card link; `text` carries the link again.
  * - `card_link_expired`: the card link expired before the shopper added a card.
  * - `cart_idle`: a cart sat without being sent for approval; `facts.nudgeNumber` counts the nudges.
+ * - `card_added`: the shopper saved a card from the card link your app sent, and can check out with it.
  */
-export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'approval_expiring' | 'approval_expired' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle';
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added';
 /** The message's values one by one, for a company that writes its own copy. A fact that does not apply is absent. */
 export interface PurchaseFacts {
     merchantName?: string;

package/dist/model-view.d.ts

@@ -20,7 +20,11 @@ export interface BuyToolModelCart {
     total: string;
 }
 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;
@@ -39,12 +43,22 @@ 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. */
     product_links_sent: number;
+    /** The product this call's `product_id` picked, and whether the cart now holds it; null when the call picked none. */
+    pick: {
+        product_id: string | null;
+        in_cart: 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
@@ -53,14 +67,20 @@ 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 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.
+ */
+export declare function pickId(product: Pick<BuyToolProduct, 'id' | 'ref'>): string | null;
 /**
  * The model's view of one answer: the status, Agentcard's reply, the newest
- * cart and every cart on the table, the products by name and price, and
+ * cart and every cart on the table, the products by id, name and price, and
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */

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,22 @@ 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 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.
+ */
+export function pickId(product) {
+    if (typeof product.ref === 'string' && product.ref !== '' && stripLinks(product.ref) === product.ref)
+        return product.ref;
+    return typeof product.id === 'string' && product.id !== '' && stripLinks(product.id) === product.id ? product.id : null;
 }
 function cartView(cart) {
     return {
@@ -78,7 +113,7 @@ function cartView(cart) {
 }
 /**
  * The model's view of one answer: the status, Agentcard's reply, the newest
- * cart and every cart on the table, the products by name and price, and
+ * cart and every cart on the table, the products by id, name and price, and
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */
@@ -92,12 +127,15 @@ export function forModel(result) {
         reply: stripLinks(result.reply),
         cart: result.cart ? cartView(result.cart) : null,
         carts: (result.carts ?? []).map(cartView),
-        products: products.map((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,
     };
 }
 /**