@agent-cards/sdk 0.23.28 → 0.24.0

package/dist/agentcard.js

@@ -1,10 +1,9 @@
 /**
- * The one client: `new Agentcard({ clientId, clientSecret, voice?, sandbox? })`,
+ * The one client: `new Agentcard({ clientId, clientSecret, sandbox? })`,
  * with two modules. `checkout` pauses a browser purchase or creates one
- * directly and replays the processor's answer; `voice` connects a person to
- * your product once and approves a purchase by voice. One pair of
- * credentials, one token, one base URL; sandbox and live are decided by the
- * credentials.
+ * directly and replays the processor's answer; `buy` asks the Purchase API
+ * for a cart and places it. One pair of credentials, one token, one base
+ * URL; sandbox and live are decided by the credentials.
  */
 import { VaultClient } from './client.js';
 import { attachToCdp, attachToPlaywright } from './cdp.js';

package/dist/amadeus.d.ts

@@ -6,6 +6,10 @@ export declare const WIX_PAYMENTS_SEND_WINDOW_MS = 20000;
 export declare const HIPAY_SEND_WINDOW_MS = 12000;
 /** How long after the pause a paused Openpay token create may still be sent, of the 40 seconds openpay.js waits. */
 export declare const OPENPAY_SEND_WINDOW_MS = 30000;
+/** How long after the pause a paused VTEX card post may still be sent, of the 12 seconds Ollie's container waits. */
+export declare const VTEX_PAYMENTS_SEND_WINDOW_MS = 8000;
+/** How long after the pause a paused ProcessOut card request may still be sent, of the 20 seconds the card frame waits. */
+export declare const PROCESSOUT_SEND_WINDOW_MS = 12000;
 /**
  * True when a request the adapters refuse must fail as a network error (ERR_FAILED) rather than as
  * the cancellation (ERR_ABORTED) they use elsewhere. An XMLHttpRequest reports a cancellation only
@@ -15,14 +19,16 @@ export declare const OPENPAY_SEND_WINDOW_MS = 30000;
  */
 export declare function failsAsNetworkError(url: string): boolean;
 /** The processor a send window's events and stop cause name. */
-export type SendWindowProcessor = 'amadeus' | 'secure_acceptance' | 'wix_payments' | 'hipay' | 'openpay';
+export type SendWindowProcessor = 'amadeus' | 'secure_acceptance' | 'wix_payments' | 'hipay' | 'openpay' | 'vtex_payments' | 'processout';
 /** Why a send window stopped its attempt: the API confirmed the card never left the device and never can. */
 export type SendWindowClosed = `${SendWindowProcessor}_send_window_closed`;
 /**
  * The send window for a request paused under a preparation for `psp`, or null when it has none: a
  * prepared Amadeus SDK add, a prepared CyberSource Secure Acceptance token create and a prepared Wix
- * tokenize request, each 20 seconds, a prepared HiPay token create, 12 seconds, and a prepared Openpay token
- * create, on exactly a token URL as openpay.js writes it, 30 seconds.
+ * tokenize request, each 20 seconds, a prepared HiPay token create, 12 seconds, a prepared Openpay token
+ * create, on exactly a token URL as openpay.js writes it, 30 seconds, a prepared VTEX card post to a store's own
+ * vault, as Ollie writes it, 8 seconds, and a prepared ProcessOut card request, on exactly a card URL as
+ * ProcessOut.js writes it, 12 seconds.
  */
 export declare function preparedSendWindowMs(psp: string | undefined, url: string): number | null;
 /** The processor a prepared request's send window names in its events, or null when it has none. */

package/dist/amadeus.js

@@ -30,6 +30,17 @@
 // get 20: the cardholder's device sends by 25 seconds after it last saw the checkout unbound (the Vault's own
 // window), and Openpay's answer, about a second, then reaches the page with the rest of those 40 seconds to spare.
 //
