@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/resources/rp-source-wordpress/lib/refund-corroboration.js

@@ -1,194 +0,0 @@
-'use strict';
-
-// The deterministic half of the refund decision: does the source actually evidence a refund, and if so
-// what is its amount and its stable identity?
-//
-// The rule this encodes is narrow for a measured reason. On a live store the field
-// `payplus_refunded` reads like "amount refunded" and actually holds the amount still AVAILABLE
-// to refund: its value equals the full order total on essentially every order that carries it. A
-// mapper trusting the name would mark essentially that whole gateway's revenue as refunded. Its
-// sibling `payplus_status` is the constant `approved` on every such order, so it discriminates nothing.
-// Field names are not evidence.
-//
-// What IS evidence is a canonical WooCommerce refund entity: it has its own identity and its own
-// amount, so it is the refund record itself rather than a hint that one exists. An earlier draft
-// of this rule required a second, independently-produced signal even for those entities -- which
-// would have refused every real refund entity a store carries, since both
-// available core signals (`shop_order_refund` and the `refunded` order status) come from the same
-// producer. Corroboration is required only when existence is being INFERRED from flags, statuses
-// or gateway metadata; it is not required to believe a record that is itself the refund.
-//
-// This module reports the amount as the raw source string. Canonicalizing money is the target
-// mapping's job (order-payment-mapping.js), so there is exactly one decimal implementation in the
-// write path.
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const REGISTRY_PATH = path.join(__dirname, 'refund-corroboration.json');
-
-function loadRegistry(registryPath = REGISTRY_PATH) {
-  return JSON.parse(fs.readFileSync(registryPath, 'utf8'));
-}
-
-function trimmed(value) {
-  if (value === null || value === undefined) return null;
-  const text = String(value).trim();
-  return text.length > 0 ? text : null;
-}
-
-// Only enough parsing to decide qualification. The value handed on is the original string.
-function positiveAmount(raw) {
-  const text = trimmed(raw);
-  if (text === null) return null;
-  if (!/^\+?\d+(\.\d+)?$/.test(text)) return null;
-  return /[1-9]/.test(text) ? text : null;
-}
-
-function excludedKeyFindings(gatewayFields, registry) {
-  const findings = [];
-  const names = Object.keys(gatewayFields || {});
-  for (const rule of registry.excludedKeys) {
-    if (rule.key) {
-      if (trimmed(gatewayFields[rule.key]) !== null) {
-        findings.push({ code: 'refund-weak-signal', field: rule.key, exclusion: rule.exclusion });
-      }
-      continue;
-    }
-    if (rule.keyPattern) {
-      const prefix = rule.keyPattern.replace(/\*$/, '');
-      for (const name of names) {
-        if (name.startsWith(prefix) && trimmed(gatewayFields[name]) !== null) {
-          findings.push({ code: 'refund-weak-signal', field: name, exclusion: rule.exclusion });
-        }
-      }
-    }
-  }
-  return findings;
-}
-
-// `payplus_response` is declared unreadable rather than "to be pattern-matched later": it is a
-// raw provider blob whose sibling fields carry customer name, phone and email. A
-// refund contract that requires parsing unstructured PII is not one that can be honoured safely,
-// so this function must never look inside it. Asserted by the test.
-// Derived from the registry rather than duplicated here, so the declaration has one home.
-function neverReadKeys(registry = loadRegistry()) {
-  return registry.excludedKeys
-    .filter((rule) => rule.exclusion === 'never-read' && rule.key)
-    .map((rule) => rule.key);
-}
-
-// A read plan that names an unreadable field is refused before it is executed, not filtered after
-// the response comes back -- by then the blob is already in the run's working data.
-function assertNoNeverReadKeys(keys = [], registry = loadRegistry()) {
-  const forbidden = new Set(neverReadKeys(registry));
-  const violations = keys.filter((key) => forbidden.has(key));
-  if (violations.length > 0) {
-    throw new Error(
-      `these source keys are declared unreadable and must not appear in a read plan: ${violations.join(', ')}`,
-    );
-  }
-  return true;
-}
-
-function qualifyRefund({
-  refundEntity = null,
-  orderStatus = null,
-  gatewayFields = {},
-  registry = loadRegistry(),
-} = {}) {
-  const findings = excludedKeyFindings(gatewayFields, registry);
-
-  for (const key of neverReadKeys(registry)) {
-    if (Object.prototype.hasOwnProperty.call(gatewayFields, key)) {
-      findings.push({ code: 'redacted-source-values', field: key, exclusion: 'never-read' });
-    }
-  }
-
-  const status = trimmed(orderStatus);
-  const statusCorroborates = status !== null && status.toLowerCase().includes('refunded');
-
-  if (refundEntity) {
-    const sourceId = trimmed(refundEntity.id);
-    const amount = positiveAmount(refundEntity.amount);
-
-    if (!sourceId) {
-      findings.push({ code: 'refund-weak-signal', reason: 'refund entity has no stable source id' });
-      return { qualified: false, amount: null, sourceId: null, evidence: null, findings };
-    }
-    if (!amount) {
-      // An order-level `refunded` status can corroborate an entity but cannot supply its amount,
-      // and the order total is never a substitute.
-      findings.push({ code: 'refund-weak-signal', reason: 'refund entity has no parseable positive amount', sourceId });
-      return { qualified: false, amount: null, sourceId, evidence: null, findings };
-    }
-
-    if (Array.isArray(refundEntity.lineItems) && refundEntity.lineItems.length > 0) {
-      findings.push({ code: 'refund-line-detail-not-preserved', sourceId, lines: refundEntity.lineItems.length });
-    }
-    findings.push({ code: 'refund-date-not-preserved', sourceId });
-
-    return {
-      qualified: true,
-      amount,
-      sourceId,
-      evidence: 'woocommerce-refund-entity',
-      corroboratedByStatus: statusCorroborates,
-      findings,
-    };
-  }
-
-  if (statusCorroborates) {
-    findings.push({ code: 'refund-weak-signal', reason: 'refunded order status with no refund entity supplies no amount', sourceStatus: status });
-  }
-
-  return { qualified: false, amount: null, sourceId: null, evidence: null, findings };
-}
-
-// Every source order gets one refund outcome, so a run can state "0 refunds found; N orders carry
-// an uncorroborated gateway refund field" rather than reporting silence.
-function summarizeRefundEvidence(orders = [], registry = loadRegistry()) {
-  const summary = { orders: orders.length, qualified: 0, weakSignalOrders: 0, findings: {} };
-  for (const order of orders) {
-    const result = qualifyRefund({ ...order, registry });
-    if (result.qualified) summary.qualified += 1;
-    if (!result.qualified && result.findings.some((f) => f.code === 'refund-weak-signal')) {
-      summary.weakSignalOrders += 1;
-    }
-    for (const finding of result.findings) {
-      summary.findings[finding.code] = (summary.findings[finding.code] || 0) + 1;
-    }
-  }
-  return summary;
-}
-
-// Occurrence numbers for a single order's qualified refunds.
-//
-// Target-side identity is the refund's facts plus WHICH occurrence of those facts this refund is,
-// because two distinct source refunds can carry the same payment and amount. Nothing computed
-// that number, so every caller got the default of 1 and the second identical refund reconciled
-// against the first and was silently dropped. The importer writes one payment per order, so grouping
-// by amount within the order is the same grouping the target reconciler uses.
-//
-// Ordering is by stable source id so a re-run assigns the same numbers to the same refunds.
-function assignRefundOccurrences(qualifiedRefunds = []) {
-  const seen = new Map();
-  return [...qualifiedRefunds]
-    .sort((a, b) => String(a.sourceId).localeCompare(String(b.sourceId)))
-    .map((refund) => {
-      const key = String(refund.amount);
-      const occurrence = (seen.get(key) || 0) + 1;
-      seen.set(key, occurrence);
-      return { ...refund, sourceOccurrence: occurrence };
-    });
-}
-
-module.exports = {
-  REGISTRY_PATH,
-  neverReadKeys,
-  assertNoNeverReadKeys,
-  loadRegistry,
-  qualifyRefund,
-  assignRefundOccurrences,
-  summarizeRefundEvidence,
-};

