@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-replatform/resources/rp-source-wordpress/lib/wix-wp-plugin-v2-client.test-fixture.js

@@ -0,0 +1,149 @@
+'use strict';
+
+// Exercises BOTH of the handler's capabilities, not just discoverStructure -- a self-test
+// that only ever called discoverStructure would report readiness even if queryStructure
+// (the route that actually returns real data) were completely broken.
+async function selfTest({ discoverStructure, queryStructure, guardedValueColumns }) {
+  const calls = [];
+  const httpClient = {
+    async get(url, options) {
+      calls.push({ method: 'GET', url, options });
+      return {
+        table: options.params.table,
+        columns: [
+          { name: 'id', type: 'bigint(20) unsigned', nullable: false, key: 'primary' },
+          { name: 'number', type: 'varchar(64)', nullable: false, key: 'unique' },
+          { name: 'active', type: 'tinyint(1)', nullable: false, key: null },
+        ],
+      };
+    },
+    async post(url, options) {
+      calls.push({ method: 'POST', url, options });
+      return {
+        rows: [{ id: '1', number: 'CARD0001', active: '1' }],
+        pagingMetadata: { cursors: { next: null }, hasNext: false, total: 1 },
+        redactionMetadata: { redactedValueCount: 0, redactedColumns: [] },
+      };
+    },
+  };
+
+  const discovered = await discoverStructure({ httpClient, siteBaseUrl: 'https://example.test', table: 'pimwick_gift_card' });
+  if (discovered.table !== 'pimwick_gift_card' || discovered.columns.length !== 3) {
+    throw new Error('fixture discovery did not return the expected table/columns shape');
+  }
+  const getCall = calls.find((call) => call.method === 'GET');
+  if (!getCall || getCall.options.params.table !== 'pimwick_gift_card') {
+    throw new Error('fixture discovery did not request the expected table param');
+  }
+  if (!getCall.url.endsWith('/wp-json/wix-wp-plugin/v2/structure')) {
+    throw new Error('fixture discovery did not hit the expected wix-wp-plugin-v2 route');
+  }
+
+  const queried = await queryStructure({
+    httpClient,
+    siteBaseUrl: 'https://example.test',
+    structureRequest: {
+      table: 'pimwick_gift_card',
+      select: [{ column: 'id' }, { column: 'number' }, { column: 'active' }],
+      orderBy: [{ column: 'id', direction: 'asc' }],
+    },
+    limit: 10,
+  });
+  if (!Array.isArray(queried.rows) || queried.rows.length !== 1 || queried.rows[0].number !== 'CARD0001') {
+    throw new Error('fixture query did not return the expected row shape');
+  }
+  if (queried.pagingMetadata.hasNext !== false || queried.pagingMetadata.total !== 1) {
+    throw new Error('fixture query did not return the expected pagingMetadata shape');
+  }
+  const postCall = calls.find((call) => call.method === 'POST');
+  if (!postCall || !postCall.url.endsWith('/wp-json/wix-wp-plugin/v2/query/admin-key')) {
+    throw new Error('fixture query did not hit the expected wix-wp-plugin-v2 route');
+  }
+  const postedBody = JSON.parse(postCall.options.body);
+  if (postedBody.structureRequest.table !== 'pimwick_gift_card' || postedBody.limit !== 10) {
+    throw new Error('fixture query did not send the expected request body');
+  }
+
+  // --- the safety metadata must survive the client, and its absence must fail ---
+
+  if (!queried.redactionMetadata || queried.redactionMetadata.redactedValueCount !== 0) {
+    throw new Error('fixture query dropped redactionMetadata, which every response carries');
+  }
+  if (queried.eavAccess !== null) {
+    throw new Error('a plain table must report eavAccess as null, not as a fabricated object');
+  }
+
+  // A plugin too old to send redactionMetadata has no value guard at all. Accepting that
+  // response would report a guarded read that never happened, so the client must refuse it.
+  const legacyClient = {
+    async post() {
+      return { rows: [{ id: '1' }], pagingMetadata: { cursors: { next: null }, hasNext: false, total: 1 } };
+    },
+  };
+  let refusedLegacy = false;
+  try {
+    await queryStructure({
+      httpClient: legacyClient,
+      siteBaseUrl: 'https://example.test',
+      structureRequest: { table: 'pimwick_gift_card', select: [{ column: 'id' }], orderBy: [{ column: 'id', direction: 'asc' }] },
+    });
+  } catch (error) {
+    refusedLegacy = /redactionMetadata/.test(error.message);
+  }
+  if (!refusedLegacy) {
+    throw new Error('a response with no redactionMetadata must be refused, not defaulted to zero');
+  }
+
+  // A key/value table: both routes must hand the caller enough to build a legal request,
+  // INCLUDING the second guarded value column on a multi-pair schema.
+  const eavClient = {
+    async get(url, options) {
+      return {
+        table: options.params.table,
+        columns: [
+          { name: 'meta_id', type: 'bigint(20) unsigned', nullable: false, key: 'primary' },
+          { name: 'meta_key', type: 'varchar(255)', nullable: true, key: 'index' },
+          { name: 'meta_value', type: 'longtext', nullable: true, key: null },
+          { name: 'name', type: 'varchar(64)', nullable: true, key: null },
+          { name: 'value', type: 'longtext', nullable: true, key: null },
+        ],
+        eavPair: {
+          keyColumn: 'meta_key',
+          valueColumn: 'meta_value',
+          additionalPairs: [{ keyColumn: 'name', valueColumn: 'value' }],
+        },
+      };
+    },
+    async post() {
+      return {
+        rows: [{ meta_key: 'last4', n: '12' }],
+        pagingMetadata: { cursors: { next: null }, hasNext: false, total: 1 },
+        redactionMetadata: { redactedValueCount: 1, redactedColumns: ['meta_value'] },
+        eavAccess: { keyColumn: 'meta_key', valueColumn: 'meta_value', tier: 'key-discovery', pinnedKeys: [] },
+      };
+    },
+  };
+  const eavDiscovered = await discoverStructure({ httpClient: eavClient, siteBaseUrl: 'https://example.test', table: 'dual_meta' });
+  if (!eavDiscovered.eavPair || eavDiscovered.eavPair.keyColumn !== 'meta_key') {
+    throw new Error('discoverStructure dropped eavPair -- the caller loses its only advance notice that a table is key-scoped');
+  }
+  if (guardedValueColumns(eavDiscovered.eavPair).join(',') !== 'meta_value,value') {
+    throw new Error('guardedValueColumns must report EVERY guarded value column, not only the first pair\'s');
+  }
+  const eavQueried = await queryStructure({
+    httpClient: eavClient,
+    siteBaseUrl: 'https://example.test',
+    structureRequest: { table: 'dual_meta', select: [{ column: 'meta_key' }], orderBy: [{ column: 'meta_key', direction: 'asc' }] },
+  });
+  if (!eavQueried.eavAccess || eavQueried.eavAccess.tier !== 'key-discovery') {
+    throw new Error('queryStructure dropped eavAccess -- the caller cannot tell the read was key-scoped');
+  }
+  if (eavQueried.redactionMetadata.redactedValueCount !== 1
+    || eavQueried.redactionMetadata.redactedColumns[0] !== 'meta_value') {
+    throw new Error('queryStructure dropped the redaction count -- a redacted value would look like real data');
+  }
+
+  return true;
+}
+
+module.exports = selfTest;

