@agent-cards/checkout 0.8.0 → 0.9.0

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
+  }
+}

package/examples/preflight/stripe-script.direct.result.json

@@ -0,0 +1,92 @@
+{
+  "snapshot": {
+    "schema_version": 1,
+    "catalog_version": "2026-09-11.2",
+    "signals": [
+      {
+        "rule_id": "stripe-js-v3",
+        "kind": "script",
+        "frame_id": 0,
+        "parent_frame_id": null,
+        "visible": null
+      },
+      {
+        "rule_id": "stripe-js-script",
+        "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": "direct_sdk",
+      "version": "bundled"
+    },
+    "scenario": "one_time",
+    "scenario_defaulted": false,
+    "psp": "stripe",
+    "flow": null,
+    "mode": "token",
+    "status": "supported",
+    "support_scope": "processor_integration",
+    "checkout_flow_status": "unknown",
+    "candidates": [
+      {
+        "psp": "stripe",
+        "relevance": "undetermined",
+        "evidence": [
+          {
+            "rule_id": "stripe-js-v3",
+            "kind": "script",
+            "frame_id": 0,
+            "parent_frame_id": null,
+            "visible": null,
+            "origin": "https://js.stripe.com",
+            "path_pattern": "/v3/*"
+          },
+          {
+            "rule_id": "stripe-js-script",
+            "kind": "script",
+            "frame_id": 0,
+            "parent_frame_id": null,
+            "visible": null,
+            "origin": "https://js.stripe.com",
+            "path_pattern": "^/v3/?$"
+          }
+        ]
+      }
+    ],
+    "reason_codes": [
+      "checkout_flow_unidentified",
+      "processor_supported_by_integration"
+    ],
+    "limitations": [
+      "Processor assets alone do not establish the active card payment flow.",
+      "Tokenization replays a token response; it does not authorize a later PaymentIntent confirm.",
+      "Direct PaymentIntent confirms require a card-bearing template; the intent’s amount is read from Stripe and a hint sent as amount with currency must agree with it.",
+      "Direct SetupIntent confirms require a card-bearing template and save a card without charging it; future charges are merchant-managed.",
+      "Automatic token-to-PaymentIntent or token-to-SetupIntent continuation is unsupported; tokenization does not bind a later intent.",
+      "A token response does not bind a later PaymentIntent confirmation.",
+      "A token response does not bind a later SetupIntent confirmation."
+    ],
+    "missing_evidence": [
+      "active_checkout_flow"
+    ],
+    "observation": {
+      "complete": true,
+      "truncated": false,
+      "reasons": []
+    },
+    "scope": "preflight_hint",
+    "merchant_confirmation_required": true
+  }
+}

package/examples/preflight/stripe-script.observations.json

@@ -0,0 +1,16 @@
+{
+  "signals": [
+    {
+      "kind": "script",
+      "url": "https://js.stripe.com/v3/?example=discard-this-query",
+      "frame_id": 0,
+      "parent_frame_id": null,
+      "visible": null
+    }
+  ],
+  "observation": {
+    "complete": true,
+    "truncated": false,
+    "reasons": []
+  }
+}

package/examples/preflight/stripe-script.result.json

@@ -0,0 +1,87 @@
+{
+  "snapshot": {
+    "schema_version": 1,
+    "catalog_version": "2026-09-11.2",
+    "signals": [
+      {
+        "rule_id": "stripe-js-v3",
+        "kind": "script",
+        "frame_id": 0,
+        "parent_frame_id": null,
+        "visible": null
+      },
+      {
+        "rule_id": "stripe-js-script",
+        "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": "stripe",
+    "flow": null,
+    "mode": "token",
+    "status": "unknown",
+    "support_scope": null,
+    "checkout_flow_status": "unknown",
+    "candidates": [
+      {
+        "psp": "stripe",
+        "relevance": "undetermined",
+        "evidence": [
+          {
+            "rule_id": "stripe-js-v3",
+            "kind": "script",
+            "frame_id": 0,
+            "parent_frame_id": null,
+            "visible": null,
+            "origin": "https://js.stripe.com",
+            "path_pattern": "/v3/*"
+          },
+          {
+            "rule_id": "stripe-js-script",
+            "kind": "script",
+            "frame_id": 0,
+            "parent_frame_id": null,
+            "visible": null,
+            "origin": "https://js.stripe.com",
+            "path_pattern": "^/v3/?$"
+          }
+        ]
+      }
+    ],
+    "reason_codes": [
+      "checkout_flow_unidentified",
+      "integration_processor_undeclared"
+    ],
+    "limitations": [
+      "Processor assets alone do not establish the active card payment flow."
+    ],
+    "missing_evidence": [
+      "active_checkout_flow",
+      "integration_processor_capability"
+    ],
+    "observation": {
+      "complete": true,
+      "truncated": false,
+      "reasons": []
+    },
+    "scope": "preflight_hint",
+    "merchant_confirmation_required": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,24 +8,32 @@
   "exports": {
     ".": "./dist/index.js",
     "./cdp": "./dist/cdp.js",
-    "./playwright": "./dist/cdp.js"
+    "./playwright": "./dist/playwright.js",
+    "./preflight": "./dist/preflight.js",
+    "./preflight/catalog.json": "./dist/preflight-catalog.json",
+    "./preflight/schemas.json": "./dist/preflight-schemas.json"
   },
   "files": [
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "examples"
+    "examples",
+    "PREFLIGHT.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "_comment_build": "The public SDK keeps zero runtime dependencies. Its build vendors deterministic metadata and substitution artifacts from the internal payment core; TypeScript remains pinned.",
-    "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && npx -y -p typescript@5.9.3 tsc",
+    "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && npx -y -p typescript@5.9.3 tsc && node scripts/generate-preflight-contract.mjs",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs",
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs",
     "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs && node owned-shop-browser.test.mjs",
-    "check:payment-core": "node scripts/generate-payment-core.mjs --check"
+    "check:payment-core": "node scripts/generate-payment-core.mjs --check",
+    "test:preflight": "node --test preflight-package.test.mjs preflight-collector.test.mjs",
+    "test:preflight:browser": "node preflight-browser.test.mjs",
+    "pack:preview": "node scripts/pack-preflight-preview.mjs",
+    "test:preflight:schemas": "node --test preflight-schemas.test.mjs"
   },
   "keywords": [
     "payments",