@agent-cards/sdk 0.20.0 → 0.21.0

package/dist/cdp.js

@@ -1,10 +1,11 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
-import { AdyenTestPlatformRefusedError, ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, CheckoutCancelledError, MerchantTotalError, PaymentOutcomeUnknownError, PreparationRequiredError, ProcessorRefusedError, UnsupportedModeError, } from './client.js';
+import { AdyenTestPlatformRefusedError, AmountRequiredError, ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, CheckoutCancelledError, MerchantTotalError, PaymentOutcomeUnknownError, PreparationRequiredError, ProcessorRefusedError, UnsupportedCapabilityError, UnsupportedModeError, } from './client.js';
 import { PreparationGate } from './preparation.js';
 import { StripeCheckoutGate } from './stripe-checkout.js';
 import { MercadoCheckoutGate } from './mercado-checkout.js';
 import { MERCADO_CHECKOUT_PATTERN } from './mercado-checkout.generated.js';
 import { dispatchPreClaim, eventUrl } from './pre-claim.js';
+import { GMO_TOKEN_V1_PATTERNS, gmoRequestShop, isGmoTokenV1Request, recognizesGmo } from './gmo.js';
 import { CheckoutAttachmentError, attachmentDeadline, attachmentFailure, withinAttachmentDeadline } from './attachment.js';
 import { cseBody } from './cse-body.js';
 import { replayTemplatedUrl, reviewedMerchantProfileUrlPatterns } from './merchant-hosted.js';
@@ -12,6 +13,15 @@ import { MerchantHandoffWatch } from './merchant-handoff.js';
 import { MERCHANT_PAGE_WAIT_MS, MerchantTotalWatch } from './merchant-total-watch.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
+import { CaptureContexts, MicroformFrames, judgeMicroformFrameUrls, refusedRequestFailure } from './cybersource-flex.js';
+/**
+ * Fetch.failRequest's errorReason for a paused request the CDP adapter will not let through: the
+ * CDP form of refusedRequestFailure ('Failed' for a CyberSource Flex request, so the Microform field
+ * reports it to the page; 'Aborted' for every other request, as before).
+ */
+function cdpFailure(url) {
+    return refusedRequestFailure(url) === 'failed' ? 'Failed' : 'Aborted';
+}
 // Every URL that leaves this module through onEvent is redacted to origin +
 // path first. A paused PaymentIntent confirm can carry the client secret in
 // its query string (Stripe.js puts it in the body; hand-rolled runtimes and