package/skills/wix-replatform/resources/rp-source-wordpress/lib/refund-corroboration.json

@@ -1,100 +0,0 @@
-{
-  "schemaVersion": 1,
-  "purpose": "What qualifies as evidence that a source refund happened, and what may supply its amount. A gateway field name is never evidence.",
-  "qualifications": [
-    {
-      "evidence": "woocommerce-refund-entity",
-      "requires": [
-        "stable source refund id",
-        "parseable positive amount"
-      ],
-      "qualification": "authoritative",
-      "sufficientToWrite": true,
-      "maySupplyAmount": true,
-      "note": "A canonical refund entity is the refund record itself, not a signal that needs a second producer to confirm it."
-    },
-    {
-      "evidence": "woocommerce-refunded-order-status",
-      "requires": [],
-      "qualification": "corroboration-only",
-      "sufficientToWrite": false,
-      "maySupplyAmount": false,
-      "note": "Corroborates an entity but cannot establish a refund on its own and cannot supply a missing amount."
-    },
-    {
-      "evidence": "documented-gateway-refund-record",
-      "requires": [
-        "verified schema and semantics",
-        "stable id",
-        "amount"
-      ],
-      "qualification": "authoritative-once-verified",
-      "sufficientToWrite": true,
-      "maySupplyAmount": true,
-      "note": "No gateway currently qualifies. Adding one requires that gateway's own documentation."
-    },
-    {
-      "evidence": "gateway-flag-status-response-or-refundable-balance",
-      "requires": [],
-      "qualification": "weak-signal",
-      "sufficientToWrite": false,
-      "maySupplyAmount": false,
-      "note": "May corroborate an authoritative record once its semantics are documented. It never creates a refund."
-    },
-    {
-      "evidence": "two-fields-from-one-gateway-callback",
-      "requires": [],
-      "qualification": "weak-signal",
-      "sufficientToWrite": false,
-      "maySupplyAmount": false,
-      "note": "One weak signal, not two independent ones, however many fields the callback wrote."
-    }
-  ],
-  "excludedKeys": [
-    {
-      "key": "payplus_refunded",
-      "exclusion": "never-an-amount-or-existence-signal",
-      "reason": "Observed carrying the full refundable order total on essentially every order of this gateway, written at payment time. Treating it as a refund would refund that gateway's whole revenue."
-    },
-    {
-      "key": "payplus_status",
-      "exclusion": "not-a-refund-signal",
-      "reason": "Observed as a single constant value across every order of this gateway. A field with one value discriminates nothing."
-    },
-    {
-      "key": "payplus_response",
-      "exclusion": "never-read",
-      "reason": "A raw provider blob whose sibling fields carry customer personal data. A refund contract that requires parsing it is not one that can be honoured safely."
-    },
-    {
-      "keyPattern": "tranzila_*",
-      "exclusion": "excluded-until-documented",
-      "reason": "Refund-shaped keys for this gateway are unsurveyed and undocumented. Field names are not evidence."
-    },
-    {
-      "keyPattern": "_gobit_*",
-      "exclusion": "excluded-until-documented",
-      "reason": "Refund-shaped keys for this gateway are unsurveyed and undocumented. Field names are not evidence."
-    }
-  ],
-  "amountSources": [
-    "The qualified refund entity's own amount. Nothing else.",
-    "Never the order total, and never a gateway refundable-balance field."
-  ],
-  "writeContract": [
-    "Resolve the parent order through the order crosswalk.",
-    "Resolve an existing eligible target payment. If none exists, do not fabricate one; report refund-without-payment.",
-    "Add Payments runs before Refund Payments only when a real payment was produced and is not already present.",
-    "Every paymentRefunds[].externalRefund occurrence is the hardcoded literal true, with no caller override.",
-    "Omit side effects. Never place the source refund date in a customer-visible reason field.",
-    "Count every written refund in refund-date-not-preserved; the target refund date is read-only.",
-    "Import an authoritative total at order level and report refund-line-detail-not-preserved. Invent no line ids."
-  ],
-  "findings": [
-    "refund-written",
-    "refund-weak-signal",
-    "refund-without-payment",
-    "refund-date-not-preserved",
-    "refund-line-detail-not-preserved"
-  ]
-}