+// Ollie's headless checkout, which VTEX stores run, aborts its card post to the store's VTEX vault 12 seconds after it
+// starts it (AbortSignal.timeout(12e3), one signal for the post and its resends), and VTEX's answer has to reach the
+// container in that time. A paused VTEX card post gets an 8 second window: a card sent by then leaves 4 seconds for
+// VTEX's answer, the cardholder's device's report and this SDK's next read of it, every 500 ms.
+//
+// ProcessOut.js gives its card frame 20 seconds from the tokenize message before it calls the page's error callback
+// (CardField.timeout), and the frame sends its card request as soon as its sibling frames hand it the expiry and code,
+// so the pause starts a moment into those 20 seconds. A token ProcessOut mints after the page's error callback reaches a
+// page that may already have given up, so a paused card request gets HiPay's 12 second window of the 20, which leaves
+// about 8 for ProcessOut's answer, the API's record of it and the SDK's half-second read.
+//
 // So when the window closes and no answer is being handed to the page yet, the adapter asks for that
 // cancel. Confirmed: nothing was sent and nothing can be, so the attempt stops, the page's request
 // fails (a Secure Acceptance frame gets the stopped page), and the checkout reads failed. Not
@@ -43,14 +54,18 @@
 // processor: `amadeus_send_window_closed` and `amadeus_send_window_unconfirmed`,
 // `secure_acceptance_send_window_closed` and `secure_acceptance_send_window_unconfirmed`,
 // `wix_payments_send_window_closed` and `wix_payments_send_window_unconfirmed`,
-// `hipay_send_window_closed` and `hipay_send_window_unconfirmed`, or
-// `openpay_send_window_closed` and `openpay_send_window_unconfirmed`.
+// `hipay_send_window_closed` and `hipay_send_window_unconfirmed`,
+// `openpay_send_window_closed` and `openpay_send_window_unconfirmed`,
+// `vtex_payments_send_window_closed` and `vtex_payments_send_window_unconfirmed`, or
+// `processout_send_window_closed` and `processout_send_window_unconfirmed`.
 import { amadeusCardUrl } from './amadeus-checkout.generated.js';
 import { isSecureAcceptanceTokenRequest } from './cybersource-secure-acceptance.generated.js';
 import { SECURE_ACCEPTANCE_PSP, SECURE_ACCEPTANCE_SEND_WINDOW_MS } from './cybersource-secure-acceptance.js';
 import { WIX_PAYMENTS_PSP, isWixPaymentsTokenizeUrl } from './wix-payments.generated.js';
 import { HIPAY_PSP, isHipayTokenUrl } from './hipay.generated.js';
 import { OPENPAY_PSP, isOpenpayTokenUrl } from './openpay.generated.js';
+import { VTEX_PAYMENTS_PSP, isVtexPaymentsCardUrl } from './vtex-payments.generated.js';
+import { PROCESSOUT_PSP, isProcessoutCardUrl } from './processout.generated.js';
 /** How long after the pause a paused Amadeus SDK add may still be sent. */
 export const AMADEUS_SEND_WINDOW_MS = 20_000;
 /** How long after the pause a paused Wix tokenize request may still be sent, of the 30 seconds Wix's widget waits. */
@@ -59,6 +74,10 @@ export const WIX_PAYMENTS_SEND_WINDOW_MS = 20_000;
 export const HIPAY_SEND_WINDOW_MS = 12_000;
 /** How long after the pause a paused Openpay token create may still be sent, of the 40 seconds openpay.js waits. */
 export const OPENPAY_SEND_WINDOW_MS = 30_000;
