@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-execution-policy/lib/coupon-currency-plan-report.js

@@ -0,0 +1,143 @@
+'use strict';
+
+// The coupons / currency / plan-definitions section of the
+// plan report, with the same accounting discipline as payments-report.js:
+//
+//   1. Every line is emitted WITH its count, including zero. A missing line is indistinguishable
+//      from a line nobody computed.
+//   2. Per area, written + excluded + skipped = discovered, or the report is not approvable.
+//   3. The report never says "imported N coupons": the codes are overwhelmingly auto-generated
+//      single-use promos, and the redeemability breakdown is the honest count.
+//   4. "none found" is never phrased as "not supported": a store with zero plan rows has nothing
+//      to import, which is a measured fact, not a missing capability.
+
+const LINES = Object.freeze([
+  'coupons-source-total', 'coupons-not-published', 'coupons-discovered', 'coupons-written',
+  'coupons-redeemable', 'coupons-expired', 'coupons-exhausted', 'coupons-no-expiry',
+  'coupon-type-unmappable', 'coupon-scope-unmappable', 'coupons-usage-limit-unresolved', 'coupons-skipped',
+  'coupon-usage-surface', 'coupon-usage-written', 'coupon-usage-unresolved',
+  // `coupons-spent-after-capture` and `coupons-partially-used-limit-reduced` are
+  // sub-counts of `coupons-written`, NOT terms in the identity: both describe a coupon that WAS
+  // created, just not as the source snapshot described it. `coupons-face-value-precision-unsupported`
+  // is a real identity term — that coupon is refused, and a report that hid it would read as
+  // "we imported every redeemable one".
+  'coupons-spent-after-capture', 'coupons-partially-used-limit-reduced',
+  'coupons-face-value-precision-unsupported',
+  'voucher-drift-reconciled', 'voucher-drift-remedy-pending',
+  // Non-count: the money still redeemable twice, as "<amount> <currency> across <n> codes".
+  'voucher-liability-live',
+  'currency-validated', 'currency-mismatch', 'currency-multi-detected', 'currency-unresolved',
+  'plans-source-total', 'plans-written', 'plan-description-truncated', 'plans-skipped', 'plans-live-hazard',
+]);
+const TEXT_LINES = Object.freeze(['coupon-usage-surface', 'voucher-liability-live']);
+const COUNT_LINES = Object.freeze(LINES.filter((l) => !TEXT_LINES.includes(l)));
+const PROHIBITED = Object.freeze([/\bimported \d[\d,]* coupon/i, /not supported/i]);
+
+function asCount(value, code, blocking) {
+  if (value === undefined || value === null) return 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) { blocking.push({ code: 'invalid-count', detail: `${code} must be a non-negative integer, got ${JSON.stringify(value)}` }); return 0; }
+  return n;
+}
+
+function buildCouponCurrencyPlanReport({ counts = {}, notPublishedByStatus = {}, couponUsageSurface = null, voucherLiabilityLive = null, currencyOutcome = null, planSources = null, notes = [] } = {}) {
+  const blocking = [];
+  const lines = [];
+  const c = {};
+  for (const code of COUNT_LINES) c[code] = asCount(counts[code], code, blocking);
+  for (const code of Object.keys(counts)) {
+    if (code === 'skippedBy') continue; // the per-reason breakdown ridealong from tallyCouponWriteOutcomes; rendered as notes below
+    if (!LINES.includes(code)) blocking.push({ code: 'unknown-report-line', detail: `${code} is not an Appendix D line, so the report has nowhere to put it` });
+  }
+  const skippedBy = counts.skippedBy && typeof counts.skippedBy === 'object' ? counts.skippedBy : {};
+  const skippedNotes = Object.entries(skippedBy).map(([reason, n]) => `coupons-skipped: ${n} × ${reason}`);
+
+  // Coupons: discovered = written + type-unmappable + scope-unmappable + usage-limit-unresolved
+  //                       + face-value-precision-unsupported + skipped.
+  const couponAccounted = c['coupons-written'] + c['coupon-type-unmappable'] + c['coupon-scope-unmappable'] + c['coupons-usage-limit-unresolved'] + c['coupons-face-value-precision-unsupported'] + c['coupons-skipped'];
+  if (couponAccounted !== c['coupons-discovered']) {
+    blocking.push({ code: 'coupon-accounting-mismatch', detail: `written ${c['coupons-written']} + type-unmappable ${c['coupon-type-unmappable']} + scope-unmappable ${c['coupon-scope-unmappable']} + usage-limit-unresolved ${c['coupons-usage-limit-unresolved']} + face-value-precision-unsupported ${c['coupons-face-value-precision-unsupported']} + skipped ${c['coupons-skipped']} = ${couponAccounted}, but ${c['coupons-discovered']} were discovered` });
+  }
+  if (c['coupons-face-value-precision-unsupported'] > 0) {
+    blocking.push({ code: 'coupon-face-value-precision-unsupported', detail: `${c['coupons-face-value-precision-unsupported']} coupon(s) were refused because their face value carries more precision than the target can hold. Rounding them would put a different amount on the target while every check reported a match — decide per coupon before approving` });
+  }
+  // A pending remedy means money is redeemable a second time on the
+  // merchant's live store. It halts approval, and the halt names the money, not just the count.
+  if (c['voucher-drift-remedy-pending'] > 0) {
+    blocking.push({ code: 'voucher-drift-remedy-pending', detail: `${c['voucher-drift-remedy-pending']} bearer voucher(s) were spent at source and are still redeemable on the target${voucherLiabilityLive ? ` (${voucherLiabilityLive})` : ''}. Remedy: deactivate each in place and tag it Already_Used — the record, the code and the amount all survive. It needs the owner's decision per code, and a 2xx never counts as applied without a read-back` });
+  }
+  // Source total = discovered + not published; a DB total above REST is the EXPECTED shape.
+  if (c['coupons-source-total'] !== c['coupons-discovered'] + c['coupons-not-published']) {
+    blocking.push({ code: 'coupon-denominator-mismatch', detail: `source total ${c['coupons-source-total']} != discovered ${c['coupons-discovered']} + not published ${c['coupons-not-published']}` });
+  }
+  const redeemPartition = c['coupons-redeemable'] + c['coupons-expired'] + c['coupons-exhausted'] + c['coupons-usage-limit-unresolved'];
+  if (redeemPartition !== c['coupons-discovered']) {
+    blocking.push({ code: 'coupon-redeemability-mismatch', detail: `redeemable + expired + exhausted + usage-limit-unresolved = ${redeemPartition}, discovered ${c['coupons-discovered']}` });
+  }
+  // Plans: source total = written + skipped (unmappable, reconciled, failed all land in skipped).
+  if (c['plans-source-total'] !== c['plans-written'] + c['plans-skipped']) {
+    blocking.push({ code: 'plan-accounting-mismatch', detail: `plans written ${c['plans-written']} + skipped ${c['plans-skipped']} != source total ${c['plans-source-total']}` });
+  }
+  // A purchasable plan that landed and could not be archived is live on the merchant's site now.
+  if (c['plans-live-hazard'] > 0) {
+    blocking.push({ code: 'plan-live-hazard', detail: `${c['plans-live-hazard']} plan(s) came back purchasable and the archive call failed; archive them by hand (Pricing Plans V2 archive) before this report is approved` });
+  }
+  // Currency: exactly one of the four outcomes carries 1. `currency-unresolved` is its own line
+  // (the settings, the target or individual orders could not be read), not a generic "missing".
+  const currencyFlags = c['currency-validated'] + c['currency-mismatch'] + c['currency-multi-detected'] + c['currency-unresolved'];
+  if (currencyFlags !== 1) blocking.push({ code: 'currency-outcome-missing', detail: `exactly one currency outcome must be reported, got ${currencyFlags}` });
+  if (c['currency-mismatch'] > 0 || c['currency-multi-detected'] > 0) {
+    blocking.push({ code: 'currency-halt', detail: 'order import must not proceed: the source history is not in the target site currency, or spans more than one currency' });
+  }
+  if (c['currency-unresolved'] > 0) {
+    blocking.push({ code: 'currency-halt', detail: 'order import must not proceed: the store currency, the target site currency, or the currency of some orders could not be resolved (see the gate\'s findings)' });
+  }
+  if (couponUsageSurface === null || couponUsageSurface === undefined) {
+    blocking.push({ code: 'coupon-usage-surface-missing', detail: 'the discovery must name which surface carried coupon usage (rest-order-coupon-lines, wc_order_coupon_lookup, or none-found)' });
+  }
+
+  for (const code of LINES) {
+    if (code === 'coupon-usage-surface') lines.push({ code, label: code, value: couponUsageSurface === null || couponUsageSurface === undefined ? 'not-reported' : String(couponUsageSurface) });
+    else if (code === 'voucher-liability-live') lines.push({ code, label: code, value: voucherLiabilityLive === null || voucherLiabilityLive === undefined ? 'none' : String(voucherLiabilityLive) });
+    else lines.push({ code, label: code, value: c[code] });
+  }
+  for (const [status, n] of Object.entries(notPublishedByStatus || {})) {
+    lines.push({ code: `coupons-not-published:${status}`, label: `coupons-not-published (${status}, deliberately excluded)`, value: asCount(n, `coupons-not-published:${status}`, blocking) });
+  }
+  if (planSources) {
+    for (const [source, n] of Object.entries(planSources)) lines.push({ code: `plans-source-total:${source}`, label: `plans-source-total (${source})`, value: asCount(n, `plans-source-total:${source}`, blocking) });
+  }
+
+  const rendered = renderCouponCurrencyPlanReport({ lines, notes: [...skippedNotes, ...notes], counts: c, currencyOutcome, voucherLiabilityLive });
+  for (const pattern of PROHIBITED) {
+    if (pattern.test(rendered)) blocking.push({ code: 'prohibited-phrase', detail: `the report matches ${pattern}: counts must carry the redeemability breakdown, and absence is "none found", never "not supported"` });
+  }
+  return { lines, blocking, rendered, approvable: blocking.length === 0 };
+}
+
+function renderCouponCurrencyPlanReport({ lines, notes = [], counts = {}, currencyOutcome = null, voucherLiabilityLive = null }) {
+  const out = ['Coupons, currency and pricing-plan definitions', ''];
+  // The honest headline, never "imported N coupons".
+  out.push(`  ${counts['coupons-discovered'] || 0} published coupon codes discovered: ${counts['coupons-redeemable'] || 0} redeemable, ${counts['coupons-expired'] || 0} expired, ${counts['coupons-exhausted'] || 0} fully redeemed, ${counts['coupons-no-expiry'] || 0} with no expiry`);
+  // Money redeemable twice is the one thing that must not be a line item to scroll past.
+  if ((counts['voucher-drift-remedy-pending'] || 0) > 0) {
+    out.push(`  ⚠️ ${counts['voucher-drift-remedy-pending']} bearer voucher(s) spent at source are still redeemable on the target${voucherLiabilityLive ? `: ${voucherLiabilityLive}` : ''}`);
+  }
+  if ((counts['coupons-spent-after-capture'] || 0) > 0) {
+    out.push(`  ${counts['coupons-spent-after-capture']} coupon(s) were used up at source between the read and the write, and were created switched off`);
+  }
+  if ((counts['coupons-face-value-precision-unsupported'] || 0) > 0) {
+    out.push(`  ⚠️ ${counts['coupons-face-value-precision-unsupported']} coupon(s) carry a face value the target cannot hold and were NOT created — reported rather than rounded`);
+  }
+  if ((counts['coupons-partially-used-limit-reduced'] || 0) > 0) {
+    out.push(`  ${counts['coupons-partially-used-limit-reduced']} coupon(s) were partly used at source and carry only the uses the holder has left`);
+  }
+  if ((counts['plans-source-total'] || 0) === 0) out.push('  no pricing plans found in the source (all plan-shaped sources hold zero rows)');
+  if (currencyOutcome) out.push(`  currency: ${currencyOutcome}`);
+  out.push('');
+  for (const line of lines) out.push(`  ${line.label}: ${line.value}`);
+  if (notes.length > 0) { out.push(''); for (const note of notes) out.push(`  note: ${note}`); }
+  return out.join('\n');
+}
+
+module.exports = { LINES, COUNT_LINES, TEXT_LINES, buildCouponCurrencyPlanReport, renderCouponCurrencyPlanReport };

