@agent-cards/checkout 0.18.0 → 0.21.0

package/dist/preflight-playwright.d.ts

@@ -1,34 +0,0 @@
-import { type CheckoutSignalSnapshot, type CheckoutPreflightOptions, type CheckoutSupportResult } from './preflight.js';
-/** The public Playwright methods used by inspection; no Playwright dependency is required. */
-export interface CheckoutInspectionFrame {
-    url(): string;
-    parentFrame(): CheckoutInspectionFrame | null;
-    isDetached(): boolean;
-    evaluate<Result, Argument>(fn: (argument: Argument) => Result | Promise<Result>, argument: Argument): Promise<Result>;
-    frameElement(): Promise<{
-        evaluate<Result>(fn: (element: Element) => Result | Promise<Result>): Promise<Result>;
-        dispose(): Promise<void>;
-    }>;
-}
-export interface CheckoutInspectionPage {
-    frames(): CheckoutInspectionFrame[];
-    on(event: 'framenavigated' | 'frameattached' | 'framedetached', listener: (frame: CheckoutInspectionFrame) => void): unknown;
-    off(event: 'framenavigated' | 'frameattached' | 'framedetached', listener: (frame: CheckoutInspectionFrame) => void): unknown;
-}
-export interface CheckoutCollectionOptions {
-    /** Total inspection deadline, including all frames. Default 1,500 ms; maximum 10,000 ms. */
-    timeoutMs?: number;
-    /** Maximum frame count. Default and maximum 64. */
-    maxFrames?: number;
-    /** Maximum document and asset observations. Default and maximum 2,048. */
-    maxSignals?: number;
-    /** Maximum transient observation and returned snapshot size. Default and maximum 262,144 bytes; minimum 512 bytes. */
-    maxSnapshotBytes?: number;
-}
-export type InspectCheckoutOptions = CheckoutPreflightOptions & {
-    collection?: CheckoutCollectionOptions;
-};
-/** Read only frame, external asset and form locations; return reviewed rule IDs, never raw URLs. */
-export declare function collectCheckoutSignals(page: CheckoutInspectionPage, options?: CheckoutCollectionOptions): Promise<CheckoutSignalSnapshot>;
-/** Inspect once without preparing or submitting a checkout. */
-export declare function inspectCheckout(page: CheckoutInspectionPage, options?: InspectCheckoutOptions): Promise<CheckoutSupportResult>;

package/dist/preflight-playwright.js

