@agent-cards/sdk 0.23.9 → 0.23.11

package/dist/cdp.js

@@ -1,6 +1,7 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
 import { AdyenTestPlatformRefusedError, AmountRequiredError, ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, CheckoutCancelledError, CheckoutPreparationError, MerchantTotalError, PaymentOutcomeUnknownError, PreparationRequiredError, ProcessorRefusedError, UnsupportedCapabilityError, UnsupportedModeError, } from './client.js';
 import { PreparationGate } from './preparation.js';
+import { preparedApprovalAnswersRetry } from './prepared-processor.js';
 import { StripeCheckoutGate } from './stripe-checkout.js';
 import { MercadoCheckoutGate } from './mercado-checkout.js';
 import { MERCADO_CHECKOUT_PATTERN } from './mercado-checkout.generated.js';
@@ -29,6 +30,7 @@ import { CARD_ENDPOINT_REFUSED_STEP_ANSWER, CARD_ENDPOINT_WITHHELD_ANSWER, CardE
 import { CardEndpointFactsWatch } from './card-endpoint-facts.js';
 import { PAYRAILS_GUARD_PATTERNS, PAYRAILS_INIT_BODY_LIMIT, PayrailsSessionCapture, isPayrailsHost, payrailsInitCandidate, recognizesPayrails, } from './payrails.js';
 import { cardEndpointStoppedPage, refusedNavigationOutcome } from './card-endpoint-page.js';
+import { WorldlineMyCheckoutProducts } from './worldline-mycheckout.js';
 /**
  * How an adapter fails a paused request it will not let through: as a network error for a
  * CyberSource Flex request (refusedRequestFailure, so the Microform field reports it to the page)
@@ -328,15 +330,15 @@ function cseAuthorizedDetail(replay, url, shijiCvv = null) {
  * getCvvId companion right before the continue (shiji-sts.ts). It is written
  * only into `approved`, the request the approval was created from, byte for
  * byte, so the accessToken and keySequence are the ones the API reviewed, and
- * the cvv is bound to the reviewed getCvvId keys the approval served
- * (`shijiCvvKeySequences`): no keys, no continuation. Every other processor
- * takes cseContinuationBody (cse-body.ts cseBody), and `shijiCvv` and
- * `shijiCvvKeySequences` are null.
+ * the cvv is bound to the SHA-256 of the reviewed getCvvId keys the approval
+ * served (`shijiCvvKeySequenceSha256`): no keys, no continuation. Every other
+ * processor takes cseContinuationBody (cse-body.ts cseBody), and `shijiCvv` and
+ * `shijiCvvKeySequenceSha256` are null.
  */
 function cseContinuation(opts, url, body, replay, approved, preparation) {
     const shiji = shijiStsTokenContinuation(url, body, replay.substitutions, approved, replay.kind === 'merchant_hosted' || replay.kind === 'verifone' ? undefined : replay.shijiStsCompanion);
-    return shiji ? { body: shiji.body, shijiCvv: shiji.cvv, shijiCvvKeySequences: shiji.cvvKeySequences }
-        : { body: cseContinuationBody(opts, body, replay, url, preparation), shijiCvv: null, shijiCvvKeySequences: null };
+    return shiji ? { body: shiji.body, shijiCvv: shiji.cvv, shijiCvvKeySequenceSha256: shiji.cvvKeySequenceSha256 }
+        : { body: cseContinuationBody(opts, body, replay, url, preparation), shijiCvv: null, shijiCvvKeySequenceSha256: null };
 }
 /**
  * The opaque page id a Shiji STS companion is bound to: the CDP session and
@@ -1287,7 +1289,10 @@ function sameCheckoutRequest(first, retry) {
  * answer is a token or ciphertext, and any request for the same purchase can
  * carry it. No for a hosted form (a navigation: there is no request to
  * answer once the page has moved on), a prepared checkout (single use, bound
- * to one native request by design), a native Stripe Checkout step, a
+ * to one native request by design) other than a Bambora token create, whose
+ * card frame gives up 5 seconds after sending it and whose page asks again
+ * with the same body (preparedApprovalAnswersRetry), from that same card frame
+ * only (sameFrame), a native Stripe Checkout step, a
  * Mercado Pago request whose claim is bound to one document read, a Juspay
  * /txns (the device pays that request's own order; a page that clicks Pay
  * again creates a new order, which the earlier answer would send to the
@@ -1303,12 +1308,23 @@ function sameCheckoutRequest(first, retry) {
  * getTokenId while the cardholder decides. Unknown modes (a duck-typed vault
  * without checkoutModeOf) are taken as `token`.
  */
-function survivesAbandonment(opts, url, method, navigation, bound) {
+function survivesAbandonment(opts, url, method, navigation, bound, preparation) {
     if (navigation || bound || isShijiStsHost(url))
         return false;
+    if (preparation && !preparedApprovalAnswersRetry(preparation.psp))
+        return false;
     const mode = typeof opts.vault?.checkoutModeOf === 'function' ? opts.vault.checkoutModeOf(url, method) : 'token';
     return mode === 'token' || mode === 'cse';
 }
+/**
+ * Whether `frameId` on `sessionId` is `owner`, the frame a prepared request came from. A prepared
+ * approval that outlives its request (survivesAbandonment) belongs to that card frame for as long as
+ * it lasts: only that frame's retry is answered from it, and the frame's removal stops the attachment
+ * even after the page gave the request up. A frame with no id is nobody's.
+ */
+function sameFrame(owner, sessionId, frameId) {
+    return !!owner && typeof owner.frameId === 'string' && owner.frameId !== '' && owner.frameId === frameId && owner.sessionId === sessionId;
+}
 /**
  * One card request's attempt at an approval, and the browser request that
  * currently carries it. Separate from explicit cancellation: the client can
@@ -1973,6 +1989,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let lastSubmitted = null;
     // The approved Datatrans answers, per frameId: the repeat rule (datatrans.ts).
     const datatransRepeats = new DatatransRepeats();
+    // The card product each Worldline MyCheckout hosted checkout chose (worldline-mycheckout.ts).
+    const worldlineProducts = new WorldlineMyCheckoutProducts();
     // The Shiji STS getCvvId companion of the getTokenId this attachment last continued (shiji-sts.ts).
     // A cancelled attachment drops it, and the device's CVV ciphertext with it, at once: no getCvvId
     // can use it any more (pre-claim.ts refuses every one once the lifecycle is aborted). The page,
@@ -2284,9 +2302,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             if (!(method === 'Page.frameDetached' && params.reason === 'swap')) {
                 microforms.forget(method === 'Page.frameDetached' ? params.frameId : method === 'Target.detachedFromTarget' ? params.targetId : undefined);
             }
+            // A prepared request's card frame ends its approval even once the page gave the request up and its
+            // live frame id is gone; a target's detach is still read from the session, which a loss keeps.
             if (activeRequest && (method === 'Target.detachedFromTarget' ? activeRequest.sessionId === params.sessionId
                 : method === 'Inspector.detached' ? activeRequest.sessionId === sessionId
-                    : activeRequest.sessionId === sessionId && activeRequest.frameId === params.frameId))
+                    : (activeRequest.sessionId === sessionId && activeRequest.frameId === params.frameId)
+                        || sameFrame(activeRequest.preparedFrame, sessionId, params.frameId)))
                 activeRequest.attempt.stop();
             // The frame or target the bound getTokenId came from is gone, so its getCvvId cannot follow:
             // drop the companion binding and the CVV ciphertext it holds (a binding elsewhere stays).
@@ -2437,6 +2458,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             frame: typeof frameId === 'string' && frameId ? frameId : undefined,
             payrails,
             shijiSts: { companions: shijiCompanions, page: () => cdpShijiPage(sessionId, frameId) },
+            worldlineMyCheckout: worldlineProducts,
         });
         const preClaim = preClaimResult instanceof Promise ? await preClaimResult : preClaimResult;
         if (preClaim.kind !== 'pause')
@@ -2477,8 +2499,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         }
         let preparation;
+        // The page asking again while a prepared approval outlives its first request (survivesAbandonment):
+        // the preparation is already bound to that approval, so the request is judged as its retry below
+        // and never claimed again.
+        const preparedRetry = awaitingApproval && activeRequest?.attempt.lost === true && preparationGate.isConsumed();
         try {
-            preparation = stripeStep ? undefined : preparationGate.claim(request.url, request.method, pausedBody(request), request.headers);
+            preparation = stripeStep || preparedRetry ? undefined : preparationGate.claim(request.url, request.method, pausedBody(request), request.headers);
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -2499,7 +2525,10 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             && 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), flexPause?.shape);
-            if (retry && activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)) {
+            // A prepared approval is answered only in the card frame it was bound in: the same request from
+            // another frame (a replacement for a removed one, or a second card frame) is refused below.
+            if (retry && activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)
+                && (!activeRequest.preparedFrame || sameFrame(activeRequest.preparedFrame, sessionId, frameId))) {
                 if (preparation)
                     preparationGate.retireUnboundClaim();
                 activeRequest.requestId = requestId;
@@ -2535,7 +2564,10 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         // Same stop condition as the Playwright adapter: once a failure proves
         // retrying is pointless, fail the request without calling the API again.
-        if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
+        // A request that skipped the spent preparation's claim and was not bound as
+        // its retry (the approval ended while it was judged) is refused as that
+        // claim would refuse it, never asked as a new approval.
+        if (terminal || lifecycle.isBlocked() || awaitingApproval || preparedRetry || Date.now() < quietUntil) {
             let repeatedAuthorizationId = null;
             if (lastSubmitted) {
                 const body = pausedBody(request);
@@ -2543,7 +2575,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     repeatedAuthorizationId = lastSubmitted.authorizationId;
                 }
             }
-            const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+            const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding'
+                : preparedRetry ? 'CheckoutPreparationError' : 'awaiting approval cooldown');
             opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
             if (preparation)
                 preparationGate.retireUnboundClaim();
@@ -2571,8 +2604,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         awaitingApproval = true;
         // A card endpoint approval never outlives its request: the device answers that
         // request, and a retry after the page gave up on it is refused, not bound.
-        const attempt = merchantAttempt(lifecycle, survivesAbandonment(opts, request.url, request.method, resourceType === 'Document', !!preparation || !!stripeStep || !!cardEndpoint || mercadoCheckout.requiresDocument(request.url, request.method)
-            || juspayCheckout.bindsApproval(request.url, request.method)));
+        const attempt = merchantAttempt(lifecycle, survivesAbandonment(opts, request.url, request.method, resourceType === 'Document', !!stripeStep || !!cardEndpoint || mercadoCheckout.requiresDocument(request.url, request.method)
+            || juspayCheckout.bindsApproval(request.url, request.method), preparation));
         let handoffStarted = false;
         // The approval the device gave, and whether it reached a browser request.
         let approvedId = null;
@@ -2614,7 +2647,8 @@ 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, flexPause?.shape) };
+                identity: requestIdentity(opts, request.url, request.method, body, undefined, undefined, flexPause?.shape),
+                preparedFrame: preparation ? { sessionId, frameId } : undefined };
             // An ACI card-number request: the page's CVC and expiry requests for its checkout are held
             // until this approval ends (see AciGate). One whose checkout already has a card-number
             // request running or answered never begins; the pre-claim gate refuses it before this.
@@ -2787,7 +2821,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 const continuation = cseContinuation(opts, deliverRequest.url, deliverBody, replay, { url: request.url, body }, preparation);
                 const postData = Buffer.from(continuation.body).toString('base64');
                 if (continuation.shijiCvv !== null) {
-                    shijiCompanions.bind({ url: request.url, method: request.method, body }, cdpShijiPage(sessionId, frameId), continuation.shijiCvv, continuation.shijiCvvKeySequences ?? []);
+                    shijiCompanions.bind({ url: request.url, method: request.method, body }, cdpShijiPage(sessionId, frameId), continuation.shijiCvv, continuation.shijiCvvKeySequenceSha256 ?? []);
                 }
                 handoffStarted = true;
                 if (replay.kind === 'verifone') {
@@ -3276,7 +3310,8 @@ export async function attachToPlaywright(page, opts) {
         }
     });
     page.on?.('framedetached', (frame) => {
-        if (activeRequest?.frames.includes(frame))
+        // As in attachToCdp: a prepared request's card frame ends its approval even after the page gave the request up.
+        if (activeRequest && (activeRequest.frames.includes(frame) || activeRequest.preparedFrames?.includes(frame)))
             activeRequest.attempt.stop();
         const gone = frame && typeof frame === 'object' ? playwrightShijiFrames.get(frame) : undefined;
         if (gone)
@@ -3287,6 +3322,8 @@ export async function attachToPlaywright(page, opts) {
     let lastSubmitted = null;
     // The approved Datatrans answers, per Frame: the repeat rule (datatrans.ts).
     const datatransRepeats = new DatatransRepeats();
+    // The card product each Worldline MyCheckout hosted checkout chose (worldline-mycheckout.ts).
+    const worldlineProducts = new WorldlineMyCheckoutProducts();
     const frameOf = (request) => { try {
         return request.frame?.() ?? undefined;
     }
@@ -3304,7 +3341,10 @@ export async function attachToPlaywright(page, opts) {
         // so the ACI gate routes them (never ACI's widget script, /bins or /v1/collect).
         // The matcher sees only the URL. Worldpay eProtect's registration is a GET, so its family and
         // the vendor's give-up reports are routed by the eProtect gate (never its scripts).
-        (url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()) || stripeCheckout.matches(url.toString()) || mercadoCheckout.matches(url.toString())
+        // Gravy's session fields are a PUT, so a URL a PUT recognizer claims is routed too; the
+        // pre-claim gates then pause only the PUT and continue the URL's other methods.
+        (url) => opts.vault.isCardRequest(url.toString()) || opts.vault.isCardRequest(url.toString(), 'PUT')
+            || guards.matches(url.toString()) || stripeCheckout.matches(url.toString()) || mercadoCheckout.matches(url.toString())
             || eprotect.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)
@@ -3423,6 +3463,7 @@ export async function attachToPlaywright(page, opts) {
                 frame: frameOf(request),
                 payrails,
                 shijiSts: { companions: shijiCompanions, page: async () => (await playwrightShijiDocumentPage(request)) ?? `pw:none:${++playwrightShijiSeq}` },
+                worldlineMyCheckout: worldlineProducts,
             });
             const preClaim = preClaimResult instanceof Promise ? await preClaimResult : preClaimResult;
             if (preClaim.kind !== 'pause')
@@ -3458,8 +3499,10 @@ export async function attachToPlaywright(page, opts) {
             if (withoutCard === 'continue')
                 return route.fallback();
             let preparation;
+            // As in attachToCdp: the retry of a prepared request whose approval outlived it is never claimed again.
+            const preparedRetry = awaitingApproval && activeRequest?.attempt.lost === true && preparationGate.isConsumed();
             try {
-                preparation = stripeStep ? undefined : preparationGate.claim(request.url(), request.method(), request.postData() ?? '', request.headers());
+                preparation = stripeStep || preparedRetry ? undefined : preparationGate.claim(request.url(), request.method(), request.postData() ?? '', request.headers());
             }
             catch (error) {
                 opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -3473,15 +3516,17 @@ export async function attachToPlaywright(page, opts) {
             // 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), flexPause?.shape);
-                if (activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)) {
+                const retryFrames = [];
+                try {
+                    for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                        retryFrames.push(frame);
+                }
+                catch { /* covered by requestfailed */ }
+                // As in attachToCdp: a prepared approval is answered only in the card frame it was bound in.
+                if (activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)
+                    && (!activeRequest.preparedFrames || (retryFrames.length > 0 && retryFrames[0] === activeRequest.preparedFrames[0]))) {
                     if (preparation)
                         preparationGate.retireUnboundClaim();
-                    const retryFrames = [];
-                    try {
-                        for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
-                            retryFrames.push(frame);
-                    }
-                    catch { /* covered by requestfailed */ }
                     activeRequest.request = request;
                     activeRequest.frames = retryFrames;
                     opts.onEvent?.({ type: 'card_request_paused', detail: { url: eventUrl(opts.vault, request.url()), recognizer: recognizerNameOf(opts, request.url(), request.method()), authorizationId: lifecycle.getState().authorizationId, retry: true } });
@@ -3507,7 +3552,8 @@ export async function attachToPlaywright(page, opts) {
             // CDP adapter's Fetch.failRequest uses, so a refused request resolves
             // identically whichever adapter is attached. An Amadeus card request is
             // 'failed' (ERR_FAILED) in both too, see failsAsNetworkError (refusalFailure).
-            if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
+            // As in attachToCdp: an unbound request that skipped the spent preparation's claim is refused.
+            if (terminal || lifecycle.isBlocked() || awaitingApproval || preparedRetry || Date.now() < quietUntil) {
                 let repeatedAuthorizationId = null;
                 if (lastSubmitted) {
                     let body = null;
@@ -3519,7 +3565,8 @@ export async function attachToPlaywright(page, opts) {
                         repeatedAuthorizationId = lastSubmitted.authorizationId;
                     }
                 }
-                const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+                const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding'
+                    : preparedRetry ? 'CheckoutPreparationError' : 'awaiting approval cooldown');
                 opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
                 if (preparation)
                     preparationGate.retireUnboundClaim();
@@ -3546,8 +3593,8 @@ export async function attachToPlaywright(page, opts) {
                 navigation = false;
             }
             // A card endpoint approval never outlives its request (see attachToCdp).
-            const attempt = merchantAttempt(lifecycle, survivesAbandonment(opts, request.url(), request.method(), navigation, !!preparation || !!stripeStep || !!cardEndpoint || mercadoCheckout.requiresDocument(request.url(), request.method())
-                || juspayCheckout.bindsApproval(request.url(), request.method())));
+            const attempt = merchantAttempt(lifecycle, survivesAbandonment(opts, request.url(), request.method(), navigation, !!stripeStep || !!cardEndpoint || mercadoCheckout.requiresDocument(request.url(), request.method())
+                || juspayCheckout.bindsApproval(request.url(), request.method()), preparation));
             const frames = [];
             try {
                 for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
@@ -3555,9 +3602,13 @@ export async function attachToPlaywright(page, opts) {
             }
             catch { /* requestfailed/page close still cover unavailable frame metadata */ }
             // Judged on the request that currently carries the attempt: after a
-            // retry binds, the first request's failure is history, not a loss.
+            // retry binds, the first request's failure is history, not a loss. A
+            // prepared request's own frames are judged for as long as the approval
+            // lasts, as framedetached judges them: their removal ends it.
             const assertRequestLive = () => {
                 const current = attempt.target;
+                if (preparation && frames.some((frame) => frame.isDetached?.()))
+                    attempt.stop();
                 if (current && (current.request.failure?.() || current.frames.some((frame) => frame.isDetached?.())))
                     attempt.lose();
                 if (page.isClosed?.())
@@ -3587,7 +3638,8 @@ 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, flexPause?.shape) };
+                    identity: requestIdentity(opts, request.url(), request.method(), body, undefined, undefined, flexPause?.shape),
+                    preparedFrames: preparation ? [...frames] : undefined };
                 // An ACI card-number request: see the same step in attachToCdp.
                 if (!aci.begin(request.url(), request.method(), body, preparation?.merchantOrigin)) {
                     throw new CheckoutPreparationError(preparation?.id ?? null, ACI_CHECKOUT_REUSED);
@@ -3728,7 +3780,7 @@ export async function attachToPlaywright(page, opts) {
                         if (boundPage === null)
                             throw new ShijiStsError('unsupported');
                         assertRequestLive();
-                        shijiCompanions.bind({ url: request.url(), method: request.method(), body }, boundPage, continuation.shijiCvv, continuation.shijiCvvKeySequences ?? []);
+                        shijiCompanions.bind({ url: request.url(), method: request.method(), body }, boundPage, continuation.shijiCvv, continuation.shijiCvvKeySequenceSha256 ?? []);
                     }
                     handoffStarted = true;
                     if (replay.kind === 'verifone') {

package/dist/client.d.ts

@@ -41,11 +41,13 @@ export interface PausedRequest {
         facts?: CardEndpointFactsRecord;
     };
     /**
-     * A Payrails card save (mode device_encrypt) only: the session key the page's
-     * Payrails init payload named (vaultConfiguration.encryptionPublicKey), which
-     * the save itself does not carry. The adapters capture it; a caller running
-     * its own interception passes it here, and a save without it is refused
-     * before anything is created.
+     * A Payrails card save or card-form payment (mode device_encrypt) only: the
+     * session key the page's Payrails init payload named
+     * (vaultConfiguration.encryptionPublicKey), which the request itself does not
+     * carry, and for a card-form payment the payload's holderReference, which the
+     * payment's ciphertext carries and its body does not. The adapters capture
+     * both; a caller running its own interception passes them here, and a request
+     * without them is refused before anything is created.
      */
     payrails?: PayrailsSidecar;
 }
@@ -54,7 +56,7 @@ export interface PausedRequest {
  * only recognizers in these modes, so a request this build cannot complete
  * is never paused) and sent on every create. `device_encrypt`: the adapters
  * capture the Payrails session key the page's init payload names (payrails.ts),
- * and the cardholder's device encrypts and sends the save.
+ * and the cardholder's device encrypts and sends the save or card-form payment.
  */
 export declare const SUPPORTED_MODES: readonly CheckoutMode[];
 /**
@@ -124,14 +126,17 @@ export declare const SUPPORTED_REGISTRY_FEATURES: readonly string[];
  * `primer_payment_instruments`: Primer's card tokenization, which this build
  * judges before it pauses (primer.ts) and hands back to the page only as a
  * single-use token. A merchant's client session can save the card after the
- * payment with no sign in that request, so the API creates a Primer
- * authorization only for a test-mode client and refuses a live one (400
- * invalid_primer_request, live_keep_on_file) until the cardholder can consent
- * to that save; this build then aborts the paused request with nothing sent. A
- * gated recognizer never sits in BUILTIN_REGISTRY, so it is paused only after a
- * sync.
- * `payrails_device_encrypt`: Payrails' card-form save, which this build pauses
- * only once it has bound the save to a captured session (payrails.ts). A gated
+ * payment with no sign in that request, so the API creates a live Primer
+ * authorization only when it names the checkout page's https origin
+ * (checkout_origin, which this build sends from the page's origin): the
+ * approval says the merchant keeps the card on file, under the merchant name
+ * the create sent, which Agentcard cannot confirm, and pays only with a card
+ * the person stored. A refused create aborts the paused request with nothing
+ * sent. A gated recognizer never sits in BUILTIN_REGISTRY, so it is paused only
+ * after a sync.
+ * `payrails_device_encrypt`: Payrails' card save and card-form payment, which
+ * this build pauses only once it has bound the request to a captured session
+ * (payrails.ts). A gated
  * recognizer never sits in BUILTIN_REGISTRY, so it is paused only after a sync.
  * `converge_hpp_process`: Elavon Converge's Hosted Payment Page card request
  * (elavon-converge.ts), paused in token mode and judged by the pre-claim gate.
@@ -183,6 +188,22 @@ export declare const SUPPORTED_REGISTRY_FEATURES: readonly string[];
  * finds a card in it (cybersource-secure-acceptance.ts). Served on the same terms,
  * so every other company keeps the stop every build applies to a card posted to
  * Secure Acceptance.
+ * `gravy_session_fields_put`: Gravy Secure Fields' update of a checkout session,
+ * the one card request a recognizer declares as a PUT. This build pauses that PUT
+ * from Gravy's controller frame as it pauses a POST (isRecognizerRequest), creates
+ * the authorization with the PUT, and answers the frame with Gravy's own answer to
+ * the cardholder's device. Served on the same terms; an older build never sees the
+ * entry, and every company Agentcard has not turned Gravy on for keeps today's path,
+ * where the request continues to Gravy untouched.
+ * `moneris_hosted_tokenization`: Moneris Hosted Tokenization's card request, the
+ * frame's form post to /HPPtoken/request.php. This build pauses it only when it
+ * carries the number, the expiry and the CVD the cardholder's device fills, fails a
+ * frame that leaves the expiry or CVD to the merchant's page in the browser with a
+ * `blocked` event, `request_without_card`, and answers with Moneris's token as the
+ * API recorded it. The device sends the card through the checkout relay. Served on
+ * the same terms: only to a build that lists it, for a company Agentcard turned
+ * Moneris on for. A gated recognizer never sits in BUILTIN_REGISTRY, so it is paused
+ * only after a sync.
  */
 export declare const SUPPORTED_CAPABILITIES: readonly string[];
 /**
@@ -276,12 +297,13 @@ export interface CseReplay extends ExecutionMetadata {
     authorizationId: string;
     substitutions: Substitutions;
     /**
-     * Shiji STS only: the getCvvId keySequence values the API reviewed as the booking page's own and
-     * served beside the set (`shiji_sts_companion`). The adapters bind the companion getCvvId to them
-     * (shiji-sts.ts ShijiStsCompanions), so the device's CVV goes under no other key.
+     * Shiji STS only: the SHA-256 of each getCvvId keySequence the API reviewed as the booking page's
+     * own, served beside the set (`shiji_sts_companion.key_sequence_sha256`). The adapters bind the
+     * companion getCvvId to a key that hashes to one of them (shiji-sts.ts ShijiStsCompanions), so the
+     * device's CVV goes under no other key.
      */
     shijiStsCompanion?: Readonly<{
-        keySequences: readonly string[];
+        keySequenceSha256: readonly string[];
     }>;
     amountAuthority?: AmountAuthority;
 }
@@ -401,12 +423,15 @@ export interface CardEndpointReplay extends ExecutionMetadata {
 /**
  * The device_encrypt flow (Payrails): the cardholder's device encrypted the
  * real card under the session key the page's init payload named and sent the
- * save to Payrails itself. This is Payrails' 201 for that save, rebuilt from an
- * allow-list (the instrument's identifiers, its status, the network, the BIN
- * cut to six digits, the last four, the expiry, the holder name and the
- * fingerprint), to replay into the paused request as in the token flow. The
- * ciphertext the device made never reaches the runtime or the page. Never an
- * autopilot result: autopilot refuses this mode.
+ * save or card-form payment to Payrails itself. This is Payrails' answer,
+ * rebuilt from an allow-list, to replay into the paused request as in the token
+ * flow: for a save its 201 (the instrument's identifiers, its status, the
+ * network, the BIN cut to six digits, the last four, the expiry, the holder
+ * name and the fingerprint); for a card-form payment its 2xx naming the
+ * authorize action (its name, id, time and execution link, which the page's
+ * Payrails SDK polls for the issuer's answer). The ciphertext the device made
+ * never reaches the runtime or the page. Never an autopilot result: autopilot
+ * refuses this mode.
  */
 export interface DeviceEncryptReplay extends ExecutionMetadata {
     mode: 'device_encrypt';
@@ -430,11 +455,14 @@ export interface PrepareCheckoutOptions {
      * card request is then the one request this preparation pays.
      *
      * A Fiserv checkout (psp 'fiserv'): the id of the key Agentcard pinned for the
-     * merchant, `agentcard_sandbox` in the sandbox environment. Required for Fiserv,
+     * merchant: `homedepot_orangepay` for Blinds.com and homedepot.com, and
+     * `agentcard_sandbox` in the sandbox environment. Required for Fiserv,
      * and refused for every processor but Adyen and Fiserv. The cardholder is asked to
      * approve a payment to the merchant that key belongs to, so the checkout's `merchant`
-     * must be that merchant's name (`Agentcard sandbox` for `agentcard_sandbox`), and the
-     * one card capture this preparation pays must carry an envelope under that key.
+     * must be that merchant's name (`Home Depot` for `homedepot_orangepay`, `Agentcard
+     * sandbox` for `agentcard_sandbox`), and the one card capture this preparation pays
+     * must be that merchant's, under that key or under a credentials session's key,
+     * which the envelope's key replaces.
      *
      * A Verifone checkout (psp 'verifone'): the id of the Verifone profile Agentcard
      * reviewed for the merchant, which this client must have armed and enabled
@@ -711,6 +739,12 @@ export interface PlaceholderCard {
     /** The stored card's expiry year, four digits ("2031"). */
     readonly expiryYear: string;
 }
+/**
+ * The placeholder number for a network (lowercase, as GET /api/v2/vault_cards names it) on a
+ * processor's page: the processor's own number for that network when `overrides` names one, else
+ * the network's default, else undefined for a network with no placeholder.
+ */
+export declare function placeholderNumber(brand: string, psp?: string, overrides?: Readonly<Record<string, Readonly<Record<string, string>>>>): string | undefined;
 /**
  * The recognizer says this processor is preparation-required, and no preparation
  * was passed. Its card may be sent only after the cardholder approved a
@@ -1198,8 +1232,9 @@ export declare class VaultClient {
     private mergedRegistry;
     /**
      * The recogniser that claims a card request, or null; what a paused request names as
-     * `recognizer`. A POST to a recognised endpoint, or for a recognizer whose card request is a
-     * GET (Worldpay eProtect) that exact GET, query included.
+     * `recognizer`. A POST to a recognised endpoint, a PUT for a recognizer whose card request is
+     * a PUT (Gravy), or for a recognizer whose card request is a GET (Worldpay eProtect) that
+     * exact GET, query included.
      */
     recognizerOf(url: string, method?: string): Recognizer | null;
     /** Refresh recognizers from the API so new PSPs work without a redeploy. */
@@ -1244,8 +1279,9 @@ export declare class VaultClient {
     cardOnFilePolicy(url: string, method?: string): string | null;
     /**
      * True when this request is a card tokenization we can take over: a POST to
-     * a recognized endpoint, or for a recognizer whose card request is a GET
-     * (Worldpay eProtect) that exact GET, query included.
+     * a recognized endpoint, a PUT for a recognizer whose card request is a PUT
+     * (Gravy), or for a recognizer whose card request is a GET (Worldpay eProtect)
+     * that exact GET, query included.
      */
     isCardRequest(url: string, method?: string): boolean;
     /**
@@ -1306,12 +1342,16 @@ export declare class VaultClient {
      * 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.
+     * The facts hold only while the cardholder pays with that card. `psp` names the processor
+     * whose card form the agent types into (the recognizer's name, `worldline_mycheckout`): a
+     * processor that needs its own number for the card's network gets it, and every other gets the
+     * network's default. Throws PlaceholderCardError when there is no such card, its network has no
+     * placeholder, or it carries no expiry.
      */
     placeholderCard(input: {
         user: string;
         cardId?: string;
+        psp?: string;
         signal?: AbortSignal;
     }): Promise<PlaceholderCard>;
     /** Wait for real device approval before the caller starts native tokenization. */