package/skills/wix-replatform/resources/rp-source-wordpress/lib/woo-inventory.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Source policy only. The target adapter owns how these canonical values are written.
+function mapWooInventory(source = {}, { parent } = {}) {
+  const gap = (reason) => ({ status: 'decision-needed', fields: {}, reason });
+  if (source.backorders_allowed === true || source.backordered === true ||
+      (source.backorders != null && source.backorders !== 'no') || source.stock_status === 'onbackorder') {
+    return gap('backorder-policy');
+  }
+  if (source.manage_stock === 'parent' ||
+      (parent && parent.manage_stock === true && source.manage_stock !== true)) {
+    return gap('shared-parent-stock');
+  }
+  if (!['instock', 'outofstock'].includes(source.stock_status)) return gap('missing-or-unknown-stock-status');
+  if (source.manage_stock === false) {
+    return { status: 'mapped', fields: { inventoryTracked: false, inStock: source.stock_status === 'instock' } };
+  }
+  if (source.manage_stock !== true) return gap('missing-or-unknown-tracking-method');
+  const quantity = source.stock_quantity;
+  if (!Number.isInteger(quantity) || quantity < 0 || quantity > 99999) return gap('invalid-stock-quantity');
+  if ((quantity > 0) !== (source.stock_status === 'instock')) return gap('stock-status-quantity-conflict');
+  return { status: 'mapped', fields: { inventoryTracked: true, inventoryQuantity: quantity } };
+}
+
+module.exports = { mapWooInventory };

