@agent-cards/commerce-sdk 0.2.0 → 0.5.0

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.2.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",