@agent-cards/checkout 0.7.0 → 0.9.0

package/dist/registry.d.ts

@@ -50,25 +50,8 @@ export interface Recognizer {
     /** How the card reaches the processor; absent means 'token'. Carried verbatim by syncRegistry. */
     mode?: CheckoutMode;
 }
-/**
- * Every PSP the service recognizes, shipped with the package.
- *
- * This list is the FALLBACK that decides interception whenever
- * `syncRegistry()` is skipped or its fetch fails — and that failure is silent
- * by design ("never break checkout over a registry fetch"). A PSP missing here
- * is not an error: its tokenization request is simply never paused, the vault
- * is never consulted, and the shopper pays with their OWN card.
- *
- * It shipped with only 5 of the service's 22 recognizers, which meant 17
- * processors degraded to a silent wrong-card charge for any integrator whose
- * sync had not landed. Generated from the backend registry
- * (packages/backend/src/services/checkout-recognizers.ts) so the two cannot
- * drift by transcription; `sdk-registry-drift.test.ts` fails CI if they do.
- *
- * Syncing still matters — it is how a NEW processor arrives without an npm
- * release. This list is the floor, not the ceiling.
- */
-export declare const BUILTIN_REGISTRY: Recognizer[];
+import { BUILTIN_REGISTRY } from './builtin-registry.generated.js';
+export { BUILTIN_REGISTRY };
 export declare function findRecognizer(url: string, registry?: Recognizer[]): Recognizer | null;
 /**
  * Glob url patterns covering every host in `registry` — what to hand

package/dist/registry.js

@@ -6,194 +6,9 @@
  * site shares another. The list is served from the Agentcard API at runtime so
  * integrators pick up new processors without shipping a release.
  */
