@agent-cards/checkout 0.3.0 → 0.4.0

package/dist/client.js

@@ -6,6 +6,16 @@ import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecogni
  */
 export const SUPPORTED_MODES = ['token', 'cse', 'hosted_form'];
 const AMOUNT_AUTHORITIES = ['stripe_payment_intent', 'hosted_form_sum', 'display_only'];
+export class CheckoutPreparationError extends Error {
+    preparationId;
+    reason;
+    constructor(preparationId, reason) {
+        super(`Checkout preparation unavailable: ${reason}`);
+        this.preparationId = preparationId;
+        this.reason = reason;
+        this.name = 'CheckoutPreparationError';
+    }
+}
 export class CardEncryptedError extends Error {
     psp;
     constructor(psp) {
@@ -223,6 +233,8 @@ export class VaultClient {
     pollIntervalMs;
     unverifiableRetryDelaysMs;
     registry;
+    preparations = new WeakSet();
+    usedPreparations = new WeakSet();
     constructor(opts) {
         this.opts = opts;
         this.baseUrl = (opts.baseUrl ?? 'https://api.agentcard.sh').replace(/\/$/, '');
@@ -274,14 +286,125 @@ export class VaultClient {
     cardUrlPatterns() {
         return deriveCardUrlPatterns(this.registry);
     }
+    /** Wait for real device approval before the caller starts native tokenization. */
+    async prepareCheckout(input) {
+        input = { ...input };
+        const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
+        if (input.psp !== 'square' || !['production', 'sandbox'].includes(input.environment))
+            throw fail('unsupported_processor');
+        if (!Number.isSafeInteger(input.amountCents) || input.amountCents <= 0 || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
+            throw fail('amount_required');
+        const origin = new URL(input.merchantOrigin);
+        if (!(origin.protocol === 'https:' || (origin.protocol === 'http:' && origin.hostname === 'localhost')) || origin.origin !== input.merchantOrigin)
+            throw fail('merchant_origin_invalid');
+        if (!input.checkoutKey || !input.user || !input.merchant)
+            throw fail('checkout_context_required');
+        const timeoutMs = input.timeoutMs ?? 15 * 60_000;
+        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+            throw fail('timeout_invalid');
+        const signal = input.signal ? AbortSignal.any([input.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+        if (signal.aborted)
+            throw fail('cancelled');
+        let id = null;
+        let ready = false;
+        try {
+            // Drain a sent creation even after caller cancellation to retire its ID.
+            // The separate stop signal prevents dispatch after a slow OAuth exchange.
+            const created = await this.post('/v2/checkout/preparations', {
+                user: input.user, merchant: input.merchant, amount_cents: input.amountCents, currency: input.currency.toLowerCase(),
+                ...(input.cardId ? { card_id: input.cardId } : {}), psp: input.psp, mode: 'token',
+                environment: input.environment, checkout_key: input.checkoutKey, merchant_origin: input.merchantOrigin,
+            }, AbortSignal.timeout(30_000), signal);
+            if (!created || typeof created.id !== 'string' || !/^cprep_[A-Za-z0-9_-]{1,128}$/.test(created.id))
+                throw fail('create_unconfirmed');
+            const preparationId = created.id;
+            id = preparationId;
+            try {
+                Promise.resolve(input.onPreparationCreated?.(preparationId)).catch(() => { });
+            }
+            catch { /* observer only */ }
+            if (signal.aborted)
+                throw fail('cancelled', id);
+            if (typeof created.approvalUrl !== 'string')
+                throw fail('approval_url_missing', id);
+            try {
+                Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
+            }
+            catch { /* observer only */ }
+            while (!signal.aborted) {
+                const state = await this.get(`/v2/checkout/preparations/${id}`, signal);
+                if (signal.aborted)
+                    throw fail('cancelled', id);
+                if (state?.id !== id)
+                    throw fail('status_unconfirmed', id);
+                if (state.status === 'ready') {
+                    const expiry = Date.parse(state.ready_expires_at);
+                    if (!Number.isFinite(expiry) || expiry <= Date.now() || typeof state.card_id !== 'string' || !state.card_id
+                        || state.payment_status !== 'not_started' || state.amount_authority !== 'display_only'
+                        || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
+                        || state.amount_cents !== input.amountCents || state.currency !== input.currency.toLowerCase()
+                        || state.psp !== 'square' || state.mode !== 'token' || state.environment !== input.environment
+                        || state.checkout_key !== input.checkoutKey)
+                        throw fail('ready_unconfirmed', id);
+                    const prepared = Object.freeze({
+                        id: preparationId, status: 'ready', psp: input.psp, environment: input.environment, expiresAt: state.ready_expires_at,
+                        cardId: state.card_id, user: input.user, merchant: input.merchant, amountCents: input.amountCents,
+                        currency: input.currency.toLowerCase(), merchantOrigin: input.merchantOrigin, checkoutKey: input.checkoutKey,
+                        paymentStatus: 'not_started', amountAuthority: 'display_only',
+                    });
+                    this.preparations.add(prepared);
+                    ready = true;
+                    return prepared;
+                }
+                if (state.status !== 'awaiting_approval')
+                    throw fail(['cancelled', 'expired', 'bound'].includes(state.status) ? state.status : 'status_unconfirmed', id);
+                await interruptibleSleep(this.pollIntervalMs, signal);
+            }
+            throw fail('cancelled', id);
+        }
+        catch (error) {
+            if (error instanceof CheckoutPreparationError)
+                throw error;
+            throw fail(signal.aborted ? 'cancelled' : 'preparation_unconfirmed', id);
+        }
+        finally {
+            if (id && !ready)
+                await this.cancelPreparation(id).catch(() => { });
+        }
+    }
+    /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
+    async cancelPreparation(id) {
+        if (!/^cprep_[A-Za-z0-9_-]{1,128}$/.test(id))
+            throw new CheckoutPreparationError(null, 'id_invalid');
+        const state = await this.post(`/v2/checkout/preparations/${id}/cancel`, {}, AbortSignal.timeout(5_000));
+        if (state?.id !== id || !['cancelled', 'expired'].includes(state.status))
+            throw new CheckoutPreparationError(id, 'cancel_unconfirmed');
+    }
     /**
      * Hand us a paused tokenization request. We ask the cardholder to approve,
      * their device supplies the card and calls the merchant, and you get back the
      * response to replay into the browser. Your process never sees a card.
      */
     async authorize(input) {
+        const preparation = input.preparation;
+        if (preparation) {
+            if (!this.preparations.has(preparation) || this.usedPreparations.has(preparation))
+                throw new CheckoutPreparationError(preparation.id ?? null, 'already_used_or_foreign');
+            // Consume locally before any await, including OAuth, and never recycle it.
+            this.usedPreparations.add(preparation);
+            const url = new URL(input.request.url);
+            const host = preparation.environment === 'production' ? 'pci-connect.squareup.com' : 'pci-connect.squareupsandbox.com';
+            if (Date.parse(preparation.expiresAt) <= Date.now())
+                throw new CheckoutPreparationError(preparation.id, 'expired');
+            if (input.user !== preparation.user || input.merchant !== preparation.merchant || input.amountCents !== preparation.amountCents
+                || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
+                || url.origin !== `https://${host}` || url.pathname !== '/v2/card-nonce' || url.username || url.password)
+                throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
+        }
         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)}`);
@@ -333,6 +456,7 @@ export class VaultClient {
             // the recognizer and refuses a disagreement before a row exists.
             mode,
             ...(input.cardId ? { cardId: input.cardId } : {}),
+            ...(preparation ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin } : {}),
             request: {
                 url: input.request.url,
                 method: input.request.method,
@@ -341,141 +465,218 @@ export class VaultClient {
             },
         };
         try {
-            created = await this.createAuthorization(payload, input.currency, operationSignal);
+            created = await this.createAuthorization(payload, input.currency, AbortSignal.any([operationSignal, AbortSignal.timeout(30_000)]), input.merchantSignal);
         }
         catch (error) {
+            if (error instanceof PaymentOutcomeUnknownError) {
+                if (preparation && !error.authorizationId)
+                    throw new PaymentOutcomeUnknownError(await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated), error.reason);
+                throw error;
+            }
+            if (preparation && error instanceof CheckoutApiError && error.code === 'preparation_bound') {
+                const id = typeof error.details.authorization_id === 'string' && /^cauth_[A-Za-z0-9_-]+$/.test(error.details.authorization_id) ? error.details.authorization_id : null;
+                if (id) {
+                    try {
+                        Promise.resolve(input.onAuthorizationCreated?.(id)).catch(() => { });
+                    }
+                    catch { /* observer only */ }
+                }
+                throw new PaymentOutcomeUnknownError(id, 'preparation_already_bound');
+            }
             // 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 new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_unanswered');
             }
             throw error;
         }
         if (!created || typeof created.id !== 'string' || !created.id)
-            throw new PaymentOutcomeUnknownError(null, 'authorization_create_malformed');
+            throw new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_malformed');
         const authorizationId = created.id;
+        let failed = false;
+        const stopSignal = input.merchantSignal
+            ? AbortSignal.any([input.merchantSignal, ...(input.signal ? [input.signal] : [])]) : input.signal;
         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) {
-            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');
+                Promise.resolve(input.onAuthorizationCreated?.(authorizationId)).catch(() => { });
             }
-            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');
+            catch { /* observer only */ }
+            if (input.merchantSignal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+            if (!preparation) {
+                try {
+                    Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
                 }
-                return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority };
+                catch { /* approval delivery must not lose an existing authorization */ }
             }
-            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');
+            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 (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 (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');
+                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 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,
-                    ...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');
             }
-            if (s.status === 'expired') {
-                if (s.replay_attempted === false)
-                    throw new ApprovalTimeoutError(timeoutMs);
-                throw new PaymentOutcomeUnknownError(authorizationId, 'expired_after_possible_replay');
+            // 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) {
+            failed = true;
+            if (input.merchantSignal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+            throw error;
+        }
+        finally {
+            if (input.merchantSignal?.aborted || (preparation && failed)) {
+                // 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(() => { });
             }
-            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');
+    }
+    /** A lost bind acknowledgement must never resume the request. Recover metadata only for safe cleanup. */
+    async retireUncertainPreparation(preparation, onCreated) {
+        // Race cancellation atomically against a create still arriving at the API.
+        // A bound preparation refuses cancellation; resolve its ID exactly once below.
+        await this.cancelPreparation(preparation.id).catch(() => { });
+        let state;
+        try {
+            state = await this.get(`/v2/checkout/preparations/${preparation.id}`, AbortSignal.timeout(3_000));
+        }
+        catch {
+            return null;
+        }
+        if (state?.id !== preparation.id || state.status !== 'bound' || typeof state.authorization_id !== 'string'
+            || !/^cauth_[A-Za-z0-9_-]{1,128}$/.test(state.authorization_id))
+            return null;
+        const id = state.authorization_id;
+        try {
+            Promise.resolve(onCreated?.(id)).catch(() => { });
+        }
+        catch { /* observer only */ }
+        await this.cancelAuthorization(id).catch(() => { });
+        return id;
+    }
+    /** 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`
@@ -484,10 +685,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, signal) {
+    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, signal);
+                return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
             }
             catch (err) {
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
@@ -496,11 +699,11 @@ export class VaultClient {
                 }
                 // Two 502s the API asks to be retried: Stripe did not answer the
                 // amount read-back, or Adyen did not answer the public-key fetch.
-                const retryable = err instanceof CheckoutApiError && err.status === 502
+                const retryable = !payload.preparation_id && err instanceof CheckoutApiError && err.status === 502
                     && (err.code === 'amount_unverifiable' || err.code === 'cse_key_unavailable');
                 if (!retryable || attempt >= this.unverifiableRetryDelaysMs.length)
                     throw err;
-                await interruptibleSleep(this.unverifiableRetryDelaysMs[attempt], signal);
+                await interruptibleSleep(this.unverifiableRetryDelaysMs[attempt], stopRetries ? AbortSignal.any([stopRetries, ...(signal ? [signal] : [])]) : signal);
                 if (signal?.aborted)
                     throw signal.reason;
             }
@@ -545,9 +748,14 @@ export class VaultClient {
         return this.inflight;
     }
     /** Authenticated request that retries ONCE on a 401 with a fresh token. */
-    async call(path, init = {}, retried = false) {
+    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,
@@ -555,15 +763,17 @@ export class VaultClient {
         }), signal);
         // A token can be revoked or expire early; one forced refresh, then give up.
         if (r.status === 401 && !retried) {
+            if (stopNewRequests?.aborted)
+                throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
             await withSignal(this.accessToken(true), signal);
-            return this.call(path, { ...init, signal }, true);
+            return this.call(path, { ...init, signal }, true, stopNewRequests);
         }
         if (!r.ok)
             throw new CheckoutApiError(r.status, path, await withSignal(r.text(), signal));
         return withSignal(r.json(), signal);
     }
-    post(path, body, signal) {
-        return this.call(path, { method: 'POST', body: JSON.stringify(body), signal });
+    post(path, body, signal, stopNewRequests) {
+        return this.call(path, { method: 'POST', body: JSON.stringify(body), signal }, false, stopNewRequests);
     }
     get(path, signal) {
         return this.call(path, { signal });

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
+export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, PrepareCheckoutOptions, PrepareCheckoutInput, PreparedCheckout, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } 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

@@ -1,4 +1,4 @@
-import { type ReplayResponse } from './client.js';
+import { CheckoutPreparationError, type PrepareCheckoutOptions, type PreparedCheckout, 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 = {
@@ -13,8 +13,9 @@ export type MerchantResult = {
     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';
+    status: 'idle' | 'awaiting_approval' | 'ready_to_submit' | 'awaiting_merchant' | 'requires_user_action' | 'completed' | 'declined' | 'timed_out' | 'cancelled' | 'unsupported' | 'outcome_unknown' | 'failed';
     authorizationId: string | null;
+    preparationId?: string;
     mode?: CheckoutMode;
     orderId?: string;
     /** Stable SDK category; never includes a request body, processor response, or approval link. */
@@ -36,7 +37,9 @@ export interface LifecycleOptions {
 }
 export interface CheckoutController {
     getState(): Readonly<CheckoutState>;
-    /** Stop this attachment locally. Does not revoke an approval link or cancel a processor payment. */
+    /** Await device consent before the caller starts the first native Pay action. One use per attachment. */
+    prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
+    /** Stop locally and best-effort retire an unbound preparation. Does not cancel a processor payment. */
     cancel(): void;
     /** Ask the application's merchant resolver. A rejection records unknown; never automatically retries payment. */
     reconcile(): Promise<Readonly<CheckoutState>>;
@@ -54,11 +57,20 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private held;
     private active;
     private cancelled;
+    private merchantAborted;
     private unboundStripeToken;
     private reconciliation;
+    private preparationHandler?;
+    private preparationUsed;
     readonly abort: AbortController;
     constructor(options: LifecycleOptions);
     getState(): Readonly<CheckoutState>;
+    setPreparationHandler(handler: (options: PrepareCheckoutOptions) => Promise<PreparedCheckout>): void;
+    prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
+    preparing(): void;
+    preparationCreated(preparationId: string): void;
+    prepared(preparation: PreparedCheckout): void;
+    preparationFailed(error: CheckoutPreparationError): void;
     isBlocked(): boolean;
     isCancelled(): boolean;
     begin(): void;
@@ -68,6 +80,8 @@ export declare class CheckoutLifecycle implements CheckoutController {
     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;