@agent-cards/checkout 0.2.1 → 0.3.1

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,10 @@ 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();
+        if (input.merchantSignal?.aborted)
+            throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
         const rec = findRecognizer(input.request.url, this.registry);
         if (!rec)
             throw new Error(`not a known tokenization endpoint: ${redactUrl(input.request.url)}`);
@@ -301,7 +318,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,94 +341,180 @@ 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;
-        while (Date.now() < deadline) {
-            await sleep(this.pollIntervalMs);
-            const s = await this.get(`/v2/checkout/authorizations/${authorizationId}`);
-            const amountAuthority = typeof s.amount_authority === 'string' && AMOUNT_AUTHORITIES.includes(s.amount_authority)
-                ? { amountAuthority: s.amount_authority }
-                : {};
-            if (s.status === 'submitted_on_device') {
-                // 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).
-                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}`);
-                if (typeof s.submitted_at !== 'string' || !s.submitted_at) {
-                    throw new Error(`malformed hosted_form submission on authorization ${authorizationId}: no submitted_at`);
-                }
-                return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority };
+        };
+        try {
+            created = await this.createAuthorization(payload, input.currency, AbortSignal.any([operationSignal, AbortSignal.timeout(30_000)]), input.merchantSignal);
+        }
+        catch (error) {
+            if (error instanceof PaymentOutcomeUnknownError)
+                throw 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;
+        const stopSignal = input.merchantSignal
+            ? AbortSignal.any([input.merchantSignal, ...(input.signal ? [input.signal] : [])]) : input.signal;
+        try {
+            try {
+                Promise.resolve(input.onAuthorizationCreated?.(authorizationId)).catch(() => { });
+            }
+            catch { /* observer only */ }
+            if (input.merchantSignal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+            try {
+                Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
             }
-            if (s.status === 'approved') {
-                const approvedMode = typeof s.mode === 'string' ? s.mode : 'token';
-                if (approvedMode === 'hosted_form') {
-                    // 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`);
+            catch { /* approval delivery must not lose an existing authorization */ }
+            while (Date.now() < deadline) {
+                if (stopSignal?.aborted)
+                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
+                await interruptibleSleep(Math.min(this.pollIntervalMs, Math.max(0, deadline - Date.now())), stopSignal);
+                if (stopSignal?.aborted)
+                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
+                let s;
+                const deadlineSignal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
+                const pollSignal = stopSignal ? AbortSignal.any([stopSignal, deadlineSignal]) : deadlineSignal;
+                try {
+                    s = await this.get(`/v2/checkout/authorizations/${authorizationId}`, pollSignal);
+                }
+                catch {
+                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'authorization_poll_failed');
                 }