@@ -144,7 +154,8 @@ function isApprovalOutcome(err) {
  *
  * Terminal means "will answer identically next time no matter who does what":
  * a misconfiguration or an unsupported PSP. Nothing a person does changes
- * those, so asking again is pure waste.
+ * those, so asking again is pure waste. A GMO request with no `amount`
+ * (AmountRequiredError) is one: the attachment's options do not change.
  *
  * Other errors may be retryable unless the lifecycle holds the attachment
  * for merchant reconciliation, as it does after a processor refusal.
@@ -161,7 +172,8 @@ function isTerminal(err) {
     // Refused at create for Adyen's test platform: the page's next request is refused the same way.
     if (err instanceof AdyenTestPlatformRefusedError)
         return err.stage === 'create';
-    return err instanceof CardEncryptedError || err instanceof UnsupportedModeError || err instanceof PreparationRequiredError;
+    return err instanceof CardEncryptedError || err instanceof UnsupportedModeError || err instanceof PreparationRequiredError
+        || err instanceof AmountRequiredError || err instanceof UnsupportedCapabilityError;
 }
 /**
  * cseBody, retiring a merchant-hosted approval it refuses. The refusal (a live body
@@ -734,12 +746,26 @@ function bodyShape(body) {
     }
     return { shape: `raw:${body}`, namesAmount: false };
 }
-/** The identity of a request from its parts; see CheckoutRequestIdentity. */
-function requestIdentity(opts, url, method, body, documentUrl, pageAmount) {
-    const shaped = bodyShape(body);
-    return { url, method, documentUrl, pageAmount, body: shaped.shape,
+/**
+ * The identity of a request from its parts; see CheckoutRequestIdentity. A CyberSource Flex
+ * body is a fresh JWE every time the card field seals, and it names no amount, so its shape is
+ * the one the Flex gate read from the field iframe (cybersource-flex.ts: microform type, fields,
+ * the capture context's key id and the context itself), never the ciphertext.
+ */
+function requestIdentity(opts, url, method, body, documentUrl, pageAmount, flexShape) {
+    const shaped = flexShape !== undefined ? { shape: flexShape, namesAmount: false } : bodyShape(body);
+    // A GMO token is minted for the one shop its request names, and the body's shape leaves that value
+    // out, so the shop joins the identity: a retry that names another shop needs its own approval.
+    const shop = gmoRequestShop(url, body);
+    return { url, method, documentUrl, pageAmount, body: shop === undefined ? shaped.shape : `${shaped.shape};gmo_shop:${JSON.stringify(shop)}`,
         amountEvidence: opts.amount != null || pageAmount !== undefined || shaped.namesAmount };
 }
+/** A CDP frame or request URL with its fragment, which CDP reports apart (urlFragment). */
+function withFragment(value) {
+    if (typeof value?.url !== 'string')
+        return undefined;
+    return value.url + (typeof value.urlFragment === 'string' ? value.urlFragment : '');
+}
 /**
  * May this request be answered from the approval the other one raised?
  *
@@ -1115,6 +1141,39 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     const lifecycle = new CheckoutLifecycle(opts);
     const stripeCheckout = new StripeCheckoutGate(opts);
     const mercadoCheckout = new MercadoCheckoutGate();
+    // CyberSource Flex card field iframes and their capture contexts, recorded from the CDP
+    // events that report a frame's committed document with its fragment (cybersource-flex.ts).
+    const microforms = new MicroformFrames();
+    /**
+     * One bounded read of a session's frame tree, for a Flex request whose frame is not on record:
+     * records every frame it finds and resolves to the committed URL of `frameId`, or undefined
+     * when that frame is not in the tree.
+     */
+    const rereadMicroforms = async (sessionId, frameId) => {
+        if (!sessionId)
+            return undefined;
+        let timer;
+        try {
+            const tree = await Promise.race([cdp.send('Page.getFrameTree', {}, sessionId),
+                new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error('frame_tree_unavailable')), 1_000); })]);
+            let issuing;
+            const walk = (node, depth) => {
+                if (!node?.frame || depth > 16)
+                    return;
+                const url = withFragment(node.frame);
+                microforms.observe(node.frame.id, url);
+                if (node.frame.id === frameId)
+                    issuing = url;
+                for (const child of Array.isArray(node.childFrames) ? node.childFrames : [])
+                    walk(child, depth + 1);
+            };
+            walk(tree?.frameTree, 0);
+            return issuing;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
     let preparationFrameId;
     const readDocumentUrl = async () => {
         const tree = await cdp.send('Page.getFrameTree', {}, pageSessionId);
@@ -1293,8 +1352,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     // that the vault names no profile for.
     const merchantPatterns = [...reviewedMerchantProfileUrlPatterns(),
         ...(typeof opts.vault?.merchantProfileUrlPatterns === 'function' ? opts.vault.merchantProfileUrlPatterns() : [])];
+    // GMO token v1's JSONP GET is armed only when the synced registry recognizes
+    // GMO (an org the API served the dark entry to), so the gate can refuse it;
+    // for every other org it is never intercepted, as before (see gmo.ts).
     const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns,
-            ...(stripeCheckout.isEnabled() ? ['https://api.stripe.com/*'] : []), MERCADO_CHECKOUT_PATTERN, ...merchantPatterns])];
+            ...(stripeCheckout.isEnabled() ? ['https://api.stripe.com/*'] : []), MERCADO_CHECKOUT_PATTERN, ...merchantPatterns,
+            ...(recognizesGmo(opts.vault) ? GMO_TOKEN_V1_PATTERNS : [])])];
     const arm = async (sessionId, resume = false, worker = false) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
