@wix/agent-skills 1.33.0 → 1.34.0

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

@@ -0,0 +1,566 @@
+'use strict';
+
+const { isBlank } = require('./value-utils.js');
+
+// rp-target-wix — the DETERMINISTIC "PW WooCommerce Gift Cards" issuance line item -> Wix
+// gift-cards/v1 Create Gift Card payload builder. Companion to discount-rule-build.js / tax-build.js;
+// implements domains/gift-cards/entities/gift-card.json's mappingGuidance/pitfalls as code.
+//
+// Input is one WooCommerce order (as returned by GET /wc/v3/orders/{id}) plus the specific
+// line_item on it that carries pw_gift_card_number in its meta_data (see
+// plugins/pw-woocommerce-gift-cards.json's gift-card entity for how that meta gets there and why
+// it only exists once the order has reached processing/completed).
+//
+// LIVE-VERIFIED 2026-08-17 against a WordPress/WooCommerce test site (source: WooCommerce REST API + a headless storefront
+// checkout; target: a test site). Test orders were completed via
+// the WooCommerce REST API (not the storefront) with pw_gift_card_amount/to/from/message set on
+// the line item exactly as the plugin's own checkout hook would set them; each produced a
+// pw_gift_card_number on completion. A further order redeemed one of those cards through a headless
+// storefront checkout. The Wix side was exercised too: this builder's output was POSTed to
+// POST /gift-cards/v1/gift-cards on a test site (after installing the Wix Gift Cards app,
+// appDefId d80111c5-a0f4-47a8-b63a-65b54d774a27 — see domains/gift-cards/domain.json's
+// gift-card-app-required pitfall) and read back successfully.
+//
+// CORRECTED 2026-08-18: `pw_gift_card_number` is a REPEATED meta key, not a single
+// value — for line-item quantity N, the plugin's own add_gift_cards_to_order() calls
+// wc_add_order_item_meta(..., $unique = false) once per card, so the same key appears N times with
+// N different codes. The main entry point below (buildGiftCardsFromOrderLineItem) always returns
+// an ARRAY, one entry per issued card, never just the first, and recipients are correlated to cards (see
+// the recipient-correlation rule below).
+//
+// What this module deliberately does NOT do: resolve a redeemed/partial balance on its own.
+// Redemption is a custom order-item type ('pw_gift_card') that the stock WooCommerce REST Orders
+// controller never serializes (verified live — see plugins/pw-woocommerce-gift-cards.json's
+// gift-card-activity entity, redemption-invisible-even-in-order-rest-data pitfall) — there is no
+// source signal this builder could read to know a card was later spent. Every card is built at its
+// original face value (Policy A) unless the caller supplies a validated
+// `remainingBalance` from some out-of-band reconciliation (Policy B — the bridge plugin, or
+// a merchant-supplied list). The two policies are mutually exclusive per card; this module does not
+// enforce that across calls, only validates a single call's input (see validateRemainingBalance).
+
+const ORDER_STATUSES_WITH_ISSUED_CARDS = new Set(['processing', 'completed']);
+const CODE_MIN_LENGTH = 8;
+const CODE_MAX_LENGTH = 20;
+// VERIFIED LIVE 2026-08-17: Wix rejects any non-alphanumeric character in giftCard.code outright
+// (428 INVALID_CODE), independent of length — see gift-card.json's code-alphanumeric-only pitfall.
+const CODE_ALLOWED_CHARS = /^[A-Za-z0-9]+$/;
+// Wix money amounts are decimal strings with at most 2 decimal places (gift-card.json
+// mappingGuidance) — enforced on any caller-supplied remainingBalance override.
+const MAX_MONEY_DECIMALS = 2;
+// WooCommerce order.currency is always a 3-letter ISO 4217 code; Wix giftCard.currency rejects
+// anything else with a 400. Checked here so a missing/malformed order.currency surfaces as a
+// named gap instead of a payload that only fails later against the live endpoint.
+const CURRENCY_CODE_PATTERN = /^[A-Z]{3}$/;
+// The Wix Gift Cards app's own appDefId — VERIFIED LIVE 2026-08-17 via Get Gift Card, which
+// returns the CREATING app's id for a card built by this module (source: 'MANUAL'), not an
+// external provider's (see domains/gift-cards/domain.json's gift-card-app-required pitfall).
+// Create Gift Card itself has no explicit appId field (this constant isn't used above) — it's
+// exported here because gift-card-redemption-build.js's Redeem Gift Card call needs it, and this
+// is the one place that constant is already live-verified.
+const WIX_GIFT_CARDS_APP_ID = 'd80111c5-a0f4-47a8-b63a-65b54d774a27';
+
+// Every value stored under `key`, in meta_data array order — WooCommerce/WordPress's own meta
+// retrieval is ORDER BY meta_id ASC, and the plugin appends one pw_gift_card_number row per card
+// in creation order, so this order is the plugin's own creation order, not an arbitrary one.
+function metaValues(metaData, key) {
+  return (metaData || []).filter((m) => m.key === key).map((m) => m.value);
+}
+
+function metaValue(metaData, key) {
+  return metaValues(metaData, key)[0];
+}
+
+// Mirrors add_gift_cards_to_order()'s own fallback in pw-gift-cards-purchasing.php: when
+// pw_gift_card_amount is missing/non-numeric, the plugin itself falls back to
+// subtotal / quantity. A reader has to apply the same fallback or it will under-read older orders.
+// This amount is per-card (the plugin sets it from the unit price), shared by every card issued
+// from the same line item — there is no per-card amount variant to resolve separately.
+function resolveFaceValue(lineItem, metaData) {
+  const metaAmount = metaValue(metaData, 'pw_gift_card_amount');
+  if (!isBlank(metaAmount) && Number.isFinite(Number(metaAmount))) {
+    const numeric = Number(metaAmount);
+    if (numeric < 0) {
+      return {
+        amount: null,
+        source: null,
+        gap: {
+          code: 'invalid-gift-card-amount',
+          summary: `pw_gift_card_amount (${numeric}) on line item ${lineItem.id} is negative — a gift card face value cannot be negative.`,
+        },
+      };
+    }
+    // A zero meta value is treated the same as missing/blank, not a real $0.00 face value: PHP's
+    // own empty() (which the plugin's meta checks are built on) is true for "0"/0, so
+    // pw_gift_card_amount = "0" falls through to the SAME subtotal/quantity fallback as a
+    // genuinely missing value would, rather than minting a $0.00 card for a real purchase.
+    if (numeric !== 0) {
+      return { amount: numeric, source: 'pw_gift_card_amount meta' };
+    }
+  }
+  const subtotal = Number(lineItem.subtotal);
+  const quantity = Number(lineItem.quantity);
+  if (Number.isFinite(subtotal) && Number.isFinite(quantity) && quantity > 0) {
+    return { amount: Math.round((subtotal / quantity) * 100) / 100, source: 'subtotal / quantity fallback (pw_gift_card_amount was missing or zero)' };
+  }
+  return { amount: null, source: null };
+}
+
+// The recipient-correlation rule. pw_gift_card_to is ONE string that may list
+// several whitespace/comma-separated recipients; the plugin sets cart quantity = recipient count
+// ONLY when that count is greater than 1, so:
+//   - recipients.length === cardCount: zip 1:1 by position (both are creation-order lists).
+//   - recipients.length is 0 or 1: that single recipient (or none) applies to every card.
+//   - anything else is not a shape the plugin's own code produces under normal use — a gap, not a
+//     guessed pairing.
+function resolveRecipients(metaData, cardCount) {
+  const raw = metaValue(metaData, 'pw_gift_card_to');
+  if (isBlank(raw)) return { recipients: new Array(cardCount).fill(undefined) };
+  const split = String(raw).split(/[\s,]+/).filter(Boolean);
+  if (split.length === cardCount) return { recipients: split };
+  if (split.length <= 1) return { recipients: new Array(cardCount).fill(split[0]) };
+  return {
+    recipients: null,
+    gap: {
+      code: 'recipient-card-count-mismatch',
+      summary: `pw_gift_card_to lists ${split.length} recipient(s) but ${cardCount} card(s) were issued on this line item — cannot safely pair recipients to cards. This is not a shape the plugin's own code produces under normal use; treat it as a data-integrity gap, not something to guess a pairing for.`,
+    },
+  };
+}
+
+// Validation for one already-resolved balance override value (Policy B).
+// Never throws, never silently coerces an invalid value into a number — returns a named gap
+// instead.
+function validateRemainingBalance(remainingBalance, faceValue) {
+  if (typeof remainingBalance === 'string' && remainingBalance.trim() === '') {
+    return { gap: { code: 'invalid-remaining-balance', summary: 'the resolved remainingBalance was an empty/whitespace string.' } };
+  }
+  const numeric = Number(remainingBalance);
+  if (!Number.isFinite(numeric)) {
+    return { gap: { code: 'invalid-remaining-balance', summary: `the resolved remainingBalance "${remainingBalance}" is not a finite number (NaN/Infinity/non-numeric text are all rejected).` } };
+  }
+  if (numeric < 0) {
+    return { gap: { code: 'invalid-remaining-balance', summary: `the resolved remainingBalance (${numeric}) is negative — a gift card balance cannot be negative.` } };
+  }
+  const scaled = numeric * 10 ** MAX_MONEY_DECIMALS;
+  if (Math.abs(scaled - Math.round(scaled)) > 1e-9) {
+    return { gap: { code: 'invalid-remaining-balance', summary: `the resolved remainingBalance (${numeric}) has more than ${MAX_MONEY_DECIMALS} decimal places — Wix money amounts are decimal strings with at most 2 decimal places.` } };
+  }
+  if (faceValue != null && numeric > faceValue) {
+    return {
+      gap: {
+        code: 'remaining-balance-exceeds-face-value',
+        summary: `the resolved remainingBalance (${numeric}) is greater than the card's face value (${faceValue}) — a stored-value card's balance cannot legitimately exceed what it was issued for in this migration's model. This indicates a source data-quality problem needing its own investigation, not a value to pass through.`,
+      },
+    };
+  }
+  return { amount: numeric };
+}
+
+// Per card, fixed 2026-08-18: the balance-policy signal is now
+// EXPLICIT (`options.balancePolicy`) instead of inferred from whether `remainingBalance` happens
+// to be set — a Policy B lookup that came back empty must fail closed as its own gap, never fall
+// through to Policy A's face-value path undetected (both used to look identical: an omitted
+// value). The override itself is resolved PER SOURCE CARD (`options.remainingBalanceByCard`,
+// keyed by the raw `pw_gift_card_number`), not one scalar shared across every card on a
+// multi-quantity line — two cards from the same line can have been independently, differently
+// spent, and sharing one balance would silently misprice one of them.
+// Shared by every per-card lookup map this module accepts (remainingBalanceByCard,
+// lifecycleByCard, ...): both a plain object and a Map are accepted, keyed by the raw
+// `pw_gift_card_number`. `has` is distinct from `value` so a map that explicitly sets an entry to
+// `null`/`undefined` (a lookup that ran and found nothing) is still visible as "present but
+// empty," not indistinguishable from "never looked up."
+function lookupByCard(map, sourceNumber) {
+  if (map instanceof Map) return { has: map.has(sourceNumber), value: map.get(sourceNumber) };
+  const has = map != null && Object.prototype.hasOwnProperty.call(map, sourceNumber);
+  return { has, value: has ? map[sourceNumber] : undefined };
+}
+
+function hasOwn(object, field) {
+  return object != null && Object.prototype.hasOwnProperty.call(object, field);
+}
+
+// Fixed 2026-08-18: Policy A ("face value, no replay") and Policy B ("verified remaining balance at creation") are the only two policies
+// gift-card-build.js itself needs to know about — both simply decide whether THIS create call
+// uses face value or an override. Policy C ("face value now, then bring it down to the correct
+// balance by replaying each real order-linked redemption via gift-card-redemption-build.js") is
+// declared here too, in the same enum, purely so a caller can record the decision — but its
+// resolveCardBalance() behavior is IDENTICAL to Policy A's (face value at creation; the
+// correction happens later, via a separate redeem call, not here). The corresponding safety rule
+// lives in gift-card-redemption-build.js: it accepts a redemption ONLY for a card explicitly
+// declared Policy C, and rejects A (contradicts "no replay") and B (would double-decrement a
+// card already created at its correct balance) outright.
+function resolveCardBalance(sourceNumber, faceValue, options) {
+  const { balancePolicy, remainingBalanceByCard } = options || {};
+  const { has: hasOverrideEntry, value: rawValue } = lookupByCard(remainingBalanceByCard, sourceNumber);
+
+  if (balancePolicy == null || balancePolicy === 'A' || balancePolicy === 'C') {
+    if (hasOverrideEntry) {
+      return {
+        amount: null,
+        note: `options.remainingBalanceByCard has an entry for card ${sourceNumber}, but options.balancePolicy is not "B" — it was IGNORED; set balancePolicy: 'B' to actually apply it.`,
+      };
+    }
+    return { amount: null };
+  }
+
+  if (balancePolicy !== 'B') {
+    return { gap: { code: 'invalid-balance-policy', summary: `options.balancePolicy must be "A", "B", or "C" — got ${JSON.stringify(balancePolicy)}.` } };
+  }
+
+  if (!hasOverrideEntry) {
+    return {
+      gap: {
+        code: 'unavailable-remaining-balance',
+        summary: `options.balancePolicy is "B" but options.remainingBalanceByCard has no entry for card ${sourceNumber} — a failed/missing balance lookup must never fall back to face value silently; the caller must explicitly decide to skip this card, supply its verified balance, or halt the run.`,
+      },
+    };
+  }
+
+  if (isBlank(rawValue)) {
+    return {
+      gap: {
+        code: 'unavailable-remaining-balance',
+        summary: `options.balancePolicy is "B" but the resolved remainingBalance for card ${sourceNumber} is blank/null — a failed lookup must be reported as unavailable, never treated as "use face value".`,
+      },
+    };
+  }
+
+  return validateRemainingBalance(rawValue, faceValue);
+}
+
+// A Wix date-time field, per the documented Gift Card Object (RFC 3339, e.g.
+// "2026-11-11T00:00:00Z") — NOT the bare "YYYY-MM-DD" shape the bridge plugin's
+// expiration_date column returns. Requires an explicit time-of-day and zone designator so a
+// caller can never forward the raw MySQL DATE value unconverted.
+const EXPIRATION_DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+const REQUIRED_VERIFIED_LIFECYCLE_FIELDS = ['active', 'expirationDate', 'expirationDateConversionError'];
+
+// Fixed 2026-08-18: the source card's own lifecycle facts (`active`, `expiration_date`
+// — only reachable via the bridge plugin, never from order/line-item data this module
+// otherwise reads) were previously dropped entirely, silently recreating an expired or
+// admin-disabled source card as a normal, active, non-expiring Wix card — resurrecting unusable
+// customer value.
+//
+// Fixed 2026-08-18 — two more gaps in this same fix:
+//
+// 1. **A missing per-card lookup entry was itself indistinguishable from "verified active, no
+//    expiration"** — the exact same silent-fallback shape already fixed for Policy B balances.
+//    `options.lifecyclePolicy` now makes the caller's intent explicit, mirroring `balancePolicy`.
+// 2. **A resolved `expirationDate` was forwarded to the create payload without validating its
+//    shape.** Wix's Gift Card Object documents `expirationDate` as an RFC 3339 date-time (e.g.
+//    `"2026-11-11T00:00:00Z"`), not the bare `"2027-01-01"` date the bridge plugin's
+//    `expiration_date` column returns. `EXPIRATION_DATE_TIME_PATTERN` now rejects anything that
+//    isn't already a real date-time with a zone designator.
+//
+// Fixed 2026-08-18: `options.expirationDateByCard`/`options.activeByCard`
+// used to be TWO SEPARATE per-card maps. The bridge plugin exposes `expiration_date_gmt` and
+// `expiration_date_conversion_error` as a PAIR — `expiration_date_gmt` is `null` both for a
+// genuine "no expiration" AND for a failed conversion, distinguished only by the sibling flag —
+// but nothing forced a caller assembling two independent maps to actually carry that flag through
+// at all. A caller who copied `expiration_date_gmt` into `expirationDateByCard` while dropping
+// `expiration_date_conversion_error` would have a failed conversion silently accepted as a
+// verified "no expiration" under `lifecyclePolicy: 'verified'` — the exact same class of bug this
+// whole fix exists to prevent, just moved one level up. There is now ONE per-card map,
+// `options.lifecycleByCard` (see `lookupByCard`), each entry a single record: `{ active,
+// expirationDate, expirationDateConversionError }`. A follow-up review closed the remaining hole
+// in that shape: under `lifecyclePolicy: 'verified'`, all three fields are required and the
+// conversion status must be present; whenever active or conversion status is supplied under any
+// policy it must be boolean, so malformed safety signals cannot silently become active/no-error.
+//
+// `active: false` has no direct create-time equivalent: Wix's Create Gift Card has no
+// "create disabled" option (the gift-cards API offers only create, send
+// email, query/search, disable, find-by-email, redeem, void), and this repo has not live-verified a Disable
+// Gift Card request shape to build a real follow-up call from. Rather than guess one, or silently
+// create the card active anyway, an inactive source card fails closed as a named gap by default —
+// the caller must explicitly opt in (`options.allowInactiveCardCreation`) to accept creating it
+// active with a manual Disable Gift Card follow-up still owed, or exclude the card instead.
+function resolveCardLifecycle(sourceNumber, options) {
+  const { lifecycleByCard, allowInactiveCardCreation = false, lifecyclePolicy } = options || {};
+
+  if (lifecyclePolicy != null && lifecyclePolicy !== 'not-tracked' && lifecyclePolicy !== 'verified') {
+    return { gap: { code: 'invalid-lifecycle-policy', summary: `options.lifecyclePolicy must be "not-tracked" or "verified" — got ${JSON.stringify(lifecyclePolicy)}.` } };
+  }
+
+  // Fixed 2026-08-18: an OMITTED lifecyclePolicy still defaults to
+  // 'not-tracked' (breaking every existing caller to force an explicit value was judged too
+  // disruptive), but that default is no longer silent — every card built this way carries a
+  // prominent note recording the decision, instead of the fidelity loss being invisible unless a
+  // reader already knows to go looking for it.
+  const notes = [];
+  if (lifecyclePolicy == null) {
+    notes.push(`options.lifecyclePolicy was not set for card ${sourceNumber} — defaulting to "not-tracked": this card's active/expiration state was NOT verified against the source. Pass lifecyclePolicy: "verified" with a real lifecycleByCard record if source lifecycle fidelity matters for this migration.`);
+  }
+
+  const { has: hasRecord, value: record } = lookupByCard(lifecycleByCard, sourceNumber);
+  const missingRequiredFields = REQUIRED_VERIFIED_LIFECYCLE_FIELDS.filter((field) => !hasOwn(record, field));
+  const active = hasOwn(record, 'active') ? record.active : undefined;
+  const expirationDate = hasOwn(record, 'expirationDate') ? record.expirationDate : undefined;
+  const conversionError = hasOwn(record, 'expirationDateConversionError') ? record.expirationDateConversionError : undefined;
+
+  if (lifecyclePolicy === 'verified' && (!hasRecord || missingRequiredFields.length > 0)) {
+    return {
+      gap: {
+        code: 'unavailable-lifecycle-data',
+        summary: `options.lifecyclePolicy is "verified" but card ${sourceNumber} is missing required lifecycleByCard data (${missingRequiredFields.join(', ') || 'record'}) — a missing/failed lifecycle lookup must never be treated as "active, no expiration"; supply "active", "expirationDate", and "expirationDateConversionError" (expirationDate may be explicitly null only when expirationDateConversionError is explicitly false), or use lifecyclePolicy: "not-tracked" as an explicit, visible decision to accept the fidelity loss for this card.`,
+      },
+    };
+  }
+
+  // Unlike expiration shape/status, inactive state is honored regardless of lifecyclePolicy (see
+  // the active===false gate below). Therefore a supplied active value must always be a boolean:
+  // accepting "false" or 0 would silently recreate an inactive source card as active.
+  if (hasOwn(record, 'active') && typeof active !== 'boolean') {
+    return {
+      gap: {
+        code: 'invalid-lifecycle-data',
+        summary: `card ${sourceNumber}'s lifecycleByCard record has active ${JSON.stringify(active)} — this field must be an explicit boolean so an inactive source card can never be recreated as active through coercion.`,
+      },
+    };
+  }
+
+  if (hasOwn(record, 'expirationDateConversionError') && typeof conversionError !== 'boolean') {
+    return {
+      gap: {
+        code: 'invalid-lifecycle-data',
+        summary: `card ${sourceNumber}'s lifecycleByCard record has expirationDateConversionError ${JSON.stringify(conversionError)} — this field must be an explicit boolean so conversion failure cannot be confused with a "no expiration" value.`,
+      },
+    };
+  }
+
+  if (lifecyclePolicy === 'verified' && expirationDate !== null && (typeof expirationDate !== 'string' || isBlank(expirationDate))) {
+    return {
+      gap: {
+        code: 'invalid-lifecycle-data',
+        summary: `card ${sourceNumber}'s verified lifecycleByCard record has expirationDate ${JSON.stringify(expirationDate)} — this field must be either an explicit null (verified no expiration) or a nonblank RFC 3339 date-time string.`,
+      },
+    };
+  }
+
+  // Checked regardless of lifecyclePolicy, same as the active===false check below: if the
+  // caller's own data says the conversion failed, that is real signal to honor, not something a
+  // policy setting should be able to suppress. This is exactly the case the bridge's
+  // expiration_date_conversion_error field exists to report — a non-null
+  // source expiration_date that could not be converted must never be treated as "no expiration."
+  if (conversionError === true) {
+    return {
+      gap: {
+        code: 'expiration-date-conversion-failed',
+        summary: `card ${sourceNumber}'s lifecycleByCard record has expirationDateConversionError: true — the source's expiration date failed to convert to a usable value and must never be treated as "no expiration" or silently dropped. Investigate the source data (the bridge plugin's expiration_date_conversion_error) before proceeding with this card.`,
+      },
+    };
+  }
+
+  if (!isBlank(expirationDate) && !EXPIRATION_DATE_TIME_PATTERN.test(expirationDate)) {
+    return {
+      gap: {
+        code: 'invalid-expiration-date-shape',
+        summary: `options.lifecycleByCard's record for card ${sourceNumber} has expirationDate "${expirationDate}", which is not an RFC 3339 date-time (e.g. "2026-11-11T00:00:00Z") — Wix's Gift Card Object requires a date-time, not a bare date. Never forward the bridge plugin's raw expiration_date (a MySQL DATE) directly; use its expiration_date_gmt (preserving end-of-day/site-timezone semantics) instead.`,
+      },
+    };
+  }
+
+  if (active === false) {
+    if (!allowInactiveCardCreation) {
+      return {
+        gap: {
+          code: 'inactive-source-card',
+          summary: `card ${sourceNumber} is inactive at the source (active: false) — Wix's Create Gift Card has no "create disabled" option, so creating it normally would resurrect deactivated customer value as a live, spendable card. Set options.allowInactiveCardCreation to explicitly accept creating it active anyway (with a manual Disable Gift Card follow-up still owed), or exclude this card from the migration.`,
+        },
+      };
+    }
+    notes.push(`card ${sourceNumber} is inactive at the source but was created anyway per options.allowInactiveCardCreation — it now exists as an ACTIVE Wix gift card; a manual Disable Gift Card follow-up is required to match the source state (no verified Disable Gift Card request shape is recorded in this repo yet).`);
+    return { expirationDate, note: notes.join(' ') };
+  }
+
+  return { expirationDate, note: notes.length ? notes.join(' ') : undefined };
+}
+
+// Main entry: one WooCommerce order + one of its pw-gift-card line items -> an ARRAY of Wix
+// POST /gift-cards/v1/gift-cards create results, one per issued card (a line item at quantity N
+// issues N cards — see the cardinality note above). Each array entry is
+// { sourceNumber, payload, gaps, notes }; `payload` is null when `gaps` is non-empty.
+//
+// `options.balancePolicy` — 'A', 'B', or 'C', chosen once per migration run
+// per card, never inferred. 'A' and 'C' both create at face value here (identical behavior in
+// THIS builder); they differ only in what happens next: 'A' accepts the resulting overstatement
+// as a known consequence (manual disable-and-replace to correct it), while 'C' declares that the
+// correct balance will be reached afterward by replaying real order-linked redemptions via
+// gift-card-redemption-build.js (which only accepts a redemption for a card declared 'C' — 'A'
+// and 'B' are both rejected there, for different reasons: 'A' contradicts its own "no replay"
+// rule, and 'B' would double-decrement a card already created at its correct balance). Under 'B',
+// `options.remainingBalanceByCard` (a plain object or Map keyed by the raw `pw_gift_card_number`)
+// must carry a verified current balance for EACH card being built here — a missing entry is a
+// named gap, never a silent fall-through to face value, and a scalar override is never broadcast
+// across every card on a multi-quantity line (two cards from the same line can have been spent
+// by different amounts).
+//
+// `options.lifecyclePolicy` — 'not-tracked' (default/omitted) or 'verified', mirroring
+// `balancePolicy`'s explicit-signal shape. `options.lifecycleByCard` (a plain object or Map keyed
+// by the raw `pw_gift_card_number`) carries ONE combined record per card — `{ active,
+// expirationDate, expirationDateConversionError }` — never split across separate maps (see
+// resolveCardLifecycle's own comment). Under 'not-tracked', a card with no `lifecycleByCard`
+// record is simply created active/non-expiring (today's behavior, now an explicit, visible
+// decision rather than an implicit default). Under 'verified', EVERY card must carry a record with
+// `active`, `expirationDate`, and boolean `expirationDateConversionError` fields present (an
+// explicit `null` expiration is a valid, verified "no expiration" only alongside an explicit
+// `false` conversion status) — a missing record or field fails closed as a named gap rather than
+// silently assuming active/non-expiring. A record with `expirationDateConversionError: true` is
+// always a hard gap, regardless of `lifecyclePolicy`. See resolveCardLifecycle for the inactive-
+// card and expiration-date-shape rules this also enforces.
+//
+// `options.normalizeCode` — set true to strip non-alphanumeric characters from a source code that
+// Wix would otherwise reject (see CODE_ALLOWED_CHARS above). Off by default: this changes the code
+// a customer may already hold printed/emailed, so it must be an explicit, visible decision (a
+// `notes` entry records exactly what changed), never a silent default — same principle as
+// `balancePolicy`/`lifecyclePolicy`.
+function buildGiftCardsFromOrderLineItem(order, lineItem, options) {
+  const opts = options || {};
+  const { normalizeCode = false } = opts;
+
+  if (!ORDER_STATUSES_WITH_ISSUED_CARDS.has(order.status)) {
+    return [{
+      sourceNumber: null,
+      payload: null,
+      gaps: [{
+        code: 'order-not-yet-completed',
+        summary: `order ${order.id} has status "${order.status}" — PW WooCommerce Gift Cards only mints a card number once an order reaches processing/completed (see gift-card.json's issuance-is-core-meta-not-db-only pitfall). Re-check after the order progresses.`,
+      }],
+      notes: [],
+    }];
+  }
+
+  const metaData = lineItem.meta_data || [];
+  const sourceNumbers = metaValues(metaData, 'pw_gift_card_number');
+  if (sourceNumbers.length === 0) {
+    return [{
+      sourceNumber: null,
+      payload: null,
+      gaps: [{ code: 'no-gift-card-number', summary: `line item ${lineItem.id} on order ${order.id} has no pw_gift_card_number meta — it is not a gift-card issuance line, or the order hasn't triggered issuance yet.` }],
+      notes: [],
+    }];
+  }
+
+  const { amount, source: amountSource, gap: faceValueGap } = resolveFaceValue(lineItem, metaData);
+  if (faceValueGap) {
+    return [{ sourceNumber: null, payload: null, gaps: [faceValueGap], notes: [] }];
+  }
+  if (amount == null) {
+    return [{
+      sourceNumber: null,
+      payload: null,
+      gaps: [{ code: 'unresolvable-amount', summary: `could not resolve a face value for line item ${lineItem.id} on order ${order.id} from either pw_gift_card_amount meta or subtotal/quantity.` }],
+      notes: [],
+    }];
+  }
+
+  const { recipients, gap: recipientGap } = resolveRecipients(metaData, sourceNumbers.length);
+  const buyerEmail = order.billing && order.billing.email;
+  const currencyGap = CURRENCY_CODE_PATTERN.test(order.currency)
+    ? null
+    : { code: 'invalid-currency', summary: `order ${order.id} has currency "${order.currency}" — expected a 3-letter ISO 4217 code (e.g. "USD"); Wix giftCard.currency rejects anything else.` };
+
+  return sourceNumbers.map((sourceNumber, index) => {
+    const notes = [];
+    if (amountSource !== 'pw_gift_card_amount meta') notes.push(`face value for card ${sourceNumber} used the ${amountSource}.`);
+
+    // Resolved PER CARD, not once for the whole line item — see resolveCardBalance's own comment.
+    const { amount: overrideAmount, gap: balanceGap, note: balanceNote } = resolveCardBalance(sourceNumber, amount, opts);
+    if (balanceNote) notes.push(balanceNote);
+    const { expirationDate, gap: lifecycleGap, note: lifecycleNote } = resolveCardLifecycle(sourceNumber, opts);
+    if (lifecycleNote) notes.push(lifecycleNote);
+
+    if (recipientGap) return { sourceNumber, payload: null, gaps: [recipientGap], notes };
+    if (balanceGap) return { sourceNumber, payload: null, gaps: [balanceGap], notes };
+    if (currencyGap) return { sourceNumber, payload: null, gaps: [currencyGap], notes };
+    if (lifecycleGap) return { sourceNumber, payload: null, gaps: [lifecycleGap], notes };
+
+    let code = sourceNumber;
+    if (isBlank(code)) {
+      return { sourceNumber, payload: null, gaps: [{ code: 'no-gift-card-number', summary: `card #${index + 1} on line item ${lineItem.id} has a blank pw_gift_card_number value.` }], notes };
+    }
+
+    if (!CODE_ALLOWED_CHARS.test(code)) {
+      if (!normalizeCode) {
+        return {
+          sourceNumber,
+          payload: null,
+          gaps: [{ code: 'code-contains-disallowed-characters', summary: `source code "${code}" contains characters Wix's giftCard.code rejects (letters/numbers only — see gift-card.json's code-alphanumeric-only pitfall). Pass options.normalizeCode to strip them, but that changes the code the customer already holds — get an explicit decision first.` }],
+          notes,
+        };
+      }
+      const stripped = code.replace(/[^A-Za-z0-9]/g, '');
+      notes.push(`code normalized for Wix (stripped non-alphanumeric characters): source "${code}" -> "${stripped}" — this changes the code the customer already holds; only done because options.normalizeCode was explicitly set.`);
+      code = stripped;
+    }
+
+    if (code.length < CODE_MIN_LENGTH || code.length > CODE_MAX_LENGTH) {
+      return { sourceNumber, payload: null, gaps: [{ code: 'code-length-out-of-range', summary: `code "${code}" is ${code.length} characters; Wix giftCard.code must be 8-20 characters and is immutable. Report this card instead of rewriting a code the customer already holds.` }], notes };
+    }
+
+    let initialValueAmount = amount;
+    if (overrideAmount != null) {
+      initialValueAmount = overrideAmount;
+      notes.push(`imported at the caller-resolved remainingBalanceByCard entry (${overrideAmount}) instead of face value (${amount}) — balance-policy decision made by the caller, not this builder (Policy B).`);
+    } else {
+      notes.push(`imported at face value (${amount}); redemption/balance history is not readable from source data (see plugins/pw-woocommerce-gift-cards.json's gift-card-activity redemption-invisible-even-in-order-rest-data pitfall) — if this card is known to have been partially spent, pass options.balancePolicy: 'B' with a verified remainingBalanceByCard entry.`);
+    }
+
+    const recipient = recipients[index];
+    if (!isBlank(recipient) && recipient !== buyerEmail) {
+      notes.push(`recipient ("${recipient}") differs from the buyer (billing.email "${buyerEmail}") — the Create Gift Card API has no documented recipient/contactId field, so this is carried as a note for a human CRM-linking step, not sent in the payload.`);
+    }
+
+    const payload = {
+      code,
+      // CORRECTED 2026-08-17 (live 400 on the real endpoint): `currency` is top-level on giftCard,
+      // NOT nested inside `initialValue` — see gift-card.json's mappingGuidance.
+      initialValue: { amount: initialValueAmount.toFixed(2) },
+      currency: order.currency,
+      // Required, and distinguishes an imported card from one bought through a Wix order — see
+      // gift-cards/gift-card.json's mappingGuidance.
+      source: 'MANUAL',
+      // Stable per SOURCE CARD, not just per order+line-item — quantity > 1 issues multiple cards
+      // from the same line item, which would otherwise collide on the same key.
+      idempotencyKey: `pw-gift-card:order-${order.id}:item-${lineItem.id}:number-${sourceNumber}`,
+    };
+
+    // Only set when options.lifecycleByCard has a real record for this card (see
+    // resolveCardLifecycle) — an absent record omits the field entirely rather than guessing
+    // "no expiration," since this builder has no access to the source card's own expiration_date
+    // without a caller-supplied lookup (the bridge plugin).
+    if (!isBlank(expirationDate)) payload.expirationDate = expirationDate;
+
+    // Deliberately absent: `notificationInfo`. Including it emails the recipient immediately
+    // (notificationDate empty) — a historical import would re-mail every card holder. See
+    // gift-cards/gift-card.json's suppress-recipient-email-on-import pitfall.
+
+    return { sourceNumber, payload, gaps: [], notes };
+  });
+}
+
+// Convenience: fan out every pw-gift-card line item found on an order, and every card issued from
+// each of them.
+function buildGiftCardsFromOrder(order, options) {
+  const giftCardLineItems = (order.line_items || []).filter(
+    (li) => metaValues(li.meta_data, 'pw_gift_card_number').length > 0 || !isBlank(metaValue(li.meta_data, 'pw_gift_card_amount'))
+  );
+  return giftCardLineItems.flatMap((lineItem) =>
+    buildGiftCardsFromOrderLineItem(order, lineItem, options).map((result) => ({ lineItemId: lineItem.id, ...result }))
+  );
+}
+
+module.exports = {
+  ORDER_STATUSES_WITH_ISSUED_CARDS,
+  CODE_MIN_LENGTH,
+  CODE_MAX_LENGTH,
+  CODE_ALLOWED_CHARS,
+  MAX_MONEY_DECIMALS,
+  CURRENCY_CODE_PATTERN,
+  WIX_GIFT_CARDS_APP_ID,
+  resolveRecipients,
+  validateRemainingBalance,
+  resolveCardBalance,
+  resolveCardLifecycle,
+  buildGiftCardsFromOrderLineItem,
+  buildGiftCardsFromOrder,
+};