@agent-cards/commerce-sdk 0.1.0 → 0.5.0

package/dist/messages.js

@@ -0,0 +1,206 @@
+/**
+ * Text cut into the messages a shopper reads one at a time. A chat app sends each paragraph as its
+ * own message, so a reply written as three paragraphs arrives as three texts. A blank line ends a
+ * paragraph, with two exceptions that keep a block whole: a fenced code block, and a list whose
+ * items a blank line separates.
+ */
+/** A line holding nothing but spaces or tabs. */
+const BLANK = /^[ \t]*$/;
+/** A list item: `-`, `*` or `+`, or a number followed by `.` or `)`, then a space or the line's end. */
+const LIST_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/;
+/** A list item whose marker a space already follows, the only kind a line still being written is sure to stay. */
+const LIST_ITEM_SPACED = /^ {0,3}(?:[-*+]|\d{1,9}[.)])[ \t]/;
+/** A line indented under a list item: two spaces or a tab, then text. */
+const INDENTED = /^(?: {2,}|\t)\S/;
+/** The start of a line that can still grow into a list item or an indented line once more text arrives. */
+const MAYBE_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)]?)?$|^[ \t]*$/;
+/** A code fence: three or more backticks or tildes, indented by at most three spaces. */
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+/** How the line after a blank line inside a list reads: it continues the list, it ends it, or it is too short to tell. */
+function afterListBlank(line, complete) {
+    // `1.` alone is an item once the line ends there, and the start of `1.5 cups` while it is still arriving.
+    if ((complete ? LIST_ITEM : LIST_ITEM_SPACED).test(line) || INDENTED.test(line))
+        return 'continues';
+    if (!complete && MAYBE_ITEM.test(line))
+        return 'unknown';
+    return 'ends';
+}
+/** True when `line` closes the fence `open` opened: the same character, at least as many times, and nothing after. */
+function closesFence(line, open) {
+    const match = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+    return !!match && match[1][0] === open[0] && match[1].length >= open.length;
+}
+/**
+ * Reads text line by line and closes each message once nothing later can change it. It keeps only
+ * the message being built, so text fed in pieces costs what the text costs once.
+ */
+class Scanner {
+    onClose;
+    current = [];
+    fence = null;
+    inList = false;
+    blankInList = false;
+    constructor(onClose) {
+        this.onClose = onClose;
+    }
+    close() {
+        const message = this.current.join('\n').trim();
+        this.current = [];
+        this.inList = false;
+        this.blankInList = false;
+        if (message)
+            this.onClose(message);
+    }
+    /** One whole line. */
+    line(line) {
+        if (this.fence !== null) {
+            this.current.push(line);
+            if (closesFence(line, this.fence))
+                this.fence = null;
+            return;
+        }
+        if (BLANK.test(line)) {
+            if (this.current.length === 0)
+                return;
+            // A blank line ends the paragraph, unless it sits between two items of one list.
+            if (this.inList)
+                this.blankInList = true;
+            else
+                this.close();
+            return;
+        }
+        if (this.blankInList) {
+            if (afterListBlank(line, true) === 'ends')
+                this.close();
+            else
+                this.current.push('');
+            this.blankInList = false;
+        }
+        this.current.push(line);
+        if (LIST_ITEM.test(line))
+            this.inList = true;
+        else if (this.current.length === 1)
+            this.inList = false;
+        const open = FENCE.exec(line);
+        if (open)
+            this.fence = open[1];
+    }
+    /**
+     * The start of a line still being written. After a blank line inside a list, its first characters
+     * can already say the list ended, and the list goes out as soon as they do. Only the start counts:
+     * no marker, indent or number runs past 16 characters.
+     */
+    partial(start) {
+        if (this.fence === null && this.blankInList && afterListBlank(start.slice(0, 16), false) === 'ends')
+            this.close();
+    }
+    /** The text is whole: the message being built closes. */
+    end() {
+        this.close();
+    }
+}
+/**
+ * The text as separate messages, in order: one per paragraph, each trimmed, with empty ones left
+ * out. One or more blank lines end a paragraph. A fenced code block stays one message whatever blank
+ * lines it holds, and so does a list whose items blank lines separate.
+ *
+ * ```ts
+ * toMessages('Found two.\n\nWant the first one?'); // ['Found two.', 'Want the first one?']
+ * ```
+ */
+export function toMessages(text) {
+    const messages = [];
+    const scanner = new Scanner((message) => messages.push(message));
+    for (const line of String(text ?? '').replace(/\r\n?/g, '\n').split('\n'))
+        scanner.line(line);
+    scanner.end();
+    return messages;
+}
+/**
+ * Cuts streamed text into the messages `toMessages` finds, as it arrives. Each paragraph goes to
+ * `onMessage` the moment the blank line that ends it arrives, whatever the pieces split it into. A
+ * paragraph inside a list waits for the first characters of the line after the blank, which say
+ * whether the list goes on. `end` hands over the last message and waits for every send.
+ *
+ * ```ts
+ * const paragraphs = messageStream({ onMessage: (text) => sendToShopper(text) });
+ * stream.on('text', (delta) => paragraphs.push(delta));
+ * await stream.done();
+ * await paragraphs.end();
+ * ```
+ */
+export function messageStream(options) {
+    const onMessage = options?.onMessage;
+    if (typeof onMessage !== 'function')
+        throw new TypeError('Pass onMessage as a function that takes each message.');
+    // The line still being written. A trailing \r waits here too, in case its \n is in the next piece.
+    let open = '';
+    let ended = false;
+    let failure = null;
+    // Messages waiting for the send before them. A send that returns no promise goes out at once.
+    const queue = [];
+    let running = null;
+    const drain = () => {
+        while (queue.length > 0 && !failure) {
+            const message = queue.shift();
+            let sent;
+            try {
+                sent = onMessage(message);
+            }
+            catch (error) {
+                failure = { error };
+                break;
+            }
+            if (sent && typeof sent.then === 'function') {
+                return Promise.resolve(sent).then(() => drain() ?? undefined, (error) => {
+                    failure = { error };
+                });
+            }
+        }
+        return null;
+    };
+    const kick = () => {
+        if (running)
+            return;
+        const pending = drain();
+        if (pending) {
+            running = pending.then(() => {
+                running = null;
+                kick();
+            });
+        }
+    };
+    const scanner = new Scanner((message) => {
+        queue.push(message);
+        kick();
+    });
+    return {
+        push(delta) {
+            if (ended)
+                throw new Error('This message stream has ended. Start a new one for the next text.');
+            if (typeof delta !== 'string' || delta === '')
+                return;
+            const text = open + delta;
+            const cut = text.endsWith('\r') ? text.length - 1 : text.length;
+            const lines = text.slice(0, cut).replace(/\r\n?/g, '\n').split('\n');
+            open = (lines.pop() ?? '') + text.slice(cut);
+            for (const line of lines)
+                scanner.line(line);
+            // A held \r is a line ending still arriving, not text that could end a list.
+            scanner.partial(open.endsWith('\r') ? open.slice(0, -1) : open);
+        },
+        async end() {
+            if (!ended) {
+                ended = true;
+                for (const line of open.replace(/\r\n?/g, '\n').split('\n'))
+                    scanner.line(line);
+                open = '';
+                scanner.end();
+            }
+            while (running)
+                await running;
+            if (failure)
+                throw failure.error;
+        },
+    };
+}