-                if (approvedMode === 'cse') {
-                    const sub = s.substitutions;
-                    const fieldsOk = sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.at
-                        && 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}`);
-                    // `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}`);
+                if (input.merchantSignal?.aborted)
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+                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 }
+                    : {};
+                if (s.status === 'submitted_on_device') {
+                    // 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. 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 PaymentOutcomeUnknownError(authorizationId, 'submission_mode_mismatch');
+                    if (typeof s.submitted_at !== 'string' || !s.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 };
+                }
+                if (s.status === 'approved') {
+                    const approvedMode = typeof s.mode === 'string' ? s.mode : 'token';
+                    if (approvedMode === 'hosted_form') {
+                        // 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 PaymentOutcomeUnknownError(authorizationId, 'hosted_form_approval_malformed');
+                    }
+                    if (approvedMode === 'cse') {
+                        const sub = s.substitutions;
+                        const fieldsOk = sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.at
+                            && 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 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 PaymentOutcomeUnknownError(authorizationId, 'cse_remove_malformed');
+                        }
+                        return {
+                            mode: 'cse',
+                            authorizationId,
+                            substitutions: {
+                                encoding: 'json',
+                                at: sub.at,
+                                fields: { ...sub.fields },
+                                ...(removeRaw ? { remove: [...removeRaw] } : {}),
+                            },
+                            ...amountAuthority,
+                        };
+                    }
+                    if (approvedMode !== 'token')
+                        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: 'cse',
+                        mode: 'token',
                         authorizationId,
-                        substitutions: {
-                            encoding: 'json',
-                            at: sub.at,
-                            fields: { ...sub.fields },
-                            ...(removeRaw ? { remove: [...removeRaw] } : {}),
-                        },
+                        ...response,
+                        amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
+                        chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : null,
+                        chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
+                        chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
                         ...amountAuthority,
                     };
                 }
-                if (approvedMode !== 'token')
-                    throw new UnsupportedModeError(approvedMode);
-                const response = s.response;
-                return {
-                    mode: 'token',
-                    authorizationId,
-                    ...response,
-                    amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
-                    chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : null,
-                    chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
-                    chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
-                    ...amountAuthority,
-                };
-            }
-            if (s.status === 'declined') {
-                // The pre-replay checks declined it: typed, with the numbers, so the
-                // caller can say what happened rather than "the user said no".
-                if (s.reason === 'amount_mismatch') {
-                    throw new AmountMismatchError(String(created.id), Number(s.expected_cents), Number(s.actual_cents), String(s.currency ?? input.currency ?? ''), s.actual_currency != null ? String(s.actual_currency) : undefined, 'pre_replay');
+                if (s.status === 'declined') {
+                    // The pre-replay checks declined it: typed, with the numbers, so the
+                    // caller can say what happened rather than "the user said no".
+                    if (s.reason === 'amount_mismatch') {
+                        throw new AmountMismatchError(String(created.id), Number(s.expected_cents), Number(s.actual_cents), String(s.currency ?? input.currency ?? ''), s.actual_currency != null ? String(s.actual_currency) : undefined, 'pre_replay');
+                    }
+                    if (s.reason === 'intent_not_confirmable')
+                        throw new IntentNotConfirmableError(String(created.id));
+                    if (s.reason === 'processor_refused') {
+                        throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null);
+                    }
+                    throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
                 }
-                if (s.reason === 'intent_not_confirmable')
-                    throw new IntentNotConfirmableError(String(created.id));
-                if (s.reason === 'processor_refused') {
-                    throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null);
+                if (s.status === 'expired') {
+                    if (s.replay_attempted === false)
+                        throw new ApprovalTimeoutError(timeoutMs);
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'expired_after_possible_replay');
                 }
-                throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
+                if (s.status !== 'awaiting_approval')
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_unrecognized');
             }
+            // A local deadline is not server-side expiry; the person may still use the approval link.
+            throw new PaymentOutcomeUnknownError(authorizationId, 'local_approval_timeout');
+        }
+        catch (error) {
+            if (input.merchantSignal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+            throw error;
         }
-        throw new ApprovalTimeoutError(timeoutMs);
+        finally {
+            if (input.merchantSignal?.aborted) {
+                // Drain a create acknowledgement even after the merchant aborts so its
+                // known ID can be retired. An unacknowledged create remains unknown.
+                // A started/finalized replay or failed cleanup never becomes a claimed
+                // cancellation, and this best-effort cleanup never retries a payment.
+                await this.cancelAuthorization(authorizationId).catch(() => { });
+            }
+        }
+    }
+    /** Retire only a pre-replay authorization. A 409 or missing response remains unknown. */
+    async cancelAuthorization(authorizationId) {
+        if (!/^cauth_[A-Za-z0-9_-]{1,128}$/.test(authorizationId))
+            throw new Error('Invalid authorization ID.');
+        const result = await this.post(`/v2/checkout/authorizations/${authorizationId}/cancel`, {}, AbortSignal.timeout(5_000));
+        if (result?.id !== authorizationId || result.status !== 'declined'
+            || result.reason !== 'merchant_request_aborted' || result.cancelled !== true
+            || result.processor_request_started !== false) {
+            throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_cancel_unconfirmed');
+        }
+        return { id: authorizationId, status: 'declined', reason: 'merchant_request_aborted',
+            cancelled: true, processor_request_started: false };
     }
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
@@ -414,10 +523,12 @@ 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, stopRetries) {
         for (let attempt = 0;; attempt++) {
+            if (stopRetries?.aborted)
+                throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
             try {
-                return await this.post('/v2/checkout/authorizations', payload);
+                return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
             }
             catch (err) {
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
@@ -430,7 +541,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], stopRetries ? AbortSignal.any([stopRetries, ...(signal ? [signal] : [])]) : signal);
+                if (signal?.aborted)
+                    throw signal.reason;
             }
         }
     }
@@ -457,6 +570,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.
@@ -472,26 +586,35 @@ export class VaultClient {
         return this.inflight;
     }
     /** 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}`, {
+    async call(path, init = {}, retried = false, stopNewRequests) {
+        const signal = init.signal ?? AbortSignal.timeout(30_000);
+        const token = await withSignal(this.accessToken(), signal);
+        // Auth can outlive the merchant request. Stop a create that has not left
+        // yet, while preserving the response of one already sent for cleanup.
+        if (stopNewRequests?.aborted)
+            throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
+        signal.throwIfAborted();
+        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);
+            if (stopNewRequests?.aborted)
+                throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
+            await withSignal(this.accessToken(true), signal);
+            return this.call(path, { ...init, signal }, true, stopNewRequests);
         }
         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, stopNewRequests) {
+        return this.call(path, { method: 'POST', body: JSON.stringify(body), signal }, false, stopNewRequests);
     }
-    get(path) {
-        return this.call(path);
+    get(path, signal) {
+        return this.call(path, { signal });
     }
 }
 /**
@@ -509,4 +632,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,4 +1,4 @@
-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, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
@@ -8,3 +8,4 @@ export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted
 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,4 +1,4 @@
-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 { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';

package/dist/lifecycle.d.ts

@@ -0,0 +1,94 @@
+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 merchantAborted;
+    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;
+    /** The exact browser request is gone; a late approval cannot reopen it. */
+    merchantRequestAborted(): 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;
+};