@agent-cards/checkout 0.2.0 → 0.3.0

package/dist/client.js

@@ -16,15 +16,14 @@ export class CardEncryptedError extends Error {
     }
 }
 /**
- * The API approved an authorization in a mode this SDK build cannot finish.
- * Unreachable by construction (syncRegistry asks only for SUPPORTED_MODES and
- * every create names its mode), so it is treated as terminal: retrying the
- * same page could only raise more prompts for the same dead end.
+ * The registry requests a mode this SDK build cannot finish, before creation.
+ * A response in an unexpected mode after creation has an unknown payment
+ * outcome instead and raises PaymentOutcomeUnknownError.
  */
 export class UnsupportedModeError extends Error {
     mode;
     constructor(mode) {
-        super(`the authorization was approved in mode "${mode}", which this version of @agent-cards/checkout cannot complete; upgrade the SDK.`);
+        super(`the checkout requests mode "${mode}", which this version of @agent-cards/checkout cannot complete; upgrade the SDK.`);
         this.mode = mode;
         this.name = 'UnsupportedModeError';
     }
@@ -32,6 +31,20 @@ export class UnsupportedModeError extends Error {
 export class ApprovalTimeoutError extends Error {
     constructor(ms) { super(`user did not approve within ${ms}ms`); this.name = 'ApprovalTimeoutError'; }
 }
+export class CheckoutCancelledError extends Error {
+    constructor() { super('checkout cancelled locally before authorization creation'); this.name = 'CheckoutCancelledError'; }
+}
+/** The payment may have reached the processor. Reconcile the merchant order before any new attempt. */
+export class PaymentOutcomeUnknownError extends Error {
+    authorizationId;
+    reason;
+    constructor(authorizationId, reason) {
+        super(`payment outcome unknown${authorizationId ? ` for ${authorizationId}` : ''}: ${reason}; check the merchant order before retrying`);
+        this.authorizationId = authorizationId;
+        this.reason = reason;
+        this.name = 'PaymentOutcomeUnknownError';
+    }
+}
 export class ApprovalDeclinedError extends Error {
     constructor(reason) { super(`user declined: ${reason}`); this.name = 'ApprovalDeclinedError'; }
 }
@@ -267,6 +280,8 @@ export class VaultClient {
      * response to replay into the browser. Your process never sees a card.
      */
     async authorize(input) {
+        if (input.signal?.aborted)
+            throw new CheckoutCancelledError();
         const rec = findRecognizer(input.request.url, this.registry);
         if (!rec)
             throw new Error(`not a known tokenization endpoint: ${redactUrl(input.request.url)}`);
@@ -301,7 +316,13 @@ export class VaultClient {
             throw new Error('authorize needs amount (a display string), or amountCents with currency.');
         }
         const timeoutMs = input.timeoutMs ?? 15 * 60_000;
-        const created = await this.createAuthorization({
+        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+            throw new Error('timeoutMs must be a positive integer no larger than 2147483647.');
+        const deadline = Date.now() + timeoutMs;
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const operationSignal = input.signal ? AbortSignal.any([input.signal, timeoutSignal]) : timeoutSignal;
+        let created;
+        const payload = {
             user: input.user,
             merchant: input.merchant,
             ...(input.amount ? { amount: input.amount } : {}),
@@ -318,13 +339,50 @@ export class VaultClient {
                 headers: pickHeaders(input.request.headers, rec.passthroughHeaders),
                 body: input.request.body,
             },
-        }, input.currency);
-        input.onApprovalUrl?.(created.approvalUrl);
-        const authorizationId = String(created.id);
-        const deadline = Date.now() + timeoutMs;
+        };
+        try {
+            created = await this.createAuthorization(payload, input.currency, operationSignal);
+        }
+        catch (error) {
+            // A missing answer or generic 5xx can hide a committed row and a delivered approval link.
+            // Only the documented pre-create read-back errors prove it is safe to retry.
+            const safeReadFailure = error instanceof CheckoutApiError
+                && error.status === 502 && (error.code === 'amount_unverifiable' || error.code === 'cse_key_unavailable');
+            if ((error instanceof CheckoutApiError && error.status >= 500 && !safeReadFailure)
+                || (!(error instanceof CheckoutApiError) && !(error instanceof ApprovalDeclinedError))) {
+                throw new PaymentOutcomeUnknownError(null, 'authorization_create_unanswered');
+            }
+            throw error;
+        }
+        if (!created || typeof created.id !== 'string' || !created.id)
+            throw new PaymentOutcomeUnknownError(null, 'authorization_create_malformed');
+        const authorizationId = created.id;
+        try {
+            Promise.resolve(input.onAuthorizationCreated?.(authorizationId)).catch(() => { });
+        }
+        catch { /* observer only */ }
+        try {
+            Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
+        }
+        catch { /* approval delivery must not lose an existing authorization */ }
         while (Date.now() < deadline) {
-            await sleep(this.pollIntervalMs);
-            const s = await this.get(`/v2/checkout/authorizations/${authorizationId}`);
+            if (input.signal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'local_cancel');
+            await interruptibleSleep(Math.min(this.pollIntervalMs, Math.max(0, deadline - Date.now())), input.signal);
+            if (input.signal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'local_cancel');
+            let s;
+            const deadlineSignal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
+            const pollSignal = input.signal ? AbortSignal.any([input.signal, deadlineSignal]) : deadlineSignal;
+            try {
+                s = await this.get(`/v2/checkout/authorizations/${authorizationId}`, pollSignal);
+            }
+            catch {
+                throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_poll_failed');
+            }
+            if (!s || typeof s !== 'object' || Array.isArray(s) || typeof s.status !== 'string') {
+                throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
+            }
             const amountAuthority = typeof s.amount_authority === 'string' && AMOUNT_AUTHORITIES.includes(s.amount_authority)
                 ? { amountAuthority: s.amount_authority }
                 : {};
@@ -332,13 +390,13 @@ export class VaultClient {
                 // The device attested that the processor's form left it; the stamp
                 // is the whole fact and it is NOT an approval (see HostedFormReplay).
                 // Only a hosted_form row may carry this status; a stamp without its
-                // time is not one this SDK can act on (not permanent: the next poll,
-                // or request, may carry it).
+                // time is not one this SDK can act on. The device may already have paid,
+                // so the adapter holds the attempt until the merchant is reconciled.
                 const mode = typeof s.mode === 'string' ? s.mode : 'token';
                 if (mode !== 'hosted_form')
-                    throw new Error(`malformed authorization ${authorizationId}: submitted_on_device on mode ${mode}`);
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'submission_mode_mismatch');
                 if (typeof s.submitted_at !== 'string' || !s.submitted_at) {
-                    throw new Error(`malformed hosted_form submission on authorization ${authorizationId}: no submitted_at`);
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'submission_timestamp_missing');
                 }
                 return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority };
             }
@@ -348,7 +406,7 @@ export class VaultClient {
                     // Never: the API finishes a hosted form as submitted_on_device, and
                     // its database refuses `approved` on that mode. An answer that says
                     // otherwise is not one to act on as a payment.
-                    throw new Error(`malformed authorization ${authorizationId}: a hosted_form authorization finishes as submitted_on_device, never approved`);
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'hosted_form_approval_malformed');
                 }
                 if (approvedMode === 'cse') {
                     const sub = s.substitutions;
@@ -356,14 +414,14 @@ export class VaultClient {
                         && sub.fields && typeof sub.fields === 'object' && !Array.isArray(sub.fields)
                         && Object.values(sub.fields).every((v) => typeof v === 'string' && v.length > 0);
                     if (!fieldsOk)
-                        throw new Error(`malformed substitutions on approved authorization ${authorizationId}`);
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
                     // `remove`: sibling keys the API says to drop with the swap (Adyen's
                     // `brand`, stamped by adyen-web from the agent's dummy digits). Absent
                     // on an older API; anything but a list of names is refused, since a
                     // half-understood instruction would continue a body Adyen refuses.
                     const removeRaw = sub.remove;
                     if (removeRaw !== undefined && !(Array.isArray(removeRaw) && removeRaw.every((k) => typeof k === 'string' && k.length > 0))) {
-                        throw new Error(`malformed substitutions.remove on approved authorization ${authorizationId}`);
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'cse_remove_malformed');
                     }
                     return {
                         mode: 'cse',
@@ -378,8 +436,12 @@ export class VaultClient {
                     };
                 }
                 if (approvedMode !== 'token')
-                    throw new UnsupportedModeError(approvedMode);
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'approved_mode_unsupported');
                 const response = s.response;
+                if (!response || !Number.isInteger(response.status) || response.status < 100 || response.status > 599
+                    || typeof response.body !== 'string' || !response.headers || typeof response.headers !== 'object' || Array.isArray(response.headers)) {
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'approved_response_malformed');
+                }
                 return {
                     mode: 'token',
                     authorizationId,
@@ -404,8 +466,16 @@ export class VaultClient {
                 }
                 throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
             }
