@agent-cards/sdk 0.20.0

package/dist/buy.d.ts

@@ -0,0 +1,374 @@
+/**
+ * The buy module of the SDK: `agentcard.buy.*`. The Purchase API from the
+ * same client the voice module uses: one pair of client credentials, one
+ * token. A business asks for a cart on behalf of a person it connected,
+ * confirms the cart by its hash, and, when it already holds an approval the
+ * person gave by voice, names that approval on the confirm so the API places
+ * against it and asks the person for nothing a second time (decision 234).
+ * With `approval: 'voice'` the confirm asks the API to mint the purchase's
+ * own approval instead of an approval page, the business runs the key word
+ * in its app on that id, and the same confirm placed again completes the
+ * order (decision 237).
+ *
+ * Every call names `user_id`, the person the connect exchange returned, so a
+ * server serving many people never buys for the wrong one. A person who is
+ * not connected to this client is refused with `user_not_connected`.
+ */
+import { ApiModule, type ApiTransport } from './api-module.js';
+import { AgentcardError } from './voice-types.js';
+/** Where a turn stands. `needs_input` is the common case: a question, or a cart waiting for its confirm; `needs_approval` is a confirm under `approval: 'voice'` waiting for the person's verdict on `authorization_id`. */
+export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
+/** How a confirm that pays with the person's own card asks them: `page`, Agentcard's approval page on `approval_url` (the default); `voice`, the key word inside your app on the purchase's own `authorization_id`. */
+export type BuyApproval = 'voice' | 'page';
+/** The two ways a purchase approved by voice ends without an order: the person declined it, or the approval ran out before a confirm placed against it. */
+export type BuyVoiceDeclineCode = 'voice_declined' | 'approval_expired';
+/** The one refusal a store makes under `approval: 'voice'`: its connector cannot place under a voice verdict, and the business takes its own path. A 409, as `BuyError.code`. */
+export declare const VOICE_EXECUTION_UNSUPPORTED = "voice_execution_unsupported";
+/** One line of a cart as the API shows it; `product_id` is the merchant's id for the line, null on a cart recorded before it was kept. */
+export interface BuyCartLine {
+    name: string;
+    qty: number;
+    priceCents?: number;
+    product_id: string | null;
+}
+/**
+ * A cart on the table, as the API answers it. `hash` is what a confirm echoes;
+ * `totalCents` is the all-in figure the person saw (the merchant's total, the
+ * service fees and the tip); `approvedCeilingCents` is the most a confirm may
+ * authorize when the merchant finalizes tax and shipping at placement, null
+ * when the ceiling is the total. The hash covers every field here except `store`, which the API
+ * derives from the lines when it answers and which is a label, not confirmation-bound information.
+ */
+/** A store a cart or a search result is at: the retailer's id (`amazon`) and its name (`Amazon`) when known. */
+export interface BuyStore {
+    id: string;
+    name?: string;
+}
+export interface BuyCart {
+    merchant: string;
+    merchant_name: string;
+    /** The store the cart is at, when one is known: for `retail`, the retailer every line is at. Null otherwise. */
+    store: BuyStore | null;
+    items: BuyCartLine[];
+    serviceFeesCents: number;
+    tipCents: number;
+    totalCents: number;
+    approvedCeilingCents: number | null;
+    hash: string;
+}
+/** A delivery address the business already holds for the person; the API binds these values and asks the person for none of them. */
+export interface BuyDeliveryAddress {
+    street: string;
+    city: string;
+    state: string;
+    zip: string;
+    address2?: string;
+    phone?: string;
+    name?: string;
+    country?: string;
+    can_leave_at_door?: boolean;
+}
+/** What paid, or would have paid. */
+export interface BuyPaymentSource {
+    source: string;
+    brand: string | null;
+    last4: string | null;
+}
+/**
+ * The typed outcome of a checkout attempt, every field null when no checkout
+ * ran on the call. `decline_code` is a refusal's machine code
+ * (`authorization_not_approved`, `authorization_mismatch`,
+ * `authorization_spent`, `user_not_connected`, `voice_declined`,
+ * `approval_expired`, a gate's or a merchant's code); `approval_url` is
+ * where the person approves when the confirm paused for one;
+ * `authorization_id` is the approval the order was placed against, or, on a
+ * `needs_approval` turn, the one the person is about to give by voice.
+ */
+export interface BuyOutcome {
+    order_id: string | null;
+    payment_source: BuyPaymentSource | null;
+    decline_code: string | null;
+    refusal_code: string | null;
+    approval_url: string | null;
+    charge_status: string | null;
+    merchant_total_cents: number | null;
+    merchant_currency: string | null;
+    authorization_id: string | null;
+}
+/** One cart's outcome on a confirm of several carts; each order is its own turn, so some may place and others not. */
+export interface BuyPlacement extends BuyOutcome {
+    merchant: string;
+    merchant_name: string;
+    status: BuyStatus;
+    reply: string;
+    error_code: string | null;
+}
+/** The last product search as data, for a picker of your own. */
+export interface BuyCatalog {
+    merchant: string;
+    merchant_name: string;
+    /** The store searched, or the one store every result is at. Null when the results span stores; each item then names its own. */
+    store: (BuyStore & {
+        eta_minutes?: number | null;
+    }) | null;
+    /** `store`: the retailer this result is at, on a `retail` search across stores. */
+    items: Array<{
+        id: string;
+        name?: string;
+        priceCents?: number;
+        image_url?: string;
+        store?: BuyStore;
+    }>;
+    as_of: string;
+}
+/** An ask that reached no cart, with the reason the API derived. */
+export interface BuyUnmatched {
+    merchant: string;
+    requested: string;
+    reason: 'not_found' | 'unavailable';
+    detail: string | null;
+    at: string;
+}
+/**
+ * One turn's answer. Branch on `status`; read `cart.hash` for the confirm
+ * that follows; never parse `reply`. `error_code: 'turn_timeout'` means the
+ * turn is still running: the carts here are what it had shown so far, and
+ * `buy.conversation` reads when it is done. A `declined` turn carries its
+ * `decline_code`; a `partially_placed` one names each cart's outcome in
+ * `placements`.
+ */
+export interface BuyTurn extends BuyOutcome {
+    conversation_id: string;
+    status: BuyStatus;
+    reply: string;
+    messages: string[];
+    message_id: string | null;
+    cart: BuyCart | null;
+    carts: BuyCart[];
+    placements: BuyPlacement[] | null;
+    catalog: BuyCatalog | null;
+    error_code: string | null;
+    unmatched: BuyUnmatched[];
+}
+/** A turn the API declined: `status: 'declined'` with the code that says why. `isBuyDeclined` narrows to it. */
+export type BuyDeclined = BuyTurn & {
+    status: 'declined';
+};
+/** True for a turn the API declined; `decline_code` says why (it is null when the loop refused in prose only). */
+export declare function isBuyDeclined(turn: BuyTurn | BuyVoiceUnsupported): turn is BuyDeclined;
+/** A confirm under `approval: 'voice'` waiting for the person: `authorization_id` is the purchase's own approval, minted by the API, for `voice.challengeForHost`. `isBuyNeedsApproval` narrows to it. */
+export type BuyNeedsApproval = BuyTurn & {
+    status: 'needs_approval';
+    authorization_id: string;
+};
+/** True for a confirm waiting for the person's verdict by voice; `authorization_id` is the id your app runs the key word on. */
+export declare function isBuyNeedsApproval(turn: BuyTurn | BuyVoiceUnsupported): turn is BuyNeedsApproval;
+/**
+ * The store's refusal to place under a voice verdict, as `buy.approveByVoice`
+ * returns it instead of throwing: `status: 'voice_execution_unsupported'`,
+ * the conversation, the approval the API had minted when it had, and the
+ * `BuyError` as the confirm raised it. The business takes its own path.
+ */
+export interface BuyVoiceUnsupported {
+    status: typeof VOICE_EXECUTION_UNSUPPORTED;
+    conversation_id: string;
+    authorization_id: string | null;
+    error: BuyError;
+}
+/** True when the store could not place under a voice verdict; `error` is the refusal. */
+export declare function isBuyVoiceUnsupported(turn: BuyTurn | BuyVoiceUnsupported): turn is BuyVoiceUnsupported;
+/** What `buy.approveByVoice` returns: the final turn (`order_placed`, `declined`, or `needs_approval` when the verdict was still out on the retry), or the store's refusal to run under a voice verdict. */
+export type BuyVoiceTurn = BuyTurn | BuyVoiceUnsupported;
+/** An order a conversation placed, from the ledger. */
+export interface BuyOrder {
+    order_id: string | null;
+    merchant: string;
+    merchant_name: string;
+    status: 'settled' | 'confirming' | 'failed' | 'cancelled';
+    total_cents: number;
+    payment_source: BuyPaymentSource | null;
+    placed_at: string | null;
+    retailer_order_id: string | null;
+    delivery_window: string | null;
+    confirmed_at: string | null;
+    merchant_total_cents: number | null;
+    merchant_currency: string | null;
+}
+/** The most recent checkout attempt on a conversation, whatever its outcome. */
+export interface BuyLastCheckout extends BuyOutcome {
+    at: string;
+    merchant: string;
+    merchant_name: string;
+    status: string;
+    code: string | null;
+    message: string | null;
+    total_cents: number;
+    items: unknown;
+}
+/**
+ * The API's view of one conversation, for a caller whose confirm timed out or
+ * whose webhook never came: is a turn still running, what the last checkout
+ * did, and every order the conversation placed, from the ledger.
+ */
+export interface BuyConversation {
+    conversation_id: string;
+    status: 'open' | 'closed';
+    turn_in_progress: boolean;
+    last_checkout: BuyLastCheckout | null;
+    orders: BuyOrder[];
+    carts: BuyCart[];
+    unmatched: BuyUnmatched[];
+    created_at: string;
+    updated_at: string;
+}
+/** `buy.ask`: a question or an order in words, for the person `user_id` names. */
+export interface BuyAskInput {
+    /** The person the connect exchange returned. Required on every call. */
+    user_id: string;
+    /** What the person wants, in words. */
+    ask: string;
+    /** The conversation to continue; leave it out to start one. */
+    conversation_id?: string;
+    /** The person's delivery address as you hold it; the cart is built for it and the person is asked for nothing. */
+    delivery_address?: BuyDeliveryAddress;
+    /** How long this call waits for the turn. Default 130 seconds, past the API's own soft budget, so a slow turn answers `turn_timeout` rather than a client-side abort. */
+    timeout_ms?: number;
+}
+/** `buy.confirm`: the cart, by its hash, and the approval the business already holds for it. */
+export interface BuyConfirmInput {
+    /** The person the connect exchange returned. Required on every call. */
+    user_id: string;
+    /** The conversation the cart was shown in. */
+    conversation_id: string;
+    /** The hash of the cart the person saw (`turn.cart.hash`), or several carts' hashes to place each as its own order. */
+    confirm: string | string[];
+    /**
+     * An approval the business already holds for this purchase, `cauth_…`, as
+     * `voice.authorizations.create` minted it and `voice.awaitResult` read it
+     * approved. The API places the cart against it and asks the person for
+     * nothing a second time. Sent only when named.
+     */
+    authorization_id?: string;
+    /** The delivery address the cart was built for, when the ask named one. */
+    delivery_address?: BuyDeliveryAddress;
+    /** `'vault'`: pay with the person's own stored card; the confirm pauses with an `approval_url` until they approve. */
+    payment_source?: 'vault';
+    /**
+     * How the person approves a confirm that pays with their own card. `page`
+     * (the default, and today's behaviour): the API answers `declined` with the
+     * `approval_url` they approve on. `voice`: the API mints the purchase's
+     * own approval and answers `needs_approval` with its `authorization_id`;
+     * your app runs the key word on it (`voice.challengeForHost(id)`), and the
+     * same confirm sent again places the order, or answers `declined` with
+     * `voice_declined` or `approval_expired`. Sent only when named.
+     */
+    approval?: BuyApproval;
+    /** How long this call waits for the turn. Default 130 seconds. */
+    timeout_ms?: number;
+}
+/** `buy.approveByVoice`: the cart, the person, and the approval your app runs on the id the API mints. */
+export interface BuyApproveByVoiceInput {
+    /** The person the connect exchange returned. Required on every call. */
+    user_id: string;
+    /** The conversation the cart was shown in. */
+    conversation_id: string;
+    /** The hash of the cart the person saw (`turn.cart.hash`), or several carts' hashes. */
+    confirm: string | string[];
+    /** The delivery address the cart was built for, when the ask named one. */
+    delivery_address?: BuyDeliveryAddress;
+    /**
+     * Your app's approval: given the `authorization_id` the API minted (and the
+     * `needs_approval` turn it rode on), mint the key word with
+     * `voice.challengeForHost(authorizationId)`, hand the bundle to the app,
+     * and resolve once the verdict is in (`voice.awaitResult`, or the app's
+     * own word). The confirm is sent again when this resolves; a rejection is
+     * thrown as it came and nothing is placed.
+     */
+    challenge: (authorizationId: string, turn: BuyNeedsApproval) => Promise<void>;
+    /** How long each confirm waits for its turn. Default 130 seconds. */
+    timeout_ms?: number;
+}
+/** `buy.conversation`: one read of where a conversation stands. */
+export interface BuyConversationInput {
+    /** The person the connect exchange returned. Required on every call. */
+    user_id: string;
+    conversation_id: string;
+}
+/**
+ * A refusal from the Purchase API, as an `AgentcardError` whose `code` is the
+ * API's (`user_not_connected`, `authorization_not_approved`,
+ * `authorization_mismatch`, `authorization_spent`, `turn_in_progress`,
+ * `delivery_address_changed`, `cart_changed`, `nothing_to_confirm`,
+ * `conversation_not_found`, `conversation_closed`,
+ * `voice_execution_unsupported`) or the client's own before any call
+ * (`not_connected`, `invalid_ask`, `invalid_cart_hash`,
+ * `invalid_authorization_id`, `invalid_payment_source`, `invalid_approval`,
+ * `missing_conversation_id`, `missing_authorization_id`). `carts` carries the
+ * carts as they stand when the refusal named them, so a confirm of a changed
+ * cart reads the fresh hash from the error.
+ */
+export declare class BuyError extends AgentcardError {
+    /** The same code, under the name the turn envelope uses. */
+    readonly error_code: string;
+    readonly conversation_id: string | null;
+    readonly cart: BuyCart | null;
+    readonly carts: BuyCart[];
+    constructor(code: string, message: string, status?: number, details?: Record<string, unknown>);
+    /** The refusal's code when it is one of a checkout's decline codes; the same string as `code`. */
+    get decline_code(): string;
+}
+/** The wait for one turn: past the API's soft budget (110 s), so a slow turn answers `turn_timeout` with its carts rather than aborting here. */
+export declare const BUY_TURN_TIMEOUT_MS = 130000;
+/** A turn as the API answers it, every field read for its type; a field an older API does not carry reads as null or empty. */
+export declare function turnOf(body: Record<string, unknown>): BuyTurn;
+/** `agentcard.buy`: constructed by the client, never on its own. */
+export declare class BuyModule extends ApiModule {
+    constructor(t: ApiTransport);
+    /**
+     * One turn: the person's words go in, a question or a cart comes back.
+     * `status: 'needs_input'` is the normal answer, not a failure: read
+     * `turn.cart` and confirm its hash. The turn is sent once, with no retry,
+     * so a lost answer never runs the turn twice; `buy.conversation` reads
+     * what became of it.
+     */
+    ask(input: BuyAskInput): Promise<BuyTurn>;
+    /**
+     * Places the cart the person saw, by its hash, for the person `user_id`
+     * names. With `authorization_id`, the approval the person already gave by
+     * voice for this purchase, the API places against that approval and asks
+     * for nothing a second time; the answer carries `authorization_id` back.
+     * Without it the confirm runs as before: the person's rules, or the
+     * approval the API asks for on `approval_url`. A cart that changed since
+     * its hash was issued is `cart_changed` with the fresh carts on the error;
+     * an approval that is not approved, is for another purchase, or already
+     * paid one is `authorization_not_approved`, `authorization_mismatch` or
+     * `authorization_spent`, and nothing is charged.
+     */
+    confirm(input: BuyConfirmInput): Promise<BuyTurn>;
+    /**
+     * The whole approval by voice, for a business whose app holds the person:
+     * confirms the cart with the person's own card and `approval: 'voice'`,
+     * hands the `authorization_id` the API minted to your `challenge` (your
+     * app runs the key word on it; you resolve when the verdict is in), then
+     * sends the same confirm again and returns what it answered:
+     * `order_placed` with `order_id`, `declined` with `voice_declined` or
+     * `approval_expired`, or `needs_approval` again when the verdict was still
+     * out. A store whose connector cannot place under a voice verdict is
+     * returned as `status: 'voice_execution_unsupported'`, not thrown, so the
+     * business falls back to its own path; every other refusal throws as
+     * `buy.confirm` does. A first confirm the API completes without asking (a
+     * rule took it, or it declined outright) is returned as it came and
+     * `challenge` is never called. Two confirms at most; nothing is polled.
+     */
+    approveByVoice(input: BuyApproveByVoiceInput): Promise<BuyVoiceTurn>;
+    /**
+     * One read of a conversation, with no wait: whether a turn is still
+     * running, the last checkout attempt, every order it placed from the
+     * ledger, and the carts still on the table. The way an ambiguous confirm
+     * resolves: a `turn_timeout` answer, a lost connection, a webhook that
+     * never came. `slow_down` is waited out.
+     */
+    conversation(input: BuyConversationInput): Promise<BuyConversation>;
+    /** One POST /buy, sent once: a turn is a model run against live merchants, and a retry after a lost answer would run it again. */
+    private turn;
+}