+/** How long after the pause a paused VTEX card post may still be sent, of the 12 seconds Ollie's container waits. */
+export const VTEX_PAYMENTS_SEND_WINDOW_MS = 8_000;
+/** How long after the pause a paused ProcessOut card request may still be sent, of the 20 seconds the card frame waits. */
+export const PROCESSOUT_SEND_WINDOW_MS = 12_000;
 /**
  * True when a request the adapters refuse must fail as a network error (ERR_FAILED) rather than as
  * the cancellation (ERR_ABORTED) they use elsewhere. An XMLHttpRequest reports a cancellation only
@@ -72,10 +91,14 @@ export function failsAsNetworkError(url) {
 /**
  * The send window for a request paused under a preparation for `psp`, or null when it has none: a
  * prepared Amadeus SDK add, a prepared CyberSource Secure Acceptance token create and a prepared Wix
- * tokenize request, each 20 seconds, a prepared HiPay token create, 12 seconds, and a prepared Openpay token
- * create, on exactly a token URL as openpay.js writes it, 30 seconds.
+ * tokenize request, each 20 seconds, a prepared HiPay token create, 12 seconds, a prepared Openpay token
+ * create, on exactly a token URL as openpay.js writes it, 30 seconds, a prepared VTEX card post to a store's own
+ * vault, as Ollie writes it, 8 seconds, and a prepared ProcessOut card request, on exactly a card URL as
+ * ProcessOut.js writes it, 12 seconds.
  */
 export function preparedSendWindowMs(psp, url) {
+    if (psp === VTEX_PAYMENTS_PSP)
+        return isVtexPaymentsCardUrl(url) ? VTEX_PAYMENTS_SEND_WINDOW_MS : null;
     if (psp === 'amadeus_checkout')
         return amadeusCardUrl(url)?.path === 'sdk' ? AMADEUS_SEND_WINDOW_MS : null;
     if (psp === SECURE_ACCEPTANCE_PSP) {
@@ -94,6 +117,8 @@ export function preparedSendWindowMs(psp, url) {
         return isHipayTokenUrl(url) ? HIPAY_SEND_WINDOW_MS : null;
     if (psp === OPENPAY_PSP)
         return isOpenpayTokenUrl(url) ? OPENPAY_SEND_WINDOW_MS : null;
+    if (psp === PROCESSOUT_PSP)
+        return isProcessoutCardUrl(url) ? PROCESSOUT_SEND_WINDOW_MS : null;
     return null;
 }
 /** The processor a prepared request's send window names in its events, or null when it has none. */
@@ -104,6 +129,10 @@ export function sendWindowProcessor(psp) {
         return 'hipay';
     if (psp === OPENPAY_PSP)
         return 'openpay';
+    if (psp === VTEX_PAYMENTS_PSP)
+        return 'vtex_payments';
+    if (psp === PROCESSOUT_PSP)
+        return 'processout';
     return psp === 'amadeus_checkout' ? 'amadeus' : psp === SECURE_ACCEPTANCE_PSP ? 'secure_acceptance' : null;
 }
 /** The send window for a prepared Amadeus SDK add, or null: preparedSendWindowMs for Amadeus alone. */

package/dist/api-module.d.ts

@@ -1,4 +1,3 @@
-import type { Languages } from './languages.js';
 /** What the client lends its modules: the shared token, the shared HTTP path, and its settings. */
 export interface ApiTransport {
     /** The client-credentials bearer, cached and refreshed by the client; an `AgentcardError('oauth_failed')` when the exchange is refused. */
@@ -11,19 +10,14 @@ export interface ApiTransport {
         timeoutMs?: number;
     }): Promise<T>;
     pollIntervalMs: number;
-    /** Deadline for the await calls. Default 60 s. */
-    pollTimeoutMs?: number;
     /** Test seam: the retry pauses. */
     backoffMs?: readonly number[];
     /** The pause between two polls; an app may pass one that also wakes when it returns to the foreground. */
     wait?: (ms: number) => Promise<void>;
-    /** The languages Agentcard speaks, shared by every module that names one. */
-    languages: Languages;
 }
 export declare abstract class ApiModule {
     protected readonly t: ApiTransport;
     protected readonly backoff: readonly number[];
-    protected readonly pollTimeoutMs: number;
     protected readonly wait: (ms: number) => Promise<void>;
     protected constructor(t: ApiTransport);
     /** One call, tried again through a transient failure (no response, 502, 503, 504). */
@@ -50,5 +44,5 @@ export declare abstract class ApiModule {
      * asks between two reads; the client never polls faster than the larger of
      * it and its own `pollIntervalMs`.
      */
-    protected poll<T>(read: () => Promise<T | undefined>, timeoutMs: number | undefined, onDeadline: () => T, spacingMs?: () => number | undefined): Promise<T>;
+    protected poll<T>(read: () => Promise<T | undefined>, timeoutMs: number, onDeadline: () => T, spacingMs?: () => number | undefined): Promise<T>;
 }

package/dist/api-module.js

@@ -4,8 +4,8 @@
  * `slow_down`, and the poll that stops at a deadline. Constructed by the
  * client, never on their own.
  */
-import { isTransient, RETRY_BACKOFF_MS, sleep, withRetries } from './voice-retry.js';
-import { AgentcardError } from './voice-types.js';
+import { isTransient, RETRY_BACKOFF_MS, sleep, withRetries } from './api-retry.js';
+import { AgentcardError } from './api-types.js';
 /** The longest one `slow_down` wait, whatever interval the API names. */
 const SLOW_DOWN_WAIT_CAP_MS = 30_000;
 /** The longest a single read waits out `slow_down` in all before the refusal is thrown to the caller. */
@@ -13,12 +13,10 @@ const SLOW_DOWN_TOTAL_CAP_MS = 120_000;
 export class ApiModule {
     t;
     backoff;
-    pollTimeoutMs;
     wait;
     constructor(t) {
         this.t = t;
         this.backoff = t.backoffMs ?? RETRY_BACKOFF_MS;
-        this.pollTimeoutMs = t.pollTimeoutMs ?? 60_000;
         this.wait = t.wait ?? sleep;
     }
     /** One call, tried again through a transient failure (no response, 502, 503, 504). */
@@ -60,7 +58,7 @@ export class ApiModule {
      * it and its own `pollIntervalMs`.
      */
     async poll(read, timeoutMs, onDeadline, spacingMs = () => undefined) {
-        const deadline = Date.now() + (timeoutMs ?? this.pollTimeoutMs);
+        const deadline = Date.now() + timeoutMs;
         let lastFailure = null;
         for (;;) {
             try {

package/dist/{voice-retry.js → api-retry.js}

@@ -1,4 +1,4 @@
-import { AgentcardError } from './voice-types.js';
+import { AgentcardError } from './api-types.js';
 // A phone's network comes and goes and a gateway can be mid-deploy. One
 // failed request is not a failed step: it is tried again, three times, with a
 // growing pause. A write repeated after a lost response may leave a row behind

package/dist/api-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The purchase's wire shapes the webhooks read, and the error every module
+ * throws. Spellings are the API's (snake_case), so a response can be handed
+ * through untouched.
+ */
+export type AuthorizationStatus = 'awaiting_approval' | 'approved' | 'declined' | 'expired' | 'cancelled' | 'completed' | 'timeout';
+/**
+ * The business's own words for withdrawing a purchase it watches, while the person is still deciding: the person
+ * closed the sheet, the person changed their mind, or a reason of the business's own. The withdrawal stamps one;
+ * it is the request's `terminal_reason` from then on.
+ */
+export type CancelReason = 'person_closed_sheet' | 'person_changed_mind' | 'business_cancelled';
+/**
+ * How the approval request ended, as CIBA names it. Null while it awaits the person. `cancelled` is the runtime's
+ * withdrawal or a processor refusal; the three `CancelReason` words are the business's own withdrawal. A purchase
+ * withdrawn before a decision reads `status: 'cancelled'` (since 2026-09-25); its terminal reason says who withdrew it.
+ */
+export type TerminalReason = 'approved' | 'declined_by_person' | 'expired' | 'refused_by_rule' | 'approval_changed' | 'cancelled' | CancelReason;
+/**
+ * Whether the charge settled, read back from the processor by Agentcard itself after the purchase finished: the
+ * same object the `checkout_authorization.approved` webhook carries at finish and the `settled` /
+ * `settlement_unconfirmed` webhook carries once the read lands. `status` is `settled` (the processor holds a
+ * succeeded payment), `not_settled` (no charge was made: `reason` says why), or `unknown` (`reason` names what
+ * was seen last, `check_pending` while Agentcard is still reading). `final: false` means one of the two
+ * settlement webhooks follows; `true` means Agentcard will not check again. `settled_amount` and
+ * `settled_currency` are what the processor reports collected, in the currency's smallest unit; `message` is
+ * the answer in one sentence.
+ */
+export interface Settlement {
+    status: 'settled' | 'not_settled' | 'unknown';
+    reason: string;
+    final: boolean;
+    processor_reference: string | null;
+    processor_status: string | null;
+    processor_error_code: string | null;
+    settled_amount: number | null;
+    settled_currency: string | null;
+    checked_at: string | null;
+    resolved_at: string | null;
+    message: string;
+}
+export declare class AgentcardError extends Error {
+    /** The API's error code (`slow_down`), or the client's own (`oauth_failed`). */
+    readonly code: string;
+    readonly status?: number | undefined;
+    /** The rest of the API's error envelope: `slow_down` carries `interval`. */
+    readonly details: Record<string, unknown>;
+    constructor(
+    /** The API's error code (`slow_down`), or the client's own (`oauth_failed`). */
+    code: string, message: string, status?: number | undefined, 
+    /** The rest of the API's error envelope: `slow_down` carries `interval`. */
+    details?: Record<string, unknown>);
+}

package/dist/{voice-types.js → api-types.js}

@@ -1,11 +1,16 @@
+/**
+ * The purchase's wire shapes the webhooks read, and the error every module
+ * throws. Spellings are the API's (snake_case), so a response can be handed
+ * through untouched.
+ */
 export class AgentcardError extends Error {
     code;
     status;
     details;
     constructor(
-    /** The API's error code (`invalid_return_url`, `action_unavailable`, `voice_not_enrolled`, `slow_down`, `invalid_grant`), or the client's own (`unreachable`, `connect_timeout`, `oauth_failed`, `state_mismatch`). */
+    /** The API's error code (`slow_down`), or the client's own (`oauth_failed`). */
     code, message, status, 
-    /** The rest of the API's error envelope: `slow_down` carries `interval`, `grant_requires_exchange` carries `request_id`. */
+    /** The rest of the API's error envelope: `slow_down` carries `interval`. */
     details = {}) {
         super(message);
         this.code = code;

package/dist/approvals.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The approvals module of the SDK: `agentcard.approvals.*`. Your server creates
+ * a purchase for a person connected to your client, the person approves it on
+ * Agentcard's page at `approval_url`, and your server reads the decision or
+ * waits for it. Same credentials, same token as the checkout calls.
+ */
+import type { PausedRequest } from './client.js';
+import { ApiModule, type ApiTransport } from './api-module.js';
+import { type AuthorizationStatus, type CancelReason, type Settlement, type TerminalReason } from './api-types.js';
+export interface CreateAuthorizationInput {
+    /** The person who approves: the `user_id` of a person connected to your client. Required, so a server serving many people never charges the wrong one. */
+    user_id: string;
+    merchant: string;
+    /** An integer in the currency's smallest unit (599 for $5.99). */
+    amount: number;
+    /** Lowercase ISO code, `usd`. */
+    currency: string;
+    /**
+     * The processor's card request the purchase pauses on: one a browser purchase paused on, one
+     * `checkout.requests.build` made, or `'sandbox'`, which names no processor and which only a sandbox
+     * client may send (`sandbox_request_in_live` otherwise).
+     */
+    request: PausedRequest | 'sandbox';
+    /** The processor the request belongs to, as the recognisers name it (`stripe`, `braintree`, `mercado_pago`, …). Default `stripe`. */
+    psp?: string;
+    /** How the card reaches the processor. Absent means `token`; `cse` and `hosted_form` are checked against the recogniser by the API. */
+    mode?: 'token' | 'cse' | 'hosted_form';
+    /** Your own key for this create; the same key creates once. The SDK sends a fresh one when you name none. */
+    idempotency_key?: string;
+    /** The link the approval page sends the person back to, stored on the request. Exactly one of your registered links. */
+    return_url?: string;
+    /**
+     * The exact https origin your app or checkout page pays from (`https://yourapp.example`): what an
+     * auto-approval rule the person confirmed needs to take the purchase. Agentcard stores no `origin` header
+     * from the paused request, so without this a rule never applies and the create answers
+     * `execution_reason: 'unverified_origin'`. Absent, the SDK sends the paused request's `origin` header when
+     * it is such an origin (`stripePaymentIntentConfirm(origin, …)` sets one).
+     */
+    checkout_origin?: string;
+    /** Pins the card that pays: one of the person's stored cards. Absent, the person's recommended card pays, else their only card, and `card` on the answer says which. */
+    card_id?: string;
+}
+/** The card that pays, as every read names it. */
+export interface PayingCard {
+    id: string;
+    /** How the card is named on screen: its product, else its label, else "Visa ····4242". */
+    name: string;
+    last4: string | null;
+    brand: string | null;
+    reason: string | null;
+}
+/** One of the cards the person may pay with instead, while the purchase awaits a decision. */
+export interface ChoosableCard extends PayingCard {
+    recommended: boolean;
+    auto_approve?: boolean;
+}
+/** The fields every read of a purchase carries beside its status. */
+export interface AuthorizationFields {
+    /** The request handle (`areq_…`); the webhooks carry it too. */
+    request_id?: string | null;
+    /** Your own id for the person, as the connect named it. */
+    external_user_id?: string | null;
+    /** Seconds between two reads; `awaitResult` polls no faster. */
+    interval?: number;
+    /** The same interval in milliseconds, exactly as the request was configured. */
+    poll_interval_ms?: number;
+    expires_at?: string;
+    /** How the request ended; null while it awaits the person. */
+    terminal_reason?: TerminalReason | null;
+    /** `user_approval`: the person approves on Agentcard's page. `autopilot`: the person's rule took it, no approval step. */
+    execution_mode?: 'user_approval' | 'autopilot' | string;
+    /** Why no rule took the purchase when your server could mend it: `unverified_origin`, the create named no `checkout_origin`. `execution_detail` says so in a sentence. */
+    execution_reason?: 'unverified_origin' | string;
+    execution_detail?: string;
+    /** The card that pays: the one your create pinned, else the person's recommended card, else their only card; null when several could pay and none is chosen yet. */
+    card?: PayingCard | null;
+    /** Every card the person may pay with instead, while the purchase awaits a decision. */
+    cards?: ChoosableCard[];
+}
+export interface Authorization extends AuthorizationFields {
+    id: string;
+    status: AuthorizationStatus;
+    /**
+     * The purchase's own approval page, while it awaits the person: they approve there with Face ID, Touch ID or
+     * their master password. Open it in your app, or send it to them. The link is id-only; where the page sends the
+     * person afterwards is the `return_url` stored on the request.
+     */
+    approval_url?: string;
+    /** The registered link the approval page ends on, as stored on the request. */
+    return_url?: string;
+}
+export interface AuthorizationResult extends AuthorizationFields {
+    /** The purchase's id (`cauth_…`), as read; absent only on `timeout`, which is the SDK's own answer. */
+    id?: string;
+    /**
+     * `approved`, `declined` (the person said no, or a rule or the processor refused), `cancelled` (withdrawn
+     * before a decision, by your server's `approvals.cancel` or by the runtime), `expired`, or `timeout` at the
+     * deadline.
+     */
+    status: AuthorizationStatus;
+    /** The purchase's approval page while it awaits the person; absent otherwise. */
+    approval_url?: string;
+    /**
+     * Whether the charge settled, on a finished purchase: present on `approved`, `null` when there is nothing to read
+     * back (the request tokenized a card the merchant charges itself), absent while the purchase is open or on
+     * `timeout`. `final: false` means the `checkout_authorization.settled` or `settlement_unconfirmed` webhook follows.
+     */
+    settlement?: Settlement | null;
+    /** `passkey` or `bearer` for a person's approval; empty when a rule took the purchase. */
+    approved_with?: string;
+}
+export interface Cancelled {
+    id: string;
+    status: 'cancelled';
+    /** The reason as stamped; `terminal_reason` is the same word on every later read and on the `checkout_authorization.cancelled` webhook. */
+    reason: CancelReason;
+    terminal_reason: TerminalReason;
+    request_id: string | null;
+}
+/** Your server's words for withdrawing a purchase (`approvals.cancel`); anything else is refused before any call. */
+export declare const CANCEL_REASONS: readonly CancelReason[];
+/**
+ * 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 declare const SANDBOX_REQUEST: PausedRequest;
+/** `agentcard.approvals`: constructed by the client, never on its own. */
+export declare class ApprovalsModule extends ApiModule {
+    private readonly clientIsSandbox;
+    constructor(t: ApiTransport, clientIsSandbox: () => boolean);
+    /**
+     * 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.
+     */
+    create(input: CreateAuthorizationInput): Promise<Authorization>;
+    /**
+     * 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.
+     */
+    get(authorizationId: string): Promise<AuthorizationResult>;
+    /**
+     * 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).
+     */
+    cancel(authorizationId: string, opts: {
+        reason: CancelReason;
+    }): Promise<Cancelled>;
+    /**
+     * 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.
+     */
+    awaitResult(authorizationId: string, opts?: {
+        timeout_ms?: number;
+    }): Promise<AuthorizationResult>;
+}