@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/lib/gift-card-redemption-build.js

@@ -0,0 +1,249 @@
+'use strict';
+
+const { isBlank } = require('./value-utils.js');
+const { WIX_GIFT_CARDS_APP_ID } = require('./gift-card-build.js');
+
+// rp-target-wix — given the bridge-plugin activity rows
+// for one card, netted per source order, build the deterministic
+// POST /ecom/v1/gift-cards/redeem request body: { code, amount, orderId, appId }.
+//
+// The mechanism itself is LIVE-VERIFIED IN ISOLATION 2026-08-17: a real Redeem Gift Card call against a real imported
+// order correctly decremented a card's balance (10 -> 7) and returned a transactionId. What this
+// module is BLOCKED on is the INPUT, not the mechanism: the activity row shape it consumes comes
+// from the bridge plugin, which is code-only and not yet installed/live-tested on any
+// real WordPress site. This builder is ready to consume that
+// data the moment it exists.
+//
+// Ordering requirement: the source card's issuance must already
+// be recorded in the crosswalk (gift-card-build.js ran first) and the order this redemption
+// belongs to must already be imported (order-channel-build.js), before a
+// redemption can be linked — this module does not check either precondition itself, it only
+// requires the caller to already have both resolved ids in hand.
+
+// A single activity row's `action` label is NOT independently confirmed against the plugin's
+// exact stored string — the available evidence only documents the function name
+// (`debit_gift_cards()`), not the literal VARCHAR value it writes. Classifying by the SIGN of
+// `amount` instead is grounded directly in the plugin's own documented balance computation
+// (balance = SUM(activity.amount)), not a guessed string.
+function isRedemptionActivityRow(row) {
+  return row != null && Number(row.amount) < 0;
+}
+
+// Fixed 2026-08-18: a naive "replay every negative row" double-removes value the
+// source has already restored. Most gift-card plugins (PW Gift Cards included, per its own
+// debit/credit activity model) can credit a card back when an order tied
+// to a prior debit is later cancelled, refunded, or fails — a -10/+10 pair for the SAME order
+// must net to zero, not emit a 10.00 redemption. This exact reversal mechanism is not
+// independently verified against the plugin's own PHP source in this repo yet, but netting per
+// order is the only sound behavior regardless of the specific trigger, since ANY reversal for ANY
+// reason produces exactly this shape: two-or-more rows, same order, opposite signs.
+//
+// Returns an array of 0 or 1 netted-activity objects (`{ orderId, amount, activityIds, rows }`) —
+// an array, not a bare object, so a fully-reversed or never-redeemed order (net >= 0) can return
+// "nothing to build" the same way a not-found lookup would, rather than a sentinel the caller has
+// to remember to check.
+function findRedemptionActivityForOrder(activityRows, sourceOrderId) {
+  const rowsForOrder = (activityRows || []).filter(
+    (row) => row != null && Number(row.order_id) === Number(sourceOrderId)
+  );
+  if (rowsForOrder.length === 0) return [];
+
+  const net = rowsForOrder.reduce((sum, row) => {
+    const rowAmount = Number(row.amount);
+    return sum + (Number.isFinite(rowAmount) ? rowAmount : 0);
+  }, 0);
+
+  // net >= 0: no debit at all for this order, or a later reversal already restored it in full —
+  // either way, nothing left to redeem in Wix.
+  if (net >= 0) return [];
+
+  return [{
+    orderId: sourceOrderId,
+    amount: net,
+    activityIds: rowsForOrder.map((row) => row.activity_id),
+    rows: rowsForOrder,
+  }];
+}
+
+// Fixed 2026-08-18: Policy C's own soundness has a precondition this
+// module did not check. Replaying every order-linked redemption reaches the CORRECT final balance
+// only when the drift between face value and the bridge's reported current balance is FULLY
+// explained by order-linked activity. The bridge explicitly allows manual, non-order-linked
+// adjustments (extract_order_id() returns null for these): a
+// card can carry face value 25, a manual credit +5 (order_id null), and a real redemption -10
+// (order-linked) — the bridge's own current balance is 20, but blindly replaying only the
+// order-linked -10 debit would leave the Wix card at 25 - 10 = 15, silently wrong by 5.
+//
+// This is the pre-write reconciliation required before Policy C may be used
+// for a card: predict the final balance IF only order-linked activity is replayed (summing, per
+// order, the same net-per-order computation findRedemptionActivityForOrder itself uses — a
+// net-positive order, like the one that issued the card, correctly contributes nothing to
+// replay, exactly the way findRedemptionActivityForOrder already treats it), then compare that
+// prediction against the bridge's own reported CURRENT balance (which sums literally every row,
+// order-linked or not — no need to specifically detect "the issuance row" or "manual rows"; any
+// unaccounted-for activity of any kind surfaces as a mismatch here). A mismatch means Policy C is
+// not safe for this card — it must gap for manual review, or fall back to Policy B (create
+// directly at the bridge's verified current balance) instead.
+function verifyPolicyCReplaySufficiency({ activityRows, faceValue, bridgeCurrentBalance } = {}) {
+  const face = faceValue == null ? NaN : Number(faceValue);
+  const bridgeBalance = bridgeCurrentBalance == null ? NaN : Number(bridgeCurrentBalance);
+  if (!Number.isFinite(face) || !Number.isFinite(bridgeBalance)) {
+    return {
+      safe: false,
+      gap: {
+        code: 'policy-c-verification-missing-input',
+        summary: `faceValue (${JSON.stringify(faceValue)}) and bridgeCurrentBalance (${JSON.stringify(bridgeCurrentBalance)}) must both be finite numbers to verify Policy C is safe for this card.`,
+      },
+    };
+  }
+
+  const orderIds = Array.from(
+    new Set((activityRows || []).map((row) => (row == null ? null : row.order_id)).filter((orderId) => orderId != null))
+  );
+
+  const totalReplayAmount = orderIds.reduce((sum, orderId) => {
+    const net = findRedemptionActivityForOrder(activityRows, orderId);
+    return sum + net.reduce((s, entry) => s + Math.abs(entry.amount), 0);
+  }, 0);
+
+  const predictedFinalBalance = Math.round((face - totalReplayAmount) * 100) / 100;
+  const roundedBridgeBalance = Math.round(bridgeBalance * 100) / 100;
+  const drift = Math.round((roundedBridgeBalance - predictedFinalBalance) * 100) / 100;
+
+  if (Math.abs(drift) > 0.005) {
+    return {
+      safe: false,
+      predictedFinalBalance,
+      bridgeCurrentBalance: roundedBridgeBalance,
+      drift,
+      gap: {
+        code: 'policy-c-unexplained-activity',
+        summary: `replaying only this card's order-linked activity would leave it at ${predictedFinalBalance}, but the bridge reports a current balance of ${roundedBridgeBalance} (drift ${drift}) — some activity (e.g. a manual, non-order-linked adjustment) is not accounted for by order-linked replay. Policy C is not safe for this card; either gap it for manual review, or use Policy B (create directly at the bridge's verified current balance) instead.`,
+      },
+    };
+  }
+
+  return { safe: true, predictedFinalBalance, bridgeCurrentBalance: roundedBridgeBalance };
+}
+
+// One order's redemption -> one Redeem Gift Card body. `sourceOrderId` is the WooCommerce order
+// id whose redemption is being linked; the netted activity for it is DERIVED INTERNALLY from
+// `options.activityRows` via findRedemptionActivityForOrder — see the fix note below for why this
+// is no longer a caller-supplied parameter. `wixCode` is the code the card was actually CREATED
+// with (gift-card-build.js's payload.code — after any options.normalizeCode stripping), resolved
+// from the crosswalk row this card's issuance produced (sourceStableKey
+// `woocommerce:giftCard:<number>`), never re-derived from the raw source number here. `wixOrderId`
+// is the real Wix order id returned by Import Order for the order this redemption belongs to.
+//
+// Fixed 2026-08-18: `options.balancePolicy` is now REQUIRED and must be
+// `'C'` — the only one of the three balance policies (A, B, C) a redemption replay is
+// safe under. Policy A is explicitly defined as "face value, no replay"; building a redemption
+// for an 'A' card would contradict that policy's own accepted-overstatement design instead of
+// implementing it (an 'A' card's overstatement is meant to be corrected manually, via
+// disable-and-replace, or accepted — not silently patched by a redemption call the card's own
+// policy never called for). Policy B already creates the card at its verified CURRENT balance —
+// replaying the same historical redemption on a 'B' card would double-decrement it (once
+// implicitly, by never having had the spend reflected in a face-value creation that never
+// happened; once again by this call). 'C' is the one policy that means what a redemption call
+// does: create at face value, then bring the balance down to correct by replaying real,
+// order-linked redemptions — see gift-card-build.js's resolveCardBalance for its (identical to
+// 'A') creation-time behavior.
+//
+// Fixed 2026-08-18: declaring Policy C is not by itself proof that
+// replay will reach the correct balance for THIS card — see verifyPolicyCReplaySufficiency's own
+// comment for the manual-adjustment failure mode this closes. `options.activityRows`,
+// `options.faceValue`, and `options.bridgeCurrentBalance` are now REQUIRED alongside
+// `balancePolicy: 'C'`, and this function runs that verification itself on every call rather than
+// trusting a boolean the caller claims to have already checked — a card that fails verification
+// gets a named gap here, never a payload.
+//
+// Fixed 2026-08-18: the fourth pass's own verification was DISCONNECTED
+// from the payload it gated. `netActivity` used to be a second, independently caller-supplied
+// argument — nothing checked that it was actually derived from the same `activityRows` the
+// verification ran against, so a caller (or a bug) could pass activity rows that verify cleanly
+// while separately passing a fabricated `netActivity.amount` and still get a real redemption
+// payload built for an amount that was never verified at all. There is now exactly ONE source of
+// truth: `sourceOrderId` plus `options.activityRows`, and this function derives the netted
+// activity itself via `findRedemptionActivityForOrder` — the same call, on the same rows,
+// `verifyPolicyCReplaySufficiency` already used — so the built payload can never diverge from
+// what was verified.
+function buildGiftCardRedemption(sourceOrderId, options) {
+  const { wixCode, wixOrderId, wixAppId = WIX_GIFT_CARDS_APP_ID, balancePolicy, activityRows, faceValue, bridgeCurrentBalance } = options || {};
+  const notes = [];
+
+  if (balancePolicy !== 'C') {
+    return {
+      payload: null,
+      gaps: [{
+        code: 'redemption-replay-requires-policy-c',
+        summary: `options.balancePolicy must be "C" to build a redemption — got ${JSON.stringify(balancePolicy)}. Policy A means "face value, no replay"; replaying a redemption on an 'A' card contradicts that policy instead of implementing it. Policy B already creates the card at its verified current balance; replaying the same redemption on a 'B' card would double-decrement it. Only a card explicitly declared Policy C — face value now, corrected later by replaying real order-linked redemptions — may be redeemed here.`,
+      }],
+      notes,
+    };
+  }
+
+  const verification = verifyPolicyCReplaySufficiency({ activityRows, faceValue, bridgeCurrentBalance });
+  if (!verification.safe) {
+    return { payload: null, gaps: [verification.gap], notes };
+  }
+
+  if (isBlank(wixCode)) {
+    return {
+      payload: null,
+      gaps: [{ code: 'missing-wix-code', summary: 'options.wixCode is required — resolve it from the crosswalk row this card was issued under (sourceStableKey woocommerce:giftCard:<number>) before building a redemption; never re-derive it from the raw source number, which may have been normalized at creation.' }],
+      notes,
+    };
+  }
+  if (isBlank(wixOrderId)) {
+    return {
+      payload: null,
+      gaps: [{ code: 'missing-wix-order-id', summary: 'options.wixOrderId is required — the order this redemption is linked to must already be imported before its redemptions can be recorded.' }],
+      notes,
+    };
+  }
+
+  // Derived from the SAME activityRows the verification above just ran against — never a
+  // separately caller-supplied value (see the fifth-pass fix note above).
+  const [netActivity = null] = findRedemptionActivityForOrder(activityRows, sourceOrderId);
+
+  const netAmount = netActivity == null ? null : Number(netActivity.amount);
+  if (netActivity == null || !Number.isFinite(netAmount) || netAmount >= 0) {
+    return {
+      payload: null,
+      gaps: [{
+        code: 'not-a-net-redemption',
+        summary: `net activity for order ${sourceOrderId} is "${netActivity && netActivity.amount}" — not a negative net amount once every activity row for this order is netted together, so there is nothing to redeem (either no debit occurred, or a later same-order reversal already restored it).`,
+      }],
+      notes,
+    };
+  }
+
+  const amount = Math.abs(netAmount);
+  if (amount <= 0) {
+    return {
+      payload: null,
+      gaps: [{ code: 'invalid-redemption-amount', summary: `net activity for order ${netActivity.orderId} has amount "${netActivity.amount}", not a positive value once its sign is taken.` }],
+      notes,
+    };
+  }
+
+  notes.push(`redemption sourced from netted bridge-plugin activity for order_id ${netActivity.orderId} (activity rows: ${JSON.stringify(netActivity.activityIds)}) — net amount after any same-order reversal is ${netActivity.amount}.`);
+
+  return {
+    payload: {
+      code: wixCode,
+      amount: amount.toFixed(2),
+      orderId: wixOrderId,
+      appId: wixAppId,
+    },
+    gaps: [],
+    notes,
+  };
+}
+
+module.exports = {
+  isRedemptionActivityRow,
+  findRedemptionActivityForOrder,
+  verifyPolicyCReplaySufficiency,
+  buildGiftCardRedemption,
+};