-/**
- * Every PSP the service recognizes, shipped with the package.
- *
- * This list is the FALLBACK that decides interception whenever
- * `syncRegistry()` is skipped or its fetch fails — and that failure is silent
- * by design ("never break checkout over a registry fetch"). A PSP missing here
- * is not an error: its tokenization request is simply never paused, the vault
- * is never consulted, and the shopper pays with their OWN card.
- *
- * It shipped with only 5 of the service's 22 recognizers, which meant 17
- * processors degraded to a silent wrong-card charge for any integrator whose
- * sync had not landed. Generated from the backend registry
- * (packages/backend/src/services/checkout-recognizers.ts) so the two cannot
- * drift by transcription; `sdk-registry-drift.test.ts` fails CI if they do.
- *
- * Syncing still matters — it is how a NEW processor arrives without an npm
- * release. This list is the floor, not the ceiling.
- */
-export const BUILTIN_REGISTRY = [
-    {
-        psp: 'shopify',
-        match: /(checkout\.pci\.shopifyinc\.com|deposit\.[a-z0-9-]+\.shopifycs\.com)\/sessions/i,
-        hosts: ["^checkout\\.pci\\.shopifyinc\\.com$", "^deposit\\.[a-z0-9-]+\\.shopifycs\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^shopify-identification-signature$/i],
-    },
-    {
-        psp: 'stripe',
-        match: /api\.stripe\.com\/v1\/(payment_methods|tokens|setup_intents\/seti_\w+\/confirm|payment_intents\/pi_\w+\/confirm)/i,
-        hosts: ["^api\\.stripe\\.com$"],
-        encoding: 'form',
-        passthroughHeaders: [/^authorization$/i, /^stripe-version$/i, /^x-stripe-client-user-agent$/i],
-    },
-    {
-        psp: 'braintree',
-        match: /payments(\.sandbox)?\.braintree-api\.com\/graphql/i,
-        hosts: ["^payments\\.braintree-api\\.com$", "^payments\\.sandbox\\.braintree-api\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^authorization$/i, /^braintree-version$/i],
-    },
-    {
-        psp: 'checkout_com',
-        // Flow's native card controller can use either tokenization host.
-        match: /(api|card-acquisition-gateway)(\.sandbox)?\.checkout\.com\/tokens/i,
-        hosts: [
-            "^api\\.checkout\\.com$", "^api\\.sandbox\\.checkout\\.com$",
-            "^card-acquisition-gateway\\.checkout\\.com$", "^card-acquisition-gateway\\.sandbox\\.checkout\\.com$",
-        ],
-        encoding: 'json',
-        passthroughHeaders: [/^authorization$/i],
-    },
-    {
-        psp: 'adyen',
-        match: /(checkoutshopper-(test|live(-[a-z]+)?)\.adyen\.com|([a-z0-9-]+\.)*adyenpayments\.com)\/checkoutshopper\/v1\/sessions\/[A-Za-z0-9_-]+\/payments/i,
-        hosts: ["^checkoutshopper-(test|live(-[a-z]+)?)\\.adyen\\.com$", "^([a-z0-9-]+\\.)*adyenpayments\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-        clientSideEncrypted: true,
-        mode: 'cse',
-    },
-    {
-        psp: 'tranzila',
-        match: /(direct\.tranzila\.com\/process\/n\/|directng\.tranzila\.com\/process\/?)/i,
-        hosts: ["^direct\\.tranzila\\.com$", "^directng\\.tranzila\\.com$"],
-        encoding: 'form',
-        passthroughHeaders: [],
-        mode: 'hosted_form',
-    },
-    {
-        psp: 'square',
-        match: /pci-connect\.squareup(?:sandbox)?\.com\/v2\/card-nonce/i,
-        hosts: ["^pci-connect\\.squareup\\.com$", "^pci-connect\\.squareupsandbox\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'authorize_net',
-        match: /(api2|apitest)\.authorize\.net\/xml\/v1\/request\.api/i,
-        hosts: ["^api2\\.authorize\\.net$", "^apitest\\.authorize\\.net$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'worldpay',
-        match: /(try\.)?access\.worldpay\.com\/(sessions\/card|verifiedTokens\/sessions)/i,
-        hosts: ["^access\\.worldpay\\.com$", "^try\\.access\\.worldpay\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^accept$/i],
-    },
-    {
-        psp: 'nuvei',
-        match: /(secure|ppp-test)\.safecharge\.com\/ppp\/api\/v1\/(?:cardTokenization|clientPayment|websdk\/initPaymentWithCardTokenization)\.do/i,
-        hosts: ["^secure\\.safecharge\\.com$", "^ppp-test\\.safecharge\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'airwallex',
-        match: /(checkout(\.sandbox)?\.airwallex\.com|pci-api(\.sandbox)?\.airwallex\.com)\/api\/v1\/pa\/(payment_intents\/[^\/?#]+\/confirm|payment_consents\/[^\/?#]+\/verify|payment_methods\/create)(\?|$)/i,
-        hosts: ["^checkout\\.airwallex\\.com$", "^checkout\\.sandbox\\.airwallex\\.com$", "^pci-api\\.airwallex\\.com$", "^pci-api\\.sandbox\\.airwallex\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^client-secret$/i, /^authorization$/i, /^x-auth-token$/i, /^x-on-behalf-of$/i, /^x-api-version$/i],
-    },
-    {
-        psp: 'rapyd',
-        match: /(api|sandboxapi)\.rapyd\.net\/v1\/(?:hosted\/collect\/card\/[^\/?#]+\/payment_method|checkout\/checkout_[A-Za-z0-9]+)(?:[?#]|$)/i,
-        hosts: ["^api\\.rapyd\\.net$", "^sandboxapi\\.rapyd\\.net$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'dlocal',
-        match: /ppmcc(-sandbox)?\.dlocal\.com\/cvault\/credit-card\/temporal/i,
-        hosts: ["^ppmcc\\.dlocal\\.com$", "^ppmcc-sandbox\\.dlocal\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^x-fields-api-key$/i, /^x-uow$/i, /^x-dlocal-infrav2$/i],
-    },
-    {
-        psp: 'ebanx',
-        match: /(?:(?:customer-frontier|customer|api-local-latam|api|sandbox-local-latam|sandbox)\.ebanx\.com|(?:api-diamond|api|sandbox)\.ebanxpay\.com)\/ws\/token/i,
-        hosts: ["^customer\\.ebanx\\.com$", "^customer-frontier\\.ebanx\\.com$", "^api\\.ebanx\\.com$", "^sandbox\\.ebanx\\.com$", "^api-local-latam\\.ebanx\\.com$", "^sandbox-local-latam\\.ebanx\\.com$", "^api-diamond\\.ebanxpay\\.com$", "^api\\.ebanxpay\\.com$", "^sandbox\\.ebanxpay\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'mercado_pago',
-        match: /api\.mercadopago\.com\/v1\/card_tokens(?![\w\/-])/i,
-        hosts: ["^api\\.mercadopago\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^x-product-id$/i],
-    },
-    {
-        psp: 'payu',
-        match: /(secure\.payu\.com|(merch-prod|secure)\.snd\.payu\.com)\/api\/front\/tokens/i,
-        hosts: ["^secure\\.payu\\.com$", "^(merch-prod|secure)\\.snd\\.payu\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'razorpay',
-        match: /api\.razorpay\.com\/v1\/(?:standard_checkout\/)?payments\/create\/(?:ajax|checkout|fees)/i,
-        hosts: ["^api\\.razorpay\\.com$"],
-        encoding: 'form',
-        passthroughHeaders: [/^x-razorpay-sessionid$/i, /^x-customer-access-token$/i],
-    },
-    {
-        psp: 'mollie',
-        match: /api\.cc\.mollie\.com\/v1\/card-tokens/i,
-        hosts: ["^api\\.cc\\.mollie\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'paysafe',
-        match: /(?:api(\.test)?\.paysafe\.com\/(?:paymenthub\/v1\/singleusepaymenthandles|js\/api\/v1\/tokenize)|hosted(\.test)?\.paysafe\.com\/checkout\/api\/v1\/tokenize)(?![\w\/-])/i,
-        hosts: ["^api\\.paysafe\\.com$", "^api\\.test\\.paysafe\\.com$", "^hosted\\.paysafe\\.com$", "^hosted\\.test\\.paysafe\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^authorization$/i, /^x-paysafe-credentials$/i, /^correlationid$/i],
-    },
-    {
-        psp: 'recurly',
-        match: /api(\.eu)?\.recurly\.com\/js\/v1\/token(?![\w-])/i,
-        hosts: ["^api\\.recurly\\.com$", "^api\\.eu\\.recurly\\.com$"],
-        encoding: 'form',
-        passthroughHeaders: [/^recurly-credential-checkout-hostname$/i],
-    },
-    {
-        psp: 'moneris',
-        match: /(www3|esqa|gateway|gatewayqa|gatewayt|gatewaydev)\.moneris\.com\/HPPtoken\/request\.php/i,
-        hosts: ["^www3\\.moneris\\.com$", "^esqa\\.moneris\\.com$", "^gateway\\.moneris\\.com$", "^gatewayqa\\.moneris\\.com$", "^gatewayt\\.moneris\\.com$", "^gatewaydev\\.moneris\\.com$"],
-        encoding: 'form',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'bambora',
-        match: /(api\.na\.bambora\.com|api\.bam\.shift4api\.net)\/scripts\/tokenization\/tokens/i,
-        hosts: ["^api\\.na\\.bambora\\.com$", "^api\\.bam\\.shift4api\\.net$"],
-        encoding: 'json',
-        passthroughHeaders: [],
-    },
-    {
-        psp: 'global_payments',
-        match: /(?:api\.heartlandportico\.com\/SecureSubmit\.v1\/api\/token|cert\.api2\.heartlandportico\.com\/Hps\.Exchange\.PosGateway\.Hpf\.v1\/api\/token|apis(?:\.sandbox)?(?:\.eu)?\.globalpay\.com\/ucp\/(?:merchants\/[^\/]+\/)?payment-methods)/i,
-        hosts: ["^api\\.heartlandportico\\.com$", "^cert\\.api2\\.heartlandportico\\.com$", "^apis\\.globalpay\\.com$", "^apis\\.sandbox\\.globalpay\\.com$", "^apis\\.eu\\.globalpay\\.com$", "^apis\\.sandbox\\.eu\\.globalpay\\.com$"],
-        encoding: 'json',
-        passthroughHeaders: [/^authorization$/i, /^x-gp-version$/i],
-    },
-];
+// Pinned fallback generated from the single shared processor catalog.
+import { BUILTIN_REGISTRY } from './builtin-registry.generated.js';
+export { BUILTIN_REGISTRY };
 export function findRecognizer(url, registry = BUILTIN_REGISTRY) {
     // Match the way the SERVER does, on the PARSED url — never as a substring of
     // the raw string. `match` is unanchored, so a raw-string test classifies any

package/dist/substitute.d.ts

@@ -29,14 +29,10 @@ export interface Substitutions {
      */
     remove?: string[];
 }
-/** The paused body could not take the substitutions. Not terminal: the next request may differ. */
-export declare class SubstitutionError extends Error {
+declare class SubstitutionErrorShape extends Error {
     constructor(message: string);
 }
-/**
- * Return the paused JSON body with `sub.fields` written over the same-named
- * string members of the object at `sub.at`. Throws SubstitutionError when the
- * body is not JSON, the path does not lead to an object, or any field is not
- * already a string there.
- */
-export declare function substituteEncryptedFields(body: string, sub: Substitutions): string;
+export type SubstitutionError = SubstitutionErrorShape;
+export declare const SubstitutionError: typeof SubstitutionErrorShape;
+export declare const substituteEncryptedFields: (body: string, sub: Substitutions) => string;
+export {};

package/dist/substitute.js

@@ -16,72 +16,8 @@
  * and Adyen refuses the mismatch), and a body that does not carry the fields
  * is refused rather than guessed at.
  */
-/** The paused body could not take the substitutions. Not terminal: the next request may differ. */
-export class SubstitutionError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'SubstitutionError';
-    }
-}
-const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
-function isPlainObject(v) {
-    return !!v && typeof v === 'object' && !Array.isArray(v);
-}
-/**
- * Return the paused JSON body with `sub.fields` written over the same-named
- * string members of the object at `sub.at`. Throws SubstitutionError when the
- * body is not JSON, the path does not lead to an object, or any field is not
- * already a string there.
- */
-export function substituteEncryptedFields(body, sub) {
-    if (!sub || sub.encoding !== 'json') {
-        throw new SubstitutionError(`unsupported substitution encoding: ${String(sub?.encoding)}`);
-    }
-    if (typeof sub.at !== 'string' || !sub.at)
-        throw new SubstitutionError('substitutions name no path');
-    if (!isPlainObject(sub.fields) || Object.keys(sub.fields).length === 0) {
-        throw new SubstitutionError('substitutions carry no fields');
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(body);
-    }
-    catch {
-        throw new SubstitutionError('the paused body is not JSON');
-    }
-    if (!isPlainObject(parsed))
-        throw new SubstitutionError('the paused body is not a JSON object');
-    let node = parsed;
-    for (const step of sub.at.split('.')) {
-        if (!step || FORBIDDEN_KEYS.has(step))
-            throw new SubstitutionError(`refusing substitution path ${sub.at}`);
-        const next = node[step];
-        if (!isPlainObject(next))
-            throw new SubstitutionError(`the paused body has no object at ${sub.at}`);
-        node = next;
-    }
-    for (const [key, value] of Object.entries(sub.fields)) {
-        if (FORBIDDEN_KEYS.has(key))
-            throw new SubstitutionError(`refusing substitution field ${key}`);
-        if (typeof value !== 'string' || value.length === 0)
-            throw new SubstitutionError(`substitution for ${key} is not a string`);
-        if (typeof node[key] !== 'string')
-            throw new SubstitutionError(`the paused body has no string field ${sub.at}.${key}`);
-    }
-    const remove = sub.remove ?? [];
-    if (!Array.isArray(remove))
-        throw new SubstitutionError('substitutions.remove is not a list');
-    for (const key of remove) {
-        if (typeof key !== 'string' || !key || FORBIDDEN_KEYS.has(key))
-            throw new SubstitutionError(`refusing removal of ${String(key)}`);
-        if (key in sub.fields)
-            throw new SubstitutionError(`substitution field ${key} is also listed for removal`);
-    }
-    // Only past every check, so a refused body is never half-written.
-    for (const [key, value] of Object.entries(sub.fields))
-        node[key] = value;
-    for (const key of remove)
-        if (Object.prototype.hasOwnProperty.call(node, key))
-            delete node[key];
-    return JSON.stringify(parsed);
-}
+// The implementation is bundled from the internal core; the published SDK
+// keeps its existing public types and does not require another package at runtime.
+import { substituteEncryptedFields as sharedSubstitute, SubstitutionError as SharedSubstitutionError, } from './substitutions.generated.js';
+export const SubstitutionError = SharedSubstitutionError;
+export const substituteEncryptedFields = sharedSubstitute;

package/dist/substitutions.generated.d.ts

@@ -0,0 +1,10 @@
+declare var SubstitutionError: {
+    new (message: any): {
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+};
+declare function substituteEncryptedFields(body: any, sub: any): string;
+export { SubstitutionError, substituteEncryptedFields };

package/dist/substitutions.generated.js

@@ -0,0 +1,66 @@
+// @ts-nocheck
+// Generated from @agent-cards/payment-core. Do not edit.
+// artifact-sha256: a74db713f1742d9bc5dc8efc78b364d2a69b255ee8da7f98345242f02114e6ce
+// src/substitutions.js
+var SubstitutionError = class extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SubstitutionError";
+    }
+};
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function isPlainObject(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function substituteEncryptedFields(body, sub) {
+    if (!sub || sub.encoding !== "json") {
+        throw new SubstitutionError(`unsupported substitution encoding: ${String(sub?.encoding)}`);
+    }
+    if (typeof sub.at !== "string" || !sub.at)
+        throw new SubstitutionError("substitutions name no path");
+    if (!isPlainObject(sub.fields) || Object.keys(sub.fields).length === 0) {
+        throw new SubstitutionError("substitutions carry no fields");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new SubstitutionError("the paused body is not JSON");
+    }
+    if (!isPlainObject(parsed))
+        throw new SubstitutionError("the paused body is not a JSON object");
+    let node = parsed;
+    for (const step of sub.at.split(".")) {
+        if (!step || FORBIDDEN_KEYS.has(step))
+            throw new SubstitutionError(`refusing substitution path ${sub.at}`);
+        const next = node[step];
+        if (!isPlainObject(next))
+            throw new SubstitutionError(`the paused body has no object at ${sub.at}`);
+        node = next;
+    }
+    for (const [key, value] of Object.entries(sub.fields)) {
+        if (FORBIDDEN_KEYS.has(key))
+            throw new SubstitutionError(`refusing substitution field ${key}`);
+        if (typeof value !== "string" || value.length === 0)
+            throw new SubstitutionError(`substitution for ${key} is not a string`);
+        if (typeof node[key] !== "string")
+            throw new SubstitutionError(`the paused body has no string field ${sub.at}.${key}`);
+    }
+    const remove = sub.remove ?? [];
+    if (!Array.isArray(remove))
+        throw new SubstitutionError("substitutions.remove is not a list");
+    for (const key of remove) {
+        if (typeof key !== "string" || !key || FORBIDDEN_KEYS.has(key))
+            throw new SubstitutionError(`refusing removal of ${String(key)}`);
+        if (key in sub.fields)
+            throw new SubstitutionError(`substitution field ${key} is also listed for removal`);
+    }
+    for (const [key, value] of Object.entries(sub.fields))
+        node[key] = value;
+    for (const key of remove)
+        if (Object.prototype.hasOwnProperty.call(node, key))
+            delete node[key];
+    return JSON.stringify(parsed);
+}
+export { SubstitutionError, substituteEncryptedFields };

package/examples/preflight/classify-direct.mjs

@@ -0,0 +1,21 @@
+// Run from an installed SDK or from this package after npm run build.
+// Optional argument: observations JSON path. Uses this SDK's bundled capabilities.
+import { readFile } from 'node:fs/promises';
+import {
+  normalizeCheckoutSignals,
+  assessCheckoutSupport,
+} from '@agent-cards/checkout/preflight';
+
+try {
+  const observations = JSON.parse(await readFile(
+    process.argv[2] ?? new URL('./stripe-script.observations.json', import.meta.url), 'utf8',
+  ));
+  const snapshot = normalizeCheckoutSignals(observations);
+  const result = assessCheckoutSupport(snapshot, { scenario: 'one_time' });
+
+  // Read support_scope and checkout_flow_status with status before continuing.
+  console.log(JSON.stringify({ snapshot, result }, null, 2));
+} catch {
+  console.error('Could not assess the observations. Check the JSON file against PREFLIGHT.md.');
+  process.exitCode = 1;
+}

package/examples/preflight/classify-kernel.mjs

@@ -0,0 +1,30 @@
+// Run from an installed SDK or from this package after npm run build.
+// Optional arguments: observations JSON path, profile JSON path, adapter version.
+import { readFile } from 'node:fs/promises';
+import {
+  normalizeCheckoutSignals,
+  assessCheckoutSupport,
+} from '@agent-cards/checkout/preflight';
+
+const [observationsPath, profilePath, adapterVersion = 'example-native-adapter'] = process.argv.slice(2);
+
+try {
+  const observations = JSON.parse(await readFile(
+    observationsPath ?? new URL('./stripe-script.observations.json', import.meta.url), 'utf8',
+  ));
+  const profile = JSON.parse(await readFile(
+    profilePath ?? new URL('./kernel-profile.empty.json', import.meta.url), 'utf8',
+  ));
+  const snapshot = normalizeCheckoutSignals(observations);
+  const result = assessCheckoutSupport(snapshot, {
+    scenario: 'one_time',
+    integration: { id: 'kernel_native', version: adapterVersion },
+    profile,
+  });
+
+  // Normalized snapshots contain reviewed rule IDs rather than raw asset URLs.
+  console.log(JSON.stringify({ snapshot, result }, null, 2));
+} catch {
+  console.error('Could not assess the observations. Check the JSON files and adapter version against PREFLIGHT.md.');
+  process.exitCode = 1;
+}

package/examples/preflight/inspect-browser.mjs

@@ -0,0 +1,44 @@
+// Read an existing checkout tab. Does not navigate, click, fill, or attach payment interception.
+// Install playwright-core in the consuming project before running this example.
+import { readFile } from 'node:fs/promises';
+import { chromium } from 'playwright-core';
+import { inspectCheckout } from '@agent-cards/checkout/playwright';
+
+let browser;
+try {
+  if (!process.env.CHECKOUT_CDP_URL) throw new Error('missing_connection');
+  const integration = process.env.CHECKOUT_INTEGRATION ?? 'kernel_native';
+  if (!['kernel_native', 'direct_sdk'].includes(integration)) throw new Error('invalid_integration');
+  const pageIndex = Number(process.env.CHECKOUT_PAGE_INDEX ?? 0);
+  if (!Number.isSafeInteger(pageIndex) || pageIndex < 0) throw new Error('invalid_page_index');
+
+  const profile = integration === 'kernel_native' && process.env.CHECKOUT_PROFILE
+    ? JSON.parse(await readFile(process.env.CHECKOUT_PROFILE, 'utf8'))
+    : undefined;
+  const options = integration === 'direct_sdk'
+    ? { scenario: 'one_time' }
+    : {
+      scenario: 'one_time',
+      integration: { id: 'kernel_native', version: process.env.CHECKOUT_ADAPTER_VERSION ?? null },
+      profile,
+    };
+
+  browser = await chromium.connectOverCDP(process.env.CHECKOUT_CDP_URL, { timeout: 15_000 });
+  const page = browser.contexts()[0]?.pages()[pageIndex];
+  if (!page) throw new Error('page_not_found');
+
+  const result = await inspectCheckout(page, options);
+  console.log(JSON.stringify(result, null, 2));
+} catch {
+  // A browser connection URL can contain a credential. Do not print connection errors.
+  console.error('Could not inspect the checkout. Check the CDP connection, page index, integration, and optional profile.');
+  process.exitCode = 1;
+} finally {
+  if (browser) {
+    // Disconnect this CDP client; the existing agent keeps its browser session.
+    await browser.close().catch(() => {
+      console.error('Could not disconnect the inspection client. Close this local process before inspecting again.');
+      process.exitCode = 1;
+    });
+  }
+}

package/examples/preflight/kernel-profile.empty.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "profile_version": "kernel-template-1",
+  "catalog_version": "2026-09-11.2",
+  "integration": {
+    "id": "kernel_native",
+    "version": "example-native-adapter"
+  },
+  "entries": [],
+  "processor_entries": []
+}

package/examples/preflight/mollie-hosted.observations.json

@@ -0,0 +1,23 @@
+{
+  "signals": [
+    {
+      "kind": "document",
+      "url": "https://www.mollie.com/checkout/credit-card/session/synthetic-example",
+      "frame_id": 0,
+      "parent_frame_id": null,
+      "visible": true
+    },
+    {
+      "kind": "script",
+      "url": "https://js.mollie.com/v2/mollie.js",
+      "frame_id": 0,
+      "parent_frame_id": null,
+      "visible": null
+    }
+  ],
+  "observation": {
+    "complete": true,
+    "truncated": false,
+    "reasons": []
+  }
+}

package/examples/preflight/mollie-hosted.result.json

@@ -0,0 +1,103 @@
+{
+  "snapshot": {
+    "schema_version": 1,
+    "catalog_version": "2026-09-11.2",
+    "signals": [
+      {
+        "rule_id": "mollie-hosted-credit-card",
+        "kind": "document",
+        "frame_id": 0,
+        "parent_frame_id": null,
+        "visible": true
+      },
+      {
+        "rule_id": "mollie-components-script",
+        "kind": "script",
+        "frame_id": 0,
+        "parent_frame_id": null,
+        "visible": null
+      },
+      {
+        "rule_id": "mollie-components-v2",
+        "kind": "script",
+        "frame_id": 0,
+        "parent_frame_id": null,
+        "visible": null
+      }
+    ],
+    "observation": {
+      "complete": true,
+      "truncated": false,
+      "reasons": []
+    }
+  },
+  "result": {
+    "schema_version": 1,
+    "catalog_version": "2026-09-11.2",
+    "integration": {
+      "id": "kernel_native",
+      "version": "example-native-adapter"
+    },
+    "scenario": "one_time",
+    "scenario_defaulted": false,
+    "psp": "mollie",
+    "flow": "mollie.hosted_components",
+    "mode": "token",
+    "status": "unknown",
+    "support_scope": null,
+    "checkout_flow_status": "identified",
+    "candidates": [
+      {
+        "psp": "mollie",
+        "relevance": "active",
+        "evidence": [
+          {
+            "rule_id": "mollie-hosted-credit-card",
+            "kind": "document",
+            "frame_id": 0,
+            "parent_frame_id": null,
+            "visible": true,
+            "origin": "https://www.mollie.com",
+            "path_pattern": "/checkout/credit-card/session/:session"
+          },
+          {
+            "rule_id": "mollie-components-script",
+            "kind": "script",
+            "frame_id": 0,
+            "parent_frame_id": null,
+            "visible": null,
+            "origin": "https://js.mollie.com",
+            "path_pattern": "/v2/mollie.js"
+          },
+          {
+            "rule_id": "mollie-components-v2",
+            "kind": "script",
+            "frame_id": 0,
+            "parent_frame_id": null,
+            "visible": null,
+            "origin": "https://js.mollie.com",
+            "path_pattern": "^/v2/mollie\\.js$"
+          }
+        ]
+      }
+    ],
+    "reason_codes": [
+      "integration_flow_undeclared"
+    ],
+    "limitations": [
+      "The payment request must match the supported Mollie Components card-token format.",
+      "Authentication and merchant confirmation must finish in the merchant browser.",
+      "Merchant configuration, card eligibility and processor approval still determine whether the purchase succeeds."
+    ],
+    "missing_evidence": [
+      "integration_flow_capability"
+    ],
+    "observation": {
+      "complete": true,
+      "truncated": false,
+      "reasons": []
+    },
+    "scope": "preflight_hint",
+    "merchant_confirmation_required": true
+  }
+}