+            if (s.status === 'expired') {
+                if (s.replay_attempted === false)
+                    throw new ApprovalTimeoutError(timeoutMs);
+                throw new PaymentOutcomeUnknownError(authorizationId, 'expired_after_possible_replay');
+            }
+            if (s.status !== 'awaiting_approval')
+                throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_unrecognized');
         }
-        throw new ApprovalTimeoutError(timeoutMs);
+        // A local deadline is not server-side expiry; the person may still use the approval link.
+        throw new PaymentOutcomeUnknownError(authorizationId, 'local_approval_timeout');
     }
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
@@ -414,10 +484,10 @@ export class VaultClient {
      * `amount_mismatch` becomes an AmountMismatchError at stage 'create' so the
      * adapters treat it as an answered request, not a dead page.
      */
-    async createAuthorization(payload, currency) {
+    async createAuthorization(payload, currency, signal) {
         for (let attempt = 0;; attempt++) {
             try {
-                return await this.post('/v2/checkout/authorizations', payload);
+                return await this.post('/v2/checkout/authorizations', payload, signal);
             }
             catch (err) {
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
@@ -430,7 +500,9 @@ export class VaultClient {
                     && (err.code === 'amount_unverifiable' || err.code === 'cse_key_unavailable');
                 if (!retryable || attempt >= this.unverifiableRetryDelaysMs.length)
                     throw err;
-                await sleep(this.unverifiableRetryDelaysMs[attempt]);
+                await interruptibleSleep(this.unverifiableRetryDelaysMs[attempt], signal);
+                if (signal?.aborted)
+                    throw signal.reason;
             }
         }
     }
@@ -457,6 +529,7 @@ export class VaultClient {
                 method: 'POST',
                 headers: { 'content-type': 'application/x-www-form-urlencoded' },
                 body: body.toString(),
+                signal: AbortSignal.timeout(30_000),
             });
             if (!r.ok) {
                 // RFC 6749 error shape, which real OAuth clients expect verbatim.
@@ -473,25 +546,27 @@ export class VaultClient {
     }
     /** Authenticated request that retries ONCE on a 401 with a fresh token. */
     async call(path, init = {}, retried = false) {
-        const token = await this.accessToken();
-        const r = await this.fetch(`${this.baseUrl}${path}`, {
+        const signal = init.signal ?? AbortSignal.timeout(30_000);
+        const token = await withSignal(this.accessToken(), signal);
+        const r = await withSignal(this.fetch(`${this.baseUrl}${path}`, {
             ...init,
+            signal,
             headers: { ...(init.headers ?? {}), authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-        });
+        }), signal);
         // A token can be revoked or expire early; one forced refresh, then give up.
         if (r.status === 401 && !retried) {
-            await this.accessToken(true);
-            return this.call(path, init, true);
+            await withSignal(this.accessToken(true), signal);
+            return this.call(path, { ...init, signal }, true);
         }
         if (!r.ok)
-            throw new CheckoutApiError(r.status, path, await r.text());
-        return r.json();
+            throw new CheckoutApiError(r.status, path, await withSignal(r.text(), signal));
+        return withSignal(r.json(), signal);
     }
-    post(path, body) {
-        return this.call(path, { method: 'POST', body: JSON.stringify(body) });
+    post(path, body, signal) {
+        return this.call(path, { method: 'POST', body: JSON.stringify(body), signal });
     }
-    get(path) {
-        return this.call(path);
+    get(path, signal) {
+        return this.call(path, { signal });
     }
 }
 /**
@@ -509,4 +584,25 @@ function pickHeaders(headers, allow) {
         out['content-type'] = 'application/json';
     return out;
 }
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Settle local work even if a custom fetch implementation ignores AbortSignal. */
+function withSignal(operation, signal) {
+    return new Promise((resolve, reject) => {
+        const aborted = () => { signal.removeEventListener('abort', aborted); reject(signal.reason); };
+        if (signal.aborted) {
+            operation.catch(() => { });
+            aborted();
+            return;
+        }
+        signal.addEventListener('abort', aborted, { once: true });
+        operation.then(value => { signal.removeEventListener('abort', aborted); resolve(value); }, error => { signal.removeEventListener('abort', aborted); reject(error); });
+    });
+}
+function interruptibleSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, } from './client.js';
 export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, } from './client.js';
-export { attachToCdp, attachToPlaywright } from './cdp.js';
-export type { CdpLike, AttachOptions } from './cdp.js';
+export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export type { Substitutions } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
 export type { HostedFormSubmittedPageInput, SyntheticPage } from './hosted-form.js';
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';
 export type { Recognizer, CheckoutMode } from './registry.js';
+export type { CheckoutController, CheckoutState, MerchantResult, UserAction, LifecycleOptions, PaymentEndpointGuard } from './lifecycle.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, } from './client.js';
-export { attachToCdp, attachToPlaywright } from './cdp.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, } from './client.js';
+export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';

package/dist/lifecycle.d.ts

@@ -0,0 +1,91 @@
+import { type ReplayResponse } from './client.js';
+import type { CheckoutMode } from './registry.js';
+/** A processor approval is not an order. Only the merchant can confirm this result. */
+export type MerchantResult = {
+    status: 'completed';
+    orderId: string;
+} | {
+    status: 'failed';
+} | {
+    status: 'pending' | 'unknown';
+} | {
+    status: 'requires_user_action';
+    reason: '3ds' | 'redirect' | 'other';
+};
+export interface CheckoutState {
+    status: 'idle' | 'awaiting_approval' | 'awaiting_merchant' | 'requires_user_action' | 'completed' | 'declined' | 'timed_out' | 'cancelled' | 'unsupported' | 'outcome_unknown' | 'failed';
+    authorizationId: string | null;
+    mode?: CheckoutMode;
+    orderId?: string;
+    /** Stable SDK category; never includes a request body, processor response, or approval link. */
+    reason?: string;
+}
+export interface UserAction {
+    reason: 'approval' | '3ds' | 'redirect' | 'other';
+    authorizationId: string | null;
+    /** Sensitive approval capability. Deliver privately; do not put this in ordinary telemetry. */
+    approvalUrl?: string;
+}
+export interface LifecycleOptions {
+    onStateChange?: (state: Readonly<CheckoutState>) => void;
+    onUserAction?: (action: UserAction) => void | Promise<void>;
+    /** Read authoritative merchant order state; do not click Pay or initiate a new charge here. */
+    resolveMerchantResult?: (state: Readonly<CheckoutState>) => Promise<MerchantResult>;
+    /** Hold further card requests after handoff until the merchant result is reconciled. Default false for compatibility. */
+    requireMerchantResult?: boolean;
+}
+export interface CheckoutController {
+    getState(): Readonly<CheckoutState>;
+    /** Stop this attachment locally. Does not revoke an approval link or cancel a processor payment. */
+    cancel(): void;
+    /** Ask the application's merchant resolver. A rejection records unknown; never automatically retries payment. */
+    reconcile(): Promise<Readonly<CheckoutState>>;
+    /** Signal an observed challenge; the SDK cannot detect every processor's 3DS UI. */
+    requestUserAction(reason: '3ds' | 'redirect' | 'other'): Promise<void>;
+    /** Start a new attempt after merchant-confirmed failure. Cancelled, completed and unbound Stripe-token attachments cannot reset. */
+    retryAfterMerchantFailure(result: {
+        status: 'failed';
+    }): void;
+}
+/** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
+export declare class CheckoutLifecycle implements CheckoutController {
+    private readonly options;
+    private state;
+    private held;
+    private active;
+    private cancelled;
+    private unboundStripeToken;
+    private reconciliation;
+    readonly abort: AbortController;
+    constructor(options: LifecycleOptions);
+    getState(): Readonly<CheckoutState>;
+    isBlocked(): boolean;
+    isCancelled(): boolean;
+    begin(): void;
+    end(): void;
+    private set;
+    approvalCreated(authorizationId: string): void;
+    approvalUrl(approvalUrl: string): void;
+    private notify;
+    cancel(): void;
+    unsupported(): void;
+    prepareHandoff(replay: ReplayResponse, requestUrl: string): void;
+    handedOff(replay: ReplayResponse): void;
+    failed(error: unknown, handoffStarted?: boolean): void;
+    requestUserAction(reason: '3ds' | 'redirect' | 'other'): Promise<void>;
+    reconcile(): Promise<Readonly<CheckoutState>>;
+    private resolve;
+    retryAfterMerchantFailure(result: {
+        status: 'failed';
+    }): void;
+}
+/** Exact origin and path, supplied by the integrator after observing a payment endpoint. No query/body matching. */
+export interface PaymentEndpointGuard {
+    origin: string;
+    pathname: string;
+    methods?: readonly string[];
+}
+export declare function paymentEndpointGuards(input?: readonly PaymentEndpointGuard[]): {
+    patterns: string[];
+    matches(url: string, method?: string): boolean;
+};

package/dist/lifecycle.js

@@ -0,0 +1,193 @@
+import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, IntentNotConfirmableError, PaymentOutcomeUnknownError } from './client.js';
+/** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
+export class CheckoutLifecycle {
+    options;
+    state = { status: 'idle', authorizationId: null };
+    held = false;
+    active = false;
+    cancelled = false;
+    unboundStripeToken = false;
+    reconciliation = null;
+    abort = new AbortController();
+    constructor(options) {
+        this.options = options;
+    }
+    getState() { return { ...this.state }; }
+    isBlocked() { return this.held || this.cancelled; }
+    isCancelled() { return this.cancelled; }
+    begin() {
+        this.active = true;
+        this.set({ status: 'awaiting_approval', authorizationId: null });
+    }
+    end() { this.active = false; }
+    set(state) {
+        this.state = state;
+        // Application telemetry must never interrupt a paused payment after it reaches the processor.
+        try {
+            Promise.resolve(this.options.onStateChange?.(this.getState())).catch(() => { });
+        }
+        catch { /* observer only */ }
+    }
+    approvalCreated(authorizationId) {
+        this.set({ ...this.state, authorizationId });
+    }
+    approvalUrl(approvalUrl) {
+        this.notify({ reason: 'approval', authorizationId: this.state.authorizationId, approvalUrl });
+    }
+    notify(action) {
+        try {
+            Promise.resolve(this.options.onUserAction?.(action)).catch(() => { });
+        }
+        catch { /* observer only */ }
+    }
+    cancel() {
+        this.cancelled = true;
+        this.held = true;
+        this.abort.abort();
+        this.set({ ...this.state, status: this.active || this.state.authorizationId ? 'outcome_unknown' : 'cancelled', reason: 'local_cancel' });
+    }
+    unsupported() {
+        this.held = true;
+        if (this.state.authorizationId)
+            return; // do not hide an outstanding/completed payment behind a later unsupported request
+        this.set({ ...this.state, status: 'unsupported', reason: 'unrecognized_payment_endpoint' });
+    }
+    prepareHandoff(replay, requestUrl) {
+        // A tokenization approval has no authoritative PaymentIntent or amount
+        // binding. Neither the first observed confirm nor the returned opaque
+        // token can supply one. Hold even in compatibility mode: this attachment
+        // must never turn that token into an unreviewed payment continuation.
+        if (!replay.mode || replay.mode === 'token') {
+            try {
+                const url = new URL(requestUrl);
+                if (url.origin === 'https://api.stripe.com' && ['/v1/payment_methods', '/v1/tokens'].includes(url.pathname)) {
+                    // Set before delivery: a lost browser acknowledgement must not reset
+                    // an already-issued token into a retryable authorization.
+                    this.unboundStripeToken = true;
+                    this.held = true;
+                }
+            }
+            catch { /* unknown URL cannot establish a token binding */ }
+        }
+    }
+    handedOff(replay) {
+        const mismatch = (!replay.mode || replay.mode === 'token') && replay.amountVerified === false;
+        this.held = !!this.options.requireMerchantResult || replay.mode === 'hosted_form' || mismatch || this.unboundStripeToken;
+        this.set({ status: 'awaiting_merchant', authorizationId: replay.authorizationId, mode: replay.mode ?? 'token',
+            ...(mismatch ? { reason: 'charged_amount_mismatch' } : this.unboundStripeToken ? { reason: 'stripe_tokenization_unbound' } : {}) });
+    }
+    failed(error, handoffStarted = false) {
+        if (this.cancelled)
+            return;
+        const authorizationId = error instanceof PaymentOutcomeUnknownError ? error.authorizationId : this.state.authorizationId;
+        if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
+            this.held = true;
+            this.set({ ...this.state, authorizationId, status: 'outcome_unknown', reason: error instanceof PaymentOutcomeUnknownError ? error.reason : error instanceof IntentNotConfirmableError ? 'intent_not_confirmable' : 'browser_handoff_failed' });
+        }
+        else if (error instanceof CheckoutCancelledError) {
+            this.cancel();
+        }
+        else if (error instanceof ApprovalTimeoutError) {
+            this.set({ ...this.state, status: 'timed_out', reason: 'approval_expired' });
+        }
+        else if (error instanceof ApprovalDeclinedError) {
+            this.set({ ...this.state, status: 'declined', reason: 'approval_declined' });
+        }
+        else {
+            this.set({ ...this.state, status: 'failed', reason: 'checkout_failed' });
+        }
+    }
+    async requestUserAction(reason) {
+        if (this.state.status === 'completed')
+            return;
+        this.held = true;
+        this.set({ ...this.state, status: 'requires_user_action', reason });
+        // Hooks deliver a link/live view owned by the integrator; the SDK does not invent challenge URLs.
+        try {
+            await this.options.onUserAction?.({ reason, authorizationId: this.state.authorizationId });
+        }
+        catch { /* observer only */ }
+    }
+    reconcile() {
+        if (this.state.status === 'completed')
+            return Promise.resolve(this.getState());
+        if (this.reconciliation)
+            return this.reconciliation;
+        if (!this.options.resolveMerchantResult)
+            return Promise.resolve(this.getState());
+        if (this.active)
+            throw new Error('Wait for the paused request to finish before reconciling the merchant order.');
+        this.reconciliation = this.resolve().finally(() => { this.reconciliation = null; });
+        return this.reconciliation;
+    }
+    async resolve() {
+        let result;
+        try {
+            result = await this.options.resolveMerchantResult(this.getState());
+        }
+        catch {
+            result = { status: 'unknown' };
+        }
+        if (!result || typeof result !== 'object')
+            result = { status: 'unknown' };
+        if (result.status === 'completed' && typeof result.orderId === 'string' && result.orderId.length > 0) {
+            this.held = true;
+            this.set({ ...this.state, status: 'completed', orderId: result.orderId });
+        }
+        else if (result.status === 'failed') {
+            // Keep the guard armed until the application deliberately starts another attempt.
+            this.held = true;
+            this.set({ ...this.state, status: 'failed', reason: 'merchant_confirmed_failure' });
+        }
+        else if (result.status === 'requires_user_action') {
+            await this.requestUserAction(result.reason);
+        }
+        else {
+            this.held = true;
+            this.set({ ...this.state, status: result.status === 'pending' ? 'awaiting_merchant' : 'outcome_unknown', reason: 'merchant_not_confirmed' });
+        }
+        return this.getState();
+    }
+    retryAfterMerchantFailure(result) {
+        if (this.active || this.reconciliation)
+            throw new Error('Cannot start another attempt while payment or reconciliation is in progress.');
+        if (this.cancelled)
+            throw new Error('This attachment was cancelled; attach again after reconciling the merchant order.');
+        if (result?.status !== 'failed')
+            throw new Error('A merchant-confirmed failure is required before retrying.');
+        if (this.state.status === 'completed')
+            throw new Error('This order is already complete. Use a new attachment for another order.');
+        if (this.unboundStripeToken)
+            throw new Error('This attachment delivered an unbound Stripe token; reconcile the merchant order and use a separately validated checkout flow.');
+        this.held = false;
+        this.set({ status: 'idle', authorizationId: null });
+    }
+}
+export function paymentEndpointGuards(input = []) {
+    const guards = input.map((guard) => {
+        const origin = new URL(guard.origin);
+        if (!['http:', 'https:'].includes(origin.protocol) || origin.origin !== guard.origin
+            || !guard.pathname.startsWith('/') || /[?#*]/.test(guard.pathname)) {
+            throw new Error('Payment endpoint guards require a canonical http(s) origin and an exact path without wildcards or query strings.');
+        }
+        const methods = (guard.methods ?? ['POST', 'PUT', 'PATCH']).map((method) => method.toUpperCase());
+        if (!methods.length || methods.some((method) => !['POST', 'PUT', 'PATCH', 'DELETE'].includes(method))) {
+            throw new Error('Payment endpoint guards can only block explicit mutation methods.');
+        }
+        return { ...guard, methods };
+    });
+    return {
+        patterns: guards.map((guard) => `${guard.origin}${guard.pathname}*`),
+        matches(raw, method) {
+            let url;
+            try {
+                url = new URL(raw);
+            }
+            catch {
+                return false;
+            }
+            return guards.some((guard) => url.origin === guard.origin && url.pathname === guard.pathname
+                && (method === undefined || guard.methods.includes(method.toUpperCase())));
+        },
+    };
+}