@agent-cards/sdk 0.23.28 → 0.24.0

package/dist/approvals.js

@@ -0,0 +1,213 @@
+import { ApiModule } from './api-module.js';
+import { stripePaymentIntentConfirmRequest } from './requests.js';
+import { AgentcardError } from './api-types.js';
+/** Your server's words for withdrawing a purchase (`approvals.cancel`); anything else is refused before any call. */
+export const CANCEL_REASONS = ['person_closed_sheet', 'person_changed_mind', 'business_cancelled'];
+/** How long `awaitResult` waits when the call names no `timeout_ms`. */
+const AWAIT_RESULT_TIMEOUT_MS = 60_000;
+/**
+ * The sandbox request: a first run's purchase, naming no processor. Under a sandbox client
+ * `approvals.create({ request: 'sandbox' })` sends this; the sandbox completes it without reaching any
+ * processor. A live client refuses it before any call (`sandbox_request_in_live`).
+ */
+export const SANDBOX_REQUEST = stripePaymentIntentConfirmRequest({
+    origin: 'https://sandbox.agentcard.sh',
+    intent: { id: 'pi_sandbox', client_secret: 'pi_sandbox_secret_sandbox', publishable_key: 'pk_test_sandbox' },
+});
+/**
+ * The origin a paused request pays from, when its `origin` header is one Agentcard admits as `checkout_origin`
+ * (an exact https origin, or http://localhost for a local run); null otherwise.
+ */
+function checkoutOriginOf(request) {
+    const header = Object.entries(request.headers ?? {}).find(([k]) => k.toLowerCase() === 'origin')?.[1];
+    if (typeof header !== 'string')
+        return null;
+    try {
+        const u = new URL(header);
+        return u.origin === header && !u.username && !u.password && (u.protocol === 'https:' || (u.protocol === 'http:' && u.hostname === 'localhost')) ? header : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The paying card as the API names it, read for its type; null for null or anything that is not one. */
+function cardOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const c = v;
+    if (typeof c.id !== 'string' || !c.id)
+        return null;
+    return { id: c.id, name: typeof c.name === 'string' ? c.name : '', last4: typeof c.last4 === 'string' ? c.last4 : null, brand: typeof c.brand === 'string' ? c.brand : null, reason: typeof c.reason === 'string' ? c.reason : null };
+}
+/** The choosable cards as the API lists them; a list only, every entry a card. */
+function cardsOf(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = [];
+    for (const raw of v) {
+        const card = cardOf(raw);
+        if (!card)
+            continue;
+        const c = raw;
+        out.push({ ...card, recommended: c.recommended === true, ...(c.auto_approve === true ? { auto_approve: true } : {}) });
+    }
+    return out;
+}
+/** The fields a read carries beside its status, typed, and nothing the row does not carry. */
+function fieldsOf(a) {
+    const out = {};
+    if ('request_id' in a)
+        out.request_id = a.request_id ?? null;
+    if ('external_user_id' in a)
+        out.external_user_id = a.external_user_id ?? null;
+    if (typeof a.interval === 'number')
+        out.interval = a.interval;
+    if (typeof a.poll_interval_ms === 'number')
+        out.poll_interval_ms = a.poll_interval_ms;
+    if (typeof a.expires_at === 'string')
+        out.expires_at = a.expires_at;
+    if ('terminal_reason' in a)
+        out.terminal_reason = a.terminal_reason ?? null;
+    if (typeof a.execution_mode === 'string')
+        out.execution_mode = a.execution_mode;
+    if (typeof a.execution_reason === 'string')
+        out.execution_reason = a.execution_reason;
+    if (typeof a.execution_detail === 'string')
+        out.execution_detail = a.execution_detail;
+    if ('card' in a)
+        out.card = cardOf(a.card);
+    const cards = cardsOf(a.cards);
+    if (cards)
+        out.cards = cards;
+    return out;
+}
+/** A purchase as one read answers it: the status, what approved it, the request fields and the settlement. */
+function resultOf(a) {
+    // The settlement as the API carries it (the same object as on the finishing webhook), read defensively: an object
+    // with a status word, or null when there is nothing to read back; absent from an older API.
+    const settlement = 'settlement' in a
+        ? (a.settlement && typeof a.settlement === 'object' && typeof a.settlement.status === 'string' ? a.settlement : null)
+        : undefined;
+    // The API answers the link as `approvalUrl` on its reads; `approval_url` is read too.
+    const approvalUrl = typeof a.approval_url === 'string' ? a.approval_url : typeof a.approvalUrl === 'string' ? a.approvalUrl : undefined;
+    return {
+        ...(typeof a.id === 'string' ? { id: a.id } : {}),
+        status: a.status,
+        ...(typeof a.approved_with === 'string' ? { approved_with: a.approved_with } : {}),
+        ...fieldsOf(a),
+        ...(settlement === undefined ? {} : { settlement }),
+        ...(approvalUrl && a.status === 'awaiting_approval' ? { approval_url: approvalUrl } : {}),
+    };
+}
+/** A random idempotency key for one create, so a retried call makes one purchase. */
+function idempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return 'ik_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+/** `agentcard.approvals`: constructed by the client, never on its own. */
+export class ApprovalsModule extends ApiModule {
+    clientIsSandbox;
+    constructor(t, clientIsSandbox) {
+        super(t);
+        this.clientIsSandbox = clientIsSandbox;
+    }
+    /**
+     * Creates the purchase, paused for the person's approval on Agentcard's page, for the person `user_id`
+     * names. `execution_mode: 'autopilot'` means the person's rule took it and no approval follows.
+     * `request: 'sandbox'` is the first-run form: under a sandbox client (`sandbox: true`, an `sk_test_`
+     * credential, or a mode the token exchange named) it sends the sandbox request; a live client refuses it
+     * before the create leaves (`sandbox_request_in_live`). Every create carries an idempotency key, so a
+     * retried call makes one purchase.
+     */
+    async create(input) {
+        const user = input.user_id;
+        if (typeof user !== 'string' || !user)
+            throw new AgentcardError('not_connected', 'Name user_id: a person connected to your client. Refused before any call.');
+        let request;
+        if (input.request === 'sandbox') {
+            // A client that was not named sandbox may still learn it from the token exchange; the create itself has not left.
+            if (!this.clientIsSandbox())
+                await this.t.bearer();
+            if (!this.clientIsSandbox())
+                throw new AgentcardError('sandbox_request_in_live', "request: 'sandbox' is for a sandbox client. Under live credentials build the processor's request (checkout.requests.build) or hand over the request a browser purchase paused on. Refused before any call.");
+            request = SANDBOX_REQUEST;
+        }
+        else if (input.request && typeof input.request === 'object' && typeof input.request.url === 'string') {
+            request = input.request;
+        }
+        else {
+            throw new AgentcardError('invalid_request', "request must be a paused request ({ url, method, headers, body }) or 'sandbox'. Refused before any call.");
+        }
+        // The origin the purchase is paid from goes in the create (Agentcard keeps no `origin` header from the paused
+        // request), so a rule the person confirmed can take it; named on the call, else the paused request's own.
+        const checkoutOrigin = input.checkout_origin ?? checkoutOriginOf(request);
+        const body = await this.request('/v2/checkout/authorizations', {
+            method: 'POST',
+            body: {
+                user, merchant: input.merchant, amount: input.amount, currency: input.currency, psp: input.psp ?? 'stripe', mode: input.mode ?? 'token', request,
+                ...(input.return_url ? { return_url: input.return_url } : {}), ...(checkoutOrigin ? { checkout_origin: checkoutOrigin } : {}), ...(input.card_id ? { card_id: input.card_id } : {}),
+            },
+            headers: { 'idempotency-key': input.idempotency_key ?? idempotencyKey() },
+        });
+        const approvalUrl = body.approval_url ?? body.approvalUrl;
+        return {
+            id: body.id, status: body.status, ...fieldsOf(body),
+            ...(approvalUrl ? { approval_url: approvalUrl } : {}), ...(typeof body.return_url === 'string' ? { return_url: body.return_url } : {}),
+        };
+    }
+    /**
+     * One read of a purchase, with no wait: its status, what approved it, the request fields and the settlement
+     * once it finished. The way to ask "is it decided yet?" from a handler that cannot wait; `awaitResult` is the
+     * way to wait. `slow_down` is waited out.
+     */
+    async get(authorizationId) {
+        const a = await this.read(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}`);
+        return resultOf(a);
+    }
+    /**
+     * Withdraws a purchase that still awaits the person, in your server's own words: the person closed the
+     * page (`person_closed_sheet`), the person changed their mind (`person_changed_mind`), or a reason of your
+     * own (`business_cancelled`). The purchase reads `status: 'cancelled'` from then on, and the reason is its
+     * `terminal_reason` on every read and on the `checkout_authorization.cancelled` webhook. Idempotent: a
+     * purchase already withdrawn answers what it became. One the person already approved cannot be withdrawn
+     * (`409 already_finalized` once it finished, `409 outcome_unknown` while the card is with the processor).
+     */
+    async cancel(authorizationId, opts) {
+        const reason = opts?.reason;
+        if (!CANCEL_REASONS.includes(reason))
+            throw new AgentcardError('invalid_cancel_reason', `reason must be one of ${CANCEL_REASONS.join(', ')}.`);
+        const body = await this.request(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}/cancel`, { method: 'POST', body: { reason } });
+        const stamped = CANCEL_REASONS.includes(body.reason) ? body.reason : reason;
+        return { id: body.id ?? authorizationId, status: 'cancelled', reason: stamped, terminal_reason: (typeof body.terminal_reason === 'string' ? body.terminal_reason : stamped), request_id: body.request_id ?? null };
+    }
+    /**
+     * Polls the purchase until it leaves `awaiting_approval`; `{ status: 'timeout' }` at the deadline (60 s unless
+     * `timeout_ms` names another). The first read's `interval` (seconds) is the least this waits between reads, and
+     * a `slow_down` answer backs off to the interval it names and keeps polling.
+     */
+    async awaitResult(authorizationId, opts = {}) {
+        let intervalMs;
+        const timeoutMs = opts.timeout_ms ?? AWAIT_RESULT_TIMEOUT_MS;
+        const deadline = Date.now() + timeoutMs;
+        return this.poll(async () => {
+            let a;
+            try {
+                // The shared read waits out slow_down up to this call's deadline; past it the refusal is the poll
+                // loop's cue to space its next read by the interval named, and the deadline reads `timeout`.
+                a = await this.read(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}`, { deadline, onInterval: (ms) => { intervalMs = ms; } });
+            }
+            catch (err) {
+                if (err instanceof AgentcardError && err.code === 'slow_down')
+                    return undefined;
+                throw err;
+            }
+            if (typeof a.interval === 'number')
+                intervalMs = a.interval * 1000;
+            if (a.status === 'awaiting_approval')
+                return undefined;
+            return resultOf(a);
+        }, timeoutMs, () => ({ status: 'timeout' }), () => intervalMs);
+    }
+}

package/dist/buy.d.ts

@@ -1,29 +1,19 @@
 /**
  * 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
+ * same client the checkout 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
+ * person gave, 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`; `approved_not_charged` is a sandbox browser checkout the person approved, where the card was never sent to the store. */
-export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined' | 'approved_not_charged';
-/** 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";
+import { AgentcardError } from './api-types.js';
+/** Where a turn stands. `needs_input` is the common case: a question, or a cart waiting for its confirm; `approved_not_charged` is a sandbox browser checkout the person approved, where the card was never sent to the store. */
+export type BuyStatus = 'needs_input' | 'order_placed' | 'partially_placed' | 'declined' | 'approved_not_charged';
 /** 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;
@@ -50,7 +40,10 @@ export interface BuyCart {
     /** 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;
+    /** Fees on top of the items, or null while the store has not quoted them (`serviceFeesStatus` says which). */
+    serviceFeesCents: number | null;
+    /** `known` when `serviceFeesCents` is the quoted amount, `pending` before the store quotes its fees, `unknown` otherwise. */
+    serviceFeesStatus: 'known' | 'pending' | 'unknown';
     tipCents: number;
     totalCents: number;
     approvedCeilingCents: number | null;
@@ -78,11 +71,10 @@ export interface BuyPaymentSource {
  * 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
+ * `authorization_spent`, `user_not_connected`, 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.
+ * `authorization_id` is the approval the order was placed against.
  */
 export interface BuyOutcome {
     order_id: string | null;
@@ -226,30 +218,7 @@ 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;
+export declare function isBuyDeclined(turn: BuyTurn): turn is BuyDeclined;
 /** An order a conversation placed, from the ledger. */
 export interface BuyOrder {
     order_id: string | null;
@@ -318,9 +287,8 @@ export interface BuyConfirmInput {
     /** 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
+     * An approval the business already holds for this purchase, `cauth_…`.
+     * The API places the cart against it and asks the person for
      * nothing a second time. Sent only when named.
      */
     authorization_id?: string;
@@ -328,16 +296,6 @@ export interface BuyConfirmInput {
     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;
     /**
      * On a repeat confirm of a browser cart waiting for the person's approval,
      * hold up to 25 seconds and answer the moment they decide, instead of
@@ -348,28 +306,6 @@ export interface BuyConfirmInput {
     /** 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. */
@@ -381,11 +317,10 @@ export interface BuyConversationInput {
  * 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
+ * `conversation_not_found`, `conversation_closed`) 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
+ * `invalid_authorization_id`, `invalid_payment_source`,
+ * `missing_conversation_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.
  */
@@ -416,8 +351,8 @@ export declare class BuyModule extends ApiModule {
     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
+     * names. With `authorization_id`, the approval the person already gave
+     * 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
@@ -427,22 +362,6 @@ export declare class BuyModule extends ApiModule {
      * `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

package/dist/buy.js

@@ -1,39 +1,28 @@
 /**
  * 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
+ * same client the checkout 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
+ * person gave, 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 } from './api-module.js';
-import { AgentcardError } from './voice-types.js';
-/** 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 const VOICE_EXECUTION_UNSUPPORTED = 'voice_execution_unsupported';
+import { AgentcardError } from './api-types.js';
 /** True for a turn the API declined; `decline_code` says why (it is null when the loop refused in prose only). */
 export function isBuyDeclined(turn) { return turn.status === 'declined'; }
-/** 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 function isBuyNeedsApproval(turn) { return turn.status === 'needs_approval' && typeof turn.authorization_id === 'string'; }
-/** True when the store could not place under a voice verdict; `error` is the refusal. */
-export function isBuyVoiceUnsupported(turn) { return turn.status === VOICE_EXECUTION_UNSUPPORTED; }
 /**
  * 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
+ * `conversation_not_found`, `conversation_closed`) 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
+ * `invalid_authorization_id`, `invalid_payment_source`,
+ * `missing_conversation_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.
  */
@@ -69,13 +58,21 @@ function cartOf(v) {
         merchant_name: typeof c.merchant_name === 'string' ? c.merchant_name : c.merchant,
         store: storeOf(c.store),
         items: Array.isArray(c.items) ? c.items : [],
-        serviceFeesCents: typeof c.serviceFeesCents === 'number' ? c.serviceFeesCents : 0,
+        ...feesOf(c),
         tipCents: typeof c.tipCents === 'number' ? c.tipCents : 0,
         totalCents: typeof c.totalCents === 'number' ? c.totalCents : 0,
         approvedCeilingCents: typeof c.approvedCeilingCents === 'number' ? c.approvedCeilingCents : null,
         hash: c.hash,
     };
 }
+/** A pending or unreadable fee stays null with its status, so it never reads as a genuine zero. */
+function feesOf(c) {
+    const amount = typeof c.serviceFeesCents === 'number' ? c.serviceFeesCents : null;
+    const status = c.merchantFeesPending === true || c.serviceFeesStatus === 'pending' ? 'pending'
+        : (c.serviceFeesStatus === undefined || c.serviceFeesStatus === 'known')
+            && amount !== null && Number.isSafeInteger(amount) && amount >= 0 ? 'known' : 'unknown';
+    return { serviceFeesCents: status === 'known' ? amount : null, serviceFeesStatus: status };
+}
 function storeOf(v) {
     if (!v || typeof v !== 'object')
         return null;
@@ -113,7 +110,7 @@ function outcomeOf(a) {
         authorization_id: str(a.authorization_id),
     };
 }
-const STATUSES = new Set(['needs_input', 'needs_approval', 'order_placed', 'partially_placed', 'declined', 'approved_not_charged']);
+const STATUSES = new Set(['needs_input', 'order_placed', 'partially_placed', 'declined', 'approved_not_charged']);
 function statusOf(v) { return typeof v === 'string' && STATUSES.has(v) ? v : 'needs_input'; }
 function placementsOf(v) {
     if (!Array.isArray(v))
@@ -215,8 +212,8 @@ export class BuyModule extends ApiModule {
     }
     /**
      * 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
+     * names. With `authorization_id`, the approval the person already gave
+     * 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
@@ -232,11 +229,9 @@ export class BuyModule extends ApiModule {
         if (hashes.length === 0 || hashes.some((h) => typeof h !== 'string' || !CART_HASH.test(h)))
             refuse('invalid_cart_hash', 'confirm must be a cart hash from a previous turn (turn.cart.hash), or a list of them.');
         if (input.authorization_id !== undefined && (typeof input.authorization_id !== 'string' || !/^cauth_/.test(input.authorization_id)))
-            refuse('invalid_authorization_id', 'authorization_id must be the approval voice.authorizations.create minted (cauth_…).');
+            refuse('invalid_authorization_id', 'authorization_id must be the approval you hold for this purchase (cauth_…).');
         if (input.payment_source !== undefined && input.payment_source !== 'vault')
             refuse('invalid_payment_source', "payment_source must be 'vault' when named.");
-        if (input.approval !== undefined && input.approval !== 'voice' && input.approval !== 'page')
-            refuse('invalid_approval', "approval must be 'voice' or 'page' when named.");
         const body = {
             user_id,
             conversation_id,
@@ -244,60 +239,10 @@ export class BuyModule extends ApiModule {
             ...(input.authorization_id ? { authorization_id: input.authorization_id } : {}),
             ...(input.delivery_address ? { delivery_address: input.delivery_address } : {}),
             ...(input.payment_source ? { payment_source: input.payment_source } : {}),
-            ...(input.approval ? { approval: input.approval } : {}),
             ...(input.wait === true ? { wait: true } : {}),
         };
         return this.turn(body, input.timeout_ms);
     }
-    /**
-     * 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.
-     */
-    async approveByVoice(input) {
-        if (typeof input?.challenge !== 'function')
-            refuse('invalid_challenge', 'Name challenge: the function that runs the key word in your app on the authorization_id and resolves when the verdict is in.');
-        const confirm = {
-            user_id: input.user_id, conversation_id: input.conversation_id, confirm: input.confirm,
-            ...(input.delivery_address ? { delivery_address: input.delivery_address } : {}),
-            payment_source: 'vault', approval: 'voice', ...(input.timeout_ms !== undefined ? { timeout_ms: input.timeout_ms } : {}),
-        };
-        const unsupported = (err, authorization_id) => err instanceof BuyError && err.code === VOICE_EXECUTION_UNSUPPORTED ? { status: VOICE_EXECUTION_UNSUPPORTED, conversation_id: err.conversation_id ?? input.conversation_id, authorization_id, error: err } : null;
-        let first;
-        try {
-            first = await this.confirm(confirm);
-        }
-        catch (err) {
-            const u = unsupported(err, null);
-            if (u)
-                return u;
-            throw err;
-        }
-        if (first.status !== 'needs_approval')
-            return first;
-        if (!isBuyNeedsApproval(first))
-            refuse('missing_authorization_id', 'The API asked for an approval by voice but named no authorization_id to run it on.');
-        await input.challenge(first.authorization_id, first);
-        try {
-            return await this.confirm(confirm);
-        }
-        catch (err) {
-            const u = unsupported(err, first.authorization_id);
-            if (u)
-                return u;
-            throw err;
-        }
-    }
     /**
      * One read of a conversation, with no wait: whether a turn is still
      * running, the last checkout attempt, every order it placed from the

package/dist/capabilities.generated.js

@@ -1,3 +1,3 @@
 // Written by scripts/generate-capabilities.mjs from capabilities.json. Do not edit; git ignores it.
 /** capabilities.json's list, sorted; client.ts exports it as SUPPORTED_CAPABILITIES. */
-export const DECLARED_CAPABILITIES = ["aci_split_card.v1", "amadeus_checkout_actions.v1", "aps_custom_merchant_page", "authorize_net_dpm_form", "barion_hosted_payment_page", "capture_context", "clover_card_token", "comgate_hosted_payment_page", "converge_hpp_process", "creditguard_pps_process", "cybersource_sa_token_create", "datatrans_secure_fields_tokenize", "ekashu_hosted_payment_page", "eximbay_hosted_payment_page", "fastspring_card_payment", "fiserv_card_capture", "gmo_shared_pk", "gopay_card_form", "gravy_session_fields_put", "hipay_vault_token", "juspay_txns.v1", "lyra_krypton_payment", "makecommerce_card_frame", "midtrans_card_token", "moneris_hosted_tokenization", "nexi_checkout_pay", "omise_card_token", "openpay_tokenizer", "paddle_tokenex_pay", "paddle_vgs_cards", "pay_nl_card_token", "payfast_card_pay", "paygent_token", "paymob_checkout_pay", "paymongo_checkout_pay", "paypal_card_fields", "payrails_device_encrypt", "payrexx_card_frame", "paytrail_hosted_payment_page", "payu_latam_webcheckout_card", "pelecard_transaction", "pin_payments_card_token", "poynt_collect_nonce", "primer_payment_instruments", "przelewy24_hosted_payment_page", "quickpay_hosted_payment_page", "redsys_hosted_payment_page", "revolut_card_field", "sbps_token_jsonp", "shiji_sts_pinned_key", "sumup_checkout_process", "tap_card_sdk_token", "toast_pinned_key", "tokenex_iframe_tokenize", "transbank_webpay_hosted_payment_page", "twoc2p_secure_pay", "verifone_card_capture", "wix_payments_tokenize", "worldline_mycheckout_form", "worldpay_eprotect_jsonp", "wspay_confirm", "xendit_card_token"];
+export const DECLARED_CAPABILITIES = ["aci_split_card.v1", "amadeus_checkout_actions.v1", "aps_custom_merchant_page", "authorize_net_dpm_form", "barion_hosted_payment_page", "bluesnap_hosted_payment_fields", "capture_context", "clover_card_token", "comgate_hosted_payment_page", "converge_hpp_process", "creditguard_pps_process", "cybersource_sa_token_create", "datatrans_secure_fields_tokenize", "ekashu_hosted_payment_page", "eximbay_hosted_payment_page", "fastspring_card_payment", "fiserv_card_capture", "gmo_shared_pk", "gopay_card_form", "gravy_session_fields_put", "hipay_vault_token", "iyzico_checkout_form", "juspay_txns.v1", "lyra_krypton_payment", "makecommerce_card_frame", "midtrans_card_token", "moneris_hosted_tokenization", "nexi_checkout_pay", "oceanpayment_hosted_payment_page", "omise_card_token", "openpay_tokenizer", "paddle_tokenex_pay", "paddle_vgs_cards", "pay_nl_card_token", "payfast_card_pay", "paygent_token", "paymentwall_card_token", "paymob_checkout_pay", "paymongo_checkout_pay", "paypal_card_fields", "payplug_hosted_payment_page", "payrails_device_encrypt", "payrexx_card_frame", "paytrail_hosted_payment_page", "payu_latam_webcheckout_card", "pelecard_transaction", "pin_payments_card_token", "poynt_collect_nonce", "primer_payment_instruments", "processout_card_token", "przelewy24_hosted_payment_page", "quickpay_hosted_payment_page", "redsys_hosted_payment_page", "revolut_card_field", "sbps_token_jsonp", "shiji_sts_pinned_key", "sumup_checkout_process", "tap_card_sdk_token", "toast_pinned_key", "tokenex_iframe_tokenize", "transbank_webpay_hosted_payment_page", "twoc2p_secure_pay", "usaepay_payment_key", "verifone_card_capture", "vtex_payments_card_payment", "wix_payments_tokenize", "worldline_mycheckout_form", "worldpay_eprotect_jsonp", "wspay_confirm", "xendit_card_token"];