package/skills/wix-replatform/resources/rp-target-wix/lib/order-applied-discount-build.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// Coupon usage per order, as the imported order's appliedDiscounts.
+//
+// There is no standalone write: an applied discount rides in the Import Order body (entity
+// ecom/order-applied-discount, preferredWrite importOrder). So this module turns a source order's
+// coupon lines into `appliedDiscounts[]` entries for the order body, resolving each code through
+// the coupon crosswalk. A code the crosswalk cannot resolve produces NO entry and one unresolved
+// report line -- a dangling reference would name a coupon that does not exist on the target.
+//
+// Every entry is the `coupon` one-of variant, which is the only honest one here: the discount
+// genuinely was a coupon redemption. The plugin-computed `merchantDiscount` variant is a
+// different entity (ecom/discount-rule's records) and is not this module's business.
+//
+// Pure. Amounts are kept as the source recorded them; Import Order stores money as-is and never
+// recalculates, so the caller's priceSummary must already agree with these.
+
+const OUTCOMES = Object.freeze({
+  WRITTEN: 'coupon-usage-written',
+  UNRESOLVED: 'coupon-usage-unresolved',
+  NONE: 'coupon-usage-none',
+});
+
+function canonicalAmount(value) {
+  const text = value === undefined || value === null ? '' : String(value).trim();
+  if (!/^-?\d+(\.\d+)?$/.test(text)) return null;
+  const n = Math.abs(Number(text));
+  return n.toFixed(2);
+}
+
+// `couponLines`: WooCommerce order `coupon_lines[]` ({ code, discount, discount_tax }) or any
+// { code, discount } shape. `resolveCoupon(code)` -> { id, name? } | null (the coupon crosswalk).
+function buildCouponAppliedDiscounts({ couponLines = [], resolveCoupon, includeTax = false } = {}) {
+  if (typeof resolveCoupon !== 'function') throw new Error('buildCouponAppliedDiscounts needs resolveCoupon(code) backed by the coupon crosswalk');
+  if (!Array.isArray(couponLines)) throw new Error('couponLines must be an array');
+  const appliedDiscounts = [];
+  const unresolved = [];
+  const findings = [];
+  for (const line of couponLines) {
+    const code = line && line.code !== undefined && line.code !== null ? String(line.code).trim() : '';
+    if (!code) { findings.push({ code: 'coupon-line-without-code' }); continue; }
+    let amount = canonicalAmount(line.discount);
+    if (amount === null) { unresolved.push({ code, reason: 'amount-not-decimal', discount: line.discount }); continue; }
+    if (includeTax) {
+      const tax = canonicalAmount(line.discount_tax);
+      if (tax !== null) amount = (Number(amount) + Number(tax)).toFixed(2);
+    }
+    const resolved = resolveCoupon(code);
+    if (!resolved || !resolved.id) {
+      unresolved.push({ code, reason: 'coupon-not-imported', amount });
+      continue;
+    }
+    appliedDiscounts.push({
+      // Order-level: WooCommerce records a coupon's total discount against the order, not per line.
+      discountType: 'GLOBAL',
+      coupon: { id: String(resolved.id), code, name: resolved.name ? String(resolved.name) : code, amount: { amount } },
+    });
+  }
+  const outcome = couponLines.length === 0 ? OUTCOMES.NONE : (appliedDiscounts.length > 0 ? OUTCOMES.WRITTEN : OUTCOMES.UNRESOLVED);
+  return { appliedDiscounts, unresolved, findings, outcome, counts: { written: appliedDiscounts.length, unresolved: unresolved.length } };
+}
+
+module.exports = { OUTCOMES, buildCouponAppliedDiscounts, canonicalAmount };

