@agent-cards/checkout 0.4.1 → 0.6.0

package/dist/cdp.js

@@ -1,6 +1,8 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
 import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, ProcessorRefusedError, UnsupportedModeError, redactUrl, } from './client.js';
 import { PreparationGate } from './preparation.js';
+import { classifyBraintreeRequest } from './braintree.js';
+import { CheckoutAttachmentError, attachmentDeadline, attachmentFailure, withinAttachmentDeadline } from './attachment.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
@@ -327,6 +329,10 @@ function merchantAttempt(lifecycle) {
  */
 export async function attachToCdp(cdp, pageSessionId, opts) {
     opts = safeOptions(opts);
+    const setupTimeoutMs = attachmentDeadline(opts.attachmentTimeoutMs);
+    const setupStop = new AbortController();
+    let attachmentReady = false;
+    let setupFailureReported = false;
     const lifecycle = new CheckoutLifecycle(opts);
     let preparationFrameId;
     const preparationGate = new PreparationGate(opts, lifecycle, async () => {
@@ -338,6 +344,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     });
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
+    const arming = new Map();
     // Set once a failure proves that retrying cannot help; see isTerminal.
     let terminal = null;
     // Silence window after a person declined or ignored one; see APPROVAL_COOLDOWN_MS.
@@ -351,23 +358,48 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let lastSubmitted = null;
     const derived = typeof opts.vault?.cardUrlPatterns === 'function' ? opts.vault.cardUrlPatterns() : [];
     const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns])];
