@agent-cards/checkout 0.19.0 → 0.22.0

package/dist/pre-claim.js

@@ -1,386 +0,0 @@
-// One pre-claim gate registry, shared by the CDP and Playwright adapters.
-//
-// Before a paused request is claimed for the vault, a small set of processor
-// gates inspect it: Mercado Pago's native Checkout Pro configuration and
-// association, Braintree's shared /graphql endpoint, native Stripe Checkout,
-// and Fiserv's card capture. The first three used to be written inline in
-// Fetch.requestPaused and again in the page.route handler, so a decision could
-// drift between the two adapters and a new family had to be added in both places.
-//
-// dispatchPreClaim runs the gates in order and resolves the request to one of:
-//   - continue: let the request through untouched, or with a body the gate
-//     rewrote (Mercado's corrected association);
-//   - abort: fail the request, so a dummy card never reaches a live processor;
-//   - answer: fulfill locally with a synthetic response (Stripe's tokenization
-//     stub);
-//   - pause: hand the request to the vault claim flow, carrying the native
-//     Stripe step when one was claimed.
-//
-// A gate performs its own continue/answer/abort through the adapter effects so
-// that failure handling stays byte-for-byte with the inline code: Stripe's
-// fulfill and Mercado's continue run inside the gate's own try, so a transport
-// failure there is recovered exactly as before (Stripe reports stub_response,
-// Mercado stops the native checkout). The effects encapsulate each adapter's
-// mechanics (CDP Fetch.* with base64 bodies and its own catch; Playwright
-// route.*), and the state accessors are re-read after every await, as the
-// inline gates did. Adding a new family is one entry in PSP_PRE_CLAIM_GATES: a
-// non-card body on a recognized host continues, and an unsupported card body
-// aborts.
-//
-// The dispatch is synchronous unless a gate must await. The inline code reached
-// the vault claim flow for an ordinary card request without a single await, and
-// worker attribution and setup races depend on that: activeRequest is set in
-// the same microtask the request paused in. So every gate returns its decision
-// synchronously when it does no I/O (the common card request defers through
-// every gate and pauses with no await), and hands back a promise only when it must
-// read the document or talk to the browser (Mercado's continuation, Stripe once
-// a step is claimed, and the continue/abort effects).
-import { PaymentOutcomeUnknownError, redactUrl } from './client.js';
-import { classifyBraintreeRequest } from './braintree.js';
-import { StripeCheckoutClaimConflictError, stripeCheckoutReadinessError } from './stripe-checkout.js';
-import { classifyProfileRequest, merchantBodyKeyPathSha256, profileTemplatedUrl } from './merchant-hosted.js';
-import { isFiservCaptureHost, isFiservPausableBody } from './fiserv.js';
-/**
- * The URL an event may name for a request. For an armed merchant profile's
- * endpoint or a sibling of it: the endpoint origin, the path TEMPLATE and the
- * profile's own query (merchantProfileTemplatedUrl), so a user id, cart id or
- * email in the merchant's path or query never reaches telemetry. For anything
- * else: origin and path (redactUrl), as before.
- */
-export function eventUrl(vault, url) {
-    const profile = typeof vault?.merchantProfileOf === 'function' ? vault.merchantProfileOf(url) : null;
-    if (profile) {
-        try {
-            return profileTemplatedUrl(profile, url);
-        }
-        catch { /* not a profile this build reviewed */ }
-    }
-    return redactUrl(url);
-}
-// Mercado Pago's native Checkout Pro shares one origin between its BIN-lookup
-// configuration and its card association. A request that is not for that origin
-// defers synchronously; a POST to it is handled asynchronously (a document read
-// backs the capture and the correction). The continue runs inside that try, so
-// if it or a gate step throws, the native checkout is stopped and only this
-// request fails.
-const mercadoPreClaim = (ctx) => {
-    const { url, method } = ctx.request;
-    if (!(ctx.mercado.matches(url) && !['GET', 'HEAD', 'OPTIONS'].includes(method)))
-        return undefined;
-    return mercadoContinuation(ctx);
-};
-async function mercadoContinuation(ctx) {
-    const { url, method } = ctx.request;
-    try {
-        if (!ctx.attachmentReady() || ctx.interceptionAborted() || ctx.lifecycleAborted() || ctx.terminal())
-            throw new Error('checkout_interception_not_ready');
-        const body = ctx.request.body ?? '';
-        if (await ctx.mercado.configuration(url, method, body, ctx.readDocumentUrl)) {
-            await ctx.effects.continueRequest();
-            return { kind: 'continue' };
-        }
-        const postData = ctx.mercado.associationBody(url, method, body, await ctx.readDocumentUrl());
-        if (postData !== undefined) {
-            if (ctx.interceptionAborted() || ctx.lifecycleAborted() || ctx.documentClosed())
-                throw new Error('checkout_interception_not_ready');
-            await ctx.effects.continueRequest(postData);
-            return { kind: 'continue' };
-        }
-    }
-    catch {
-        ctx.mercado.invalidate();
-        ctx.lifecycle.failed(new PaymentOutcomeUnknownError(ctx.lifecycle.getState().authorizationId, 'mercado_checkout_continuation_stopped'));
-        ctx.onEvent?.({ type: 'blocked', detail: 'mercado_checkout_continuation_stopped' });
-        await ctx.effects.abort();
-        return { kind: 'abort' };
-    }
-    return undefined;
-}
-// Braintree shares /graphql between its client configuration and its card
-// tokenization. Classify (synchronously) before URL-only recognition: a
-// configuration query continues untouched, a malformed tokenization aborts,
-// everything else (a real tokenization, or a non-Braintree request) defers.
-// classifyBraintreeRequest takes the raw body (string or null); a null body on
-// a Braintree POST is classified the same as an empty one, so both adapters
-// reach the same verdict. The configuration continue swallows a transport
-// failure, as the inline CDP path did (the Playwright path never reaches a
-// failing route here).
-const braintreePreClaim = (ctx) => {
-    const { url, method, body } = ctx.request;
-    const braintree = method.toUpperCase() === 'POST' ? classifyBraintreeRequest(url, method, body) : undefined;
-    if (braintree === 'configuration')
-        return braintreeContinue(ctx);
-    if (braintree === 'invalid')
-        return braintreeAbort(ctx);
-    return undefined;
-};
-async function braintreeContinue(ctx) {
-    await ctx.effects.continueRequest().catch(() => { });
-    return { kind: 'continue' };
-}
-async function braintreeAbort(ctx) {
-    ctx.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
-    await ctx.effects.abort();
-    return { kind: 'abort' };
-}
-// Native Stripe Checkout. Enablement and the claim are synchronous, so a
-// disabled attachment or a non-Stripe request defers with no await. Once a step
-// is claimed, the readiness checks, document assertion and fulfill run
-// asynchronously: the tokenization step is answered locally with a synthetic
-// payment method (no selected-card data, no authorization) and the final
-// confirmation step pauses for the vault claim flow. The gate returns that
-// pause itself rather than deferring, so a claimed step never reaches a gate
-// registered after Stripe: a broad family gate appended later cannot continue
-// or abort the confirmation the vault must claim. The fulfill runs inside the
-// try, so a transport failure is reported as stub_response and aborts, and
-// checkout_prepared fires only after a successful fulfill.
-const stripePreClaim = (ctx) => {
-    if (!ctx.stripe.isEnabled())
-        return undefined;
-    const stripeUrl = ctx.request.url;
-    let stripeStep;
-    try {
-        const nativeRequest = { url: stripeUrl, method: ctx.request.method, headers: ctx.request.headers, body: ctx.request.body ?? '' };
-        stripeStep = ctx.stripe.claim(nativeRequest);
-    }
-    catch (error) {
-        return stripeReject(ctx, error, stripeUrl, 'classification', undefined);
-    }
-    ctx.stripeStep = stripeStep;
-    if (!stripeStep)
-        return undefined;
-    return stripeAfterClaim(ctx, stripeUrl, stripeStep);
-};
-async function stripeAfterClaim(ctx, stripeUrl, stripeStep) {
-    let stripeStage = 'readiness';
-    try {
-        if (!ctx.attachmentReady() || ctx.stripeAttachmentBusy())
-            throw stripeCheckoutReadinessError('attachment_not_ready');
-        if (ctx.interceptionAborted())
-            throw stripeCheckoutReadinessError('cancelled');
-        if (ctx.terminal() || ctx.lifecycle.isBlocked())
-            throw stripeCheckoutReadinessError(ctx.lifecycle.isCancelled() ? 'cancelled' : 'checkout_inactive');
-        if (ctx.awaitingApproval())
-            throw stripeCheckoutReadinessError('approval_pending');
-        stripeStage = 'document';
-        ctx.stripe.assertDocument(await ctx.readDocumentUrl());
-        stripeStage = 'claim';
-        ctx.stripe.assertClaim(stripeStep);
-        stripeStage = 'readiness';
-        if (ctx.interceptionAborted())
-            throw stripeCheckoutReadinessError('cancelled');
-        if (ctx.lifecycle.isBlocked())
-            throw stripeCheckoutReadinessError(ctx.lifecycle.isCancelled() ? 'cancelled' : 'checkout_inactive');
-        if (ctx.requestInactive())
-            throw stripeCheckoutReadinessError('request_inactive');
-        if (stripeStep.phase === 'tokenization') {
-            stripeStage = 'stub_response';
-            await ctx.effects.answer(stripeStep.response);
-            ctx.onEvent?.({ type: 'checkout_prepared', detail: { processor: 'stripe' } });
-            return { kind: 'answer' };
-        }
-    }
-    catch (error) {
-        return stripeReject(ctx, error, stripeUrl, stripeStage, stripeStep.phase);
-    }
-    return { kind: 'pause', stripeStep };
-}
-async function stripeReject(ctx, error, stripeUrl, stage, phase) {
-    const detail = ctx.stripe.describeRejection(error, stripeUrl, stage, phase);
-    if (!(error instanceof StripeCheckoutClaimConflictError))
-        ctx.stripe.invalidate();
-    ctx.onEvent?.({ type: 'checkout_blocked', detail });
-    ctx.onEvent?.({ type: 'blocked', detail: ctx.failureSummary(error) });
-    await ctx.effects.abort();
-    return { kind: 'abort' };
-}
-// Adyen merchant-hosted checkouts (merchant-hosted.ts). A request to an armed
-// profile's endpoint, or a sibling of it, is the profile's to judge before the
-// terminal arbiter, which would otherwise continue it (no processor recognizes a
-// merchant's own server):
-//   - no encrypted card data (a basket query, a GET, a preflight): defer, and the
-//     request is judged as it was before any profile existed;
-//   - no readable body on anything but a GET, HEAD or OPTIONS: one the adapter
-//     could not read (CDP reports it with no bytes: a blob or a file) is not
-//     proven to carry no card, so it is judged as a card body the profile cannot
-//     finish, like every unreadable card body in cdp.ts. Playwright's postData()
-//     is null for a missing body and an unreadable one alike, so an empty body
-//     counts as unread in both adapters and they reach the same verdict;
-//   - a card request to a profile this attachment already handed a card to: the
-//     page's retry carries the agent's dummy card and the approval is spent, so it
-//     aborts (merchant-handoff.ts reports the unknown outcome);
-//   - a profile in observe: report the request's shape (the SHA-256 of its key
-//     paths, never a value; null for a body that was not read) with the verdict,
-//     then abort as unsupported, so the dummy card never reaches the merchant and
-//     no authorization exists;
-//   - a card body the profile cannot finish (another operation, a stored card,
-//     storing the card, three fields, a sibling endpoint, an unreadable body):
-//     abort as unsupported, with the reason;
-//   - the profile's reviewed card request, on an enabled profile, with no
-//     preparation on this attachment: abort as preparation_required before any
-//     pause, prompt or authorization, and refuse a later prepare() the way the
-//     first card request always does (preparation.ts);
-//   - the same request with a preparation: pause for the claim flow, where only a
-//     ready preparation for this profile pays it.
-// A reader that throws on the body is not proof it carries no card either: the
-// request is judged as an unreadable card body and aborted, never left paused.
-// Synchronous until it must abort, like every gate.
-const UNREAD_BODY_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
-export const MERCHANT_BODY_UNREADABLE = 'the paused request carries no body the SDK could read, so Agentcard cannot tell whether it carries a card';
-const merchantHostedPreClaim = (ctx) => {
-    const { url, method } = ctx.request;
-    const profile = typeof ctx.vault.merchantProfileOf === 'function' ? ctx.vault.merchantProfileOf(url) : null;
-    if (!profile)
-        return undefined;
-    const body = ctx.request.body;
-    const unread = body === null || body === '';
-    let verdict;
-    try {
-        verdict = !unread ? classifyProfileRequest(profile, url, method, body)
-            : UNREAD_BODY_METHODS.has(String(method).toUpperCase()) ? { verdict: 'pass' } : { verdict: 'abort', reason: MERCHANT_BODY_UNREADABLE };
-    }
-    catch {
-        verdict = { verdict: 'abort', reason: MERCHANT_BODY_UNREADABLE };
-    }
-    if (verdict.verdict === 'pass')
-        return undefined;
-    const templated = profileTemplatedUrl(profile, url);
-    if (ctx.merchantHandoff?.retried(profile.id))
-        return merchantHostedAbort(ctx);
-    if (profile.status !== 'enabled') {
-        ctx.onEvent?.({ type: 'merchant_profile_observed', detail: { profile: profile.id, url: templated, method, verdict: verdict.verdict,
-                ...(verdict.verdict === 'abort' ? { reason: verdict.reason } : {}), keyPathSha256: unread ? null : keyPathSha256Of(body) } });
-        return merchantHostedUnsupported(ctx, profile, templated, 'merchant_profile_observe', 'Agentcard has not turned on payments to this merchant yet');
-    }
-    if (verdict.verdict === 'abort')
-        return merchantHostedUnsupported(ctx, profile, templated, 'merchant_request_unsupported', verdict.reason);
-    if (!ctx.preparationGate.isEngaged())
-        return merchantHostedPreparationRequired(ctx);
-    return { kind: 'pause', stripeStep: ctx.stripeStep };
-};
-/** The body's key-path hash for an observe event, or null when it cannot be read: telemetry never stops the gate. */
-function keyPathSha256Of(body) {
-    try {
-        return merchantBodyKeyPathSha256(body);
-    }
-    catch {
-        return null;
-    }
-}
-async function merchantHostedAbort(ctx) {
-    await ctx.effects.abort();
-    return { kind: 'abort' };
-}
-async function merchantHostedPreparationRequired(ctx) {
-    ctx.preparationGate.observeUnprepared();
-    ctx.lifecycle.preparationRequired();
-    ctx.onEvent?.({ type: 'blocked', detail: 'preparation_required' });
-    await ctx.effects.abort();
-    return { kind: 'abort' };
-}
-async function merchantHostedUnsupported(ctx, profile, url, category, reason) {
-    ctx.preparationGate.invalidate('unsupported_checkout');
-    ctx.lifecycle.unsupported(category);
-    ctx.onEvent?.({ type: 'unsupported_checkout', detail: { url, method: ctx.request.method, profile: profile.id, reason } });
-    await ctx.effects.abort();
-    return { kind: 'abort' };
-}
-// Fiserv Commerce Hub card capture (fiserv.ts). A POST the registry recognizes on
-// one of Fiserv's two card-capture hosts is this gate's to judge before any claim:
-//   - only a capture that carries no Vault card (Fastlane's PaymentToken, ACH's
-//     PaymentCheck, a gift or EBT card, each in its exact source shape) continues
-//     untouched, and no preparation is claimed or spent;
-//   - every other body is judged as a card capture, including one not proven
-//     card-free: one the adapter could not read (CDP reports it with no bytes;
-//     Playwright's postData() is null for it and for a missing body alike), one over
-//     64 KiB, one that is not JSON, a PaymentCard with a plaintext card, or a
-//     non-card type or category that also carries a card member. As the
-//     registry requires of an unsupported card body, none of them continues to
-//     Fiserv with the agent's placeholder;
-//   - a card capture with no preparation on this attachment is refused as
-//     preparation_required before any pause, prompt or authorization, since only a
-//     prepared checkout pays Fiserv, and a later prepare() is refused as after any
-//     first card request (preparation.ts). Only while the attachment is live and
-//     idle: otherwise (still arming a frame, tearing down, blocked, or an approval
-//     outstanding) the adapter refuses it the way it refuses any card request;
-//   - a card capture with a preparation pauses for the claim flow, which pays it
-//     only through a ready Fiserv preparation for this capture's endpoint, key and
-//     merchant (prepared-processor.ts) and refuses any other body as
-//     checkout_changed, and continues it with the approved envelope at
-//     source.encryptionData (cse-body.ts).
-// Synchronous until it must continue or abort, like every gate. Exported for the
-// gate registry's tests.
-export const fiservPreClaim = (ctx) => {
-    const { url, method, body } = ctx.request;
-    if (String(method).toUpperCase() !== 'POST' || !isFiservCaptureHost(url) || !ctx.vault.isCardRequest(url, method))
-        return undefined;
-    if (!isFiservPausableBody(body))
-        return fiservContinue(ctx);
-    const idle = ctx.attachmentReady() && !ctx.stripeAttachmentBusy() && !ctx.interceptionAborted() && !ctx.terminal()
-        && !ctx.lifecycle.isBlocked() && !ctx.awaitingApproval();
-    if (idle && !ctx.preparationGate.isEngaged())
-        return fiservPreparationRequired(ctx);
-    return undefined;
-};
-async function fiservContinue(ctx) {
-    await ctx.effects.continueRequest().catch(() => { });
-    return { kind: 'continue' };
-}
-async function fiservPreparationRequired(ctx) {
-    ctx.preparationGate.observeUnprepared();
-    ctx.lifecycle.preparationRequired();
-    ctx.onEvent?.({ type: 'blocked', detail: 'preparation_required' });
-    await ctx.effects.abort();
-    return { kind: 'abort' };
-}
-// The terminal arbiter, always last. A request that no gate claimed and that is
-// neither a native Stripe step nor a recognized card request continues, unless
-// it matches a declared payment endpoint we do not support (then it aborts as an
-// unsupported checkout). Otherwise it is a card request and pauses for the vault
-// claim flow. The Stripe gate pauses its own claimed final step before any later
-// gate runs, so the stripeStep check here is only a second guard. The pause is
-// synchronous (no effect); the continue swallows a transport failure, as the
-// inline CDP path did.
-const unsupportedPreClaim = (ctx) => {
-    const { url, method } = ctx.request;
-    if (!ctx.stripeStep && !ctx.vault.isCardRequest(url, method)) {
-        if (ctx.guards.matches(url, method))
-            return unsupportedAbort(ctx);
-        return unsupportedContinue(ctx);
-    }
-    return { kind: 'pause', stripeStep: ctx.stripeStep };
-};
-async function unsupportedAbort(ctx) {
-    const { url, method } = ctx.request;
-    ctx.preparationGate.invalidate('unsupported_checkout');
-    ctx.lifecycle.unsupported();
-    ctx.onEvent?.({ type: 'unsupported_checkout', detail: { url: eventUrl(ctx.vault, url), method } });
-    await ctx.effects.abort();
-    return { kind: 'abort' };
-}
-async function unsupportedContinue(ctx) {
-    await ctx.effects.continueRequest().catch(() => { });
-    return { kind: 'continue' };
-}
-/** The processor gates, in order. A new family adds one entry here; the terminal
- * arbiter runs after all of them and is not part of this list. A gate appended
- * after Stripe is never offered a step Stripe claimed: Stripe answers, aborts or
- * pauses each one itself. */
-export const PSP_PRE_CLAIM_GATES = [mercadoPreClaim, braintreePreClaim, stripePreClaim, merchantHostedPreClaim, fiservPreClaim];
-/** Run each gate in order; the first to return a decision wins. If none does,
- * the terminal arbiter decides between continue, abort (unsupported) and pause.
- * Returns synchronously while every gate defers synchronously (an ordinary card
- * request pauses with no await), and a promise once a gate does I/O. */
-export function dispatchPreClaim(ctx, gates = PSP_PRE_CLAIM_GATES) {
-    return runGates(ctx, gates, 0);
-}
-function runGates(ctx, gates, from) {
-    for (let i = from; i < gates.length; i++) {
-        const result = gates[i](ctx);
-        if (result instanceof Promise)
-            return result.then((decision) => decision ?? runGates(ctx, gates, i + 1));
-        if (result)
-            return result;
-    }
-    return unsupportedPreClaim(ctx);
-}