package/skills/wix-replatform/resources/rp-target-wix/lib/order-buyer.js

@@ -0,0 +1,187 @@
+'use strict';
+
+// An imported order carries its buyer's member id, resolved from the member crosswalk
+// and corroborated, or it carries nothing.
+//
+// `buyerInfo.memberId` is what member-facing reads authorize on: a member-identity Get Order
+// returns an order only if that member placed it, and the invoice download backend checks the
+// same field. So an imported order with no memberId is invisible to its own buyer (dormant, no
+// leak), and one with the WRONG memberId hands that member someone else's order and invoice, with
+// both checks agreeing. Import Order stores whatever GUID it is given (verified live 2026-09-05:
+// a memberId that is not a member is accepted and read back as-is). Nothing downstream catches a
+// bad link, so this module fails CLOSED: a member id is set only when the crosswalk names it AND
+// the member's login email is the order's billing email.
+//
+// Pure. The caller supplies the source order's customer id and billing email, and crosswalk
+// lookups; this decides and stamps.
+
+const crypto = require('node:crypto');
+
+const OUTCOMES = Object.freeze({
+  LINKED: 'buyer-member-linked',
+  GUEST: 'buyer-guest',
+  NOT_IMPORTED: 'buyer-member-not-imported',
+  EMAIL_MISMATCH: 'buyer-member-email-mismatch',
+  CONTACT_ONLY: 'buyer-contact-only',
+});
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const STAMP_VERSION = 'rp-order-buyer:v2';
+// ASCII `local@domain.tld` only. Case-folding non-ASCII (the Kelvin sign folds to `k`) can make two
+// distinct addresses equal, and a false link is the harm here; a non-ASCII address is simply not
+// comparable and links nothing. Plus-addressing, dots and IDN forms are NOT normalized either --
+// strict on purpose: a missed link is a reported finding, a wrong one is a leak.
+const ASCII_EMAIL = /^[\x21-\x7e]+@[a-z0-9.-]+\.[a-z]{2,}$/;
+
+function normalizeEmail(value) {
+  const raw = value === undefined || value === null ? '' : String(value).trim();
+  // ASCII is checked BEFORE case-folding: `toLowerCase()` turns the Kelvin sign into `k`, and a
+  // check after folding would have accepted it (the review's demonstration, reproduced in tests).
+  if (!/^[\x21-\x7e]+$/.test(raw)) return null;
+  const text = raw.toLowerCase();
+  return ASCII_EMAIL.test(text) && text.indexOf('@') === text.lastIndexOf('@') ? text : null;
+}
+
+// JSON-encoded (no delimiter to inject), and covering the OUTCOME and finding codes as well as the
+// ids: a review swapped `outcome` to "linked" on a mismatch result and the stamp still verified,
+// so the report would have said linked while the body carried nothing.
+function stampInput(buyer) {
+  return JSON.stringify([STAMP_VERSION, buyer.outcome || null, buyer.memberId || null, buyer.contactId || null, buyer.sourceCustomerId === undefined || buyer.sourceCustomerId === null ? null : String(buyer.sourceCustomerId), buyer.email || null, (buyer.findings || []).map((f) => f && f.code).sort()]);
+}
+function computeBuyerStamp(buyer) {
+  return crypto.createHash('sha256').update(stampInput(buyer)).digest('hex');
+}
+function verifyBuyerStamp(buyer) {
+  return Boolean(buyer && typeof buyer === 'object' && typeof buyer.buyerStamp === 'string' && buyer.buyerStamp === computeBuyerStamp(buyer));
+}
+
+// `memberCrosswalk.get(sourceCustomerId)` -> { memberId, loginEmail } | null -- what this migration
+// created (Create Member by loginEmail) keyed by the source user id.
+// `contactCrosswalk.get(key)` -> contactId | null, keyed by source customer id, else by email.
+async function resolveOrderBuyer({ sourceCustomerId = null, billingEmail = null, memberCrosswalk = null, contactCrosswalk = null } = {}) {
+  const findings = [];
+  const email = normalizeEmail(billingEmail);
+  // A WooCommerce customer id is a positive integer, possibly stringified, possibly zero-padded
+  // by a CSV. Anything else is a caller error, not a guest: `true` stringifies to "true" and a row
+  // keyed "true" would never exist, which silently under-links.
+  let customerId = null;
+  if (sourceCustomerId !== undefined && sourceCustomerId !== null && String(sourceCustomerId).trim() !== '') {
+    // A number above 2^53 has ALREADY been rounded by whoever parsed it; it cannot name a customer.
+    if (typeof sourceCustomerId === 'number' && !Number.isSafeInteger(sourceCustomerId)) throw new Error(`sourceCustomerId ${sourceCustomerId} is not a safe integer; pass large ids as strings`);
+    const raw = typeof sourceCustomerId === 'number' ? String(sourceCustomerId) : String(sourceCustomerId).trim();
+    if (!/^\d+(\.0+)?$/.test(raw)) throw new Error(`sourceCustomerId must be a non-negative integer (WooCommerce customer id), got ${JSON.stringify(sourceCustomerId)}`);
+    // Normalized as a STRING, never through Number(): above 2^53 that rounds, and review
+    // demonstrated "9007199254740993" keyed as ...992 -- another customer's row, and so another
+    // customer's order and invoice handed to the wrong member.
+    const digits = raw.replace(/\.0+$/, '').replace(/^0+(?=\d)/, '');
+    customerId = digits === '0' ? null : digits;
+  }
+  // An order that CARRIED an address `normalizeEmail` refused is a different thing
+  // from an order placed by a guest, and both end as `buyer-guest`. The outcome partition is
+  // unchanged (BUYER_OUTCOMES must keep summing to the order population); the finding rides
+  // alongside so the report can count "really a guest" apart from "we had a customer and their
+  // address was unusable". An ABSENT email is not a defect and gets no finding, and the address
+  // itself is never written down.
+  const billingEmailPresent = billingEmail !== undefined && billingEmail !== null && String(billingEmail).trim() !== '';
+  if (billingEmailPresent && email === null) {
+    findings.push({ code: 'buyer-email-unusable', ...(customerId ? { sourceCustomerId: customerId } : {}), orderEmailPresent: true });
+  }
+  let contactId = null;
+  if (contactCrosswalk && typeof contactCrosswalk.get === 'function') {
+    const byCustomer = customerId ? await contactCrosswalk.get(customerId) : null;
+    const byEmail = !byCustomer && email ? await contactCrosswalk.get(email) : null;
+    const found = byCustomer || byEmail;
+    if (found && GUID.test(String(found))) contactId = String(found);
+    else if (found) findings.push({ code: 'buyer-contact-id-not-guid', value: String(found).slice(0, 40) });
+  }
+  const finish = (outcome, memberId) => {
+    const buyer = { outcome, memberId: memberId || null, contactId, sourceCustomerId: customerId, email, findings };
+    buyer.buyerStamp = computeBuyerStamp(buyer);
+    return buyer;
+  };
+  if (!customerId) return finish(contactId ? OUTCOMES.CONTACT_ONLY : OUTCOMES.GUEST, null);
+  if (!memberCrosswalk || typeof memberCrosswalk.get !== 'function') throw new Error('resolveOrderBuyer needs a memberCrosswalk with get(sourceCustomerId) when the order has a customer id');
+  const row = await memberCrosswalk.get(customerId);
+  if (!row || !row.memberId) {
+    findings.push({ code: OUTCOMES.NOT_IMPORTED, sourceCustomerId: customerId });
+    return finish(OUTCOMES.NOT_IMPORTED, null);
+  }
+  if (!GUID.test(String(row.memberId))) {
+    findings.push({ code: 'buyer-member-id-not-guid', sourceCustomerId: customerId });
+    return finish(OUTCOMES.NOT_IMPORTED, null);
+  }
+  // Corroboration: the member the crosswalk names must be the person who placed the order. The
+  // login email is the identity Create Member deduplicated on; a row whose email disagrees with
+  // the order's billing email is a crosswalk pointing at the wrong person, which is the one
+  // outcome nothing downstream would catch.
+  const loginEmail = normalizeEmail(row.loginEmail);
+  if (!email || !loginEmail || email !== loginEmail) {
+    findings.push({ code: OUTCOMES.EMAIL_MISMATCH, sourceCustomerId: customerId, orderEmailPresent: Boolean(email), memberEmailPresent: Boolean(loginEmail) });
+    return finish(OUTCOMES.EMAIL_MISMATCH, null);
+  }
+  return finish(OUTCOMES.LINKED, String(row.memberId));
+}
+
+// The buyerInfo to put on the Import Order body, from a STAMPED resolver result. Refuses anything
+// else, so a hand-built { memberId } cannot reach the order.
+function buyerInfoFrom(buyer) {
+  if (!verifyBuyerStamp(buyer)) throw new Error('buyerInfo must come from resolveOrderBuyer (its stamp did not verify); a hand-built memberId is exactly the wrong-attribution risk this exists to prevent');
+  const info = {};
+  if (buyer.contactId) info.contactId = buyer.contactId;
+  if (buyer.memberId) info.memberId = buyer.memberId;
+  return info;
+}
+
+// The only keys a mapped order body may carry under buyerInfo BEFORE the composite sets the
+// buyer: an email, and a contactId the contact import resolved. Everything else -- memberId under
+// any spelling, visitorId, snake_case siblings -- is refused, because Wix's proto-JSON accepts
+// `member_id` as readily as `memberId` and a refusal that checks one spelling checks nothing.
+const BODY_BUYER_KEYS = Object.freeze(['contactId', 'email']);
+// The only top-level keys allowed to normalize (letters-only, lowercase) to something containing
+// "buyer" besides the `buyerInfo` container itself: legitimate, distinct Import Order scalars
+// (see domains/ecom/entities/order.json's "scalar/enum fields, no dependency" list --
+// buyerNote/tags/weightUnit/currency/taxIncludedInPrices/attributionSource/buyerLanguage) that
+// order-transform.js's toWixOrder() always sets as an object key, even when its value is
+// `undefined` (e.g. `{ buyerNote: source.customer_note || undefined }` still yields the key).
+// Checked the full sibling list above for this same class of gap: only `buyerNote` and
+// `buyerLanguage` normalize to contain "buyer" (tags/weightUnit/currency/taxIncludedInPrices/
+// attributionSource do not), so those are the only two carve-outs needed here.
+//
+// BUG FIX (2026-09-28): `buyerLanguage` was missing from this set entirely, so a
+// generated order-transform setting it would hit the same false "order/all: 0 landed" failure
+// this guard exists to prevent -- the exact failure this file's other carve-out
+// (`buyerNote`) was already added to fix, just for a sibling scalar this guard never carved out.
+const ALLOWED_BUYER_ADJACENT_KEYS = new Set(['buyernote', 'buyerlanguage']);
+function assertBodyBuyerInfo(order) {
+  for (const key of Object.keys(order || {})) {
+    if (key === 'buyerInfo') continue;
+    // this used to strip every non-letter character
+    // (`.replace(/[^a-z]/g, '')`), including digits, so a future `buyerNote2` or `buyer_note_1`
+    // normalized to the exact same string as the allowed `buyerNote`/`buyerLanguage` entries and
+    // was silently waved through -- the same enumeration-drift bug class that already caused two
+    // failures in this file where every order write was refused (`buyerNote`, then `buyerLanguage`).
+    // Strip only underscores (the test suite's `buyer_language` spelling must keep passing) and
+    // preserve digits, so a genuinely different, digit-bearing field name can never collide with
+    // an allowed one.
+    const normalized = key.toLowerCase().replace(/_/g, '');
+    if (!normalized.includes('buyer')) continue;
+    // BUG FIX (2026-09-27): the guard used to test `/buyer/i`
+    // against every top-level key, which also matched `buyerNote` and threw for 100% of orders,
+    // independent of any real data problem -- the root cause of every "order/all: 0 landed" run
+    // while it stood. The fix carves out only that one known-legitimate field by exact normalized name,
+    // rather than narrowing to an exact `buyerInfo` match -- a narrower check would have let a
+    // smuggled top-level `buyerId`/`buyerMemberId`/bare `buyer` scalar straight through with
+    // nothing else in this module (or the Import Order schema) refusing it. Any OTHER key that
+    // merely contains "buyer" -- the container under a variant spelling, or a scalar identity
+    // field under any name -- is refused; the buyer goes through `buyer` from resolveOrderBuyer
+    // and nowhere else.
+    if (ALLOWED_BUYER_ADJACENT_KEYS.has(normalized)) continue;
+    throw new Error(`order.${key} is not accepted; the buyer goes through \`buyer\` from resolveOrderBuyer`);
+  }
+  const info = order && order.buyerInfo;
+  if (info === undefined || info === null) return;
+  if (typeof info !== 'object' || Array.isArray(info)) throw new Error('order.buyerInfo must be an object');
+  const bad = Object.keys(info).filter((k) => !BODY_BUYER_KEYS.includes(k));
+  if (bad.length > 0) throw new Error(`order.buyerInfo may only carry ${BODY_BUYER_KEYS.join(', ')} before the composite sets the buyer; got ${bad.join(', ')} -- a member id is never the caller's to set`);
+}
+
+module.exports = { OUTCOMES, BODY_BUYER_KEYS, ALLOWED_BUYER_ADJACENT_KEYS, normalizeEmail, resolveOrderBuyer, buyerInfoFrom, assertBodyBuyerInfo, computeBuyerStamp, verifyBuyerStamp };