@@ -1421,6 +1484,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             // Its Fetch events, children and commands remain permanently ignored.
             if (sessionDetached(sessionId) && !matchesActive)
                 return;
+            // A frame's document request carries its URL fragment (for an out-of-process card field
+            // iframe, on the PARENT session before the child target exists), but a navigation can be
+            // stopped before it commits: it only starts the capture context's check. The frame is
+            // recorded once its document commits (Page.frameNavigated below).
+            if (params.type === 'Document')
+                microforms.warm(withFragment(params.request));
             const key = requestKey(sessionId, params.requestId);
             const record = { sessionId, networkId: params.requestId, request: params.request };
             if (sessionDetached(sessionId) || retiredSources.has(key) || hasRetiredSummary(owner, params.requestId))
@@ -1446,6 +1515,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if (sessionDetached(sessionId))
             return;
+        if (method === 'Page.frameNavigated') {
+            // A child frame committed a document: an out-of-process iframe reports its own on its
+            // session, an in-process one on its parent's (the page's top frame is handled above).
+            microforms.observe(params.frame?.id, withFragment(params.frame));
+            return;
+        }
         if (method === 'Network.loadingFinished') {
             const key = requestKey(sessionId, params.requestId);
             requestSources.delete(key);
@@ -1507,6 +1582,10 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         }
         if (method === 'Target.detachedFromTarget' || method === 'Inspector.detached' || method === 'Page.frameDetached') {
+            // A frame that moves to its own process ('swap') keeps its document; any other detach ends it.
+            if (!(method === 'Page.frameDetached' && params.reason === 'swap')) {
+                microforms.forget(method === 'Page.frameDetached' ? params.frameId : method === 'Target.detachedFromTarget' ? params.targetId : undefined);
+            }
             if (activeRequest && (method === 'Target.detachedFromTarget' ? activeRequest.sessionId === params.sessionId
                 : method === 'Inspector.detached' ? activeRequest.sessionId === sessionId
                     : activeRequest.sessionId === sessionId && activeRequest.frameId === params.frameId))
@@ -1579,6 +1658,10 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     workerOwners.set(child, owner);
                     ownersWithWorkers.add(owner);
                 }
+                // An iframe target's id is its frame id, and its url keeps the fragment: the one source
+                // for a card field iframe that rendered before this attachment (empty on a fresh one).
+                if (params.targetInfo.type === 'iframe')
+                    microforms.observe(params.targetInfo.targetId, params.targetInfo.url);
                 await arm(child, true, params.targetInfo.type === 'worker');
             }
             catch (error) {
@@ -1595,6 +1678,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         const { requestId, request, resourceType, networkId, frameId } = params;
         // When this request paused: the merchant's total is read as of this moment.
         const pausedAt = Date.now();
+        // A paused document request has not committed either: it only starts the context's check.
+        if (resourceType === 'Document')
+            microforms.warm(withFragment(request));
         // One pre-claim gate registry decides and performs the mechanics through
         // these effects; the state accessors read the same closure variables the
         // inline gates did. It resolves synchronously for an ordinary card request,
@@ -1611,7 +1697,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     responseHeaders: Object.entries(withCorsHeaders(response.headers, corsHeadersFor(request.url, request.headers)))
                         .map(([name, value]) => ({ name, value })),
                     body: Buffer.from(response.body).toString('base64') }, sessionId),
-                abort: () => cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { }),
+                abort: () => cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(request.url) }, sessionId).catch(() => { }),
             },
             attachmentReady: () => attachmentReady,
             interceptionAborted: () => setupStop.signal.aborted,
@@ -1623,14 +1709,18 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             awaitingApproval: () => awaitingApproval,
             stripeStep: null,
             merchantHandoff: { retried: (profile) => merchantHandoff.retried(profile, (judge) => awaitRetryReport(sessionId, networkId, judge)) },
+            // The card field iframe that sent a Flex request is the paused request's own frame.
+            cybersourceFlex: { judge: (flexRequest) => microforms.judge(flexRequest, frameId, () => rereadMicroforms(sessionId, frameId)) },
         });
         const preClaim = preClaimResult instanceof Promise ? await preClaimResult : preClaimResult;
         if (preClaim.kind !== 'pause')
             return;
         const stripeStep = preClaim.stripeStep;