package/dist/model-view.d.ts

@@ -1,3 +1,12 @@
+/**
+ * What the model reads: the buy tool's answer with every link taken out. A
+ * tool runner puts a tool's result straight into the model's context, and a
+ * 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.
+ */
+import type { BuyNextAction } from './client.js';
 import type { BuyToolProduct, BuyToolResult, BuyToolStatus } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
@@ -11,6 +20,8 @@ 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;
     price: string | null;
     /** True when the shopper holds this product's store page, which `sendLink` delivered beside the reply. */
@@ -19,6 +30,8 @@ export interface BuyToolModelProduct {
 /** The buy tool's answer as the model reads it. */
 export interface BuyToolModelView {
     status: BuyToolStatus;
+    /** The one thing to ask the shopper for in this message, or null when nothing waits on them. Never ask for a later step. */
+    next_action: BuyNextAction | null;
     /** Agentcard's answer for the shopper, with every link taken out. */
     reply: string;
     /** The newest cart on the table. */
@@ -32,6 +45,11 @@ export interface BuyToolModelView {
     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. */
 export declare function stripLinks(text: string): string;
@@ -47,9 +65,14 @@ export declare function money(minor: number | null | undefined, currency: string
  * 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

@@ -1,5 +1,5 @@
 const MODEL_STATUSES = new Set(['needs_input', 'needs_card', 'approval_sent', 'placing', 'order_placed', 'declined']);
-/** The model sees the first twenty products the search found, the cap the backend's catalog keeps for a turn. */
+/** At most twenty products reach the model. Agentcard's /buy answer lists three, so this cap holds only for an older answer. */
 const MAX_PRODUCTS = 20;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const SCHEME_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`)\]]*/gi;
@@ -67,6 +67,15 @@ export function money(minor, currency) {
 export function shownProducts(products) {
     return (products ?? []).filter((product) => stripLinks(product.name) !== '').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 {
         store: stripLinks(cart.store?.name ?? cart.merchant_name) || stripLinks(cart.merchant),
@@ -78,7 +87,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`.
  */
@@ -88,15 +97,18 @@ export function forModel(result) {
     const held = (product) => product.linkSent === true && typeof product.url === 'string' && product.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) => ({ 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), 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,
         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,
     };
 }
 /**

package/dist/shopper-message.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Every Agentcard event a shopper should hear about, read as one message for that shopper's chat.
+ * `purchase.message` carries the text Agentcard wrote. `order.confirmed` and `order.updated` carry
+ * facts only, so the package writes their text. Every other event type is not a shopper message.
+ */
+import { type AgentcardEvent } from './verify.js';
+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"];
+/** One of the event types that carry a message for a shopper. */
+export type ShopperEventType = (typeof SHOPPER_EVENT_TYPES)[number];
+/**
+ * The delivery stage of an order, as `order.updated` names it. A stage Agentcard adds later reads
+ * as its own name.
+ */
+export type OrderStatus = 'confirmed' | 'courier_assigned' | 'courier_at_store' | 'ready_for_pickup' | 'picked_up' | 'arriving' | 'delivered' | 'canceled';
+/**
+ * The moment a shopper message is about. The `purchase.message` kinds, then:
+ * - `order_confirmed`: the retailer accepted the order on its side (`order.confirmed`).
+ * - `order_updated`: the order reached a new delivery stage, named in `facts.orderStatus` (`order.updated`).
+ */
+export type ShopperMessageKind = PurchaseMessageKind | 'order_confirmed' | 'order_updated';
+/** The values of a shopper message one by one. A fact that does not apply is absent. */
+export interface ShopperFacts extends PurchaseFacts {
+    /** The retailer's own order number, as on its confirmation and account page. */
+    retailerOrderId?: string;
+    /** The retailer's quoted delivery window, in its own words. */
+    deliveryWindow?: string;
+    /** The order's delivery stage. */
+    orderStatus?: OrderStatus | (string & {});
+    /** The stage before this one. */
+    previousOrderStatus?: OrderStatus | (string & {});
+    /** The store's own line for the stage, such as "Your Dasher is nearby". */
+    statusTitle?: string;
+    /** The earliest and the latest arrival the store estimates, as ISO 8601 timestamps. */
+    arrivalEarliest?: string;
+    arrivalLatest?: string;
+    /** When the order was delivered, as an ISO 8601 timestamp. */
+    deliveredAt?: string;
+    /** Why the store canceled the order, in its own word. */
+    canceledReason?: string;
+}
+/** A message for one shopper's chat, read from any event that carries one. */
+export interface ShopperMessage {
+    /** The event id. Agentcard delivers at least once: handle each id once. */
+    eventId: string;
+    /** The event type the message arrived as. */
+    type: ShopperEventType;
+    /**
+     * The moment the message is about: one of the kinds above, or a kind Agentcard adds later, read
+     * as its own name. Give a `switch` over it a default branch that sends `text`.
+     */
+    kind: ShopperMessageKind | (string & {});
+    /** The shopper's Agentcard user id. */
+    userId: string;
+    /** Your own id for the shopper, when you gave Agentcard one: the chat to post `text` into. */
+    externalUserId: string | null;
+    /** The buy conversation the event belongs to, when Agentcard names one. */
+    conversationId: string | null;
+    /** Ready to send to the shopper as is. */
+    text: string;
+    /** For your agent: the facts of what happened, marked as written by the system and not typed by the shopper. */
+    note: string;
+    facts: ShopperFacts;
+    /** The OAuth client id of the app the shopper connected through, when the event names it. */
+    clientId: string | null;
+    /** False for a sandbox event. */
+    livemode: boolean;
+    /** Unix seconds. */
+    created: number;
+}
+/**
+ * The message an event carries for a shopper, or null when it carries none: an event type that is
+ * not a shopper event, an order event that names no shopper, or a delivery stage the package does
+ * not know and the store gave no line for. Pass the event `verifyAgentcardWebhook` returned.
+ * Throws a TypeError when a `purchase.message` lacks its kind, user_id or text.
+ */
+export declare function readShopperMessage(event: AgentcardEvent): ShopperMessage | null;
+/**
+ * Whether the message stopped holding before `now` (unix milliseconds, default the system clock):
+ * the link or the window its text names has closed. Drop a stale message instead of sending it.
+ */
+export declare function isStale(message: Pick<ShopperMessage, 'facts'>, now?: number): boolean;

package/dist/shopper-message.js

@@ -0,0 +1,175 @@
+/**
+ * Every Agentcard event a shopper should hear about, read as one message for that shopper's chat.
+ * `purchase.message` carries the text Agentcard wrote. `order.confirmed` and `order.updated` carry
+ * facts only, so the package writes their text. Every other event type is not a shopper message.
+ */
+import { isRecord } from './verify.js';
+import { readPurchaseMessage } 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 const SHOPPER_EVENT_TYPES = ['purchase.message', 'order.confirmed', 'order.updated'];
+const SYSTEM_LINE = 'This note was generated by the system, not typed by the user.';
+function text(value, max = 200) {
+    if (typeof value !== 'string')
+        return undefined;
+    // One line, so a value never breaks the sentence it sits in.
+    const line = value.replace(/\s+/g, ' ').trim();
+    return line === '' ? undefined : line.slice(0, max);
+}
+/** An id exactly as Agentcard sent it, so a lookup by it finds the same record the other events name. */
+function id(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** Facts without the values that do not apply. */
+function present(facts) {
+    return Object.fromEntries(Object.entries(facts).filter(([, value]) => value !== undefined));
+}
+/**
+ * The store as the shopper knows it, or null when the event names a roster of stores rather than
+ * one: a retail order names every retailer it can reach.
+ */
+function storeOf(data) {
+    if (data.merchant === 'retail')
+        return null;
+    return text(data.merchant_name, 64) ?? null;
+}
+const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+/** "Your DoorDash order is almost there." for each stage, or null for a stage the package does not know. */
+function stageText(status, store, reason, title) {
+    const order = store ? `your ${store} order` : 'your order';
+    switch (status) {
+        case 'confirmed':
+            return store ? `${store} accepted your order.` : 'The store accepted your order.';
+        case 'courier_assigned':
+            return `A driver is assigned to ${order}.`;
+        case 'courier_at_store':
+            return `The driver is at the store for ${order}.`;
+        case 'ready_for_pickup':
+            return `${capitalize(order)} is ready for pickup.`;
+        case 'picked_up':
+            return `${capitalize(order)} is picked up and on its way.`;
+        case 'arriving':
+            return `${capitalize(order)} is almost there.`;
+        case 'delivered':
+            return `${capitalize(order)} was delivered.`;
+        case 'canceled':
+            return `${capitalize(order)} was canceled${reason ? `: ${reason}` : ''}.`;
+        default:
+            return title ? `${store ? `${store}: ` : ''}${title}` : null;
+    }
+}
+function orderBase(event, type) {
+    const data = event.data;
+    const userId = id(data.user_id);
+    if (!userId)
+        return null;
+    const connection = isRecord(data.connection) ? data.connection : {};
+    return {
+        data,
+        store: storeOf(data),
+        base: {
+            eventId: event.id,
+            type,
+            userId,
+            externalUserId: id(data.external_user_id) ?? null,
+            conversationId: id(data.conversation_id) ?? null,
+            clientId: id(connection.client_id) ?? null,
+            livemode: event.livemode,
+            created: event.created,
+        },
+    };
+}
+function readOrderConfirmed(event) {
+    const read = orderBase(event, 'order.confirmed');
+    if (!read)
+        return null;
+    const { data, store, base } = read;
+    const retailerOrderId = text(data.retailer_order_id, 80);
+    const deliveryWindow = text(data.delivery_window, 80);
+    const facts = present({
+        merchantName: store ?? undefined,
+        totalCents: count(data.final_total_cents) ?? count(data.charged_cents),
+        currency: text(data.currency, 8),
+        orderId: id(data.order_id),
+        retailerOrderId,
+        deliveryWindow,
+    });
+    const who = store ? `${store} confirmed your order` : 'The store confirmed your order';
+    return {
+        ...base,
+        kind: 'order_confirmed',
+        text: `${who}${retailerOrderId ? `, order number ${retailerOrderId}` : ''}.${deliveryWindow ? ` Expected delivery: ${deliveryWindow}.` : ''}`,
+        note: `[event: the store accepted this user's order${store ? ` at ${store}` : ''} on its side, outside this conversation.` +
+            `${retailerOrderId ? ` The store's order number is ${retailerOrderId}.` : ''}` +
+            `${deliveryWindow ? ` The store quotes delivery ${deliveryWindow}.` : ''} ${SYSTEM_LINE}]`,
+        facts,
+    };
+}
+function readOrderUpdated(event) {
+    const read = orderBase(event, 'order.updated');
+    if (!read)
+        return null;
+    const { data, store, base } = read;
+    const status = text(data.status, 40);
+    if (!status)
+        return null;
+    const statusTitle = text(data.status_title, 120);
+    const canceledReason = text(data.canceled_reason, 120);
+    const message = stageText(status, store, canceledReason, statusTitle);
+    if (!message)
+        return null;
+    const arrival = isRecord(data.estimated_arrival) ? data.estimated_arrival : {};
+    const previous = text(data.previous_status, 40);
+    return {
+        ...base,
+        kind: 'order_updated',
+        text: message,
+        note: `[event: this user's order${store ? ` at ${store}` : ''} moved to the stage ${status}` +
+            `${previous ? ` from ${previous}` : ''}, outside this conversation.` +
+            `${statusTitle ? ` The store says: ${statusTitle}.` : ''}${canceledReason ? ` The store's reason: ${canceledReason}.` : ''} ${SYSTEM_LINE}]`,
+        facts: present({
+            merchantName: store ?? undefined,
+            orderId: id(data.order_id),
+            orderStatus: status,
+            previousOrderStatus: previous,
+            statusTitle,
+            arrivalEarliest: text(arrival.earliest, 40),
+            arrivalLatest: text(arrival.latest, 40),
+            deliveredAt: text(data.delivered_at, 40),
+            canceledReason,
+        }),
+    };
+}
+/**
+ * The message an event carries for a shopper, or null when it carries none: an event type that is
+ * not a shopper event, an order event that names no shopper, or a delivery stage the package does
+ * not know and the store gave no line for. Pass the event `verifyAgentcardWebhook` returned.
+ * Throws a TypeError when a `purchase.message` lacks its kind, user_id or text.
+ */
+export function readShopperMessage(event) {
+    if (event.type === 'order.confirmed')
+        return readOrderConfirmed(event);
+    if (event.type === 'order.updated')
+        return readOrderUpdated(event);
+    const message = readPurchaseMessage(event);
+    if (!message)
+        return null;
+    return {
+        ...message,
+        type: 'purchase.message',
+        conversationId: id(event.data.conversation_id) ?? null,
+    };
+}
+/**
+ * Whether the message stopped holding before `now` (unix milliseconds, default the system clock):
+ * the link or the window its text names has closed. Drop a stale message instead of sending it.
+ */
+export function isStale(message, now = Date.now()) {
+    const until = message.facts.validUntil ? Date.parse(message.facts.validUntil) : Number.NaN;
+    return Number.isFinite(until) && until <= now;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.1.0",
-  "description": "Give your agent one tool that buys for your shoppers at real stores, and hear what happened to each purchase from a signed webhook.",
+  "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.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",