@wix/agent-skills 1.35.1 → 1.36.1

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

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

@@ -1,244 +0,0 @@
-'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,
-};