+        // The capture context and fields a CyberSource Flex create carries, and its retry shape.
+        const flexPause = preClaim.cybersourceFlex;
         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(() => { });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(request.url) }, sessionId).catch(() => { });
             return;
         }
         let preparation;
@@ -1639,7 +1729,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
-            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(request.url) }, sessionId).catch(() => { });
             return;
         }
         // The page asking again for the purchase an outstanding approval is for:
@@ -1650,7 +1740,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         if (awaitingApproval && activeRequest?.attempt.lost && !terminal && !setupStop.signal.aborted && !lifecycle.isCancelled()
             && typeof networkId === 'string' && networkId) {
             const retryBody = pausedBody(request);
-            const retry = retryBody === null ? null : requestIdentity(opts, request.url, request.method, retryBody, documentKey(await documentUrlOf(readDocumentUrl, lifecycle.abort.signal)), await pageAmountOf(opts));
+            const retry = retryBody === null ? null : requestIdentity(opts, request.url, request.method, retryBody, documentKey(await documentUrlOf(readDocumentUrl, lifecycle.abort.signal)), await pageAmountOf(opts), flexPause?.shape);
             if (retry && activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)) {
                 if (preparation)
                     preparationGate.retireUnboundClaim();
@@ -1708,7 +1798,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
             if (preparation)
                 preparationGate.retireUnboundClaim();
-            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(request.url) }, sessionId).catch(() => { });
             if (repeatedAuthorizationId)
                 void opts.vault.reportDuplicateGuard?.(repeatedAuthorizationId);
             return;
@@ -1742,7 +1832,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // about the page's configuration, so the next request is judged
                 // afresh (no latch, no cooldown).
                 opts.onEvent?.({ type: 'failed', detail: BODY_UNREADABLE_REASON });
-                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+                await cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(request.url) }, sessionId).catch(() => { });
                 return;
             }
             // The body is needed to tell a re-post of the form the cardholder
@@ -1750,7 +1840,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             // and before any API call: no second prompt, no round trip.
             if (isRepeatOfSubmitted(lastSubmitted, request.url, body, repeatQuietMs)) {
                 opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
-                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+                await cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(request.url) }, sessionId).catch(() => { });
                 if (lastSubmitted)
                     void opts.vault.reportDuplicateGuard?.(lastSubmitted.authorizationId);
                 return;
@@ -1765,7 +1855,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             }
             attempt.bind({ requestId, sessionId, request });
             activeRequest = { attempt, requestId, networkId, sessionId, frameId, request,
-                identity: requestIdentity(opts, request.url, request.method, body, undefined, undefined) };
+                identity: requestIdentity(opts, request.url, request.method, body, undefined, undefined, flexPause?.shape) };
             await awaitRequestSource(activeRequest);
             if (preparation)
                 await preparationGate.assertDocument();
@@ -1821,7 +1911,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 } },
                 request: stripeStep?.phase === 'final' ? stripeStep.request : { url: request.url, method: request.method, headers: request.headers, body,
                     ...(mercadoCheckout.requiresDocument(request.url, request.method)
-                        ? { mercado_checkout: mercadoCheckout.claimToken(request.url, request.method, await readDocumentUrl()) } : {}) },
+                        ? { mercado_checkout: mercadoCheckout.claimToken(request.url, request.method, await readDocumentUrl()) } : {}),
+                    ...(flexPause ? flexPause.sidecar : {}) },
             });
             attempt.assertLive();
             approvedId = replay.authorizationId;
@@ -1956,7 +2047,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     quietUntil = Date.now() + cooldownMs;
                 opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
             }
