@agent-cards/commerce-sdk 0.5.0 → 0.8.0

package/dist/events.js

@@ -0,0 +1,79 @@
+/**
+ * Every event type Agentcard sends a company, the same list a webhook endpoint subscribes to by
+ * name. The stream (`agentcard.listen`) and a webhook endpoint carry the same types, with the same
+ * envelope and the same ids. A test holds this list to the backend's catalog.
+ */
+export const AGENTCARD_EVENT_TYPES = [
+    'card.created',
+    'card.updated',
+    'card.closed',
+    'cardholder.created',
+    'cardholder.updated',
+    'transaction.authorized',
+    'transaction.declined',
+    'transaction.cleared',
+    'transaction.voided',
+    'balance.low',
+    'cardholder_onboarding_session.completed',
+    'platform_connect_session.completed',
+    'merchant.connected',
+    'order.placed',
+    'order.confirmed',
+    'order.failed',
+    'order.updated',
+    'purchase.message',
+    'connection.created',
+    'connected_card.updated',
+    'vault.card_stored',
+    'vault.session_linked',
+    'vault.session_card_picked',
+    'vault.payment_permission.updated',
+    'action.confirmed',
+    'action.done',
+    'checkout_authorization.approved',
+    'checkout_authorization.submitted',
+    'checkout_authorization.declined',
+    'checkout_authorization.cancelled',
+    'checkout_authorization.expired',
+    'checkout_authorization.duplicate_charge',
+    'checkout_authorization.refused',
+    'checkout_authorization.watched',
+    'checkout_authorization.amount_mismatch',
+    'checkout_authorization.settled',
+    'checkout_authorization.settlement_unconfirmed',
+    'checkout_authorization.outcome_reported',
+    'card_flow.started',
+    'card_flow.failed',
+    'transfer.approved',
+    'transfer.initiated',
+    'transfer.completed',
+    'transfer.failed',
+    'transfer.released',
+    'wallet.funded',
+    'user_wallet.funding_detected',
+    'user_wallet.funded',
+    'wallet.balance.low',
+    'recovery.requested',
+    'recovery.completed',
+    'recovery.rejected',
+    'wallet.withdrawal.initiated',
+    'wallet.withdrawal.completed',
+    'wallet.withdrawal.failed',
+    'identity.verification.updated',
+    'approval.requested',
+    'reward.earned',
+    'reward.reversed',
+    'wallet_link.opened',
+];
+const KNOWN = new Set(AGENTCARD_EVENT_TYPES);
+const FAMILIES = new Set(AGENTCARD_EVENT_TYPES.map((t) => `${t.split('.')[0]}.*`));
+/** Whether a filter entry names something Agentcard sends: an event type, a family such as `order.*`, or `*`. */
+export function isEventPattern(pattern) {
+    return pattern === '*' || KNOWN.has(pattern) || FAMILIES.has(pattern);
+}
+/** Whether an event type matches a filter entry, as a webhook subscription matches it. */
+export function matchesEventPattern(type, pattern) {
+    if (pattern === '*' || pattern === type)
+        return true;
+    return pattern.endsWith('.*') && type.startsWith(pattern.slice(0, -1));
+}

package/dist/index.d.ts

@@ -2,10 +2,12 @@ export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatur
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, } from './client.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, } from './buy-tool.js';
-export { ackFor, type AckForOptions } from './ack.js';
-export { forModel, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
+export { instantAck, ackFor, type AckForOptions } from './ack.js';
+export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
+export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
+export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';

package/dist/index.js

@@ -6,6 +6,8 @@ export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_U
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, } from './messages.js';
 export { buyTool, } from './buy-tool.js';
-export { ackFor } from './ack.js';
-export { forModel, stripLinks, } from './model-view.js';
+export { instantAck, ackFor } from './ack.js';
+export { forModel, forModelError, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
+export { listenToAgentcard, } from './listen.js';
+export { AGENTCARD_EVENT_TYPES, } from './events.js';

package/dist/listen.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 { type AgentcardEvent } from './verify.js';
+import { type ShopperMessage } from './shopper-message.js';
+import { type AgentcardEventType } from './events.js';
+import { type AgentcardClient } from './client.js';
+/** Where the listener keeps the cursor of the last event it handled, so a restarted server resumes there. */
+export interface ListenCursorStore {
+    /** The cursor saved last, or null to start from now. */
+    load(): Promise<string | null> | string | null;
+    /** Called after each handled event, and at most once a minute while no event arrives. */
+    save(cursor: string): Promise<void> | void;
+}
+/** The fetch the listener streams with: the global fetch of Node 18 and later. */
+export type StreamFetch = (url: string, init: {
+    method: 'GET';
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+    ok: boolean;
+    headers: {
+        get(name: string): string | null;
+    };
+    body: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel(reason?: unknown): Promise<void>;
+        };
+    } | null;
+    text(): Promise<string>;
+}>;
+export interface ListenOptions {
+    /**
+     * Receives each event for one of your shoppers, under your own id for them, with the message
+     * ready to post into that shopper's chat: the same as `agentcardWebhook`'s `onMessage`. A message
+     * whose link or window closed before it arrived reaches no shopper: its event goes to `onEvent`.
+     */
+    onMessage?: (externalUserId: string, message: ShopperMessage, event: AgentcardEvent<AgentcardEventType>) => void | Promise<void>;
+    /** Receives every event `onMessage` does not take: every event, when you pass no `onMessage`. */
+    onEvent?: (event: AgentcardEvent<AgentcardEventType | (string & {})>) => void | Promise<void>;
+    /**
+     * Receives what went wrong: a callback that threw five times, after which the listener moves on,
+     * a lost connection it is about to retry, a cursor Agentcard no longer keeps. A reporter that
+     * throws is ignored. Default: `console.error`.
+     */
+    onError?: (error: unknown, event?: AgentcardEvent) => void | Promise<void>;
+    /** Only these events: event types, families such as `order.*`, or `*`. Default: every event. */
+    events?: string[];
+    /** Keeps the cursor across restarts. Default: in memory, so a new process starts from now. */
+    cursor?: ListenCursorStore;
+    /** `auto` streams and falls back to polling when the stream is not available. Default `auto`. */
+    transport?: 'auto' | 'stream' | 'poll';
+    /** How long polling waits between reads. Default 2000. */
+    pollIntervalMs?: number;
+    /** How long the stream may stay silent before the listener reconnects. Agentcard sends a heartbeat every 15 seconds. Default 45000. */
+    heartbeatTimeoutMs?: number;
+    /** How long one polling read may take before the listener gives up on it and reads again. Default 30000. */
+    pollTimeoutMs?: number;
+    /** The fetch to stream with. Default: the global fetch. */
+    fetch?: StreamFetch;
+}
+/** A running listener. */
+export interface AgentcardListener {
+    /** Resolves once the listener first reaches Agentcard, or once it closes. */
+    readonly ready: Promise<void>;
+    /** How the listener hears Agentcard right now. */
+    readonly transport: 'stream' | 'poll';
+    /** The cursor of the last event handled, or null before the first connection. */
+    readonly cursor: string | null;
+    /** Stops listening. Resolves once the callback that is running, if any, has returned. */
+    close(): Promise<void>;
+}
+/**
+ * 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 declare function listenToAgentcard(agentcard: AgentcardClient, opts: ListenOptions): AgentcardListener;