@agent-cards/checkout 0.19.0 → 0.22.0

package/dist/cdp.d.ts

@@ -1,192 +0,0 @@
-import { type VaultClient, type ExecutionMetadata } from './client.js';
-import { type StripeCheckoutOptions } from './stripe-checkout.js';
-import { type CheckoutController, type LifecycleOptions, type PaymentEndpointGuard } from './lifecycle.js';
-/**
- * The CORS headers a fulfilled CROSS-ORIGIN request needs, or null when the
- * request is same-origin (or carries no Origin, so no CORS check applies).
- *
- * The browser checks a fulfilled response exactly as it checks a real one. A
- * page that fetches a processor on another origin therefore needs
- * `access-control-allow-origin` on the synthetic answer, or its fetch rejects
- * with "Failed to fetch" and the page never sees the processor's reply, even
- * though the cardholder approved and the processor answered the vault.
- * Shopify never hit this on its current host: the checkout.pci.shopifyinc.com
- * card iframe posts to its own origin (its older deposit.<region>.shopifycs.com
- * host is called from the checkout.shopifycs.com frame, cross-origin, and gets
- * the answer like everyone else). Stripe hits it on every surface (Checkout on
- * checkout.stripe.com or a merchant domain, and Elements in the js.stripe.com
- * frame, all call api.stripe.com), and so does every other processor whose
- * card frame calls a separate API host. Observed live on
- * 2026-09-03: the vault replayed a Stripe PaymentMethod into a raw-CDP
- * runtime, the browser refused the answer for want of this header, and
- * Stripe Checkout showed "We are experiencing connection issues".
- *
- * The exact Origin is echoed rather than `*`: a credentialed request refuses
- * `*`, the echo satisfies both. The processor's own value can never reach
- * this adapter (a browser does not expose that header to the page that
- * replayed the call), so whatever the replay carries under these names is
- * replaced by the one value that is right for THIS request. Playwright adds
- * the same headers inside route.fulfill when a cross-origin fulfill carries
- * none (microsoft/playwright#12929), which is why attachToPlaywright never
- * needed this; it writes them itself anyway, replacing a stale value, so both
- * adapters answer the vault's replays identically.
- *
- * This widens nothing. A tokenization endpoint is built for anonymous
- * browsers and answers every origin (`access-control-allow-origin: *` on
- * Stripe's and Shopify's own replies), so the page that made the request
- * could always read the processor's answer to it; the replay is made exactly
- * as visible, to exactly that page. Whether a card goes anywhere at all is
- * decided by the cardholder on the approval screen, never by this header.
- *
- * Only what a browser serializes is ever echoed: one canonical http(s)
- * origin (`new URL(origin).origin === origin`), or the opaque `null` a
- * sandboxed or data: document sends, which Chrome matches against
- * `access-control-allow-origin: null` and which Playwright echoes too. That
- * refuses userinfo, a path, an explicit default port, several origins in one
- * value, or a control character that would break the fulfill after the
- * cardholder already approved. Anything refused simply gets no CORS answer,
- * which is what every fulfill got before this existed.
- */
-export declare function corsHeadersFor(url: string, requestHeaders: Record<string, string> | undefined): Record<string, string> | null;
-/** How a fulfill was answered, reported on the `authorized` event so a silent CORS failure is diagnosable from events alone. */
-export type CorsOutcome = 'echoed' | 'same_origin' | 'none';
-/** The CORS answer and its reason: `none` when no usable Origin was sent (or the url is not http(s)), `same_origin` when no check applies. */
-export declare function corsDecision(url: string, requestHeaders: Record<string, string> | undefined): {
-    headers: Record<string, string> | null;
-    outcome: CorsOutcome;
-};
-/**
- * `headers` with the CORS answer for this request written in; the object
- * itself when none is needed. Any header the answer names is replaced
- * whatever its case, so a name is never sent twice. The answer varies by
- * Origin, and a `vary` the replay already carries is extended rather than
- * replaced (or left alone when it already covers Origin or is `*`); a `vary`
- * the answer itself names is taken as given.
- */
-export declare function withCorsHeaders(headers: Record<string, string>, cors: Record<string, string> | null): Record<string, string>;
-/**
- * Browser-level, session-aware CDP connection. A page-scoped Playwright or
- * Puppeteer CDPSession is NOT this interface; use attachToPlaywright for those.
- *
- * Forward commands and events over a browser WebSocket with flattened sessions.
- * An omitted sessionId means the browser root, never a default page session.
- * Attachment requires Target.getTargetInfo on the supplied page session, then
- * Target.setDiscoverTargets and Target.getTargets at the browser root. Forward
- * root Target.targetCreated/targetInfoChanged events with no sessionId, and
- * preserve the sessionId on child attachment, Fetch, and Network events.
- * Page/iframe sessions must support Page, Fetch, Network, and Target; dedicated
- * workers require Network, Target, and Runtime.runIfWaitingForDebugger.
- * Unsupported or incomplete discovery fails with CheckoutAttachmentError
- * before fetch_armed. TypeScript describes forwarding; attachment verifies
- * the browser's runtime capabilities and returned metadata.
- */
-export interface CdpLike {
-    /** Read the merchant target on the page session; returns { targetInfo: CdpTargetInfo }. */
-    send(method: 'Target.getTargetInfo', params: Record<string, never>, sessionId: string): Promise<any>;
-    /** Enable root discovery events, including targets outside the page tree. */
-    send(method: 'Target.setDiscoverTargets', params: {
-        discover: boolean;
-    }, sessionId?: undefined): Promise<any>;
-    /** Read { targetInfos: CdpTargetInfo[] }; missing sessionId must remain browser-scoped. */
-    send(method: 'Target.getTargets', params?: Record<string, never>, sessionId?: undefined): Promise<any>;
-    /** Forward other CDP commands unchanged; unsupported commands must reject. */
-    send(method: string, params?: any, sessionId?: string): Promise<any>;
-    /** Deliver browser-root events as well as events from flattened child sessions. */
-    on(handler: (method: string, params: any, sessionId?: string) => void): void;
-}
-/** Browser Target metadata used to establish which checkout owns a worker. */
-export interface CdpTargetInfo {
-    targetId: string;
-    type: string;
-    /** Absent for the default browser context. */
-    browserContextId?: string;
-}
-export interface AttachOptions extends LifecycleOptions, ExecutionMetadata {
-    /** Explicit native hosted Stripe Checkout TEST integration; requires an Autopilot grant. */
-    stripeCheckout?: StripeCheckoutOptions;
-    /** Fallback when the browser cannot expose its top-level origin. Never an amount/payee authority. */
-    merchantOrigin?: string;
-    vault: VaultClient;
-    user: string;
-    merchant: string;
-    /** Return the caller's `Date.now()` at the pay click; the SDK reads it when the card request pauses. */
-    payClickedAt?: () => number | null | undefined;
-    /**
-     * Your hint at the amount, an integer in the currency's smallest unit or a
-     * decimal string in normal units, with its ISO 4217 code. See
-     * AuthorizeInput.amount: the processor's own amount is the higher authority
-     * and is read right before the card is sent; a hint lets a bad purchase be
-     * refused the moment it opens, and one that disagrees with the processor is
-     * refused with nothing charged.
-     */
-    amount?: number | string;
-    currency?: string;
-    /**
-     * The total the checkout page shows, the lowest authority: used only when
-     * neither the processor's request nor your `amount` names one. Pass a reader
-     * that returns an integer in the currency's smallest unit with its code
-     * (`{ amount: 4210, currency: 'usd' }`), read off the page however your
-     * page spells it; the adapters call it when a card request pauses, give it
-     * one second, and send nothing when it yields nothing. Absent: no page total.
-     */
-    pageAmount?: () => Promise<{
-        amount: number;
-        currency: string;
-    } | undefined>;
-    cardId?: string;
-    timeoutMs?: number;
-    /** Interception setup and request ownership deadline, separate from approval. Defaults to 30000 ms; maximum 300000 ms. */
-    attachmentTimeoutMs?: number;
-    /** Explicit payment endpoints to block if the registry cannot handle their method/format. Unlisted traffic is untouched. */
-    paymentEndpoints?: readonly PaymentEndpointGuard[];
-    onApprovalUrl?: (url: string) => void;
-    onEvent?: (e: {
-        type: string;
-        detail?: unknown;
-    }) => void;
-    /** Silence after a decline or timeout. Defaults to APPROVAL_COOLDOWN_MS. */
-    approvalCooldownMs?: number;
-    /** How long a hosted form the device already submitted stays refused on a re-post. Defaults to HOSTED_FORM_REPEAT_QUIET_MS. */
-    hostedFormRepeatQuietMs?: number;
-    /**
-     * After the cardholder approves with no live page request to answer (the
-     * page's own script gave up on its request while they decided), how long
-     * the approval waits for the page to ask again before it is retired as
-     * `merchant_never_retried`. Capped by the approval window. Defaults to
-     * MERCHANT_RETRY_WAIT_MS.
-     */
-    merchantRetryWaitMs?: number;
-}
-/**
- * Take over card tokenization for a page.
- *
- * IMPORTANT: card fields render in cross-origin iframes, which are separate CDP
- * targets. Enabling Fetch on the page session alone will never see the
- * tokenization request. This attaches recursively so every nested target is
- * armed, which is the whole reason this adapter exists.
- *
- * The patterns armed here come from the REGISTRY, not from a constant, so a PSP
- * the API knows about is paused without an SDK release — call
- * `vault.syncRegistry()` before attaching and every recognizer the server
- * serves is covered. They are a coarse pre-filter and are deliberately wider
- * than the recognizers (see cardUrlPatterns): each paused request is re-checked
- * with `isCardRequest` below and continued untouched unless it is an exact
- * match. Patterns are resolved once, at attach, so every nested target ends up
- * armed identically. Merchant profiles are the exception to syncing first: the
- * endpoint of every profile this build reviewed is armed whatever the sync said,
- * and each paused request is judged against the profiles armed when it pauses,
- * so a sync after attach arms a profile here as it does in attachToPlaywright.
- */
-export declare function attachToCdp(cdp: CdpLike, pageSessionId: string, opts: AttachOptions): Promise<CheckoutController>;
-/**
- * Playwright convenience wrapper — the path for cloud browsers that hand you a
- * CDP websocket (Kernel's `cdp_ws_url`, Browserbase, etc.):
- *
- *   const browser = await chromium.connectOverCDP(kernelBrowser.cdp_ws_url);
- *   const page = await browser.contexts()[0].newPage();
- *   await attachToPlaywright(page, { vault, user, merchant, amount });
- *
- * Uses Playwright's own request routing, which already spans subframes — see
- * the note in the body for why a hand-rolled CDPSession does not work here.
- */
-export declare function attachToPlaywright(page: any, opts: AttachOptions): Promise<CheckoutController>;