@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/lib/contact-extended-fields.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+// The LEGACY Contacts V4 custom-field path, and only that path. A migration reaches it
+// only by routing a mapping explicitly to `contactWriteSurface: "contacts-v4"`; the default V5
+// contact goes through the Data Extension Schema helper (FQDN wix.contacts.*.contact) instead.
+// The two are never both attempted for one field, and a failure on one never falls back to the
+// other: their values live in different places (`info.extendedFields` vs
+// `extendedFields.namespaces`) and pair with different contact writers.
+//
+// API facts this relies on (docs re-read 2026-09-29):
+//   * Find Or Create Extended Field is POST /contacts/v4/extended-fields {displayName, dataType}.
+//     It matches an existing field BY DISPLAY NAME and returns `{ field, newField }`; the key is
+//     generated by Wix, so setup must persist the returned key rather than derive one.
+//   * Get Extended Field is GET /contacts/v4/extended-fields/{key} -- the read-back.
+//   * Keys cannot be changed once created; deleting a field removes its values from every contact.
+//   * Created fields land in the `custom` namespace. Documented types: Text, Number, Date, URL.
+//
+// This phase admits TEXT only, for the same reason the DES helper admits `string` only: the other
+// types have not been verified end to end, and a guessed type is how an unsupported one reaches a
+// live setup call.
+
+const WIXAPIS = 'https://www.wixapis.com';
+const EXTENDED_FIELDS_URL = `${WIXAPIS}/contacts/v4/extended-fields`;
+const SCHEMA_KIND = 'crm-contact-extended-field';
+const CONTACT_WRITE_SURFACE = 'contacts-v4';
+const EXPECTED_NAMESPACE = 'custom';
+const VERIFIED_CONTACT_DATA_TYPES = new Set(['TEXT']);
+const DOCUMENTED_CONTACT_DATA_TYPES = new Set(['TEXT', 'NUMBER', 'DATE', 'URL']);
+
+function fail(errors, code, detail) {
+  errors.push({ code, detail });
+  return errors;
+}
+
+function validateContactExtendedFieldRequirement(requirement) {
+  const errors = [];
+  if (!requirement || requirement.kind !== 'extendedFieldSchema') {
+    return { valid: false, errors: fail([], 'not-an-extended-field-requirement', 'requirement.kind must be "extendedFieldSchema"') };
+  }
+  if (requirement.schemaKind !== SCHEMA_KIND) {
+    fail(errors, 'unsupported-schema-kind', `this helper implements ${SCHEMA_KIND} only, not "${requirement.schemaKind}"`);
+  }
+  if (requirement.contactWriteSurface !== CONTACT_WRITE_SURFACE) {
+    // V4 is opt-in. Without the explicit surface this is a V5 requirement in the wrong shape.
+    fail(errors, 'contact-surface-mismatch', `${SCHEMA_KIND} requires contactWriteSurface "${CONTACT_WRITE_SURFACE}", not "${requirement.contactWriteSurface}"`);
+  }
+  if (requirement.targetRef !== undefined && requirement.targetRef !== 'crm/contact') {
+    fail(errors, 'target-ref-mismatch', `a ${SCHEMA_KIND} requirement targets crm/contact, not "${requirement.targetRef}"`);
+  }
+  if (requirement.fqdn || requirement.namespace) {
+    // The DES fields on a V4 requirement mean someone mixed the two surfaces.
+    fail(errors, 'contact-surface-mismatch', `${SCHEMA_KIND} does not take fqdn/namespace; those belong to the contacts-v5 Data Extension Schema path`);
+  }
+  if (!Array.isArray(requirement.fields) || requirement.fields.length === 0) {
+    fail(errors, 'no-fields-declared', 'a requirement with no fields provisions nothing');
+    return { valid: false, errors };
+  }
+  const seen = new Set();
+  for (const field of requirement.fields) {
+    if (!field || typeof field !== 'object') {
+      fail(errors, 'field-not-an-object', 'a field intent must be an object');
+      continue;
+    }
+    if (!field.displayName || typeof field.displayName !== 'string' || !field.displayName.trim()) {
+      fail(errors, 'missing-display-name', 'a contacts-v4 field needs a displayName; Find Or Create matches by it');
+    } else {
+      // Find Or Create matches by display name, so two fields with one name would collapse into
+      // one key and one field's values would overwrite the other's.
+      const normalized = field.displayName.trim().toLowerCase();
+      if (seen.has(normalized)) fail(errors, 'duplicate-display-name', `displayName "${field.displayName}" is declared twice`);
+      seen.add(normalized);
+    }
+    if (!field.dataType) {
+      fail(errors, 'missing-data-type', `field "${field.displayName}" has no dataType`);
+    } else if (!DOCUMENTED_CONTACT_DATA_TYPES.has(field.dataType)) {
+      fail(errors, 'unsupported-contact-data-type', `dataType "${field.dataType}" is not a Wix contact field type`);
+    } else if (!VERIFIED_CONTACT_DATA_TYPES.has(field.dataType)) {
+      fail(errors, 'unverified-contact-data-type', `dataType "${field.dataType}" is not verified for this phase; only ${[...VERIFIED_CONTACT_DATA_TYPES].join(', ')} is`);
+    }
+    if (field.expectedNamespace !== undefined && field.expectedNamespace !== EXPECTED_NAMESPACE) {
+      fail(errors, 'unexpected-contact-namespace', `created contact fields land in "${EXPECTED_NAMESPACE}", not "${field.expectedNamespace}"`);
+    }
+    if (field.writePath && !/^info\.extendedFields\./.test(field.writePath)) {
+      fail(errors, 'write-path-mismatch', `a contacts-v4 value lands under info.extendedFields, not "${field.writePath}"`);
+    }
+    if (field.writePathTemplate !== undefined && field.writePathTemplate !== 'info.extendedFields.<verifiedKey>') {
+      fail(errors, 'write-path-mismatch', `writePathTemplate must be "info.extendedFields.<verifiedKey>", not "${field.writePathTemplate}"`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function buildFindOrCreateContactExtendedFieldRequest({ displayName, dataType = 'TEXT' } = {}) {
+  if (!displayName) throw new Error('buildFindOrCreateContactExtendedFieldRequest: displayName is required');
+  return { method: 'POST', url: EXTENDED_FIELDS_URL, body: { displayName, dataType } };
+}
+
+function buildGetContactExtendedFieldRequest({ key } = {}) {
+  if (!key) throw new Error('buildGetContactExtendedFieldRequest: key is required');
+  return { method: 'GET', url: `${EXTENDED_FIELDS_URL}/${encodeURIComponent(key)}` };
+}
+
+// Find Or Create and Get both answer `{ field: {...} }`. Accept a bare field too.
+function normalizeContactExtendedFieldResult(response) {
+  const field = response && (response.field || (response.key ? response : null));
+  if (!field) return null;
+  return {
+    key: field.key || null,
+    namespace: field.namespace || null,
+    dataType: field.dataType || null,
+    displayName: field.displayName || null,
+    newField: response && typeof response.newField === 'boolean' ? response.newField : null,
+  };
+}
+
+// The identity a later run must see again. A receipt records it so a key that changed between
+// runs is caught instead of silently splitting a field's values across two keys.
+function contactFieldIdentity(field) {
+  return String(field.displayName || '').trim().toLowerCase();
+}
+
+// Checks one Find Or Create answer (or its read-back) against the intent and any key recorded by
+// an earlier run. Returns null when it matches.
+function describeContactFieldMismatch(intent, normalized, { priorKey = null } = {}) {
+  if (!normalized || !normalized.key) return 'the field was not returned';
+  const differences = [];
+  // Required, not merely "not wrong": a response that omits the namespace has not shown the key
+  // lives where the writer will put values, so it cannot pass verification.
+  if (normalized.namespace !== EXPECTED_NAMESPACE) {
+    differences.push(`namespace: expected "${EXPECTED_NAMESPACE}", got ${normalized.namespace ? `"${normalized.namespace}"` : 'none'}`);
+  }
+  if (normalized.dataType !== intent.dataType) {
+    // Find Or Create matched an existing field by name; it will not retype it for us.
+    differences.push(`dataType: expected ${intent.dataType}, got ${normalized.dataType}`);
+  }
+  if (normalized.displayName && contactFieldIdentity(normalized) !== contactFieldIdentity(intent)) {
+    differences.push(`displayName: expected "${intent.displayName}", got "${normalized.displayName}"`);
+  }
+  if (priorKey && normalized.key !== priorKey) {
+    differences.push(`key: an earlier setup verified "${priorKey}" but Wix now returns "${normalized.key}"; keys cannot change`);
+  }
+  return differences.length > 0 ? differences.join('; ') : null;
+}
+
+function contactFieldWritePath(key) {
+  return `info.extendedFields.${key}`;
+}
+
+// Same stamp idea as the DES helper, hashed over what a V4 consumer depends on.
+function contactExtendedFieldContractVersion(requirement) {
+  if (!requirement || !Array.isArray(requirement.fields)) return null;
+  const material = [
+    SCHEMA_KIND,
+    requirement.contactWriteSurface || '',
+    ...requirement.fields.map((field) => [contactFieldIdentity(field), field.dataType || ''].join(':')).sort(),
+  ].join('|');
+  return crypto.createHash('sha256').update(material).digest('hex').slice(0, 16);
+}
+
+// Keys an earlier receipt verified, by display-name identity, so a re-run can enforce that they
+// did not change.
+function priorContactFieldKeys(setupVerification) {
+  const entries = !setupVerification ? []
+    : Array.isArray(setupVerification.verifications) ? setupVerification.verifications
+      : Array.isArray(setupVerification) ? setupVerification : [setupVerification];
+  const keys = new Map();
+  for (const entry of entries) {
+    if (!entry || entry.schemaKind !== SCHEMA_KIND) continue;
+    for (const verified of entry.verified || []) {
+      if (verified && verified.displayName && verified.key) keys.set(contactFieldIdentity(verified), verified.key);
+    }
+  }
+  return keys;
+}
+
+module.exports = {
+  EXTENDED_FIELDS_URL,
+  SCHEMA_KIND,
+  CONTACT_WRITE_SURFACE,
+  EXPECTED_NAMESPACE,
+  VERIFIED_CONTACT_DATA_TYPES,
+  DOCUMENTED_CONTACT_DATA_TYPES,
+  validateContactExtendedFieldRequirement,
+  buildFindOrCreateContactExtendedFieldRequest,
+  buildGetContactExtendedFieldRequest,
+  normalizeContactExtendedFieldResult,
+  describeContactFieldMismatch,
+  contactFieldIdentity,
+  contactFieldWritePath,
+  contactExtendedFieldContractVersion,
+  priorContactFieldKeys,
+};

package/skills/wix-replatform/resources/rp-target-wix/lib/contact-import.js

@@ -0,0 +1,133 @@
+'use strict';
+const w = require('./wix-writers');
+const v = require('./write-verification');
+const { contactId } = require('./bulk-results');
+const stateIO = require('../../../lib/write-verification-state');
+const local = require('../../../lib/local-state');
+const sleepDefault = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+// Schema: Contacts V5 Find Matching Contacts (GET); keep every primary identifier.
+async function findMatching(wix, expected) {
+  const params = new URLSearchParams();
+  if (expected.externalId) params.set('externalId', expected.externalId);
+  if (expected.email?.email) params.set('email', expected.email.email);
+  if (expected.phone?.phone) params.set('phone', expected.phone.phone);
+  const result = await wix.send({ method: 'GET', url: `https://www.wixapis.com/contacts/v5/contacts/find-matching?${params}` });
+  if (!Array.isArray(result?.contacts) || result.contacts.length >= 100) throw new Error('Contact lookup is malformed or may be truncated');
+  return result.contacts;
+}
+async function importContacts(wix, { projectDir, siteId, rows, verifyAttempts = 3, sleep = sleepDefault, dryRun = false } = {}) {
+  if (!projectDir || !siteId || !Array.isArray(rows) || !Number.isInteger(verifyAttempts) || verifyAttempts < 1 || verifyAttempts > 5) throw new Error('Invalid contact import arguments');
+  if (rows.some(r => typeof r.sourceKey !== 'string' || !r.sourceKey) || new Set(rows.map(r => r.sourceKey)).size !== rows.length) throw new Error('Unique source keys required');
+  return local.withStateLock(projectDir, async () => {
+    const state = await stateIO.load(projectDir, siteId);
+    const crosswalk = await local.loadCrosswalk(projectDir);
+    const work = rows.map(row => {
+      try {
+        v.assertProjection(row.contact, 'contact');
+        const expected = w.buildCreateContactRequest({ contact: row.contact }, row.safeModeOptions).body.contact;
+        v.assertProjection(expected);
+        const limits = [[expected.externalId, 100], [expected.name?.first, 1000], [expected.name?.last, 1000], [expected.email?.email, 320], [expected.phone?.phone, 50]];
+        if (limits.some(([value, max]) => value != null && (typeof value !== 'string' || value.length > max))) throw new Error('Contact field exceeds its declared type or limit');
+        for (const [key, max] of [['additionalEmails', 10], ['additionalPhones', 10], ['addresses', 50]]) if (expected[key] != null && (!Array.isArray(expected[key]) || expected[key].length > max)) throw new Error(`Contact ${key} exceeds its declared array limit`);
+        return { ...row, baseline: crosswalk.bySource[row.sourceKey] || state.rows[row.sourceKey]?.baseline || null, expected, uncertain: Boolean(state.rows[row.sourceKey]?.uncertain), targetId: state.rows[row.sourceKey]?.targetId || crosswalk.bySource[row.sourceKey]?.targetId || state.rows[row.sourceKey]?.baseline?.targetId || null };
+      } catch (e) { return { ...row, baseline: crosswalk.bySource[row.sourceKey] || state.rows[row.sourceKey]?.baseline || null, targetId: state.rows[row.sourceKey]?.targetId || crosswalk.bySource[row.sourceKey]?.targetId || state.rows[row.sourceKey]?.baseline?.targetId, uncertain: state.rows[row.sourceKey]?.uncertain, error: e.message }; }
+    });
+    // Resolve the entire input set before writes: even a later row can conflict with an earlier one.
+    const shared = new Map();
+    for (const r of work) for (const [key, value] of Object.entries({ externalId: r.expected?.externalId, email: v.email(r.expected?.email?.email), phone: r.expected?.phone?.phone })) {
+      if (!value) continue;
+      const k = `${key}:${value}`;
+      if (!shared.has(k)) shared.set(k, []);
+      shared.get(k).push(r);
+    }
+    for (const group of shared.values()) if (group.length > 1) for (const r of group) r.error = 'Conflicting source contact identifiers';
+    if (dryRun) return { siteId, intended: rows.length, status: 'simulated', verified: 0, rows: work.map(r => ({ sourceKey: r.sourceKey, verified: false, outcome: 'simulated' })) };
+    for (const r of work) {
+      if (r.error) continue;
+      try {
+        if (!r.expected.externalId && !v.email(r.expected.email?.email)) throw new Error('Phone-only or name-only identity is unsupported');
+        const candidates = await findMatching(wix, r.expected);
+        if (candidates.length > 1 || candidates.some(c => !v.contactIdentity(r.expected, c, c.id).verified)) throw Object.assign(new Error('Conflicting target contact identity'), { identityConflict: true });
+        if (r.targetId) {
+          if (!contactId(r.targetId)) throw Object.assign(new Error('Invalid candidate contact ID'), { identityConflict: true });
+          const known = await w.getContact(wix, r.targetId);
+          if (!v.contactIdentity(r.expected, known, r.targetId).verified) throw Object.assign(new Error('Crosswalk contact identity does not agree'), { identityConflict: true });
+          if (candidates.length && candidates[0].id !== r.targetId) throw Object.assign(new Error('Crosswalk and matching lookup disagree'), { identityConflict: true });
+          r.actual = known;
+        } else if (candidates.length) { r.targetId = candidates[0].id; r.actual = await w.getContact(wix, r.targetId); }
+        else if (state.rows[r.sourceKey]?.uncertain) throw new Error('Previous write outcome is uncertain; reconcile before retry');
+        if (r.actual && !v.verifyContact(r.expected, r.actual, r.targetId).verified) throw new Error('Existing contact values differ; use the revision-protected update and conflict-review flow');
+        if (r.targetId && crosswalk.rows.some(c => c.sourceStableKey !== r.sourceKey && c.targetSystem === 'wix' && c.targetId === r.targetId)) throw Object.assign(new Error('Target contact belongs to another source key'), { identityConflict: true });
+      } catch (e) { r.error = e.message; r.identityConflict = Boolean(e.identityConflict); }
+    }
+    for (const r of work) if (r.targetId && work.some(other => other !== r && other.targetId === r.targetId)) { r.error = 'Distinct source keys share a target contact'; r.identityConflict = true; }
+    const save = r => {
+      const previous = state.rows[r.sourceKey];
+      const lastVerifiedReceipt = v.validReceipt(previous?.receipt) ? previous.receipt : previous?.lastVerifiedReceipt || null;
+      state.rows[r.sourceKey] = { sourceKey: r.sourceKey, targetId: r.targetId, baseline: r.baseline, identityConflict: Boolean(r.identityConflict),
+        outcome: r.outcome || 'needs_verification', uncertain: Boolean(r.uncertain), error: r.error || null, receipt: r.receipt || null, lastVerifiedReceipt };
+    };
+    for (const r of work) save(r);
+    await stateIO.checkpoint(projectDir, state, work);
+    const pending = work.filter(r => !r.error && !(r.actual && v.verifyContact(r.expected, r.actual, r.targetId).verified));
+    const batches = [];
+    for (const memberMode of [false, true]) {
+      const selected = pending.filter(r => (r.updateMember === true) === memberMode);
+      for (let start = 0; start < selected.length; start += 100) batches.push(selected.slice(start, start + 100));
+    }
+    for (const group of batches) {
+      for (const r of group) { r.uncertain = true; save(r); }
+      await stateIO.checkpoint(projectDir, state, group);
+      try {
+        // Sanitize once per source record, never with one shared batch identity.
+        const result = await w.bulkUpsertContacts(wix, group.map(r => r.expected), { updateMember: group[0].updateMember === true }, { safeMode: false });
+        for (const outcome of result.results) {
+          if (!outcome.correlated) continue;
+          const r = group[outcome.index];
+          if (outcome.success) {
+            if (r.targetId && r.targetId !== outcome.contactId) { r.error = 'Upsert returned a different contact identity'; continue; }
+            r.targetId = outcome.contactId; r.uncertain = false; r.confirmedCreate = true;
+          } else { r.error = outcome.errorCode || 'Contact write failed'; r.uncertain = false; }
+          save(r);
+        }
+        for (const index of result.unresolvedIndexes) { group[index].error = 'Unresolved bulk contact result'; save(group[index]); }
+      } catch (e) {
+        for (const r of group) {
+          r.error = e.message;
+          if ([401, 403].includes(e.status || e.statusCode)) r.uncertain = false;
+          save(r);
+        }
+      }
+      await stateIO.checkpoint(projectDir, state, group);
+    }
+    for (const r of work) if (r.targetId && work.some(other => other !== r && other.targetId === r.targetId)) { r.error = 'Distinct source keys share a target contact'; r.identityConflict = true; }
+    const publications = [];
+    let verifiedBatch = [];
+    for (const r of work) {
+      if (!r.error && r.targetId) for (let attempt = 1; attempt <= verifyAttempts; attempt++) {
+        try {
+          const actual = await w.getContact(wix, r.targetId);
+          if (!v.contactIdentity(r.expected, actual, r.targetId).verified) r.identityConflict = true;
+          r.receipt = v.receipt({ siteId, sourceKey: r.sourceKey, kind: 'contact', expected: r.expected, actual, targetId: r.targetId, operation: 'bulkUpsertContacts', attempts: attempt });
+          if (r.identityConflict) break;
+          if (r.receipt.verified) { r.outcome = 'verified'; r.uncertain = false; break; }
+        } catch (e) { r.readError = e.message; }
+        if (attempt < verifyAttempts) await sleep(100 * attempt);
+      }
+      if (!r.receipt?.verified) { r.error ||= r.readError || 'Contact values could not be verified'; r.outcome = 'needs_verification'; }
+      save(r);
+      if (r.outcome === 'verified') publications.push({ row: {
+        schemaVersion: 1, sourceSystem: r.sourceSystem || 'source', sourceEntityType: 'contact', sourceId: r.sourceId || r.sourceKey,
+        sourceStableKey: r.sourceKey, targetSystem: 'wix', targetEntityType: 'contact', targetId: r.targetId, status: 'imported',
+      }, receipt: r.receipt, options: r });
+      verifiedBatch.push(r);
+      if (verifiedBatch.length === 100) { await stateIO.checkpoint(projectDir, state, verifiedBatch); verifiedBatch = []; }
+    }
+    await stateIO.checkpoint(projectDir, state, verifiedBatch);
+    await stateIO.persist(projectDir, state);
+    await stateIO.publishMany(projectDir, publications, work.filter(r => r.identityConflict).map(r => r.sourceKey));
+    return stateIO.report(work.map(r => state.rows[r.sourceKey]), siteId);
+  });
+}
+module.exports = { findMatching, importContacts };

package/skills/wix-replatform/resources/rp-target-wix/lib/contract-ledger.js

@@ -4,7 +4,9 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { readEntityByRef } = require('./domain-knowledge.js');
 
+const { verifySubscriptionEvidence } = require('./write-verification');
 const SCHEMA_VERSION = 1;
+const validEvidence = artifact => artifact && artifact.status === 'passed' && artifact.probeRecordId === artifact.valueEvidence?.targetId && verifySubscriptionEvidence(artifact.valueEvidence).verified;
 
 function normalizePathPresence(verifiedPaths = []) {
   return verifiedPaths
@@ -23,7 +25,7 @@ function createContractLedgerProposalFromStoresVerification(artifact) {
   return {
     schemaVersion: SCHEMA_VERSION,
     proposalId: `stores-product-subscription-create-${(artifact.timestamp || new Date().toISOString()).slice(0, 10)}`,
-    status: artifact.status === 'passed' ? 'proposed' : 'blocked',
+    status: validEvidence(artifact) ? 'proposed' : 'blocked',
     sourceVerification: {
       command: artifact.command,
       artifactPath: artifact.artifactPath || null,
@@ -38,7 +40,7 @@ function createContractLedgerProposalFromStoresVerification(artifact) {
       surface: 'catalog-v3',
       operation: 'createProduct',
       path: 'product.subscriptionDetails',
-      verificationLevel: 'live-create-and-readback',
+      verificationLevel: validEvidence(artifact) ? 'live-create-and-readback' : 'unverified',
       lastVerified: artifact.timestamp ? artifact.timestamp.slice(0, 10) : null,
       verifiedBy: artifact.targetSiteIdentifier || artifact.sourceRunId || 'live-verification',
       requiredPaths: verifiedPaths.filter((entry) => entry !== 'product.subscriptionDetails.subscriptions[].id'),
@@ -114,8 +116,11 @@ function validateContractPromotion({ domainsDir, verificationArtifacts = [], pro
 
   for (const artifactPath of verificationArtifacts) {
     const artifact = readJsonIfExists(artifactPath);
-    if (!artifact || artifact.status !== 'passed') continue;
-    if (artifact.command !== 'stores subscription-create') continue;
+    if (!artifact || artifact.command !== 'stores subscription-create') continue;
+    if (!validEvidence(artifact)) {
+      errors.push(`${artifactPath}: missing or invalid identity/value verification`);
+      continue;
+    }
     const proposalEntry = proposalsByVerification.get(path.resolve(artifactPath));
     if (!proposalEntry) {
       errors.push(`${artifactPath}: passed verification is missing contract-ledger proposal`);
@@ -123,6 +128,10 @@ function validateContractPromotion({ domainsDir, verificationArtifacts = [], pro
     }
     const { proposal } = proposalEntry;
     if (proposal.status === 'deferred' || proposal.deferralReason) continue;
+    if (proposal.status !== 'proposed' || proposal.fieldContract?.verificationLevel !== 'live-create-and-readback') {
+      errors.push(`${proposalEntry.artifactPath}: invalid verification proposal`);
+      continue;
+    }
     if (!isProposalPromoted(domainsDir, proposal)) {
       errors.push(`${proposalEntry.artifactPath}: proposal is not promoted into shared target ledger`);
     }