@agent-cards/checkout 0.12.0 → 0.14.0

package/dist/preflight-playwright.js

@@ -1,7 +1,9 @@
-import { normalizeCheckoutSignals, assessCheckoutSupport, } from './preflight.js';
+import { normalizeCheckoutSignals, assessCheckoutSupport, cardEntryAttributable, } from './preflight.js';
 const EVENTS = ['framenavigated', 'frameattached', 'framedetached'];
 const DEADLINE = Symbol('checkout inspection deadline');
 const DEFAULTS = { timeoutMs: 1_500, maxFrames: 64, maxSignals: 2_048, maxSnapshotBytes: 262_144 };
+/** Frames at one nesting depth are read together. A remote CDP connection pays per round trip, not per frame. */
+const CONCURRENCY = 8;
 const encoder = new TextEncoder();
 function bounded(value, fallback, maximum, minimum = 1) {
     if (value === undefined)
@@ -27,6 +29,28 @@ async function beforeDeadline(operation, deadline) {
             clearTimeout(timer);
     }
 }
+function httpOrigin(url) {
+    if (!url || !/^https?:/i.test(url))
+        return null;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/** Run `worker` over `items` with bounded concurrency; results keep the input order. */
+async function inBatches(items, size, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(size, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await worker(items[index]);
+        }
+    }));
+    return results;
+}
 /** Read only frame, external asset and form locations; return reviewed rule IDs, never raw URLs. */
 export async function collectCheckoutSignals(page, options = {}) {
     const limits = {
@@ -41,6 +65,7 @@ export async function collectCheckoutSignals(page, options = {}) {
     const registered = [];
     let transientBytes = 0;
     let truncated = false;
+    let stopped = false;
     const changed = () => { reasons.add('navigation_changed'); };
     const limit = (reason) => { reasons.add(reason); truncated = true; };
     const append = (signal) => {
@@ -58,6 +83,24 @@ export async function collectCheckoutSignals(page, options = {}) {
         signals.push(signal);
         return true;
     };
+    const stop = () => {
+        if (stopped)
+            return true;
+        if (performance.now() >= deadline) {
+            reasons.add('collection_timeout');
+            stopped = true;
+        }
+        else if (signals.length >= limits.maxSignals) {
+            limit('signal_limit');
+            stopped = true;
+        }
+        else if (truncated && reasons.has('snapshot_limit'))
+            stopped = true;
+        return stopped;
+    };
+    // Hostnames of visible nested card-entry frames outside the top document's origin. They stay
+    // local to this call; only the attribution verdict reaches the observation.
+    const cardEntryHosts = new Set();
     try {
         for (const event of EVENTS) {
             page.on(event, changed);
@@ -73,29 +116,25 @@ export async function collectCheckoutSignals(page, options = {}) {
         const ids = new Map(frames.map((frame, index) => [frame, index]));
         if (frames.length > limits.maxFrames)
             limit('frame_limit');
+        const topOrigin = frames.length ? httpOrigin(initialUrls.get(frames[0])) : null;
         const visibility = new Map();
-        const ordered = frames.slice(0, limits.maxFrames).sort((a, b) => {
-            const depth = (frame) => {
-                const visited = new Set();
-                while (frame.parentFrame() && !visited.has(frame)) {
-                    visited.add(frame);
-                    frame = frame.parentFrame();
-                }
-                return visited.size;
-            };
-            return depth(a) - depth(b);
-        });
-        for (const frame of ordered) {
-            if (performance.now() >= deadline) {
-                reasons.add('collection_timeout');
-                break;
-            }
-            if (signals.length >= limits.maxSignals) {
-                limit('signal_limit');
-                break;
+        const depth = (frame) => {
+            const visited = new Set();
+            while (frame.parentFrame() && !visited.has(frame)) {
+                visited.add(frame);
+                frame = frame.parentFrame();
             }
-            if (truncated && reasons.has('snapshot_limit'))
-                break;
+            return visited.size;
+        };
+        // Parents settle before their children so visibility can propagate; siblings share round trips.
+        const levels = new Map();
+        for (const frame of frames.slice(0, limits.maxFrames)) {
+            const level = depth(frame);
+            levels.set(level, [...(levels.get(level) ?? []), frame]);
+        }
+        const readFrame = async (frame) => {
+            if (stop())
+                return null;
             const parent = frame.parentFrame();
             const frame_id = ids.get(frame);
             const parent_frame_id = parent ? ids.get(parent) ?? null : null;
@@ -103,8 +142,9 @@ export async function collectCheckoutSignals(page, options = {}) {
             try {
                 if (frame.isDetached()) {
                     reasons.add('frame_unavailable');
-                    continue;
+                    return null;
                 }
+                let released;
                 if (parent) {
                     if (!ids.has(parent))
                         reasons.add('frame_unavailable');
@@ -139,8 +179,9 @@ export async function collectCheckoutSignals(page, options = {}) {
                         visible = visible === false || ownVisibility === false ? false : visible === null || ownVisibility === null ? null : true;
                     }
                     finally {
-                        // Disposal only releases our automation handle. A stalled disposal cannot extend the inspection deadline.
-                        await beforeDeadline(() => element.dispose(), deadline);
+                        // Disposal only releases our automation handle and overlaps the document read below.
+                        // A stalled disposal still cannot extend the inspection deadline.
+                        released = beforeDeadline(() => element.dispose(), deadline).then(() => undefined, error => error);
                     }
                 }
                 visibility.set(frame, visible);
@@ -149,6 +190,19 @@ export async function collectCheckoutSignals(page, options = {}) {
                     let bytes = 0;
                     let signalLimit = false;
                     let byteLimit = false;
+                    const shown = (element) => {
+                        if (!element.isConnected)
+                            return false;
+                        for (let current = element; current;) {
+                            const style = getComputedStyle(current);
+                            if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse' || style.opacity === '0')
+                                return false;
+                            const root = current.getRootNode();
+                            current = current.parentElement ?? (root instanceof ShadowRoot ? root.host : null);
+                        }
+                        const rect = element.getBoundingClientRect();
+                        return rect.width > 0 && rect.height > 0;
+                    };
                     const elements = document.querySelectorAll('script[src], iframe[src], form[action]');
                     for (let index = 0; index < elements.length; index++) {
                         if (index >= remaining) {
@@ -176,31 +230,63 @@ export async function collectCheckoutSignals(page, options = {}) {
                             byteLimit = true;
                             break;
                         }
-                        let visible = null;
-                        if (kind !== 'script') {
-                            visible = element.isConnected;
-                            for (let current = element; current && visible;) {
-                                const style = getComputedStyle(current);
-                                if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse' || style.opacity === '0')
-                                    visible = false;
-                                const root = current.getRootNode();
-                                current = current.parentElement ?? (root instanceof ShadowRoot ? root.host : null);
-                            }
-                            const rect = element.getBoundingClientRect();
-                            visible = visible && rect.width > 0 && rect.height > 0;
-                        }
-                        collected.push({ kind, url, visible });
+                        collected.push({ kind, url, visible: kind === 'script' ? null : shown(element) });
+                    }
+                    // Card-entry detection reads field metadata only: the autocomplete token or the
+                    // control's name and id. Values, labels and page text are never read.
+                    let cardEntry = false;
+                    const inputs = document.querySelectorAll('input');
+                    for (let index = 0; index < inputs.length && index < 256 && !cardEntry; index++) {
+                        const input = inputs[index];
+                        const type = (input.getAttribute('type') || 'text').toLowerCase();
+                        if (['hidden', 'submit', 'button', 'checkbox', 'radio', 'image', 'reset', 'file', 'range', 'color'].includes(type))
+                            continue;
+                        const autocomplete = (input.getAttribute('autocomplete') || '').trim().toLowerCase();
+                        const label = `${input.getAttribute('name') || ''} ${input.getAttribute('id') || ''}`.toLowerCase().replace(/[^a-z0-9]+/g, '');
+                        const cardField = /^cc-(?:number|csc|exp|exp-month|exp-year)$/.test(autocomplete)
+                            || !label.includes('gift') && /cardnumber|cardnum|cardno|ccnumber|ccnum|ccno|cvv|cvc|csc|securitycode|cardcode/.test(label);
+                        if (cardField && shown(input))
+                            cardEntry = true;
                     }
                     const documentUrl = document.URL;
                     if (documentUrl.length * 3 > byteBudget)
                         byteLimit = true;
-                    return { documentUrl: byteLimit && documentUrl.length * 3 > byteBudget ? '' : documentUrl, collected, signalLimit, byteLimit };
+                    return { documentUrl: byteLimit && documentUrl.length * 3 > byteBudget ? '' : documentUrl, collected, signalLimit, byteLimit, cardEntry };
                 }, { remaining: Math.max(0, limits.maxSignals - signals.length - 1), byteBudget: Math.max(0, limits.maxSnapshotBytes - transientBytes) }), deadline);
+                const releaseError = released ? await released : undefined;
+                if (releaseError !== undefined)
+                    throw releaseError;
                 if (frame.isDetached())
                     reasons.add('frame_unavailable');
-                if (data.documentUrl !== initialUrls.get(frame) || frame.url() !== initialUrls.get(frame))
+                // Committed URLs are compared with committed URLs. The document URL is compared only for a
+                // frame that committed an http(s) document: a script-created frame written through
+                // document.open() inherits the merchant URL without navigating anywhere.
+                const initial = initialUrls.get(frame) ?? '';
+                if (frame.url() !== initial || (/^https?:/i.test(initial) && data.documentUrl !== '' && data.documentUrl !== initial))
                     reasons.add('navigation_changed');
-                append({ kind: parent ? 'frame' : 'document', url: data.documentUrl, frame_id, parent_frame_id, visible });
+                return { frame_id, parent_frame_id, nested: parent !== null, visible, data };
+            }
+            catch (error) {
+                if (error === DEADLINE) {
+                    reasons.add('collection_timeout');
+                    stopped = true;
+                    return null;
+                }
+                // Browser errors can include complete merchant URLs. Return a bounded reason instead.
+                reasons.add('frame_unavailable');
+                return null;
+            }
+        };
+        for (const level of [...levels.keys()].sort((a, b) => a - b)) {
+            if (stop())
+                break;
+            const outcomes = await inBatches(levels.get(level), CONCURRENCY, readFrame);
+            // Append in frame order so identical pages produce identical observations.
+            for (const outcome of outcomes) {
+                if (!outcome)
+                    continue;
+                const { data, frame_id, parent_frame_id, nested, visible } = outcome;
+                append({ kind: nested ? 'frame' : 'document', url: data.documentUrl, frame_id, parent_frame_id, visible });
                 for (const signal of data.collected) {
                     if (!append({ ...signal, frame_id, parent_frame_id, visible: visible === false ? false : signal.kind === 'script' ? visible : visible === null ? null : signal.visible }))
                         break;
@@ -209,14 +295,11 @@ export async function collectCheckoutSignals(page, options = {}) {
                     limit('signal_limit');
                 if (data.byteLimit)
                     limit('snapshot_limit');
-            }
-            catch (error) {
-                if (error === DEADLINE) {
-                    reasons.add('collection_timeout');
-                    break;
+                if (nested && visible === true && data.cardEntry === true) {
+                    const origin = httpOrigin(data.documentUrl);
+                    if (origin && origin !== topOrigin)
+                        cardEntryHosts.add(new URL(origin).hostname);
                 }
-                // Browser errors can include complete merchant URLs. Return a bounded reason instead.
-                reasons.add('frame_unavailable');
             }
         }
         if (performance.now() >= deadline)
@@ -239,7 +322,17 @@ export async function collectCheckoutSignals(page, options = {}) {
             }
         }
     }
-    let snapshot = normalizeCheckoutSignals({ signals, observation: { complete: reasons.size === 0, truncated, reasons: [...reasons] } });
+    const observation = () => ({ complete: reasons.size === 0, truncated, reasons: [...reasons] });
+    let snapshot = normalizeCheckoutSignals({ signals, observation: observation() });
+    // Visible card controls on a site no evidenced processor owns mean the card form belongs to
+    // something the catalog has not reviewed. The observation is then incomplete, so a co-loaded
+    // SDK script stays a candidate instead of becoming the selected processor. A snapshot past the
+    // byte budget is already incomplete and is bounded below instead.
+    if (encoder.encode(JSON.stringify(snapshot)).length <= limits.maxSnapshotBytes
+        && [...cardEntryHosts].some(host => !cardEntryAttributable(snapshot, host))) {
+        reasons.add('card_entry_unrecognized');
+        snapshot = normalizeCheckoutSignals({ signals, observation: observation() });
+    }
     if (encoder.encode(JSON.stringify(snapshot)).length > limits.maxSnapshotBytes) {
         limit('snapshot_limit');
         const boundedSnapshot = normalizeCheckoutSignals({ signals: [], observation: { complete: false, truncated, reasons: [...reasons] } });

package/dist/preflight-schemas.json

@@ -56,7 +56,7 @@
             },
             "url": {
               "type": "string",
-              "maxLength": 4096
+              "maxLength": 65536
             }
           }
         }
@@ -90,6 +90,7 @@
                 "navigation_changed",
                 "invalid_observation",
                 "invalid_url",
+                "card_entry_unrecognized",
                 "collection_incomplete"
               ]
             }
@@ -162,7 +163,7 @@
             "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,119}$"
           },
           "catalog_version": {
-            "const": "2026-09-14.1"
+            "const": "2026-09-15.1"
           },
           "integration": {
             "type": "object",
@@ -208,6 +209,7 @@
               "properties": {
                 "psp": {
                   "enum": [
+                    "spreedly",
                     "shopify",
                     "stripe",
                     "braintree",
@@ -358,7 +360,7 @@
         "const": 1
       },
       "catalog_version": {
-        "const": "2026-09-14.1"
+        "const": "2026-09-15.1"
       },
       "signals": {
         "type": "array",
@@ -440,6 +442,8 @@
                 "paysafe-js-v1-latest",
                 "paysafe-js-v1-fields",
                 "paysafe-js-v1-fields-host-2",
+                "spreedly-iframe-v1-script",
+                "spreedly-native-card-frame",
                 "recurly-js-v4",
                 "recurly-hosted-field-v1",
                 "recurly-hosted-field-v1-host-2",
@@ -450,10 +454,29 @@
                 "bambora-na-fields-1-0-5-39",
                 "global-payments-js-4-1-3",
                 "global-payments-js-v1-alias",
+                "tranzila-terminal-hosted-page",
+                "square-card-element-frame",
+                "authorize-net-sim-hosted-form",
+                "worldpay-hosted-payment-page",
+                "rapyd-hosted-checkout-page",
+                "dlocal-smart-fields-parent",
+                "dlocal-smart-card-fields",
+                "mercado-pago-secure-fields-frame",
+                "mercado-pago-checkout-pro-card-form",
                 "square-web-sdk-sandbox",
                 "paysafe-js-test",
                 "worldpay-checkout-sdk-try",
-                "authorize-net-accept-test"
+                "authorize-net-accept-test",
+                "tranzila-terminal-hosted-page-directng",
+                "square-card-element-frame-sandbox",
+                "authorize-net-sim-hosted-form-secure2",
+                "worldpay-hosted-payment-page-test",
+                "rapyd-hosted-checkout-page-sandbox",
+                "adyen-secured-fields-live-us",
+                "adyen-secured-fields-live-au",
+                "adyen-secured-fields-live-apse",
+                "adyen-secured-fields-live-in",
+                "adyen-secured-fields-live-nea"
               ]
             },
             "kind": {
@@ -520,6 +543,7 @@
                 "navigation_changed",
                 "invalid_observation",
                 "invalid_url",
+                "card_entry_unrecognized",
                 "collection_incomplete"
               ]
             }
@@ -550,7 +574,7 @@
         "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,119}$"
       },
       "catalog_version": {
-        "const": "2026-09-14.1"
+        "const": "2026-09-15.1"
       },
       "integration": {
         "type": "object",
@@ -596,6 +620,7 @@
           "properties": {
             "psp": {
               "enum": [
+                "spreedly",
                 "shopify",
                 "stripe",
                 "braintree",
@@ -753,7 +778,7 @@
         "const": 1
       },
       "catalog_version": {
-        "const": "2026-09-14.1"
+        "const": "2026-09-15.1"
       },
       "integration": {
         "type": "object",
@@ -937,6 +962,8 @@
                       "paysafe-js-v1-latest",
                       "paysafe-js-v1-fields",
                       "paysafe-js-v1-fields-host-2",
+                      "spreedly-iframe-v1-script",
+                      "spreedly-native-card-frame",
                       "recurly-js-v4",
                       "recurly-hosted-field-v1",
                       "recurly-hosted-field-v1-host-2",
@@ -947,10 +974,29 @@
                       "bambora-na-fields-1-0-5-39",
                       "global-payments-js-4-1-3",
                       "global-payments-js-v1-alias",
+                      "tranzila-terminal-hosted-page",
+                      "square-card-element-frame",
+                      "authorize-net-sim-hosted-form",
+                      "worldpay-hosted-payment-page",
+                      "rapyd-hosted-checkout-page",
+                      "dlocal-smart-fields-parent",
+                      "dlocal-smart-card-fields",
+                      "mercado-pago-secure-fields-frame",
+                      "mercado-pago-checkout-pro-card-form",
                       "square-web-sdk-sandbox",
                       "paysafe-js-test",
                       "worldpay-checkout-sdk-try",
-                      "authorize-net-accept-test"
+                      "authorize-net-accept-test",
+                      "tranzila-terminal-hosted-page-directng",
+                      "square-card-element-frame-sandbox",
+                      "authorize-net-sim-hosted-form-secure2",
+                      "worldpay-hosted-payment-page-test",
+                      "rapyd-hosted-checkout-page-sandbox",
+                      "adyen-secured-fields-live-us",
+                      "adyen-secured-fields-live-au",
+                      "adyen-secured-fields-live-apse",
+                      "adyen-secured-fields-live-in",
+                      "adyen-secured-fields-live-nea"
                     ]
                   },
                   "kind": {
@@ -1046,6 +1092,7 @@
                 "navigation_changed",
                 "invalid_observation",
                 "invalid_url",
+                "card_entry_unrecognized",
                 "collection_incomplete"
               ]
             }

package/dist/preflight.generated.d.ts

@@ -1,11 +1,12 @@
 /** Advisory page discovery. These rules never admit a payment destination. */
 export declare const CHECKOUT_PREFLIGHT_VERSION = "1";
-export declare const CHECKOUT_PREFLIGHT_CATALOG_VERSION = "2026-09-14.1";
+export declare const CHECKOUT_PREFLIGHT_CATALOG_VERSION = "2026-09-15.1";
 export declare const CHECKOUT_PREFLIGHT_LIMITS: Readonly<{
     frames: 64;
     signals: 2048;
     snapshot_bytes: 262144;
     url_length: 4096;
+    raw_url_length: 65536;
 }>;
 export type CheckoutSignalKind = 'document' | 'frame' | 'script' | 'iframe' | 'form';
 export type CheckoutScenario = 'one_time' | 'save_card' | 'subscription_initial' | 'subscription_renewal';
@@ -126,6 +127,7 @@ export declare function getCheckoutPreflightCatalog(): {
         signals: 2048;
         snapshot_bytes: 262144;
         url_length: 4096;
+        raw_url_length: 65536;
     }>;
     known_psps: {
         psp: string;
@@ -148,6 +150,69 @@ export declare function getCheckoutPreflightCatalog(): {
         variant_unverified?: string;
     }[];
     processors: readonly [{
+        readonly psp: "spreedly";
+        readonly status: "supported";
+        readonly mode: "token";
+        readonly operations: readonly [{
+            readonly id: "spreedly.card_request";
+            readonly effect: "processor_specific_card_request";
+            readonly amount_binding: "unestablished";
+            readonly psp: "spreedly";
+            readonly version: 1;
+            readonly mode: "token";
+            readonly autopilot_eligible: false;
+            readonly requires: "reviewed_final_payment_and_continuation_evidence";
+        }];
+        readonly scenarios: {
+            readonly one_time: {
+                readonly status: "supported";
+                readonly reason: "card_request_adapter_implemented";
+                readonly requirements: readonly ["actual_payment_request_validation", "merchant_confirmation"];
+            };
+            readonly save_card: {
+                readonly status: "conditional";
+                readonly reason: "merchant_card_storage_and_consent_required";
+                readonly requirements: readonly ["actual_payment_request_validation", "merchant_confirmation", "stored_card_consent", "merchant_card_saved"];
+            };
+            readonly subscription_initial: {
+                readonly status: "conditional";
+                readonly reason: "merchant_card_storage_and_consent_required";
+                readonly requirements: readonly ["actual_payment_request_validation", "merchant_confirmation", "stored_card_consent", "merchant_subscription_confirmation"];
+            };
+            readonly subscription_renewal: {
+                readonly status: "outside_vault";
+                readonly reason: "renewal_managed_by_merchant";
+                readonly requirements: readonly ["verify_merchant_billing"];
+            };
+        };
+        readonly limitations: readonly ["Only the listed request format is recognized; a recognized processor is not verified merchant coverage.", "The adapter handles the Spreedly iframe v1 restricted endpoint for new credit cards through the encrypted relay.", "The merchant environment and optional signed iframe session must remain valid. Expired signatures require a fresh merchant checkout.", "Spreedly creates a payment-method token; the merchant still completes any gateway payment and authentication."];
+        readonly unsupported_variants: readonly [{
+            readonly variant: "general_javascript_api";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "The general payment_methods.json endpoint is outside the reviewed native iframe path.";
+        }, {
+            readonly variant: "saved_card_or_recache";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "Stored tokens and CVV-only recache requests are outside new-card tokenization.";
+        }, {
+            readonly variant: "click_to_pay_or_bank_account";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "Click to Pay and bank-account request shapes require separate validation.";
+        }, {
+            readonly variant: "gateway_purchase_or_distribution";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "Gateway transactions and payment-method distribution are outside the card tokenization adapter.";
+        }];
+        readonly processor_amount: "none";
+        readonly challenge_surface: "merchant_browser";
+        readonly merchant_confirmation_required: true;
+        readonly live_validation: "not_established_by_catalog";
+        readonly sources: readonly ["src/definitions.js", "src/operations.js", "src/backend.js", "src/spreedly.js", "../checkout/src/prepared-processor.ts"];
+    }, {
         readonly psp: "shopify";
         readonly status: "supported";
         readonly mode: "token";
@@ -1347,6 +1412,14 @@ export declare function getCheckoutPreflightCatalog(): {
     };
     observation_reason_codes: string[];
 };
+/**
+ * Whether a visible card-entry frame on `hostname` can belong to a processor already evidenced in the
+ * snapshot. A collector reports `card_entry_unrecognized` when this is false, so co-loaded SDK scripts
+ * cannot be presented as the processor behind card controls that no reviewed fingerprint explains, and
+ * a card form with no processor evidence at all is reported rather than passing as an empty page.
+ * The hostname stays local to the caller; nothing here enters evidence.
+ */
+export declare function cardEntryAttributable(input: CheckoutSignalSnapshot | unknown, hostname: unknown): boolean;
 /** Classify a sanitized snapshot. No browser, HTTP, or payment operations occur here. */
 export declare function assessCheckoutSupport(input: CheckoutSignalSnapshot | unknown, options?: CheckoutPreflightOptions): CheckoutSupportResult;
 /** Machine-readable transport shapes; semantic compatibility is checked by the classifier. */