package/skills/wix-replatform/resources/rp-source-wordpress/lib/wp-http.js

@@ -12,7 +12,9 @@
 //     self-contained.
 //
 // Keep this file dependency-free (Node built-ins / global fetch only) so the
-// vendored copy needs no install step.
+// vendored copy needs no install step. The one sibling module it reaches for --
+// ./gateway-summary.mjs -- is loaded lazily, inside fetchGatewaySummary(), so a
+// vendored copy that never reads gateway configuration still runs standalone.
 
 const DEFAULT_TIMEOUT_MS = 60000;
 const DEFAULT_RATE_LIMIT_RPM = 120;
@@ -27,6 +29,18 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+class DeadlineExceededError extends Error {
+  constructor() {
+    super('WordPress request deadline exceeded');
+    this.name = 'DeadlineExceededError';
+    this.code = 'deadline-exceeded';
+  }
+}
+
+function remainingDeadlineMs(deadlineAt) {
+  return deadlineAt === null ? Infinity : Math.max(0, deadlineAt - Date.now());
+}
+
 // Configure the shared throttle. Call once before issuing requests.
 function configureRateLimit({ rateLimitRpm = DEFAULT_RATE_LIMIT_RPM, maxRetries = DEFAULT_MAX_RETRIES } = {}) {
   const rpm = Number.isFinite(rateLimitRpm) && rateLimitRpm >= 1 ? rateLimitRpm : DEFAULT_RATE_LIMIT_RPM;
@@ -34,13 +48,16 @@ function configureRateLimit({ rateLimitRpm = DEFAULT_RATE_LIMIT_RPM, maxRetries
   rateState.maxRetries = Number.isFinite(maxRetries) && maxRetries >= 0 ? maxRetries : DEFAULT_MAX_RETRIES;
 }
 
-async function applyThrottle(progress) {
+async function applyThrottle(progress, deadlineAt = null) {
   if (rateState.minIntervalMs <= 0) {
     return;
   }
   const elapsed = Date.now() - rateState.lastRequestAt;
   const wait = rateState.minIntervalMs - elapsed;
   if (wait > 0) {
+    // A per-media-chunk deadline includes pacing. Do not start a wait that cannot
+    // finish inside it; returning immediately is what keeps the stated worst-case bound real.
+    if (wait >= remainingDeadlineMs(deadlineAt)) throw new DeadlineExceededError();
     if (progress) {
       await progress.withHeartbeat({ phase: 'discovery', step: 'rate-limit', message: 'Still waiting for WordPress rate limit' }, () => sleep(wait));
     } else {
@@ -102,13 +119,127 @@ function buildApiUrl(baseUrl, routePath, query = {}) {
   return url;
 }
 
-async function fetchJson(baseUrl, routePath, { headers, method = 'GET', query, timeoutMs = DEFAULT_TIMEOUT_MS, progress = null, progressContext = {} }) {
+// ---------------------------------------------------------------------------
+// Payment-gateway route denial
+//
+// `GET /wc/v3/payment_gateways` (and `/{id}`) returns each gateway's ENTIRE settings object.
+// On a site with a real gateway connected that includes the live API key and secret. Anything
+// a tool returns is in the model's context, the transcript, and potentially a durable run
+// artifact -- discovery's generic sampler writes sampled records to disk -- so there is no
+// careful-handling mitigation available above this line.
+//
+// The denial sits HERE, in the transport, rather than in a caller, for one reason: discovery
+// accepts `--include-route <path>` to force-sample any route. A control above that flag is a
+// control an operator can switch off by accident. This one is below it, so no CLI argument and
+// no future caller can route around it.
+//
+// It consults NOTHING but the route path. There is deliberately no `{ allowGatewayRoute }`, no
+// `{ skipDenyList }`, no capability token, no environment variable and no "internal caller"
+// parameter -- each of those is the exposure with extra steps. Their absence is asserted by
+// tests/source-wordpress/gateway-route-deny-contract-test.js.
+//
+// Honest limit: this guards the shared transport, not the network. Code that builds a URL and
+// calls global fetch itself is outside its reach; that is covered by the instructions in
+// rp-source-wordpress/SKILL.md and the codegen prohibition in rp-import-codegen/SKILL.md, not
+// by this function.
+// ---------------------------------------------------------------------------
+
+const GATEWAY_COLLECTION_ROUTE = '/wc/v3/payment_gateways';
+
+// Both shapes: the collection and the parameterized item route. Matching only the collection
+// would leave the exposure fully open -- the item route is the one that returns settings.
+// `v\d+` rather than `v3` because wc/v1 and wc/v2 expose the same route.
+const GATEWAY_ROUTE_PATTERN = /^\/wc\/v\d+\/payment_gateways(\/.*)?$/;
+
+class GatewayRouteDeniedError extends Error {
+  constructor(routePath) {
+    super(
+      `Refusing to request "${routePath}": WooCommerce payment-gateway routes return each gateway's `
+      + 'full settings object, including live API keys and secrets. Read gateway configuration through '
+      + 'fetchGatewaySummary(), which reduces the response with lib/gateway-summary.mjs and returns names '
+      + 'and states without credential values. No option, flag or override lifts this.',
+    );
+    this.name = 'GatewayRouteDeniedError';
+    this.code = 'GATEWAY_ROUTE_DENIED';
+    this.routePath = routePath;
+  }
+}
+
+// Normalize before matching, so a query string, a trailing slash, a doubled slash, a percent
+// escape, an accidental /wp-json prefix or a mixed-case spelling cannot walk past the pattern.
+function normalizeRouteForDeny(routePath) {
+  let route = typeof routePath === 'string' ? routePath : '';
+  try {
+    route = decodeURIComponent(route);
+  } catch {
+    // A malformed escape sequence is not a reason to skip the check — carry on with the raw text.
+  }
+  route = route.split('#')[0].split('?')[0].trim().toLowerCase();
+  route = route.replace(/\\/g, '/').replace(/\/{2,}/g, '/');
+  if (!route.startsWith('/')) {
+    route = `/${route}`;
+  }
+  route = route.replace(/^\/wp-json(?=\/|$)/, '').replace(/\/+$/, '');
+  return route === '' ? '/' : route;
+}
+
+/** Whether this route path returns payment-gateway configuration and must never be requested. */
+function isDeniedGatewayRoute(routePath) {
+  return GATEWAY_ROUTE_PATTERN.test(normalizeRouteForDeny(routePath));
+}
+
+// The undenied transport. MODULE-PRIVATE, and it stays that way: exporting it, or adding a
+// parameter to fetchJson that reaches it, recreates the hole the deny rule closes. The only
+// caller outside fetchJson is fetchGatewaySummary below, which hands the raw response straight
+// to a pure reducer and lets it go out of scope.
+async function fetchJsonUnchecked(baseUrl, routePath, {
+  headers,
+  method = 'GET',
+  query,
+  body,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  deadlineMs,
+  progress = null,
+  progressContext = {},
+}) {
   const url = buildApiUrl(baseUrl, routePath, query);
+  // One absolute deadline spans throttle waits, every attempt, response-body reads and every
+  // retry wait. Calls that omit deadlineMs retain the transport's existing per-attempt timeout.
+  const deadlineAt = Number.isFinite(deadlineMs) && deadlineMs >= 0 ? Date.now() + deadlineMs : null;
+  // `body` is a small, generic escape hatch for profile-declared entities whose read path
+  // is not a plain GET collection (see plugin-knowledge.js buildRequestOverrides) — it is
+  // never set on the default GET-with-query sampling path.
+  const requestInit = {
+    method,
+    headers,
+    ...(body !== undefined ? { body } : {}),
+  };
+
+  const deadlineResult = (attempt, error = new DeadlineExceededError()) => ({
+    ok: false,
+    status: 0,
+    statusText: 'Deadline Exceeded',
+    url: url.toString(),
+    headers: {},
+    json: undefined,
+    text: '',
+    error,
+    retries: attempt,
+  });
 
   for (let attempt = 0; ; attempt += 1) {
-    await applyThrottle(progress);
+    try {
+      await applyThrottle(progress, deadlineAt);
+    } catch (error) {
+      if (error && error.code === 'deadline-exceeded') return deadlineResult(attempt, error);
+      throw error;
+    }
+    const remaining = remainingDeadlineMs(deadlineAt);
+    if (remaining <= 0) return deadlineResult(attempt);
+    const attemptTimeoutMs = Math.min(timeoutMs, remaining);
+    const deadlineControlsAttempt = deadlineAt !== null && remaining <= timeoutMs;
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const timeout = setTimeout(() => controller.abort(), attemptTimeoutMs);
 
     try {
       const response = progress
@@ -118,13 +249,11 @@ async function fetchJson(baseUrl, routePath, { headers, method = 'GET', query, t
           ...progressContext,
           message: `Still waiting on WordPress ${method} ${routePath || '/'}`,
         }, () => fetch(url, {
-          method,
-          headers,
+          ...requestInit,
           signal: controller.signal,
         }))
         : await fetch(url, {
-          method,
-          headers,
+          ...requestInit,
           signal: controller.signal,
         });
       const text = await response.text();
@@ -134,6 +263,7 @@ async function fetchJson(baseUrl, routePath, { headers, method = 'GET', query, t
       // honoring Retry-After when the server provides it.
       if ((response.status === 429 || response.status === 503) && attempt < rateState.maxRetries) {
         const backoff = retryAfterMs(responseHeaders) ?? Math.min(MAX_BACKOFF_MS, 1000 * 2 ** attempt);
+        if (backoff >= remainingDeadlineMs(deadlineAt)) return deadlineResult(attempt);
         if (progress) {
           progress.warn(`WordPress ${response.status} response; backing off before retry`, {
             phase: 'discovery',
@@ -175,6 +305,9 @@ async function fetchJson(baseUrl, routePath, { headers, method = 'GET', query, t
         retries: attempt,
       };
     } catch (error) {
+      if (error.name === 'AbortError' && deadlineControlsAttempt) {
+        return deadlineResult(attempt);
+      }
       return {
         ok: false,
         status: 0,
@@ -192,6 +325,61 @@ async function fetchJson(baseUrl, routePath, { headers, method = 'GET', query, t
   }
 }
 
+/**
+ * The WordPress transport every reader uses.
+ *
+ * Identical to the core above except that it refuses payment-gateway routes BEFORE issuing the
+ * request. The refusal throws rather than returning a result object: a caller that treats a
+ * denial as "the route returned nothing" would carry on and record an empty entity, and a
+ * security control that reads as an empty result is not a control.
+ */
+async function fetchJson(baseUrl, routePath, options) {
+  if (isDeniedGatewayRoute(routePath)) {
+    throw new GatewayRouteDeniedError(routePath);
+  }
+  return fetchJsonUnchecked(baseUrl, routePath, options);
+}
+
+/**
+ * The ONE sanctioned way to read payment-gateway configuration.
+ *
+ * Note the direction of the dependency: this module imports the reducer, not the reverse. The
+ * raw response never leaves this function's scope -- it goes straight into a pure function that
+ * cannot make a request, and only that function's §1-shaped output is resolved. So there is no
+ * exemption to keep narrow, because there is no hole: `gateway-summary.mjs` has no transport to
+ * reach, and `fetchJson` has no way to be talked into the route.
+ *
+ * Refuses outright when the shared secret-value guard is not operational. A guard that quietly
+ * evaluates an empty pattern set returns display values verbatim, and an allowlisted
+ * `description` is free text a vendor controls -- so an unusable guard means we do not read.
+ *
+ * Loaded with dynamic import(), not require(): the reducer is ESM, this module is CommonJS and
+ * is vendored into generated migration projects, and import() is the one form that works from
+ * both on every Node version. Lazy, so a vendored copy that never reads gateway configuration
+ * -- which is every generated reader, by prohibition -- needs no sibling file at all.
+ */
+async function fetchGatewaySummary(baseUrl, { headers, timeoutMs = DEFAULT_TIMEOUT_MS, progress = null, progressContext = {} } = {}) {
+  const { reduceGatewayResponse, guardUnusableReason } = await import('./gateway-summary.mjs');
+
+  const guardProblem = guardUnusableReason();
+  if (guardProblem) {
+    throw new Error(
+      `Refusing to read payment-gateway configuration: the shared secret-value guard is not operational (${guardProblem}). `
+      + 'Fix secret-value-patterns.v1.json before reading gateway settings.',
+    );
+  }
+
+  const response = await fetchJsonUnchecked(baseUrl, GATEWAY_COLLECTION_ROUTE, {
+    headers,
+    method: 'GET',
+    timeoutMs,
+    progress,
+    progressContext: { step: 'gateway-summary', ...progressContext },
+  });
+
+  return reduceGatewayResponse(response);
+}
+
 // Total record count for a collection. WordPress returns it in X-WP-Total;
 // X-WP-TotalPages carries the page count. Header names are lowercased by fetch's
 // Headers iterator, but accept the canonical casing too for resilience.
@@ -236,6 +424,7 @@ module.exports = {
   DEFAULT_RATE_LIMIT_RPM,
   DEFAULT_MAX_RETRIES,
   MAX_BACKOFF_MS,
+  DeadlineExceededError,
   sleep,
   configureRateLimit,
   retryAfterMs,
@@ -243,6 +432,12 @@ module.exports = {
   normalizeBaseUrl,
   buildApiUrl,
   fetchJson,
+  // NOTE what is deliberately NOT here: the undenied transport, under any name. The gateway
+  // deny rule is only worth as much as this export list.
+  GATEWAY_COLLECTION_ROUTE,
+  GatewayRouteDeniedError,
+  isDeniedGatewayRoute,
+  fetchGatewaySummary,
   parseTotalHeader,
   parseTotalPagesHeader,
   shouldContinueCollectionPaging,

package/skills/wix-replatform/resources/rp-source-wordpress/lib/wp-image-url.js

@@ -0,0 +1,186 @@
+'use strict';
+
+// Resolve a WordPress/WooCommerce image reference to the source's ORIGINAL, maximum-resolution
+// file.
+//
+// An image reference in a WordPress-family payload is never one URL — it is a SET of candidate
+// URLs for the same picture: the file the merchant uploaded, plus the crops WordPress generated
+// from it. Which field holds which varies by route, and two routes on the SAME site disagree:
+//
+//   wc/store/v1/products  (public)         images[].src IS the original
+//   wc/v3/products        (authenticated)  images[].src can be the SMALLEST crop, because the
+//                                          admin controller resolves it through WordPress's
+//                                          registered image sizes, which any theme or
+//                                          image-optimizer plugin is free to redefine
+//
+// So no caller may name a field. Every caller hands the whole reference to resolveImageUrl and
+// gets back the biggest file available. Doing it any other way is how a whole catalog shipped as
+// 150x150 thumbnails.
+//
+// It matters because the destination gives exactly one attempt: Wix Stores media takes ONE url
+// per item and generates every derivative from it, with no way to raise the quality afterwards.
+// Whatever this function returns is that product image's permanent ceiling.
+
+// WordPress names every crop it generates by appending the dimensions to the filename, so a
+// candidate WITHOUT that suffix is the uploaded original. This is a filename convention of the
+// source platform, not a guarantee — do not reuse this module for a non-WordPress source
+// without re-deriving the rule.
+//
+// The extension group repeats (`(\.ext)+`) because image optimizers append their own format
+// rather than replacing the original one: WebP Express, EWWW and Imagify all emit
+// `photo-150x150.jpg.webp` beside `photo-150x150.jpg`. Matching only the LAST extension made
+// every such crop look like an uploaded original, so rule 3 below returned the first one it saw —
+// a 150px thumbnail winning over a 1200px sibling, reported as `isCrop: false` so nothing flagged
+// it either. That is unrecoverable once ingested, which is the whole reason this module exists.
+const CROP_SUFFIX = /-(\d+)x(\d+)(\.[A-Za-z0-9]+)+$/;
+
+// Fields that hold a single URL, across every WordPress-family shape we read:
+//   wc/v3 + wc/store/v1 product images  -> src, thumbnail
+//   wp/v2 media                         -> source_url
+const SINGLE_URL_FIELDS = ['src', 'thumbnail', 'source_url'];
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function pathOf(url) {
+  // Compare against the path only. A query string can end in anything, and matching the crop
+  // suffix against it would misread `?v=-150x150` as a crop.
+  const withoutFragment = String(url).split('#')[0];
+  return withoutFragment.split('?')[0];
+}
+
+// Width descriptors in a srcset entry ("<url> 800w") and the width baked into a crop filename
+// are both ranking keys and nothing else. Never treat either as the image's true dimensions.
+function declaredWidth(url, descriptorWidth) {
+  const match = CROP_SUFFIX.exec(pathOf(url));
+  const fromName = match ? Number(match[1]) : 0;
+  return Math.max(Number(descriptorWidth) || 0, fromName);
+}
+
+function parseSrcset(srcset) {
+  if (!isNonEmptyString(srcset)) return [];
+  return srcset
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const parts = entry.split(/\s+/);
+      const url = parts[0];
+      const descriptor = parts.length > 1 ? parts[parts.length - 1] : '';
+      const width = /^\d+w$/.test(descriptor) ? Number(descriptor.slice(0, -1)) : 0;
+      return isNonEmptyString(url) ? { url, width } : null;
+    })
+    .filter(Boolean);
+}
+
+// Every URL the record offers for this one picture, each with whatever width we can infer.
+function collectCandidates(record) {
+  if (!record || typeof record !== 'object') return [];
+  const candidates = [];
+
+  for (const field of SINGLE_URL_FIELDS) {
+    if (isNonEmptyString(record[field])) candidates.push({ url: record[field], width: 0 });
+  }
+
+  // wc/store/v1 exposes a second srcset for the thumbnail rendition; it occasionally carries a
+  // width the main one does not, and taking the max across both costs nothing.
+  for (const field of ['srcset', 'thumbnail_srcset']) {
+    candidates.push(...parseSrcset(record[field]));
+  }
+
+  // wp/v2 media keeps its renditions in a nested map rather than a srcset string.
+  const sizes = record.media_details && record.media_details.sizes;
+  if (sizes && typeof sizes === 'object') {
+    for (const size of Object.values(sizes)) {
+      if (size && isNonEmptyString(size.source_url)) {
+        candidates.push({ url: size.source_url, width: Number(size.width) || 0 });
+      }
+    }
+  }
+
+  return candidates;
+}
+
+// A raw URL with non-ASCII characters is not fetchable by ordinary HTTP clients — our own
+// verification tooling throws on it before the destination ever sees the request. Encode the
+// path only: the host is already punycode or ASCII, and the query is left to the URL parser's
+// own normalization so its parameter structure is never rewritten.
+function encodeImageUrl(url) {
+  if (!isNonEmptyString(url)) return url;
+  try {
+    const parsed = new URL(url);
+    parsed.pathname = parsed.pathname
+      .split('/')
+      .map((segment) => encodeURIComponent(decodeURIComponent(segment)))
+      .join('/');
+    return parsed.toString();
+  } catch {
+    // Not an absolute URL. Hand it back untouched rather than mangling a relative path — the
+    // caller knows its own base and this module does not.
+    return url;
+  }
+}
+
+// The one entry point. Returns the encoded URL of the largest file the record offers, or null
+// when it offers none. Never invents a URL: a record with no image is a fact to report, not a
+// gap to fill with a placeholder.
+function resolveImageUrl(record) {
+  const candidates = collectCandidates(record);
+  if (candidates.length === 0) return null;
+
+  const original = candidates.find((candidate) => !CROP_SUFFIX.test(pathOf(candidate.url)));
+  if (original) return encodeImageUrl(original.url);
+
+  // Only crops exist. Take the widest rather than failing — something always beats a thumbnail —
+  // and let the caller report it via resolvedIsCrop().
+  let best = candidates[0];
+  let bestWidth = declaredWidth(best.url, best.width);
+  for (const candidate of candidates.slice(1)) {
+    const width = declaredWidth(candidate.url, candidate.width);
+    if (width > bestWidth) {
+      best = candidate;
+      bestWidth = width;
+    }
+  }
+  return encodeImageUrl(best.url);
+}
+
+// True when the best available URL is still a generated crop, i.e. the source genuinely had no
+// original to give. Callers MUST surface this: a migration may ship a small picture when the
+// source only has a small picture, but it may not do so silently.
+function resolvedIsCrop(url) {
+  return isNonEmptyString(url) && CROP_SUFFIX.test(pathOf(url));
+}
+
+// Resolve a whole images[] array in order, dropping references that carry no URL at all.
+// Order is load-bearing downstream: the first surviving item becomes the product's main media.
+function resolveImageUrls(records) {
+  if (!Array.isArray(records)) return [];
+  return records
+    .map((record) => {
+      const url = resolveImageUrl(record);
+      if (!url) return null;
+      // The attachment id is what joins this product reference to wp/v2's media
+      // record. Preserve an explicit zero for an absent/invalid id so the confirmation boundary
+      // can fail closed with `no-source-id` rather than guessing from a filename.
+      const sourceId = Number(record && record.id);
+      const resolved = {
+        url,
+        sourceId: Number.isInteger(sourceId) && sourceId > 0 ? sourceId : 0,
+        isCrop: resolvedIsCrop(url),
+      };
+      if (isNonEmptyString(record && record.alt)) resolved.altText = record.alt;
+      if (isNonEmptyString(record && record.alt_text)) resolved.altText = record.alt_text;
+      if (isNonEmptyString(record && record.name)) resolved.displayName = record.name;
+      return resolved;
+    })
+    .filter(Boolean);
+}
+
+module.exports = {
+  resolveImageUrl,
+  resolveImageUrls,
+  resolvedIsCrop,
+  encodeImageUrl,
+};