@visa/cli 4.1.0-rc.190 → 4.1.0-rc.191

package/dist/checkout-engine/adapters/generic.d.ts

@@ -43,9 +43,11 @@ export declare function contactNameShapes(contact: Contact, cardholderName?: str
 };
 export declare function fillContactFieldMap(page: Page, fields: FieldMap, contact: Contact, opts?: {
     fillTimeoutMs?: number;
+    detect?: (page: Page) => Promise<DetectResult>;
 }): Promise<FilledField[]>;
 export declare function fillFieldMap(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact, opts?: {
     fillTimeoutMs?: number;
+    detect?: (page: Page) => Promise<DetectResult>;
 }): Promise<FilledField[]>;
 /**
  * Re-detect and adopt fresh entries for every card field after the panel is

package/dist/checkout-engine/adapters/generic.js

@@ -120,6 +120,90 @@ export function summarizeFillFailure(error) {
     return error.split('\n')[0].slice(0, 120);
 }
 const DEFAULT_FILL_TIMEOUT_MS = 5000;
+/**
+ * How many times one fill pass may re-detect after a locator goes stale.
+ *
+ * One re-mount usually invalidates a whole block of fields at once, so a single
+ * pass normally recovers all of them. The cap is here so a page that re-mounts
+ * on EVERY keystroke degrades to the old timeout behaviour instead of looping.
+ */
+const MAX_FILL_REDETECTS = 3;
+/**
+ * True when a detected field's locator no longer resolves to anything.
+ *
+ * `data-ca-id` is stamped onto the live nodes during detection, so it is an
+ * identity that dies with the node. A merchant that re-mounts part of its form
+ * mid-fill (address autocomplete is the common one) replaces those nodes with
+ * fresh, unstamped ones — the old locator then matches NOTHING and the fill
+ * waits out its entire timeout on an element that can never appear.
+ */
+async function locatorIsMissing(page, entry) {
+    try {
+        return (await resolveLocator(page, entry).count()) === 0;
+    }
+    catch {
+        // A frame that went away, a detached context: let the fill run and report
+        // the real error rather than inventing a diagnosis here.
+        return false;
+    }
+}
+/**
+ * Contact and address roles — plain inputs whose value can be read straight
+ * back. The credential roles are deliberately absent: they sit in PSP iframes
+ * that tokenize and reformat what they are given, so a readback there compares
+ * against a value the merchant never promised to keep, and they are not what an
+ * address re-mount disturbs anyway.
+ */
+const READBACK_ROLES = [
+    'name',
+    'nameFirst',
+    'nameLast',
+    'email',
+    'phone',
+    'addressLine1',
+    'addressLine2',
+    'city',
+    'state',
+    'postalCode',
+    'country',
+];
+/**
+ * Downgrade any field whose value did not survive to the end of the pass.
+ *
+ * Only runs when a re-mount was actually observed, and only for the roles
+ * above. A page that rebuilds its address block on EVERY edit erases the field
+ * we just filled when we fill the NEXT one, so a fill can report success over a
+ * box that is empty by the time anyone submits it. Recovering from a re-mount
+ * must not buy that recovery with a false claim: without this, the engine would
+ * hand the pre-submit gate a clean bill of health for an empty form — and the
+ * gate would let it through. Before the recovery existed these fields failed
+ * loudly instead, and a wrong "filled" is worse than an honest refusal.
+ */
+async function downgradeFieldsThatDidNotHold(page, fields, filled) {
+    for (const record of filled) {
+        if (!record.ok)
+            continue;
+        if (!READBACK_ROLES.includes(record.role))
+            continue;
+        const entry = fields[record.role];
+        if (!entry)
+            continue;
+        let held;
+        try {
+            const loc = resolveLocator(page, entry);
+            held = (await loc.count()) > 0 && (await loc.inputValue()).trim() !== '';
+        }
+        catch {
+            // Unreadable is not evidence of empty. Leave the record alone rather than
+            // failing a field that is probably fine.
+            continue;
+        }
+        if (held)
+            continue;
+        record.ok = false;
+        record.error = 'value did not survive a re-render of the form';
+    }
+}
 async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
     const base = {
         role,
@@ -159,23 +243,24 @@ export function contactNameShapes(contact, cardholderName) {
 }
 async function fillFields(page, fields, credential, contact, opts = {}) {
     const fillTimeoutMs = opts.fillTimeoutMs ?? DEFAULT_FILL_TIMEOUT_MS;
+    const detect = opts.detect ?? detectFields;
     const filled = [];
     const { fullName, first, last } = contactNameShapes(contact, credential?.cardholderName);
     // Order matters a little: contact/name before card is harmless, but we fill
     // card fields explicitly per role so order is not load-bearing.
+    //
+    // A job records the ROLE it fills, never a captured entry: the entry is
+    // resolved from the live map at the moment the job runs, because a re-mount
+    // part-way through this pass can replace the element a role points at.
+    // `value` is derived from that same entry, since whether a role is a <select>
+    // (and which options it offers) is a property of the element we end up with.
     const jobs = [];
-    const add = (role, entry, value, display) => {
-        if (!entry)
-            return;
-        // Skip fields that are not currently visible (e.g. a collapsed accordion
-        // panel or a not-yet-reached step). The executor reveals them and re-fills.
-        if (entry.visible === false)
+    const add = (role, detected, value, display) => {
+        // Gate on the role having been detected at all. Roles absent from the
+        // original map stay out of scope even if a later pass would find them.
+        if (!detected)
             return;
-        jobs.push({
-            role,
-            entry,
-            run: async () => fillOne(page, role, entry, value(), display(), fillTimeoutMs),
-        });
+        jobs.push({ role, value, display });
     };
     if (credential) {
         add('number', fields.number, () => credential.pan, () => maskPan(credential.pan));
@@ -190,30 +275,22 @@ async function fillFields(page, fields, credential, contact, opts = {}) {
     // Expiry display values are always redacted: the expiry is part of the
     // keyable credential (DPAN + expiry + DAVV) and never enters the log.
     if (credential && fields.expCombined) {
-        const e = fields.expCombined;
-        const v = expCombinedValue(e, credential.expMonth, credential.expYear);
-        add('expCombined', e, () => v, () => maskExpiry());
+        add('expCombined', fields.expCombined, (e) => expCombinedValue(e, credential.expMonth, credential.expYear), () => maskExpiry());
     }
     if (credential && fields.expMonth) {
-        const e = fields.expMonth;
-        const value = e.tag === 'select'
+        add('expMonth', fields.expMonth, (e) => e.tag === 'select'
             ? (monthOptionValue(e.options ?? [], credential.expMonth) ?? pad2(credential.expMonth))
-            : pad2(credential.expMonth);
-        add('expMonth', e, () => value, () => maskExpiry());
+            : pad2(credential.expMonth), () => maskExpiry());
     }
     if (credential && fields.expYear) {
-        const e = fields.expYear;
-        let value;
-        if (e.tag === 'select') {
-            value = yearOptionValue(e.options ?? [], credential.expYear) ?? String(credential.expYear);
-        }
-        else if ((e.maxlength ?? 0) === 2) {
-            value = pad2(credential.expYear % 100);
-        }
-        else {
-            value = String(credential.expYear);
-        }
-        add('expYear', e, () => value, () => maskExpiry());
+        add('expYear', fields.expYear, (e) => {
+            if (e.tag === 'select') {
+                return yearOptionValue(e.options ?? [], credential.expYear) ?? String(credential.expYear);
+            }
+            if ((e.maxlength ?? 0) === 2)
+                return pad2(credential.expYear % 100);
+            return String(credential.expYear);
+        }, () => maskExpiry());
     }
     // Contact / shipping. Display values are always redacted: these are PII and
     // the evidence log is built to be persistable.
@@ -230,23 +307,52 @@ async function fillFields(page, fields, credential, contact, opts = {}) {
     if (contact.postalCode)
         add('postalCode', fields.postalCode, () => contact.postalCode, () => redactContact('postalCode', contact.postalCode));
     if (fields.state && contact.state) {
-        const e = fields.state;
         const wanted = contact.state;
-        const value = e.tag === 'select' ? (matchOption(e.options ?? [], [wanted]) ?? wanted) : wanted;
-        add('state', e, () => value, () => redactContact('state', value));
+        add('state', fields.state, (e) => (e.tag === 'select' ? (matchOption(e.options ?? [], [wanted]) ?? wanted) : wanted), (value) => redactContact('state', value));
     }
     if (fields.country && contact.country) {
-        const e = fields.country;
-        const value = e.tag === 'select'
-            ? (matchOption(e.options ?? [], [contact.country]) ?? contact.country)
-            : contact.country;
-        add('country', e, () => value, () => redactContact('country', value));
+        const wanted = contact.country;
+        add('country', fields.country, (e) => (e.tag === 'select' ? (matchOption(e.options ?? [], [wanted]) ?? wanted) : wanted), (value) => redactContact('country', value));
     }
-    for (const j of jobs) {
-        const r = await j.run();
-        if (r)
-            filled.push(r);
+    // The map is re-read per job, and a re-detect REPLACES it wholesale rather
+    // than patching the one entry that went stale: a detection pass re-stamps
+    // every element from scratch, so an id handed out by the previous pass can
+    // afterwards name a different element. Adopting the fresh map for every
+    // remaining job is what keeps a recovery from filling the wrong box.
+    let current = fields;
+    let redetects = 0;
+    for (const job of jobs) {
+        let entry = current[job.role];
+        // Skip fields that are not currently visible (e.g. a collapsed accordion
+        // panel or a not-yet-reached step). The executor reveals them and re-fills.
+        if (!entry || entry.visible === false)
+            continue;
+        let relocated = false;
+        if (redetects < MAX_FILL_REDETECTS && (await locatorIsMissing(page, entry))) {
+            redetects++;
+            const fresh = await detect(page).then((r) => r.fields, () => null);
+            if (fresh) {
+                current = fresh;
+                const next = current[job.role];
+                if (next && next.visible !== false) {
+                    entry = next;
+                    relocated = true;
+                }
+                // If the role is gone from the fresh map, deliberately keep the stale
+                // entry and let the fill fail on it. Skipping would leave NO record of
+                // the field, and the pre-submit gate reads "never attempted" as
+                // "nothing to worry about" — which is how an incomplete form gets
+                // submitted. A recorded failure refuses; a silent skip does not.
+            }
+        }
+        const value = job.value(entry);
+        const result = await fillOne(page, job.role, entry, value, job.display(value), fillTimeoutMs);
+        filled.push(relocated ? { ...result, relocated: true } : result);
     }
+    // Only when a re-mount was actually seen: everywhere else the page never
+    // moved under us and the readback would be pure cost.
+    if (redetects > 0)
+        await downgradeFieldsThatDidNotHold(page, current, filled);
     return filled;
 }
 // Credential-free contact prefill for merchants that must calculate shipping,

package/dist/checkout-engine/executor.js

@@ -1095,6 +1095,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                     value: f.value,
                     ok: f.ok,
                     error: f.error,
+                    ...(f.relocated ? { relocated: true } : {}),
                 });
             }
             const numberOk = fill.filled.some((f) => f.role === 'number' && f.ok);

package/dist/checkout-engine/types.d.ts

@@ -23,6 +23,14 @@ export type FilledField = {
     value: string;
     ok: boolean;
     error?: string;
+    /**
+     * The detected node was gone by the time this field's turn came (the merchant
+     * re-mounted that part of the form mid-fill) and a fresh detection pass was
+     * used to find it again. Worth surfacing: a merchant that re-mounts is a
+     * merchant whose fills are order-sensitive, which is the first thing to know
+     * when one of them later refuses.
+     */
+    relocated?: boolean;
 };
 export type FillResult = {
     ok: boolean;