@visa/cli 4.1.0-rc.13 → 4.1.0-rc.131

package/dist/checkout-engine/hosted-approval.d.ts

@@ -26,15 +26,50 @@ import type { PurchaseAssurance, VgsCheckoutTarget } from './vgs-live-instrument
  * hang the runner past the advertised timeout.
  */
 export type HostedApprovalOptions = {
-    /** The verify-web deployment origin, e.g. https://v4-verify-web-….up.railway.app */
+    /** The enrollment web deployment origin (apps/web), e.g. https://web-….up.railway.app */
     baseUrl: string;
     /** Durable agentic token id from the CLI agent credential. */
     tokenId: string;
     target: VgsCheckoutTarget;
     /** Prefills the approval page's enrollment-email field (optional). */
     consumerEmail?: string;
+    /**
+     * BUDGET/mandate approval: `target.transactionAmount` is the approved spend
+     * CEILING (not one charge), so the server mints a BUDGET mint token that later
+     * accepts many sub-ceiling draws tap-free. Omit for a single-purchase approval.
+     */
+    budget?: boolean;
+    /**
+     * Exact current request-key thumbprint receiving a budget. Required for a
+     * budget and forbidden for a one-purchase approval; the authenticated page
+     * resolves it to the owner's stable agent before displaying or signing.
+     */
+    agentJkt?: string;
+    /** Advisory max draws the ceiling intent may fulfil — carried onto the token. */
+    maxDraws?: number;
+    /**
+     * Per-purchase cap (decimal string, <= the ceiling) on a BUDGET approval —
+     * shown on the approval page as a worst-case term and carried onto the mint
+     * token so the displayed cap is the enforced cap. Budget mode only.
+     */
+    perTransaction?: string;
+    /**
+     * Agent-supplied one-liner describing what this approval is for. Sanitized
+     * here (control chars stripped, trimmed, capped) and rendered by the approval
+     * page in a clearly-labeled "written by the agent" block — provenance for the
+     * human to cross-check, never a trusted field.
+     */
+    intent?: string;
     log?: (line: string) => void;
-    /** Injectable for tests; default opens the operator's default browser (macOS). */
+    /**
+     * Called once with the approval URL as DATA (not a log line) the instant it is
+     * known — before any polling. A headless agent (OpenClaw/Hermes) has no browser
+     * and no passkey; its whole job is to relay this URL to its human operator, so
+     * the URL must be capturable as a value, not just printed. The interactive CLI
+     * leaves this unset and relies on `log` + `openUrl`.
+     */
+    onApprovalUrl?: (url: string) => void;
+    /** Injectable for tests; default opens the operator's default browser, best-effort. */
     openUrl?: (url: string) => void;
     fetchImpl?: typeof fetch;
     /** Injectable for tests — never wall-clock-sleep in a unit test. */
@@ -43,15 +78,43 @@ export type HostedApprovalOptions = {
     pollIntervalMs?: number;
     timeoutMs?: number;
 };
+/** One short sentence — must match the relay's cap (agent-approval.ts). */
+export declare const APPROVAL_INTENT_MAX_CHARS = 200;
+/**
+ * Sanitize an agent-supplied intent to what the relay will accept and the page
+ * will display: control chars (and JS line separators) stripped, trimmed,
+ * TRUNCATED to the cap (the runner is the agent's own side, so truncating here
+ * beats a failed registration; the server still rejects an over-cap value).
+ * Returns undefined when nothing displayable remains.
+ */
+export declare function sanitizeApprovalIntent(value: string | undefined): string | undefined;
+/**
+ * The operator saw the request and said NO. Terminal and non-retryable: the
+ * relay entry is consumed, re-running would only re-ask a human who already
+ * refused. Callers must not classify this as transient.
+ */
+export declare class HostedApprovalDeclinedError extends Error {
+    constructor();
+}
 export declare const HOSTED_APPROVAL_TIMEOUT_MS: number;
 export declare const HOSTED_APPROVAL_POLL_MS = 3000;
+/** Emit a "still waiting" heartbeat roughly every this-many ms during the poll. */
+export declare const HOSTED_APPROVAL_HEARTBEAT_MS = 30000;
 /**
- * The one deployed verify site — hosted approval is the NORMAL path (no local
- * certs, no vendored SDK, no localhost anywhere), so its origin is a built-in
- * default rather than per-machine config. Not a secret: it's the public page
- * the operator's browser opens anyway.
+ * Resolve the approval timeout: `CHECKOUT_APPROVAL_TIMEOUT_MS` (seconds*1000, an
+ * integer ms) overrides the default when it parses to a positive integer.
+ * Lets an operator widen the window for separate-device / headless approval
+ * without threading a flag through every caller. Invalid values fall back.
  */
-export declare const DEFAULT_APPROVAL_BASE_URL = "https://v4-verify-web-visa-code-preview.up.railway.app";
+export declare function resolveApprovalTimeoutMs(): number;
+/**
+ * The staging apps/web deploy (which now hosts the /agent/enroll/approve page
+ * after the v4-verify-web GA graduation) — hosted approval is the NORMAL path
+ * (no local certs, no vendored SDK, no localhost anywhere), so its origin is a
+ * built-in default rather than per-machine config. Not a secret: it's the
+ * public page the operator's browser opens anyway.
+ */
+export declare const DEFAULT_APPROVAL_BASE_URL = "https://web-visa-code-preview.up.railway.app";
 /**
  * Flag > environment > built-in default. An explicitly EMPTY value
  * (CHECKOUT_APPROVAL_BASE_URL='') opts out of hosted approval entirely —
@@ -66,4 +129,66 @@ export declare function resolveApprovalBaseUrl(flagValue: string | undefined, en
  * assurance), so a cleartext remote origin is never acceptable.
  */
 export declare function assertApprovalBaseUrl(value: string): string;
-export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance>;
+/**
+ * The claim also releases the scoped MINT TOKEN (server-side mint, Phase 1) —
+ * bound to this exact approved purchase — so the runner can call the gateway
+ * mint routes without the VGS secret. Absent when the deployment ran the
+ * dev-auth stub (it mints no token); the caller then surfaces a clear error
+ * rather than falling back to a client-held secret.
+ */
+export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance & {
+    mintToken?: string;
+    validUntil?: number;
+}>;
+/**
+ * A panel-initiated mandate handoff, released by its single-use pickup code.
+ * The context here is SERVER truth (an owner-authenticated panel session parked
+ * it, and the code is the credential that releases it) — the runner had no part
+ * in registering it, so unlike {@link runHostedApproval} the fields are
+ * returned for the caller to act on rather than compared against a local run.
+ * What IS verified here is the binding: the entry must be a budget approval
+ * minted for exactly THIS runtime's request key and THIS device's card token.
+ */
+export type MandatePickupClaim = {
+    /** Null only when {@link assuranceExempt} — a code-verified card runs no ceremony. */
+    assuranceData: unknown;
+    assuranceExempt: boolean;
+    mintToken: string;
+    /** Unix seconds — the mandate lapse the owner approved in the panel. */
+    validUntil: number;
+    /** Decimal ceiling string exactly as approved (the context's `amount`). */
+    ceiling: string;
+    currency: string;
+    maxDraws: number;
+    perTransaction?: string;
+    merchant: {
+        name: string;
+        url: string;
+        countryCode: string;
+    };
+};
+export type ClaimMandatePickupOptions = {
+    /** The enrollment web deployment origin (apps/web). */
+    baseUrl: string;
+    /** Single-use pickup code (the approval verifier) the owner handed over. */
+    pickupCode: string;
+    /** This runtime's exact current request-key JKT — the only key the code may fund. */
+    agentJkt: string;
+    /**
+     * The agent handoff this runtime just redeemed, when the code came from one.
+     * A budget minted in the Add-agent dialog exists before the agent does, so it
+     * pins the handoff rather than a key; this is the value that pin is compared
+     * against. Absent for the panel flow, whose budgets pin a key instead.
+     */
+    expectedHandoffId?: string;
+    /** The card token id this runtime's card authority points at. */
+    tokenId: string;
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests — never wall-clock-sleep in a unit test. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Bounded retries for transient 429/5xx; the claim itself is single-use. */
+    attempts?: number;
+    retryDelayMs?: number;
+};
+export declare function claimMandatePickup(opts: ClaimMandatePickupOptions): Promise<MandatePickupClaim>;