-    opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
-    const arm = async (sessionId) => {
+    const arm = async (sessionId, resume = false) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
+        if (arming.has(key))
+            return arming.get(key);
         // Fetch's interception ID differs from Network's ID. Enable failure events
         // before intercepting and bind each attempt to both its ID and CDP session.
-        await cdp.send('Network.enable', {}, sessionId);
-        await cdp.send('Page.enable', {}, sessionId).catch(() => { });
-        await cdp.send('Fetch.enable', {
-            patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
-        }, sessionId);
-        // Descend into this target's own children (iframes inside iframes).
-        await cdp.send('Target.setAutoAttach', {
-            autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
-        }, sessionId);
-        armed.add(key);
+        const pending = withinAttachmentDeadline(async (assertActive) => {
+            await cdp.send('Network.enable', {}, sessionId);
+            assertActive();
+            await cdp.send('Page.enable', {}, sessionId).catch(() => { });
+            assertActive();
+            await cdp.send('Fetch.enable', {
+                patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
+            }, sessionId);
+            assertActive();
+            // Descend into this target's own children (iframes inside iframes).
+            await cdp.send('Target.setAutoAttach', {
+                autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
+            }, sessionId);
+            assertActive();
+            // A child remains part of setup until Chrome acknowledges its resume.
+            // Deduplicate this command with arming, and bound the acknowledgement too.
+            if (resume) {
+                await cdp.send('Runtime.runIfWaitingForDebugger', {}, sessionId);
+                assertActive();
+            }
+        }, setupTimeoutMs, setupStop.signal);
+        arming.set(key, pending);
+        try {
+            await pending;
+            armed.add(key);
+        }
+        catch (error) {
+            const failure = attachmentFailure(error);
+            setupStop.abort(failure);
+            throw failure;
+        }
+        finally {
+            arming.delete(key);
+        }
     };
     cdp.on(async (method, params, sessionId) => {
         if (((method === 'Page.frameNavigated' && !params.frame?.parentId) || (method === 'Page.navigatedWithinDocument' && preparationFrameId && params.frameId === preparationFrameId)) && sessionId === pageSessionId) {
@@ -378,6 +410,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if ((method === 'Inspector.detached' && sessionId === pageSessionId)
             || (method === 'Target.detachedFromTarget' && params.sessionId === pageSessionId)) {
+            setupStop.abort(new CheckoutAttachmentError('closed'));
             preparationGate.invalidate('merchant_document_closed');
             // The root page owns every attached OOPIF; its loss ends child requests too.
             activeRequest?.attempt.stop();
@@ -395,24 +428,43 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         }
         if (method === 'Target.attachedToTarget') {
+            if (setupStop.signal.aborted)
+                return;
             const child = params.sessionId;
             try {
-                await arm(child);
+                await arm(child, true);
             }
-            catch {
+            catch (error) {
+                // Shared child setup and sibling cancellation can reject several
+                // handlers together. Publish the terminal setup failure only once.
+                if (setupFailureReported)
+                    return;
+                setupFailureReported = true;
+                setupStop.abort(attachmentFailure(error));
                 terminal = new Error('browser_interception_unavailable');
                 lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'browser_interception_unavailable'));
                 opts.onEvent?.({ type: 'failed', detail: 'browser_interception_unavailable' });
                 // Leave this target paused: resuming an unarmed card frame would silently bypass the vault.
                 return;
             }
-            // Child targets start paused when waitForDebuggerOnStart is set.
-            await cdp.send('Runtime.runIfWaitingForDebugger', {}, child).catch(() => { });
             return;
         }
         if (method !== 'Fetch.requestPaused')
             return;
         const { requestId, request, resourceType, networkId, frameId } = params;
+        // Braintree shares /graphql between configuration and card mutations.
+        // Classify before URL-only recognition or claiming a prepared request.
+        const braintree = request.method.toUpperCase() === 'POST'
+            ? classifyBraintreeRequest(request.url, request.method, pausedBody(request)) : undefined;
+        if (braintree === 'configuration') {
+            await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
+            return;
+        }
+        if (braintree === 'invalid') {
+            opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
+        }
         if (!opts.vault.isCardRequest(request.url, request.method)) {
             if (guards.matches(request.url, request.method)) {
                 preparationGate.invalidate('unsupported_checkout');
@@ -424,9 +476,14 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             return;
         }
+        if (!attachmentReady || arming.has(sessionId ?? '__root__') || setupStop.signal.aborted) {
+            opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
+        }
         let preparation;
         try {
-            preparation = preparationGate.claim(request.url);
+            preparation = preparationGate.claim(request.url, pausedBody(request));
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -576,7 +633,24 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 preparationGate.retireUnboundClaim();
         }
     });
-    await arm(pageSessionId);
+    try {
+        await arm(pageSessionId);
+        if (setupStop.signal.aborted)
+            throw attachmentFailure(setupStop.signal.reason);
+        attachmentReady = true;
+        opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
+    }
+    catch (error) {
+        const failure = attachmentFailure(error);
+        setupStop.abort(failure);
+        terminal = failure;
+        if (!setupFailureReported) {
+            setupFailureReported = true;
+            lifecycle.cancel();
+            opts.onEvent?.({ type: 'failed', detail: `checkout_attachment_${failure.reason}` });
+        }
+        throw failure;
+    }
     return lifecycle;
 }
 /**
@@ -592,6 +666,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
  */
 export async function attachToPlaywright(page, opts) {
     opts = safeOptions(opts);
+    const setupTimeoutMs = attachmentDeadline(opts.attachmentTimeoutMs);
+    const setupStop = new AbortController();
+    let attachmentReady = false;
     // Routing cannot see requests owned by a service worker. Existing controlled
     // contexts must be recreated with serviceWorkers: 'block' before checkout.
     if (page.context?.().serviceWorkers?.().length) {
@@ -628,8 +705,10 @@ export async function attachToPlaywright(page, opts) {
         if (activeRequest && activeRequest.request === request)
             activeRequest.attempt.stop();
     });
-    page.on?.('close', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
-    page.on?.('crash', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('close', () => { if (!attachmentReady)
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('crash', () => { if (!attachmentReady)
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
     page.on?.('framenavigated', (frame) => {
         if (frame === page.mainFrame?.()) {
             preparationGate.invalidate('merchant_document_changed');
@@ -644,139 +723,175 @@ export async function attachToPlaywright(page, opts) {
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
-    await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
-        const request = route.request();
-        // The matcher only sees the URL; a preflight or a GET must pass through
-        // untouched or the browser's CORS check fails on our synthetic answer.
-        if (!opts.vault.isCardRequest(request.url(), request.method())) {
-            if (guards.matches(request.url(), request.method())) {
-                preparationGate.invalidate('unsupported_checkout');
-                lifecycle.unsupported();
-                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+    const install = async (assertActive) => {
+        if (page.isClosed?.()) {
+            const failure = new CheckoutAttachmentError('closed');
+            setupStop.abort(failure);
+            throw failure;
+        }
+        await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
+            const request = route.request();
+            const braintree = request.method().toUpperCase() === 'POST'
+                ? classifyBraintreeRequest(request.url(), request.method(), request.postData() ?? '') : undefined;
+            if (braintree === 'configuration')
+                return route.fallback();
+            if (braintree === 'invalid') {
+                opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
                 return route.abort('aborted');
             }
-            return route.fallback();
-        }
-        let preparation;
-        try {
-            preparation = preparationGate.claim(request.url());
-        }
-        catch (error) {
-            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
-            return route.abort('aborted');
-        }
-        // Fail closed and stay quiet: no card may reach the PSP, but neither may
-        // the page's retry loop turn into a stream of doomed API calls. Every
-        // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
-        // CDP adapter's Fetch.failRequest uses, so a refused navigation
-        // resolves identically whichever adapter is attached.
-        if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
-            const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
-            opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
-            if (preparation)
-                preparationGate.retireUnboundClaim();
-            return route.abort('aborted');
-        }
-        // Reserved before anything that could yield, matching attachToCdp.
-        awaitingApproval = true;
-        const attempt = merchantAttempt(lifecycle);
-        const frames = [];
-        try {
-            for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
-                frames.push(frame);
-        }
-        catch { /* requestfailed/page close still cover unavailable frame metadata */ }
-        const assertRequestLive = () => {
-            if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
-                attempt.stop();
-            attempt.assertLive();
-        };
-        let handoffStarted = false;
-        try {
-            const body = request.postData() ?? '';
-            if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
-                opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
-                return await route.abort('aborted');
+            // The matcher only sees the URL; a preflight or a GET must pass through
+            // untouched or the browser's CORS check fails on our synthetic answer.
+            if (!opts.vault.isCardRequest(request.url(), request.method())) {
+                if (guards.matches(request.url(), request.method())) {
+                    preparationGate.invalidate('unsupported_checkout');
+                    lifecycle.unsupported();
+                    opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+                    return route.abort('aborted');
+                }
+                return route.fallback();
             }
-            opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
-            lifecycle.begin();
-            activeRequest = { request, frames, attempt };
-            if (preparation)
-                await preparationGate.assertDocument();
-            assertRequestLive();
-            const replay = await opts.vault.authorize({
-                user: opts.user,
-                merchant: opts.merchant,
-                amount: opts.amount,
-                amountCents: opts.amountCents,
-                currency: opts.currency,
-                cardId: preparation?.cardId ?? opts.cardId,
-                preparation,
-                timeoutMs: opts.timeoutMs,
-                signal: lifecycle.abort.signal,
-                merchantSignal: attempt.signal,
-                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
-                    lifecycle.approvalUrl(url);
-                    return opts.onApprovalUrl?.(url);
-                } },
-                request: { url: request.url(), method: request.method(), headers: request.headers(), body },
-            });
-            assertRequestLive();
-            if (lifecycle.isCancelled())
-                throw new Error('checkout cancelled locally after approval');
-            lifecycle.prepareHandoff(replay, request.url());
-            handoffStarted = replay.mode !== 'cse';
-            if (replay.mode === 'hosted_form') {
-                // Same as the CDP path: the paused navigation resolves to the
-                // synthetic page, and a re-post of this form is refused.
-                const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
-                // Inert on a navigation (never CORS-checked); one path for every fulfill.
-                await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
-                assertRequestLive();
-                lastSubmitted = { url: request.url(), body, at: Date.now() };
-                opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+            if (!attachmentReady || setupStop.signal.aborted) {
+                opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
+                return route.abort('aborted');
             }
-            else if (replay.mode === 'cse') {
-                // Same as the CDP path: the request continues from this browser
-                // with the ciphertext swapped in and no header override; Playwright
-                // recomputes the length itself.
-                const postData = cseBody(body, replay);
-                handoffStarted = true;
-                await route.continue({ postData });
-                assertRequestLive();
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+            let preparation;
+            try {
+                preparation = preparationGate.claim(request.url(), request.postData() ?? '');
             }
-            else {
-                // Playwright adds these itself when a cross-origin fulfill carries
-                // none; written here anyway (replacing a stale value) so a
-                // cross-origin answer is the same whichever adapter ran.
-                const cors = corsDecision(request.url(), request.headers());
-                await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+            catch (error) {
+                opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+                return route.abort('aborted');
+            }
+            // Fail closed and stay quiet: no card may reach the PSP, but neither may
+            // the page's retry loop turn into a stream of doomed API calls. Every
+            // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
+            // CDP adapter's Fetch.failRequest uses, so a refused navigation
+            // resolves identically whichever adapter is attached.
+            if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
+                const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+                opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
+                if (preparation)
+                    preparationGate.retireUnboundClaim();
+                return route.abort('aborted');
+            }
+            // Reserved before anything that could yield, matching attachToCdp.
+            awaitingApproval = true;
+            const attempt = merchantAttempt(lifecycle);
+            const frames = [];
+            try {
+                for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                    frames.push(frame);
+            }
+            catch { /* requestfailed/page close still cover unavailable frame metadata */ }
+            const assertRequestLive = () => {
+                if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
+                    attempt.stop();
+                attempt.assertLive();
+            };
+            let handoffStarted = false;
+            try {
+                const body = request.postData() ?? '';
+                if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
+                    opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
+                    return await route.abort('aborted');
+                }
+                opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
+                lifecycle.begin();
+                activeRequest = { request, frames, attempt };
+                if (preparation)
+                    await preparationGate.assertDocument();
                 assertRequestLive();
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
+                const replay = await opts.vault.authorize({
+                    user: opts.user,
+                    merchant: opts.merchant,
+                    amount: opts.amount,
+                    amountCents: opts.amountCents,
+                    currency: opts.currency,
+                    cardId: preparation?.cardId ?? opts.cardId,
+                    preparation,
+                    timeoutMs: opts.timeoutMs,
+                    signal: lifecycle.abort.signal,
+                    merchantSignal: attempt.signal,
+                    onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                    onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
+                        lifecycle.approvalUrl(url);
+                        return opts.onApprovalUrl?.(url);
+                    } },
+                    request: { url: request.url(), method: request.method(), headers: request.headers(), body },
+                });
+                assertRequestLive();
+                if (lifecycle.isCancelled())
+                    throw new Error('checkout cancelled locally after approval');
+                lifecycle.prepareHandoff(replay, request.url());
+                handoffStarted = replay.mode !== 'cse';
+                if (replay.mode === 'hosted_form') {
+                    // Same as the CDP path: the paused navigation resolves to the
+                    // synthetic page, and a re-post of this form is refused.
+                    const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
+                    // Inert on a navigation (never CORS-checked); one path for every fulfill.
+                    await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
+                    assertRequestLive();
+                    lastSubmitted = { url: request.url(), body, at: Date.now() };
+                    opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+                }
+                else if (replay.mode === 'cse') {
+                    // Same as the CDP path: the request continues from this browser
+                    // with the ciphertext swapped in and no header override; Playwright
+                    // recomputes the length itself.
+                    const postData = cseBody(body, replay);
+                    handoffStarted = true;
+                    await route.continue({ postData });
+                    assertRequestLive();
+                    opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+                }
+                else {
+                    // Playwright adds these itself when a cross-origin fulfill carries
+                    // none; written here anyway (replacing a stale value) so a
+                    // cross-origin answer is the same whichever adapter ran.
+                    const cors = corsDecision(request.url(), request.headers());
+                    await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                    assertRequestLive();
+                    opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
+                }
+                lifecycle.handedOff(replay);
             }
-            lifecycle.handedOff(replay);
-        }
-        catch (err) {
-            if (activeRequest?.attempt === attempt)
-                activeRequest = null;
-            lifecycle.failed(err, handoffStarted);
-            if (isTerminal(err))
-                terminal = err;
-            else if (isApprovalOutcome(err))
-                quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
-            await route.abort('aborted').catch(() => { });
-        }
-        finally {
-            if (activeRequest?.attempt === attempt)
-                activeRequest = null;
-            awaitingApproval = false;
-            lifecycle.end();
-            if (preparation)
-                preparationGate.retireUnboundClaim();
-        }
-    });
+            catch (err) {
+                if (activeRequest?.attempt === attempt)
+                    activeRequest = null;
+                lifecycle.failed(err, handoffStarted);
+                if (isTerminal(err))
+                    terminal = err;
+                else if (isApprovalOutcome(err))
+                    quietUntil = Date.now() + cooldownMs;
+                opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
+                await route.abort('aborted').catch(() => { });
+            }
+            finally {
+                if (activeRequest?.attempt === attempt)
+                    activeRequest = null;
+                awaitingApproval = false;
+                lifecycle.end();
+                if (preparation)
+                    preparationGate.retireUnboundClaim();
+            }
+        });
+        assertActive();
+    };
+    try {
+        await withinAttachmentDeadline(install, setupTimeoutMs, setupStop.signal);
+        if (setupStop.signal.aborted)
+            throw attachmentFailure(setupStop.signal.reason);
+        attachmentReady = true;
+    }
+    catch (error) {
+        const failure = attachmentFailure(error);
+        setupStop.abort(failure);
+        terminal = failure;
+        lifecycle.cancel();
+        opts.onEvent?.({ type: 'failed', detail: `checkout_attachment_${failure.reason}` });
+        // A route registration may finish after this rejection. Keep its handler
+        // inert for card traffic; removing it would reopen the failed checkout.
+        throw failure;
+    }
     return lifecycle;
 }

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { type CheckoutMode, type Recognizer } from './registry.js';
 import type { Substitutions } from './substitute.js';
+import { type PreparationProcessor } from './prepared-processor.js';
 export interface PausedRequest {
     url: string;
     method: string;
@@ -99,9 +100,9 @@ export interface HostedFormReplay {
 /** What authorize() resolves with; branch on `mode` (absent means token). */
 export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
 export interface PrepareCheckoutOptions {
-    psp: 'square';
+    psp: PreparationProcessor;
     /** The processor environment, independent of your Agentcard client's mode. */
-    environment: 'production' | 'sandbox';
+    environment: 'production' | 'sandbox' | 'shared';
     signal?: AbortSignal;
 }
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
@@ -120,8 +121,8 @@ export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
 export interface PreparedCheckout {
     readonly id: string;
     readonly status: 'ready';
-    readonly psp: 'square';
-    readonly environment: 'production' | 'sandbox';
+    readonly psp: PreparationProcessor;
+    readonly environment: 'production' | 'sandbox' | 'shared';
     readonly expiresAt: string;
     readonly cardId: string;
     readonly user: string;

package/dist/client.js

@@ -1,4 +1,5 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
+import { matchesPreparedRequest, validPreparationEnvironment } from './prepared-processor.js';
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
  * only recognizers in these modes, so a request this build cannot complete
@@ -314,7 +315,7 @@ export class VaultClient {
     async prepareCheckout(input) {
         input = { ...input };
         const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
-        if (input.psp !== 'square' || !['production', 'sandbox'].includes(input.environment))
+        if (!validPreparationEnvironment(input.psp, 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');
@@ -367,7 +368,7 @@ export class VaultClient {
                         || 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.psp !== input.psp || state.mode !== 'token' || state.environment !== input.environment
                         || state.checkout_key !== input.checkoutKey)
                         throw fail('ready_unconfirmed', id);
                     const prepared = Object.freeze({
@@ -416,13 +417,11 @@ export class VaultClient {
                 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)
+                || !matchesPreparedRequest(preparation.psp, preparation.environment, input.request.url, input.request.method ?? 'POST', input.request.body))
                 throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
         }
         if (input.signal?.aborted)
@@ -437,6 +436,8 @@ export class VaultClient {
         // clientSideEncrypted entry (an older registry, a hand-built one) still
         // refuses here, exactly as before.
         const mode = rec.mode ?? 'token';
+        if (preparation && (rec.psp !== preparation.psp || mode !== 'token'))
+            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
         if (rec.clientSideEncrypted && mode !== 'cse')
             throw new CardEncryptedError(rec.psp);
         if (!SUPPORTED_MODES.includes(mode))

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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, RazorpayProcessorError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export { CheckoutAttachmentError } from './attachment.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export type { Substitutions } from './substitute.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 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 { CheckoutAttachmentError } from './attachment.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/preparation.d.ts

@@ -15,7 +15,7 @@ export declare class PreparationGate {
     constructor(opts: AttachOptions, lifecycle: CheckoutLifecycle, readDocumentUrl: () => Promise<string>);
     private prepare;
     /** Called for every recognized card mutation, before any await or local retry guard. */
-    claim(requestUrl: string): PreparedCheckout | undefined;
+    claim(requestUrl: string, requestBody?: string | null): PreparedCheckout | undefined;
     assertDocument(): Promise<void>;
     private readDocument;
     isEngaged(): boolean;