package/skills/wix-replatform/resources/rp-execution-policy/lib/payments-report.js

@@ -0,0 +1,244 @@
+'use strict';
+
+// The payments section of the plan report, and the accounting rules
+// that decide whether it can be approved at all.
+//
+// Three properties this module exists to guarantee, each of which a hand-written report has got
+// wrong before:
+//
+//   1. THE OUTCOMES PARTITION THE POPULATION. Every source order lands in exactly one bucket, and
+//      the buckets sum to the denominator. A report whose numbers do not add up is not a report
+//      with a rounding problem, it is a report that is hiding orders -- so a mismatch BLOCKS the
+//      approval gate rather than printing a caveat.
+//   2. ZERO IS A RESULT. Every outcome and every count is emitted even when it is zero. "0 refunds
+//      found" is reviewable at a glance and is the cheapest place to catch a mis-mapped source
+//      field; a missing line is indistinguishable from a line nobody computed.
+//   3. CANDIDATE COVERAGE IS NOT WRITABLE COVERAGE. Many orders carry some
+//      reference-shaped value while only a smaller share is currently defensible. Reporting the
+//      first number as though it were the second overstates fidelity, so the two are separate
+//      lines and the report refuses to collapse them.
+//
+// The denominator gets its own guard. A prior survey's narrower "card order" count must never
+// stand in for the run's own reconciled read: the two can differ on a trading
+// store, and the completeness claim is only as good as what it counted.
+
+// The codes come from one frozen registry shared with the writers, not from a list kept here and
+// not from scraping the writer source. A hand-maintained list drifted four times; the scraper that
+// replaced it missed an outcome produced by a ternary, which is a green test over a real gap.
+const registry = require('../../../lib/payments-outcome-registry.js');
+
+const PAYMENT_OUTCOMES = registry.PAYMENT_OUTCOMES;
+const ADDITIONAL_COUNTS = registry.REPORTABLE;
+
+// False for records, and therefore prohibited: changing payment provider does not lose payment
+// history, because these records are provider-independent.
+// Mirrors invoice-discovery's STRATEGIES. A store-wide strategy, never a per-document action.
+const INVOICE_STRATEGIES = ['none-found', 'number-only', 'wordpress-hosted', 'third-party-hosted', 'mixed'];
+
+const PROHIBITED_PHRASES = ['lose your history', 'lose their history', 'loses your history'];
+
+// A count is a non-negative integer. Coercing anything else let a report with `sourceOrders: -1`
+// and `payment-written: -1` come back approvable -- the sum check passes and the numbers are
+// nonsense, which is worse than a missing line.
+function asCount(value, code, label, blocking) {
+  if (value === undefined || value === null) return 0;
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < 0) {
+    if (blocking) {
+      blocking.push({ code: code || 'invalid-count', detail: `${label} must be a non-negative integer, got ${JSON.stringify(value)}` });
+    }
+    return 0;
+  }
+  return numeric;
+}
+
+function buildPaymentsReport({
+  denominator = {},
+  outcomes = {},
+  counts = {},
+  referenceCoverage = {},
+  providers = null,
+  providerParity = {},
+  invoiceStrategy = null,
+  notes = [],
+} = {}) {
+  const blocking = [];
+  const lines = [];
+
+  const sourceOrders = asCount(denominator.sourceOrders, 'invalid-denominator', 'denominator.sourceOrders', blocking);
+  const priorSurvey = denominator.priorSurveyCount === undefined || denominator.priorSurveyCount === null
+    ? null
+    : asCount(denominator.priorSurveyCount, 'invalid-count', 'denominator.priorSurveyCount', blocking);
+
+  if (denominator.from !== 'run-reconciled-read') {
+    blocking.push({
+      code: 'denominator-not-from-reconciled-read',
+      detail: 'the denominator must come from this run\'s own reconciled source reads, not from a prior survey or a remembered constant',
+    });
+  }
+  // A stored count differing from a fresh one is NOT a defect. A store that is still trading
+  // takes new orders continuously, so two counts taken hours apart legitimately differ
+  // and no amount of reconciling makes them agree. Blocking on it would block every run on any
+  // live store. It is reported as drift, for context, and the run's own read is authoritative.
+  if (priorSurvey !== null && priorSurvey !== sourceOrders) {
+    lines.push({
+      code: 'denominator-drift',
+      label: 'Change since the prior survey (expected on a trading store)',
+      value: sourceOrders - priorSurvey,
+    });
+  }
+
+  lines.push({ code: 'source-orders', label: 'Source orders discovered', value: sourceOrders });
+  if (priorSurvey !== null) {
+    lines.push({ code: 'prior-survey-orders', label: 'Prior survey count (not the denominator)', value: priorSurvey });
+  }
+
+  let outcomeTotal = 0;
+  for (const code of PAYMENT_OUTCOMES) {
+    const value = asCount(outcomes[code], 'invalid-count', `outcome ${code}`, blocking);
+    outcomeTotal += value;
+    lines.push({ code, label: code, value, partitioning: true });
+  }
+
+  // The buyer outcomes are a second partition. Optional as a whole (older runs report
+  // none), but once any is present they must account for every source order, or the report is
+  // hiding orders the same way a short payment partition would.
+  const buyerCodes = Object.keys(outcomes).filter((code) => registry.BUYER_OUTCOMES.includes(code));
+  if (buyerCodes.length > 0) {
+    let buyerTotal = 0;
+    for (const code of registry.BUYER_OUTCOMES) buyerTotal += asCount(outcomes[code], 'invalid-count', `outcome ${code}`, blocking);
+    if (buyerTotal !== sourceOrders) {
+      blocking.push({ code: 'buyer-outcome-sum-mismatch', detail: `the buyer outcomes sum to ${buyerTotal} but the run discovered ${sourceOrders} source orders` });
+    }
+  }
+  const unknownOutcomes = Object.keys(outcomes).filter((code) => !PAYMENT_OUTCOMES.includes(code) && !registry.BUYER_OUTCOMES.includes(code));
+  if (unknownOutcomes.length > 0) {
+    blocking.push({
+      code: 'unknown-payment-outcome',
+      detail: `these outcomes are not declared as partitioning buckets, so the sum cannot be trusted: ${unknownOutcomes.join(', ')}`,
+    });
+  }
+  if (outcomeTotal !== sourceOrders) {
+    blocking.push({
+      code: 'payment-outcome-sum-mismatch',
+      detail: `the payment outcomes sum to ${outcomeTotal} but the run discovered ${sourceOrders} source orders; ${Math.abs(sourceOrders - outcomeTotal)} order(s) have no reported outcome`,
+    });
+  }
+  lines.push({ code: 'payment-outcome-total', label: 'Payment outcomes total', value: outcomeTotal });
+
+  // Both coverage numbers, always, and never one in place of the other.
+  const candidates = asCount(referenceCoverage.candidates, 'invalid-count', 'referenceCoverage.candidates', blocking);
+  const defensible = asCount(referenceCoverage.defensible, 'invalid-count', 'referenceCoverage.defensible', blocking);
+  lines.push({ code: 'reference-candidates', label: 'Orders carrying a reference-shaped candidate', value: candidates });
+  lines.push({ code: 'reference-defensible', label: 'Orders with a defensible provider reference', value: defensible });
+  lines.push({ code: 'reference-not-defensible', label: 'Orders whose candidate could not be attributed', value: Math.max(candidates - defensible, 0) });
+  if (defensible > candidates) {
+    blocking.push({
+      code: 'reference-coverage-impossible',
+      detail: `defensible references (${defensible}) exceed candidates (${candidates}), so one of the two was miscomputed`,
+    });
+  }
+
+  for (const code of ADDITIONAL_COUNTS) {
+    // Buyer outcomes arrive under `outcomes` (they partition); everything else under `counts`.
+    const source = registry.BUYER_OUTCOMES.includes(code) ? outcomes : counts;
+    lines.push({ code, label: code, value: asCount(source[code], 'invalid-count', `count ${code}`, blocking) });
+  }
+
+  // Same provenance rule as the invoice strategy: an absent inventory is missing discovery, not a
+  // store with no providers. Rendering "none found" for something nobody looked for is the exact
+  // confusion this report exists to prevent.
+  if (providers === null || providers === undefined) {
+    blocking.push({
+      code: 'provider-discovery-missing',
+      detail: 'no provider inventory was supplied; a store with genuinely no providers must pass an empty array',
+    });
+  }
+  const providerLines = (providers || []).map((provider) => ({
+    id: provider.id,
+    displayName: provider.displayName,
+    enabled: Boolean(provider.enabled),
+  }));
+  for (const provider of providers || []) {
+    for (const forbidden of ['secret', 'key', 'token', 'password', 'credential']) {
+      for (const [field, value] of Object.entries(provider)) {
+        if (field.toLowerCase().includes(forbidden) && value !== undefined && value !== null && value !== '') {
+          blocking.push({
+            code: 'provider-inventory-carries-credential-shaped-field',
+            detail: `provider ${provider.id} exposes "${field}" in the report; the inventory carries identifier, display name and enabled state only`,
+          });
+        }
+      }
+    }
+  }
+
+  const parity = {
+    country: providerParity.country || null,
+    currency: providerParity.currency || null,
+    supported: providerParity.supported || [],
+    confidence: providerParity.providerIdentityExposed === true ? 'verified-provider-parity' : 'unverified-provider-parity',
+  };
+
+  // A missing strategy is missing DISCOVERY, not an empty result -- reporting it as "none-found"
+  // makes "we looked and there is nothing" indistinguishable from "we never looked". And the
+  // value must be one of the strategies, not an action: `reference-only` is what happens to one
+  // document, and it passed silently as a store-wide strategy.
+  const strategy = invoiceStrategy === null || invoiceStrategy === undefined ? null : String(invoiceStrategy);
+  if (strategy === null) {
+    blocking.push({ code: 'invoice-discovery-missing', detail: 'no invoice strategy was reported; discovery must run before the plan is approved' });
+  } else if (!INVOICE_STRATEGIES.includes(strategy)) {
+    blocking.push({ code: 'invalid-invoice-strategy', detail: `"${strategy}" is not an invoice strategy; expected one of ${INVOICE_STRATEGIES.join(', ')}` });
+  }
+  lines.push({ code: 'invoice-strategy', label: 'Invoice strategy', value: strategy === null ? 'not-reported' : strategy });
+
+  const rendered = renderPaymentsReport({ lines, providers: providerLines, parity, notes });
+  const lowered = rendered.toLowerCase();
+  for (const phrase of PROHIBITED_PHRASES) {
+    if (lowered.includes(phrase)) {
+      blocking.push({
+        code: 'prohibited-phrase',
+        detail: `the report contains "${phrase}", which is false for payment records: they are provider-independent and survive a provider change`,
+      });
+    }
+  }
+
+  return { lines, providers: providerLines, parity, blocking, rendered, approvable: blocking.length === 0 };
+}
+
+function renderPaymentsReport({ lines, providers, parity, notes = [] }) {
+  const out = ['Payments, refunds and invoice documents', ''];
+
+  out.push('Source payment providers found:');
+  if (providers.length === 0) {
+    out.push('  none found');
+  } else {
+    for (const provider of providers) {
+      out.push(`  ${provider.id} — ${provider.displayName} — ${provider.enabled ? 'enabled' : 'disabled'}`);
+    }
+  }
+  out.push('  no credential value was read or retained');
+  out.push('');
+
+  out.push(`Provider availability for ${parity.country || 'unknown country'} / ${parity.currency || 'unknown currency'}: ${parity.confidence}`);
+  if (parity.supported.length > 0) out.push(`  supported: ${parity.supported.join(', ')}`);
+  out.push('');
+
+  for (const line of lines) {
+    out.push(`  ${line.label}: ${line.value}`);
+  }
+
+  if (notes.length > 0) {
+    out.push('');
+    for (const note of notes) out.push(`  note: ${note}`);
+  }
+  return out.join('\n');
+}
+
+module.exports = {
+  PAYMENT_OUTCOMES,
+  ADDITIONAL_COUNTS,
+  PROHIBITED_PHRASES,
+  INVOICE_STRATEGIES,
+  buildPaymentsReport,
+  renderPaymentsReport,
+};