package/skills/wix-replatform/resources/rp-source-wordpress/lib/sampled-ids-batch.js

@@ -1,157 +0,0 @@
-'use strict';
-
-// Generic pagination + bounded batching for the $SAMPLED_IDS mechanism: a
-// profile-declared requestOverride body may reference another route's FULL id
-// list via "$SAMPLED_IDS:<route>". That dependency route can hold an unknown, unbounded number
-// of records (e.g. an entire product catalog), so this module never assumes the id list fits
-// on one page or that the dependent query can carry every id in a single request:
-//
-//   1. paginate the dependency route to exhaustion, collecting every record's id;
-//   2. split that id list into bounded batches;
-//   3. issue one dependent-route request per batch, with the placeholder resolved to just
-//      that batch's ids;
-//   4. normalize each batch's response (caller-supplied, since response shape is a per-profile
-//      concern) and merge, deduplicating by a caller-supplied record key;
-//   5. stop and report the exact failure on the first page or batch that cannot be read,
-//      rather than returning a partial/undercounted result silently.
-//
-// wp-discovery.js and any rp-import-codegen-generated reader for a requestOverride entity with
-// a $SAMPLED_IDS placeholder both drive this same algorithm, so "does this mechanism scale past
-// a handful of records" has exactly one implementation to get right.
-
-const { fetchJson, shouldContinueCollectionPaging } = require('./wp-http.js');
-
-const DEFAULT_PAGE_SIZE = 100;
-const DEFAULT_BATCH_SIZE = 50;
-
-function chunk(items, size) {
-  const batches = [];
-  for (let i = 0; i < items.length; i += size) {
-    batches.push(items.slice(i, i + size));
-  }
-  return batches;
-}
-
-// Pages a plain GET collection route to exhaustion, collecting `idField` off every record.
-// Returns { ok: true, ids } or { ok: false, ids, failure }. On failure, `ids` holds whatever
-// was collected before the failing page, but callers must treat a failed run as unusable —
-// never as "the true, if undercounted, id list" — a partial id list understates the dependent
-// query rather than correctly reporting it as unknown.
-async function collectAllIds({
-  baseUrl, headers, route, idField = 'id', pageSize = DEFAULT_PAGE_SIZE,
-  query = {}, timeoutMs, progress, fetchJsonFn = fetchJson,
-}) {
-  const ids = [];
-  let page = 1;
-  for (;;) {
-    const response = await fetchJsonFn(baseUrl, route, {
-      headers,
-      method: 'GET',
-      query: { ...query, page, per_page: pageSize },
-      timeoutMs,
-      progress,
-      progressContext: { step: 'paginate-dependency', entity: route, page },
-    });
-    if (!response.ok) {
-      return { ok: false, ids, failure: { route, page, status: response.status, statusText: response.statusText } };
-    }
-    // A 2xx whose body is not an array (an envelope, an error object, malformed JSON) is not an
-    // empty page: coercing it to [] would end pagination and report an exact zero instead of
-    // deferring the dependent query as unknown.
-    if (!Array.isArray(response.json)) {
-      return { ok: false, ids, failure: { route, page, status: response.status, statusText: response.statusText, reason: 'malformed-response' } };
-    }
-    const items = response.json;
-    for (const item of items) {
-      const id = item && item[idField];
-      if (id !== undefined && id !== null) ids.push(id);
-    }
-    if (!shouldContinueCollectionPaging({ responseHeaders: response.headers, page, perPage: pageSize, itemCount: items.length })) {
-      return { ok: true, ids };
-    }
-    page += 1;
-  }
-}
-
-// Deduplicates `records` by `recordKeyField`, preserving first-seen order. A record missing
-// the key field is kept as-is (never dropped) since there is nothing to dedupe it against.
-function dedupeByKey(records, recordKeyField) {
-  if (!recordKeyField) return records;
-  const seen = new Set();
-  const deduped = [];
-  for (const record of records) {
-    const key = record && record[recordKeyField];
-    if (key === undefined || key === null) {
-      deduped.push(record);
-      continue;
-    }
-    if (seen.has(key)) continue;
-    seen.add(key);
-    deduped.push(record);
-  }
-  return deduped;
-}
-
-// Splits `ids` into bounded batches and issues one request per batch against `route`, building
-// each batch's body with `buildBody(batchIds)` and normalizing its RAW, unmodified JSON
-// response with `normalizeBatch(rawJson, { batchIndex })` — envelope resolution / fragment
-// reassembly are left to the caller so this module stays agnostic of any one profile's response
-// shape, but that only works if this module hands over the real payload rather than coercing
-// it: a batch response wrapped in a responseEnvelope is an OBJECT, not an array, and
-// pre-coercing it to `[]` here would silently discard it before normalizeBatch ever saw it.
-// `normalizeBatch` must return `{ ok, records }` — `ok: false` means the response did not
-// resolve to a usable shape (not merely "resolved to zero records", which is a legitimate `ok:
-// true` outcome for a batch whose ids simply have no matches) and is treated exactly like an
-// HTTP failure: stop and defer, discarding merged batches from this run, rather than counting
-// it as zero. Dedupes across all successful batches. Stops and reports the exact failure on the
-// first batch that cannot be read or normalized; already-merged batches from that run must be
-// discarded by the caller, not reported as a partial count.
-async function queryInBatches({
-  baseUrl, headers, route, method, buildBody, ids, batchSize = DEFAULT_BATCH_SIZE,
-  normalizeBatch = (records) => (Array.isArray(records) ? { ok: true, records } : { ok: false, records: [] }),
-  recordKeyField = 'id', timeoutMs, progress, fetchJsonFn = fetchJson,
-}) {
-  const batches = chunk(ids, batchSize);
-  const merged = [];
-  for (let batchIndex = 0; batchIndex < batches.length; batchIndex += 1) {
-    const batchIds = batches[batchIndex];
-    // `headers` is a real Headers instance (wp-http.js buildHeaders) — spreading it would
-    // silently drop every entry including Authorization, since Headers is not a plain object.
-    const withBody = new Headers(headers);
-    withBody.set('content-type', 'application/json');
-    const response = await fetchJsonFn(baseUrl, route, {
-      headers: withBody,
-      method,
-      body: JSON.stringify(buildBody(batchIds)),
-      timeoutMs,
-      progress,
-      progressContext: { step: 'query-dependent-batch', entity: route, batch: batchIndex + 1, total: batches.length },
-    });
-    if (!response.ok) {
-      return {
-        ok: false,
-        records: merged,
-        failure: { route, batchIndex, batchSize: batchIds.length, status: response.status, statusText: response.statusText, reason: 'http-error' },
-      };
-    }
-    const normalized = normalizeBatch(response.json, { batchIndex });
-    if (!normalized.ok) {
-      return {
-        ok: false,
-        records: merged,
-        failure: { route, batchIndex, batchSize: batchIds.length, status: response.status, statusText: response.statusText, reason: 'invalid-shape' },
-      };
-    }
-    merged.push(...normalized.records);
-  }
-  return { ok: true, records: dedupeByKey(merged, recordKeyField) };
-}
-
-module.exports = {
-  DEFAULT_PAGE_SIZE,
-  DEFAULT_BATCH_SIZE,
-  collectAllIds,
-  queryInBatches,
-  dedupeByKey,
-  chunk,
-};