@visa/cli 4.1.0-rc.6 → 4.1.0-rc.61

package/dist/checkout-engine/executor.d.ts

@@ -0,0 +1,176 @@
+import type { Browser, BrowserContext, Page } from 'playwright-core';
+import { type FieldMap } from './detect.js';
+import { type Mandate } from './mandate.js';
+import type { Instrument } from './instrument.js';
+import type { Contact, OtpResolver } from './types.js';
+import { EvidenceLog } from './evidence.js';
+import { type ObservedOutcome } from './outcome.js';
+export { minorFromDecimal, pageCurrency } from './amount.js';
+export type CheckoutMode = 'dry-run' | 'submit';
+export type CheckoutOutcome = 'reviewed-dry-run'
+/** Historical receipt value from the credential-disclosing dry-run. */
+ | 'filled-dry-run' | 'partial-fill' | 'adapter-required' | 'confirmed' | 'declined' | 'action-required' | 'cancelled' | 'blocked-by-mandate' | 'failed';
+export type CredentialLifecycle = 'not-requested' | 'minted-not-exposed' | 'partially-exposed' | 'fully-filled';
+export type CredentialTiming = {
+    approvedAt?: string;
+    credentialMintedAt?: string;
+    credentialExpiresAt?: string;
+    fillCompletedAt?: string;
+};
+export type CheckoutResult = {
+    outcome: CheckoutOutcome;
+    fields: FieldMap;
+    evidence: EvidenceLog;
+    confirmationRef?: string;
+    requiresAdapter: string[];
+    credentialLifecycle: CredentialLifecycle;
+    credentialTiming: CredentialTiming;
+    detail?: string;
+};
+export type PrepareCheckoutOptions = {
+    url: string;
+    mandate: Mandate;
+    browser: Browser;
+    contact?: Contact;
+    amountMinor?: number;
+    currency?: string;
+    debugShotsDir?: string;
+};
+export type RunCheckoutOptions = PrepareCheckoutOptions & {
+    instrument: Instrument;
+    contact: Contact;
+    mode: CheckoutMode;
+    outcomeDeadlineMs?: number;
+    resolveEmailOtp?: OtpResolver;
+};
+export type CheckoutReview = {
+    id: string;
+    url: string;
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+    mandateMaxAmountMinor: number;
+    mandateExpiresAt: string;
+    submitTarget: string | null;
+    submitTargetFingerprint: Readonly<CheckoutSubmitTargetFingerprint> | null;
+    detectedRoles: readonly string[];
+};
+export type CheckoutSubmitTargetFingerprint = {
+    kind: 'submit-control' | 'text-button';
+    label: string;
+    elementTag: string;
+    elementId: string | null;
+    elementName: string | null;
+    elementType: string | null;
+    formAction: string | null;
+    formMethod: string | null;
+    formTarget: string | null;
+};
+export type PreparedCheckout = {
+    readonly review: Readonly<CheckoutReview>;
+    readonly fields: Readonly<FieldMap>;
+    readonly evidence: EvidenceLog;
+    readonly requiresAdapter: readonly string[];
+};
+export type PrepareCheckoutResult = {
+    status: 'ready';
+    checkout: PreparedCheckout;
+} | {
+    status: 'finished';
+    result: CheckoutResult;
+};
+export type CheckoutApproval = {
+    approved: true;
+    reviewId: string;
+};
+export type SubmitApprovedCheckoutOptions = {
+    approval: CheckoutApproval;
+    instrument: Instrument;
+    contact: Contact;
+    mode: CheckoutMode;
+    outcomeDeadlineMs?: number;
+    challengeHoldMs?: number;
+    onChallengeHold?: (signal: string | null) => void;
+    resolveEmailOtp?: OtpResolver;
+};
+export type PreparedCheckoutSession = {
+    checkout: PreparedCheckout;
+    context: BrowserContext;
+    page: Page;
+    options: PrepareCheckoutOptions;
+    evidence: EvidenceLog;
+    fields: FieldMap;
+    requiresAdapter: Set<string>;
+};
+export type PreparedCheckoutSessionStore = {
+    put: (reviewId: string, state: PreparedCheckoutSession) => void;
+    take: (reviewId: string) => PreparedCheckoutSession | undefined;
+    peek: (reviewId: string) => PreparedCheckoutSession | undefined;
+    pendingCleanupReviewIds: () => readonly string[];
+    reapExpired: (nowMs?: number) => Promise<number>;
+    dispose: () => Promise<void>;
+};
+export type InMemoryPreparedCheckoutStoreOptions = {
+    ttlMs?: number;
+    cleanupRetryMs?: number;
+    now?: () => number;
+};
+export declare const DEFAULT_PREPARED_CHECKOUT_TTL_MS: number;
+export declare const DEFAULT_PREPARED_CHECKOUT_CLEANUP_RETRY_MS = 5000;
+export declare class InMemoryPreparedCheckoutStore implements PreparedCheckoutSessionStore {
+    private readonly entries;
+    private readonly cleanupPending;
+    private readonly ttlMs;
+    private readonly cleanupRetryMs;
+    private readonly now;
+    private reaper;
+    constructor(options?: InMemoryPreparedCheckoutStoreOptions);
+    put(reviewId: string, state: PreparedCheckoutSession): void;
+    take(reviewId: string): PreparedCheckoutSession | undefined;
+    peek(reviewId: string): PreparedCheckoutSession | undefined;
+    pendingCleanupReviewIds(): readonly string[];
+    reapExpired(nowMs?: number): Promise<number>;
+    dispose(): Promise<void>;
+    private queueCleanup;
+    private scheduleReaper;
+    private closeState;
+}
+export declare function reconcileHeldOutcome(original: ObservedOutcome, held: ObservedOutcome): ObservedOutcome;
+export declare function debugShotMaskPlan(fields: FieldMap): {
+    skipReason: string | null;
+    maskLocators: string[];
+    maskFrames: {
+        frame: string;
+        locator: string;
+    }[];
+};
+export declare function isStripeLinkConsumerRequest(url: string): boolean;
+export declare function suppressStripeLink(page: Page, evidence: EvidenceLog): Promise<void>;
+export type LinkQuietResult = {
+    fired: boolean;
+    waitedMs: number;
+};
+/**
+ * Wait for the suppressed Stripe Link lookup to fire and settle BEFORE the
+ * submit click. Stripe debounces its consumer-session lookup ~300ms after the
+ * email input changes; our fill→click gap is single-digit ms, so the (aborted)
+ * lookup used to land INSIDE Stripe's in-flight submit chain and kill it
+ * silently — the click looked accepted but tokenization never ran and the page
+ * sat on the form until the outcome deadline (#5879: three identical live
+ * stalls at donate.stripe.com). Verified live A/B on that page: instant click →
+ * dead submit, no /v1/payment_methods; lookup settled first → tokenization and
+ * the confirm step both reached.
+ *
+ * If the lookup already fired, only the short settle applies (lets Stripe's
+ * abort handling unwind). If it never fires — non-Link page variants, no email
+ * field — the bound expires and the click proceeds as before.
+ */
+export declare function waitForLinkLookupQuiet(page: Page, opts?: {
+    boundMs?: number;
+    settleMs?: number;
+    delay?: (ms: number) => Promise<void>;
+}): Promise<LinkQuietResult>;
+export declare function prepareCheckout(opts: PrepareCheckoutOptions, store?: PreparedCheckoutSessionStore): Promise<PrepareCheckoutResult>;
+export declare function submitApprovedCheckout(reviewId: string, opts: SubmitApprovedCheckoutOptions, store?: PreparedCheckoutSessionStore): Promise<CheckoutResult>;
+export declare function cancelPreparedCheckout(reviewId: string, detail?: string, store?: PreparedCheckoutSessionStore): Promise<CheckoutResult>;
+export declare function runCheckout(opts: RunCheckoutOptions, store?: PreparedCheckoutSessionStore): Promise<CheckoutResult>;