package/skills/wix-replatform/resources/rp-target-wix/lib/order-channel-build.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const { isBlank } = require('./value-utils.js');
+
+// rp-target-wix — the `channelInfo` segment of a POST /ecom/v1/orders/import
+// request body. A small, standalone builder rather than a full order-payload builder because full
+// order assembly (line items, discounts, refunds, tax, shipping) is explicitly out of scope here
+// (left for rp-import-codegen, not yet built) — this covers exactly one piece:
+// always setting a durable pointer back to the source order.
+//
+// `channelInfo.externalOrderId`/`externalOrderUrl` is a real, documented Wix order field
+// ("Reference to an order ID from an external system" — dev.wix.com order object, verified
+// 2026-08-17), not invented for this migration. It matters beyond idempotency: unlike the local
+// crosswalk.ndjson, this is visible to the merchant and support staff directly on the
+// order in the Wix dashboard.
+//
+// NOT runtime-verified: this builder has not itself been sent to a live Import Order call
+// (live verification so far exercised gift-card issuance/redemption, not channelInfo). The
+// shape matches the documented field, but treat it as code-exists-not-runtime-verified until a live Import Order call confirms it.
+
+const CHANNEL_TYPE_OTHER_PLATFORM = 'OTHER_PLATFORM';
+
+// `order` is the raw WooCommerce order (GET /wc/v3/orders/{id} shape) — only `order.id` is used.
+// `options.externalOrderUrl`, if given, is passed through as-is. Deliberately NOT constructed
+// here: a WooCommerce order's admin edit URL differs between legacy post-based storage
+// (`post.php?post=<id>&action=edit`) and High-Performance Order Storage
+// (`admin.php?page=wc-orders&action=edit&id=<id>`), and only the caller (which already knows the
+// source site's admin base URL and storage mode) can tell which applies — guessing one would risk
+// a dead link on the exact fact this field exists to make trustworthy. The URL is set only if
+// constructible — omitting it here when the caller has nothing to pass is the correct,
+// documented behavior, not a gap.
+function buildChannelInfo(order, options) {
+  const { externalOrderUrl } = options || {};
+  const notes = [];
+
+  if (order == null || isBlank(order.id)) {
+    return {
+      channelInfo: null,
+      gaps: [{
+        code: 'missing-external-order-id',
+        summary: 'order.id is required to build channelInfo.externalOrderId — without it, this order has no durable pointer back to its source.',
+      }],
+      notes,
+    };
+  }
+
+  const channelInfo = {
+    type: CHANNEL_TYPE_OTHER_PLATFORM,
+    externalOrderId: String(order.id),
+  };
+
+  if (!isBlank(externalOrderUrl)) {
+    channelInfo.externalOrderUrl = externalOrderUrl;
+  } else {
+    notes.push('externalOrderUrl omitted — not constructible from the WooCommerce order alone (legacy post.php vs HPOS wc-orders admin URL shapes differ); pass options.externalOrderUrl when the caller can build it for this site.');
+  }
+
+  return { channelInfo, gaps: [], notes };
+}
+
+module.exports = {
+  CHANNEL_TYPE_OTHER_PLATFORM,
+  buildChannelInfo,
+};