-            await cdp.send('Fetch.failRequest', { requestId: dead.requestId, errorReason: 'Aborted' }, dead.sessionId).catch(() => { });
+            await cdp.send('Fetch.failRequest', { requestId: dead.requestId, errorReason: cdpFailure(request.url) }, dead.sessionId).catch(() => { });
             settlePause();
         }
         finally {
@@ -2041,6 +2132,18 @@ export async function attachToPlaywright(page, opts) {
     const lifecycle = new CheckoutLifecycle(opts);
     const stripeCheckout = new StripeCheckoutGate(opts);
     const mercadoCheckout = new MercadoCheckoutGate();
+    // CyberSource Flex capture contexts, verified once each (cybersource-flex.ts). Playwright
+    // keeps a frame's fragment in frame.url(), so the field iframes are read when a request pauses.
+    const microformContexts = new CaptureContexts();
+    const frameUrlOf = (frame) => {
+        try {
+            const url = frame?.url?.();
+            return typeof url === 'string' ? url : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
     const readDocumentUrl = async () => {
         if (page.isClosed?.() || typeof page.url !== 'function')
             throw new Error('merchant_document_unavailable');
@@ -2162,6 +2265,9 @@ export async function attachToPlaywright(page, opts) {
     page.on?.('crash', () => { if (!attachmentReady)
         setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); handoffAnswer?.closed(); });
     page.on?.('framenavigated', (frame) => {
+        // A CyberSource Flex card field iframe loaded: start its capture-context check now, so its
+        // card request pauses without waiting on it (cybersource-flex.ts).
+        microformContexts.warm(frameUrlOf(frame));
         if (frame === page.mainFrame?.()) {
             if (documentRequest) {
                 documentRequest = null;
@@ -2204,7 +2310,9 @@ export async function attachToPlaywright(page, opts) {
         }
         await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()) || stripeCheckout.matches(url.toString()) || mercadoCheckout.matches(url.toString())
             // An armed merchant profile's endpoint or a sibling of it (merchant-hosted.ts), as attachToCdp arms it.
-            || (typeof opts.vault.merchantProfileOf === 'function' && opts.vault.merchantProfileOf(url.toString()) !== null), async (route) => {
+            || (typeof opts.vault.merchantProfileOf === 'function' && opts.vault.merchantProfileOf(url.toString()) !== null)
+            // GMO token v1's JSONP GET, routed only for an org the API served GMO to (see attachToCdp).
+            || (isGmoTokenV1Request(url.toString()) && recognizesGmo(opts.vault)), async (route) => {
             const request = route.request();
             // When this request paused, and the page it came from: the merchant's total is read as of now.
             const pausedAt = Date.now();
@@ -2226,7 +2334,7 @@ export async function attachToPlaywright(page, opts) {
                     continueRequest: (postData) => postData !== undefined ? route.continue({ postData }) : route.fallback(),
                     answer: (response) => route.fulfill({ ...response,
                         headers: withCorsHeaders(response.headers, corsHeadersFor(request.url(), request.headers())) }),
-                    abort: () => route.abort('aborted'),
+                    abort: () => route.abort(refusedRequestFailure(request.url())),
                 },
                 attachmentReady: () => attachmentReady,
                 interceptionAborted: () => setupStop.signal.aborted,
@@ -2239,14 +2347,34 @@ export async function attachToPlaywright(page, opts) {
                 stripeStep: null,
                 // This route arrives after every answer the page read before sending it; only an unfollowed 3xx is left to settle.
                 merchantHandoff: { retried: (profile) => merchantHandoff.retried(profile, () => { handoffAnswer?.settle(); return false; }) },
+                // The card field iframe that sent a Flex request, and every frame beside it on the page.
+                cybersourceFlex: { judge: (flexRequest) => {
+                        let issuing;
+                        try {
+                            issuing = request.frame?.();
+                        }
+                        catch {
+                            issuing = undefined;
+                        }
+                        let frames = [];
+                        try {
+                            frames = page.frames?.() ?? [];
+                        }
+                        catch {
+                            frames = [];
+                        }
+                        return judgeMicroformFrameUrls(flexRequest, frameUrlOf(issuing), frames.map(frameUrlOf), microformContexts);
+                    } },
             });
             const preClaim = preClaimResult instanceof Promise ? await preClaimResult : preClaimResult;
             if (preClaim.kind !== 'pause')
                 return;
             const stripeStep = preClaim.stripeStep;
+            // The capture context and fields a CyberSource Flex create carries, and its retry shape.
+            const flexPause = preClaim.cybersourceFlex;
             if (!attachmentReady || setupStop.signal.aborted) {
                 opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
-                return route.abort('aborted');
+                return route.abort(refusedRequestFailure(request.url()));
             }
             let preparation;
             try {
@@ -2254,13 +2382,13 @@ export async function attachToPlaywright(page, opts) {
             }
             catch (error) {
                 opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
-                return route.abort('aborted');
+                return route.abort(refusedRequestFailure(request.url()));
             }
             // The page asking again for the purchase an outstanding approval is
             // for, after its own request timed out: bind it to that approval (see
             // merchantAttempt and the same check in attachToCdp).
             if (awaitingApproval && activeRequest?.attempt.lost && !terminal && !setupStop.signal.aborted && !lifecycle.isCancelled()) {
-                const retry = requestIdentity(opts, request.url(), request.method(), request.postData() ?? '', documentKey(await documentUrlOf(readDocumentUrl, lifecycle.abort.signal)), await pageAmountOf(opts));
+                const retry = requestIdentity(opts, request.url(), request.method(), request.postData() ?? '', documentKey(await documentUrlOf(readDocumentUrl, lifecycle.abort.signal)), await pageAmountOf(opts), flexPause?.shape);
                 if (activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)) {
                     if (preparation)
                         preparationGate.retireUnboundClaim();
@@ -2297,9 +2425,10 @@ export async function attachToPlaywright(page, opts) {
             }
             // 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.
+            // abort in this adapter is 'aborted' (ERR_ABORTED), and a CyberSource
+            // Flex request's is 'failed' (refusedRequestFailure), the same codes the
+            // CDP adapter's Fetch.failRequest uses, so a refused request resolves
+            // identically whichever adapter is attached.
             if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
                 let repeatedAuthorizationId = null;
                 if (lastSubmitted) {
@@ -2316,7 +2445,7 @@ export async function attachToPlaywright(page, opts) {
                 opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
                 if (preparation)
                     preparationGate.retireUnboundClaim();
-                const refused = await route.abort('aborted');
+                const refused = await route.abort(refusedRequestFailure(request.url()));
                 if (repeatedAuthorizationId)
                     void opts.vault.reportDuplicateGuard?.(repeatedAuthorizationId);
                 return refused;
@@ -2362,7 +2491,7 @@ export async function attachToPlaywright(page, opts) {
                 const body = request.postData() ?? '';
                 if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
                     opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
-                    const refused = await route.abort('aborted');
+                    const refused = await route.abort(refusedRequestFailure(request.url()));
                     if (lastSubmitted)
                         void opts.vault.reportDuplicateGuard?.(lastSubmitted.authorizationId);
                     return refused;
@@ -2373,7 +2502,7 @@ export async function attachToPlaywright(page, opts) {
                 const payToInterceptMs = readPayToInterceptMs(opts.payClickedAt, approvalStartedAt);
                 attempt.bind({ route, request, frames });
                 activeRequest = { request, frames, attempt,
-                    identity: requestIdentity(opts, request.url(), request.method(), body, undefined, undefined) };
+                    identity: requestIdentity(opts, request.url(), request.method(), body, undefined, undefined, flexPause?.shape) };
                 if (preparation)
                     await preparationGate.assertDocument();
                 // One bounded read serves the merchant origin and the retry identity; see attachToCdp.
@@ -2415,7 +2544,8 @@ export async function attachToPlaywright(page, opts) {
                     } },
                     request: stripeStep?.phase === 'final' ? stripeStep.request : { url: request.url(), method: request.method(), headers: request.headers(), body,
                         ...(mercadoCheckout.requiresDocument(request.url(), request.method())
-                            ? { mercado_checkout: mercadoCheckout.claimToken(request.url(), request.method(), await readDocumentUrl()) } : {}) },
+                            ? { mercado_checkout: mercadoCheckout.claimToken(request.url(), request.method(), await readDocumentUrl()) } : {}),
+                        ...(flexPause ? flexPause.sidecar : {}) },
                 });
                 assertRequestLive();
                 approvedId = replay.authorizationId;
@@ -2507,7 +2637,7 @@ export async function attachToPlaywright(page, opts) {
                         quietUntil = Date.now() + cooldownMs;
                     opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
                 }
-                await dead.abort('aborted').catch(() => { });
+                await dead.abort(refusedRequestFailure(request.url())).catch(() => { });
             }
             finally {
                 if (activeRequest?.attempt === attempt)

package/dist/client.d.ts

@@ -7,6 +7,7 @@ import { VoiceModule, type VoiceOptions } from './voice.js';
 import { BuyModule } from './buy.js';
 import { RequestRegistry } from './requests.js';
 import type { ApiTransport } from './api-module.js';
+import { type MicroformSidecar } from './cybersource-flex.js';
 export interface PausedRequest {
     url: string;
     method: string;
@@ -14,6 +15,14 @@ export interface PausedRequest {
     body: string;
     /** Captured native Checkout Pro initialization, validated before use. */
     mercado_checkout?: unknown;
+    /**
+     * CyberSource Flex only: the capture context the card field iframe was loaded with, byte for
+     * byte from its URL fragment. The cardholder's device seals the real card under it, so the API
+     * verifies it before anything exists. The adapters read it; refused on any other processor.
+     */
+    capture_context?: string;
+    /** CyberSource Flex only: the Microform fields that loaded and the one that sent this request. */
+    microform?: MicroformSidecar;
 }
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
@@ -34,12 +43,22 @@ export declare const SUPPORTED_REGISTRY_FEATURES: readonly string[];
 /**
  * Dark-launch capabilities this build can finish. Sent on syncRegistry as
  * ?capabilities= so the API also serves the recognizers gated behind one of
- * these. `fiserv_card_capture`: Fiserv Commerce Hub's Secure Data Capture card
+ * these, and only to an org Agentcard enabled for the processor.
+ * `fiserv_card_capture`: Fiserv Commerce Hub's Secure Data Capture card
  * capture, which this build pauses and pays only through a prepared checkout
  * (pre-claim.ts, fiserv.ts). The API serves Fiserv's recognizer only to a build
  * that lists it and only for a company Agentcard turned Fiserv on for, so an older
  * SDK never pauses a capture it cannot finish and no SDK pauses one for a company
  * Fiserv is off for; the API also refuses a Fiserv payment for every such company.
+ * `gmo_shared_pk`: GMO token v2's getToken on the shared-key path, which this
+ * build judges before it pauses (gmo.ts) and pays only for the amount the
+ * agent passes. A gated recognizer never sits in BUILTIN_REGISTRY, so it is
+ * paused only after a sync.
+ * `capture_context`: CyberSource Flex Microform, whose create carries the capture
+ * context this build reads from the card field iframe (cybersource-flex.ts); the API
+ * serves Flex's recognizer the same way, only for a company Agentcard turned it on for.
+ * A gated recognizer is never in BUILTIN_REGISTRY, so a build reaches it only through a
+ * sync that declares its capability.
  */
 export declare const SUPPORTED_CAPABILITIES: readonly string[];
 /**
@@ -273,6 +292,9 @@ export interface AuthorizeInput extends ExecutionMetadata {
      * smallest unit is refused with nothing charged (an AmountMismatchError;
      * `stage` says which check). Agentcard derives the display string; you
      * never send one. Both or neither: one without the other is refused.
+     * Required when the processor's request names no amount at all (GMO): then
+     * this pair is what the cardholder approves, and a request without it
+     * throws AmountRequiredError before anything is created.
      */
     amount?: number | string;
     currency?: string;
@@ -337,6 +359,51 @@ export declare class UnsupportedModeError extends Error {
     mode: string;
     constructor(mode: string);
 }
+/**
+ * The recognizer is gated behind a dark-launch capability this SDK build does not
+ * declare (SUPPORTED_CAPABILITIES), so it cannot send what that processor's create
+ * needs. Thrown locally before any create or prompt, and terminal. A registry the
+ * API served never holds such an entry (it serves a gated one only to a build that
+ * declares it); a hand-built one can.
+ */
+export declare class UnsupportedCapabilityError extends Error {
+    capability: string;
+    constructor(capability: string);
+}
+/**
+ * placeholderCard() found no stored card to describe (`card_not_found`), the stored card's
+ * network has no documented placeholder number (`brand_unsupported`), or the stored card
+ * carries no usable expiry (`expiry_unknown`). Nothing was created and nothing was charged.
+ */
+export declare class PlaceholderCardError extends Error {
+    reason: 'card_not_found' | 'brand_unsupported' | 'expiry_unknown';
+    constructor(reason: 'card_not_found' | 'brand_unsupported' | 'expiry_unknown');
+}
+/**
+ * What the agent types into a checkout so the page's own card facts match the stored card
+ * that pays: a documented test number of the same network, a placeholder security code of that
+ * network's length, and the stored card's real expiry. CyberSource Flex merchants post the brand
+ * the card field detected from the typed number and the expiry typed into their own fields beside
+ * the token (Sonos, Amtrak), so a mismatch there fails the merchant's payment.
+ */
+export interface PlaceholderCard {
+    /**
+     * The stored card these facts describe (GET /api/v2/vault_cards). Pass it as `cardId` to
+     * attachToCdp, attachToPlaywright or authorize(): the approval page then preselects this card.
+     * Without it the page preselects its own choice, which can be another card.
+     */
+    readonly cardId: string;
+    /** Its network, as GET /api/v2/vault_cards names it. */
+    readonly brand: string;
+    /** A documented test card number of that network. Never a real card: the device supplies the real one. */
+    readonly number: string;
+    /** A placeholder security code of the length that network uses. */
+    readonly securityCode: string;
+    /** The stored card's expiry month, two digits ("04"). */
+    readonly expiryMonth: string;
+    /** The stored card's expiry year, four digits ("2031"). */
+    readonly expiryYear: string;
+}
 /**
  * The recognizer says this processor is preparation-required, and no preparation
  * was passed. Its card may be sent only after the cardholder approved a
@@ -349,6 +416,19 @@ export declare class PreparationRequiredError extends Error {
     psp: string;
     constructor(psp: string);
 }
+/**
+ * The paused request names no amount and none was passed. A GMO card token
+ * request carries no amount (the merchant's server charges the token later),
+ * so the `amount` and `currency` you pass are what the cardholder approves.
+ * Thrown locally before any create or prompt, and terminal: the same request
+ * without an amount fails the same way. The API answers 400 amount_required
+ * for the same case. A page total (`pageAmount`) does not count.
+ */
+export declare class AmountRequiredError extends Error {
+    psp: string;
+    readonly code: "amount_required";
+    constructor(psp: string);
+}
 export declare class ApprovalTimeoutError extends Error {
     constructor(ms: number);
 }
@@ -812,6 +892,22 @@ export declare class VaultClient {
      * these patterns pause.
      */
     cardUrlPatterns(): string[];
+    /**
+     * What to type into a checkout so the page's own card facts match the stored card that
+     * pays (see PlaceholderCard): read from GET /api/v2/vault_cards, which lists each stored card's
+     * network and expiry. `cardId` names the stored card; omitted, the user's most recently added
+     * card. Pin the returned `cardId` on the attachment or authorize(), so the approval page
+     * preselects that card: without a pin the page preselects its own choice (its recommended
+     * card, or the first card the cardholder's device can open), which can be another card. After
+     * prepare(), pass the prepared checkout's `cardId`, the card the cardholder already approved.
+     * The facts hold only while the cardholder pays with that card. Throws PlaceholderCardError
+     * when there is no such card, its network has no placeholder, or it carries no expiry.
+     */
+    placeholderCard(input: {
+        user: string;
+        cardId?: string;
+        signal?: AbortSignal;
+    }): Promise<PlaceholderCard>;
     /** Wait for real device approval before the caller starts native tokenization. */
     prepareCheckout(input: PrepareCheckoutInput): Promise<PreparedCheckout>;
     /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */