@agent-cards/checkout 0.8.0 → 0.9.1

package/dist/preflight-playwright.d.ts

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,262 @@
+import { normalizeCheckoutSignals, assessCheckoutSupport, } 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 };
+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);
+    }
+}
+/** 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;
+    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;
+    };
+    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 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;
+            }
+            if (truncated && reasons.has('snapshot_limit'))
+                break;
+            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');
+                    continue;
+                }
+                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. A stalled disposal cannot extend the inspection deadline.
+                        await beforeDeadline(() => element.dispose(), deadline);
+                    }
+                }
+                visibility.set(frame, visible);
+                const data = await beforeDeadline(() => frame.evaluate(({ remaining, byteBudget }) => {
+                    const collected = [];
+                    let bytes = 0;
+                    let signalLimit = false;
+                    let byteLimit = false;
+                    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;
+                        }
+                        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 });
+                    }
+                    const documentUrl = document.URL;
+                    if (documentUrl.length * 3 > byteBudget)
+                        byteLimit = true;
+                    return { documentUrl: byteLimit && documentUrl.length * 3 > byteBudget ? '' : documentUrl, collected, signalLimit, byteLimit };
+                }, { remaining: Math.max(0, limits.maxSignals - signals.length - 1), byteBudget: Math.max(0, limits.maxSnapshotBytes - transientBytes) }), deadline);
+                if (frame.isDetached())
+                    reasons.add('frame_unavailable');
+                if (data.documentUrl !== initialUrls.get(frame) || frame.url() !== initialUrls.get(frame))
+                    reasons.add('navigation_changed');
+                append({ kind: parent ? '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');
+            }
+            catch (error) {
+                if (error === DEADLINE) {
+                    reasons.add('collection_timeout');
+                    break;
+                }
+                // Browser errors can include complete merchant URLs. Return a bounded reason instead.
+                reasons.add('frame_unavailable');
+            }
+        }
+        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');
+            }
+        }
+    }
+    let snapshot = normalizeCheckoutSignals({ signals, observation: { complete: reasons.size === 0, truncated, reasons: [...reasons] } });
+    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);
+}