@agent-cards/commerce-sdk 0.0.0-stage → 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,272 @@
+/** The fetch the client calls: Node 18 and later have one built in. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    ok: boolean;
+    text(): Promise<string>;
+}>;
+export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
+/** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
+export declare const BUY_TURN_TIMEOUT_MS = 130000;
+/** A company's client credentials, or one shopper's own access token. */
+export type AgentcardClientOptions = {
+    baseUrl?: string;
+    fetch?: FetchLike;
+} & ({
+    clientId: string;
+    clientSecret: string;
+    accessToken?: undefined;
+} | {
+    accessToken: string;
+    clientId?: undefined;
+    clientSecret?: undefined;
+});
+/** Who a call is for. A company names the shopper by its own id or by Agentcard's user id. Under a shopper's own token, leave both out. */
+export interface Shopper {
+    externalUserId?: string;
+    userId?: string;
+}
+/** A delivery address the company already holds for the shopper; the cart is built for it and the shopper is asked for none of it. */
+export interface BuyDeliveryAddress {
+    street: string;
+    city: string;
+    state: string;
+    zip: string;
+    address2?: string;
+    phone?: string;
+    name?: string;
+    country?: string;
+    can_leave_at_door?: boolean;
+}
+/** One `POST /buy`, as sent. */
+export interface BuyRequest {
+    ask?: string;
+    /** A cart hash from an earlier answer, or true for the cart Agentcard last answered with. */
+    confirm?: string | true;
+    /** Continue the shopper's newest open conversation instead of starting one. */
+    resume?: true;
+    /** Drop the cart on the table and start a new order. */
+    new_order?: true;
+    payment_source?: 'vault';
+    delivery_address?: BuyDeliveryAddress;
+    external_user_id?: string;
+    user_id?: string;
+}
+export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
+export interface BuyStore {
+    id: string;
+    name?: string;
+}
+export interface BuyCartLine {
+    name: string;
+    qty: number;
+    priceCents?: number;
+    product_id: string | null;
+    /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
+    url: string | null;
+}
+/**
+ * A cart as Agentcard answers it. `totalCents` is the all-in figure the shopper sees; `hash` is what a confirm names.
+ * Every amount is in the minor unit of `currency`, the store's ISO 4217 code.
+ */
+export interface BuyCart {
+    merchant: string;
+    merchant_name: string;
+    store: BuyStore | null;
+    items: BuyCartLine[];
+    serviceFeesCents: number;
+    tipCents: number;
+    totalCents: number;
+    /** The ISO 4217 code the store prices the cart in, or null when Agentcard sent none. */
+    currency: string | null;
+    approvedCeilingCents: number | null;
+    hash: string;
+}
+/** A product a search found. `priceCents` is in the minor unit of `currency`, the store's ISO 4217 code. */
+/** Supplier facts only. Missing facts stay null; fare cabin does not establish segment cabins. */
+export interface BuyFlightItinerary {
+    fareCabinClass?: string | null;
+    legs: Array<{
+        origin: string | null;
+        destination: string | null;
+        departureAt: string | null;
+        arrivalAt: string | null;
+        cabinClasses: Array<string | null>;
+    }>;
+}
+export interface BuyCatalogItem {
+    flight?: BuyFlightItinerary;
+    id: string;
+    name: string | null;
+    priceCents: number | null;
+    /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
+    currency: string | null;
+    image_url: string | null;
+    store: BuyStore | null;
+    /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
+    url: string | null;
+}
+/** The products the last search found. */
+export interface BuyCatalog {
+    merchant: string;
+    merchant_name: string;
+    items: BuyCatalogItem[];
+}
+export interface BuyPaymentSource {
+    source: string;
+    brand: string | null;
+    last4: string | null;
+}
+/**
+ * The one thing the shopper does next, as Agentcard names it, in the order a purchase asks for them:
+ * `shipping_details` (a shipping address and phone), `guest_details` (a name, email and phone for a
+ * booking), `add_card` (a card in their Vault), `confirm` (their yes to the cart), `verification_code`
+ * (the code a booking texted them), then `approve` (the approval link). A value this version does
+ * not know reads as null.
+ */
+export type BuyNextAction = 'shipping_details' | 'guest_details' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
+/** One turn's answer, every field read for its type; a field an older API does not send reads as null. */
+export interface BuyTurn {
+    conversation_id: string;
+    /** A status Agentcard adds later reads as `needs_input`. */
+    status: BuyStatus;
+    reply: string;
+    messages: string[];
+    cart: BuyCart | null;
+    carts: BuyCart[];
+    catalog: BuyCatalog | null;
+    order_id: string | null;
+    payment_source: BuyPaymentSource | null;
+    decline_code: string | null;
+    approval_url: string | null;
+    charge_status: string | null;
+    error_code: string | null;
+    authorization_id: string | null;
+    merchant_total_cents: number | null;
+    merchant_currency: string | null;
+    add_card_url: string | null;
+    add_card_expires_at: string | null;
+    placement_announced: boolean | null;
+    approval_expires_at: string | null;
+    approval_in_progress: boolean | null;
+    /** The one step the shopper takes next, or null when nothing waits on them or Agentcard named none. */
+    next_action: BuyNextAction | null;
+    /** The page where the shopper signs in to a store's own account before Agentcard can buy there. */
+    store_login_url: string | null;
+    store_login_expires_at: string | null;
+    /** The store that page signs in to. */
+    store_login_merchant_name: string | null;
+    /** The answer as Agentcard sent it. */
+    raw: Record<string, unknown>;
+}
+export interface BuyOrder {
+    order_id: string | null;
+    merchant: string;
+    merchant_name: string;
+    status: string;
+    total_cents: number;
+    placed_at: string | null;
+}
+export interface BuyLastCheckout {
+    at: string;
+    merchant: string;
+    merchant_name: string;
+    status: string;
+    code: string | null;
+    message: string | null;
+    order_id: string | null;
+    decline_code: string | null;
+    approval_url: string | null;
+    approval_expires_at: string | null;
+    placement_announced: boolean | null;
+    approval_in_progress: boolean | null;
+    /** The add-card link a checkout that found no card made, and when it stops working. */
+    add_card_url: string | null;
+    add_card_expires_at: string | null;
+    total_cents: number | null;
+}
+/** Where one conversation stands: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
+export interface BuyConversation {
+    conversation_id: string;
+    status: 'open' | 'closed';
+    turn_in_progress: boolean;
+    last_checkout: BuyLastCheckout | null;
+    orders: BuyOrder[];
+    carts: BuyCart[];
+    raw: Record<string, unknown>;
+}
+/** A Vault link: the page where a shopper connects and adds a card. */
+export interface VaultLink {
+    id: string;
+    url: string;
+    /** When the link stops working, as an ISO 8601 timestamp. */
+    expiresAt: string | null;
+    /** True when Agentcard returned a link it had already opened for this shopper. */
+    reused: boolean;
+}
+/**
+ * A refusal, or a failure to reach Agentcard. `code` is the API's own
+ * (`user_not_connected`, `external_user_id_ambiguous`, `turn_in_progress`,
+ * `user_id_mismatch`), one read from the shape of the answer
+ * (`cart_changed`, `nothing_to_confirm`, `conversation_closed`,
+ * `conversation_not_found`), or the client's (`unreachable`, `timeout`,
+ * `oauth_failed`, `unauthorized`, `http_<status>`). `status` is 0 when
+ * Agentcard never answered.
+ */
+export declare class AgentcardApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** The error body as Agentcard sent it. */
+    readonly body: Record<string, unknown>;
+    readonly conversationId: string | null;
+    /** The carts as they stand, when the refusal names them: a changed cart's fresh hash is here. */
+    readonly carts: BuyCart[];
+    constructor(status: number, code: string, message: string, body?: Record<string, unknown>, cause?: unknown);
+}
+/** A turn as Agentcard answers it. */
+export declare function turnOf(body: Record<string, unknown>): BuyTurn;
+/** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */
+export declare class AgentcardClient {
+    readonly baseUrl: string;
+    private readonly fetchFn;
+    private readonly credentials;
+    private readonly shopperToken;
+    private token;
+    private inflight;
+    private learnedSandbox;
+    constructor(options: AgentcardClientOptions);
+    /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
+    get company(): boolean;
+    /** True for a sandbox client, as the token exchange said; null until the first exchange, and under a shopper's token. */
+    get sandbox(): boolean | null;
+    /** The access token the client sends: the shopper's own, or the company's, exchanged once and renewed a minute before it expires. */
+    bearer(): Promise<string>;
+    /**
+     * One purchase turn, sent once with a 130-second wait. A turn is a model run
+     * against live stores, so a lost answer is never sent again: read the
+     * conversation instead. Only a 401 is sent again, once, with a fresh token,
+     * because Agentcard refused it before anything ran.
+     */
+    buy(body: BuyRequest): Promise<BuyTurn>;
+    /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
+    conversation(conversationId: string, who?: Shopper): Promise<BuyConversation>;
+    /**
+     * The Vault link a shopper opens to connect to your company and add a card.
+     * Agentcard returns the link it already opened for this shopper while that
+     * link has time left, so a shopper who asks twice gets one link. Sent once.
+     */
+    mintVaultLink(input: {
+        externalUserId: string;
+    }): Promise<VaultLink>;
+    /** A company names the shopper exactly once; a shopper's own token already names them. */
+    private checkShopper;
+    private call;
+    private send;
+    /** After a 401: the token another call already renewed, or one new exchange, however many calls were refused at once. */
+    private renewAfter;
+    private exchange;
+}