@@ -1,355 +0,0 @@
-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)
-        return fallback;
-    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
-        throw new TypeError('Checkout inspection limits must be positive integers within the documented bounds.');
-    }
-    return value;
-}
-async function beforeDeadline(operation, deadline) {
-    const remaining = deadline - performance.now();
-    if (remaining <= 0)
-        throw DEADLINE;
-    let timer;
-    try {
-        return await Promise.race([
-            Promise.resolve().then(operation),
-            new Promise((_resolve, reject) => { timer = setTimeout(() => reject(DEADLINE), remaining); }),
-        ]);
-    }
-    finally {
-        if (timer !== undefined)
-            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 = {
-        timeoutMs: bounded(options.timeoutMs, DEFAULTS.timeoutMs, 10_000),
-        maxFrames: bounded(options.maxFrames, DEFAULTS.maxFrames, DEFAULTS.maxFrames),
-        maxSignals: bounded(options.maxSignals, DEFAULTS.maxSignals, DEFAULTS.maxSignals),
-        maxSnapshotBytes: bounded(options.maxSnapshotBytes, DEFAULTS.maxSnapshotBytes, DEFAULTS.maxSnapshotBytes, 512),
-    };
-    const deadline = performance.now() + limits.timeoutMs;
-    const reasons = new Set();
-    const signals = [];
-    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) => {
-        if (signals.length >= limits.maxSignals) {
-            limit('signal_limit');
-            return false;
-        }
-        // Raw merchant URLs exist only during this call and never enter errors or the return value.
-        const bytes = encoder.encode(JSON.stringify(signal)).length;
-        if (transientBytes + bytes > limits.maxSnapshotBytes) {
-            limit('snapshot_limit');
-            return false;
-        }
-        transientBytes += bytes;
-        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);
-            registered.push(event);
-        }
-        const observedFrames = page.frames();
-        const roots = observedFrames.filter(frame => frame.parentFrame() === null);
-        if (roots.length !== 1)
-            reasons.add('frame_unavailable');
-        // Frame zero always denotes the main document, regardless of adapter enumeration order.
-        const frames = roots.length === 1 ? [roots[0], ...observedFrames.filter(frame => frame !== roots[0])] : observedFrames;
-        const initialUrls = new Map(frames.map(frame => [frame, frame.url()]));
-        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 depth = (frame) => {
-            const visited = new Set();
-            while (frame.parentFrame() && !visited.has(frame)) {
-                visited.add(frame);
-                frame = frame.parentFrame();
-            }
-            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;
-            let visible = parent ? visibility.get(parent) ?? null : true;
-            try {
-                if (frame.isDetached()) {
-                    reasons.add('frame_unavailable');
-                    return null;
-                }
-                let released;
-                if (parent) {
-                    if (!ids.has(parent))
-                        reasons.add('frame_unavailable');
-                    let acquisitionTimedOut = false;
-                    const acquisition = Promise.resolve().then(() => frame.frameElement());
-                    void acquisition.then(element => {
-                        if (acquisitionTimedOut)
-                            void Promise.resolve().then(() => element.dispose()).catch(() => { });
-                    }, () => { });
-                    let element;
-                    try {
-                        element = await beforeDeadline(() => acquisition, deadline);
-                    }
-                    catch (error) {
-                        acquisitionTimedOut = true;
-                        throw error;
-                    }
-                    try {
-                        const ownVisibility = await beforeDeadline(() => element.evaluate(node => {
-                            if (!node.isConnected)
-                                return null;
-                            for (let current = node; 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 = node.getBoundingClientRect();
-                            return rect.width > 0 && rect.height > 0;
-                        }), deadline);
-                        visible = visible === false || ownVisibility === false ? false : visible === null || ownVisibility === null ? null : true;
-                    }
-                    finally {
-                        // 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);
-                const data = await beforeDeadline(() => frame.evaluate(({ remaining, byteBudget }) => {
-                    const collected = [];
-                    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) {
-                            signalLimit = true;
-                            break;
-                        }
-                        const element = elements[index];
-                        const kind = element.tagName === 'SCRIPT' ? 'script' : element.tagName === 'IFRAME' ? 'iframe' : 'form';
-                        const source = element.getAttribute(kind === 'form' ? 'action' : 'src');
-                        if (!source)
-                            continue;
-                        if (source.length > byteBudget - bytes) {
-                            byteLimit = true;
-                            break;
-                        }
-                        let url;
-                        try {
-                            url = new URL(source, document.baseURI).href;
-                        }
-                        catch {
-                            continue;
-                        }
-                        bytes += url.length * 3 + 128;
-                        if (bytes > byteBudget) {
-                            byteLimit = true;
-                            break;
-                        }
-                        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, 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');
-                // 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');
-                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;
-                }
-                if (data.signalLimit)
-                    limit('signal_limit');
-                if (data.byteLimit)
-                    limit('snapshot_limit');
-                if (nested && visible === true && data.cardEntry === true) {
-                    const origin = httpOrigin(data.documentUrl);
-                    if (origin && origin !== topOrigin)
-                        cardEntryHosts.add(new URL(origin).hostname);
-                }
-            }
-        }
-        if (performance.now() >= deadline)
-            reasons.add('collection_timeout');
-        const finalFrames = page.frames();
-        if (frames.length !== finalFrames.length || finalFrames.some(frame => !ids.has(frame) || frame.url() !== initialUrls.get(frame))) {
-            reasons.add('navigation_changed');
-        }
-    }
-    catch {
-        reasons.add('frame_unavailable');
-    }
-    finally {
-        for (const event of registered) {
-            try {
-                page.off(event, changed);
-            }
-            catch {
-                reasons.add('collection_incomplete');
-            }
-        }
-    }
-    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] } });
-        let bytes = encoder.encode(JSON.stringify(boundedSnapshot)).length;
-        for (const signal of snapshot.signals) {
-            const addedBytes = encoder.encode(JSON.stringify(signal)).length + (boundedSnapshot.signals.length ? 1 : 0);
-            if (bytes + addedBytes > limits.maxSnapshotBytes)
-                break;
-            boundedSnapshot.signals.push(signal);
-            bytes += addedBytes;
-        }
-        snapshot = boundedSnapshot;
-    }
-    return snapshot;
-}
-/** Inspect once without preparing or submitting a checkout. */
-export async function inspectCheckout(page, options = {}) {
-    const { collection, ...assessment } = options;
-    return assessCheckoutSupport(await collectCheckoutSignals(page, collection), assessment);
-}