@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/resources/rp-target-wix/domains/crm/entities/contact.json

@@ -1,275 +0,0 @@
-{
-  "schemaVersion": 1,
-  "domain": "crm",
-  "entity": "contact",
-  "displayName": "CRM Contact",
-  "capability": "crm.contact",
-  "target": {
-    "classification": "native-plus-cms",
-    "nativeEntity": "Contact",
-    "verifiedFqdn": null,
-    "idPolicy": "server-assigned",
-    "crosswalkRequired": true
-  },
-  "dependsOn": [],
-  "sourceAliases": [
-    {
-      "sourceSystem": "woocommerce",
-      "sourceEntity": "customer",
-      "routes": [
-        "/wc/v3/customers"
-      ],
-      "confidence": "high"
-    },
-    {
-      "sourceSystem": "woocommerce",
-      "sourceEntity": "order",
-      "routes": [
-        "/wc/v3/orders"
-      ],
-      "confidence": "high"
-    },
-    {
-      "sourceSystem": "wordpress",
-      "sourceEntity": "user",
-      "routes": [
-        "/wp/v2/users"
-      ],
-      "confidence": "medium"
-    },
-    {
-      "sourceSystem": "wix",
-      "sourceEntity": "contact",
-      "routes": [
-        "CRM Contacts V4",
-        "CRM Contacts V5"
-      ],
-      "confidence": "high"
-    }
-  ],
-  "preferredWrite": {
-    "surface": "Contacts V5",
-    "endpoint": "POST /contacts/v5/bulk/contacts/upsert",
-    "writerId": "bulkUpsertContacts",
-    "verification": "verified-live",
-    "importSafe": true,
-    "bulk": true,
-    "releaseStatus": "ga",
-    "decision": "Contacts V5 uses flat contact fields wrapped under contacts[].contact for bulk upsert (1–100). Existing live evidence covers safe-mode basic-field upsert and query-back only, not member updates, real-value delivery, or extensions. Use the verified contact import wrapper to reconcile identifiers before writing and compare each stored record before publishing its crosswalk."
-  },
-  "alternateWrites": [
-    {
-      "surface": "Contacts V5",
-      "endpoint": "POST /contacts/v5/contacts",
-      "writerId": "createContact",
-      "verification": "unverified",
-      "importSafe": true,
-      "bulk": false,
-      "when": "Single-record creates outside the bulk import path; same flat GA contact shape."
-    },
-    {
-      "surface": "Contacts V4",
-      "endpoint": "POST /contacts/v4/contacts",
-      "writerId": null,
-      "verification": "verified-live",
-      "importSafe": true,
-      "bulk": false,
-      "when": "Legacy compatibility fallback only when a migration explicitly requires the V4 surface (e.g. V4 labels or V4 info.extendedFields semantics); requires an explicit legacy writer or direct REST plan because createContact targets V5."
-    }
-  ],
-  "extendedFields": {
-    "schemaKind": "data-extension-schema",
-    "definitionSurface": "Data Extension Schema API",
-    "definitionEndpoint": null,
-    "definitionOperation": "Create Data Extension Schema (FQDN wix.contacts.*.contact) — resolve the concrete endpoint from the Data Extension Schema API docs during setup; not recorded here to avoid guessing",
-    "valuePath": "extendedFields.namespaces._user_fields",
-    "namespaceForCreatedFields": "_user_fields",
-    "dataExtensionSchemaBacked": true,
-    "contactsV5Status": "At GA (verified 2026-08-04) the V5 contact-object docs route custom field definitions through the Data Extension Schema API with FQDN wix.contacts.*.contact, and the V5 contact carries values under extendedFields.namespaces.<ns>. CAVEAT: the Data Extension Schema intro's supported-objects table does not list contacts yet (docs inconsistency at GA cutover) — verify the DES path live during setup before relying on it. The V4 Contacts Extended Fields API (POST /contacts/v4/extended-fields, values under info.extendedFields) still exists but pairs with the V4 write surface only; do not mix the two.",
-    "setupGuidance": [
-      "Define contact custom fields during setup (Data Extension Schema, FQDN wix.contacts.*.contact) before writing contact values; verify live given the docs inconsistency.",
-      "Persist the returned field key from setup; do not invent the final key from the display name.",
-      "Write contact extended field values under extendedFields.namespaces._user_fields[returnedKey] with V5 writers; info.extendedFields is the V4 surface only.",
-      "Use Contacts V5 for contact record writes by default; surface current verification level in execution reports."
-    ],
-    "docs": [
-      "https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/contact-object",
-      "https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction",
-      "https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/extended-fields/introduction"
-    ],
-    "fqdn": "wix.contacts.*.contact",
-    "supportsFiltering": false,
-    "nestedSubrecordExtendedFields": "none known",
-    "liveVerification": "UNVERIFIED — setup gates on a live List call and fails closed with CONTACTS_V5_DES_UNVERIFIED; no automatic V4 fallback. Filtering is not listed for contacts, so it is refused.",
-    "legacyV4": {
-      "schemaKind": "crm-contact-extended-field",
-      "contactWriteSurface": "contacts-v4",
-      "operation": "Find Or Create Extended Field (POST /contacts/v4/extended-fields), read back by GET /contacts/v4/extended-fields/{key}",
-      "valuePath": "info.extendedFields.<verifiedKey>",
-      "namespaceForCreatedFields": "custom",
-      "admittedDataTypes": [
-        "TEXT"
-      ],
-      "liveVerification": "UNVERIFIED — offline contract only; explicit opt-in per mapping."
-    }
-  },
-  "safeModeContactFields": [
-    {
-      "kind": "email",
-      "targetPath": "contact.email.email",
-      "source": "target-schema",
-      "notes": "Contacts V5 GA main email; subscription status and matching key on this value."
-    },
-    {
-      "kind": "email",
-      "targetPath": "contact.additionalEmails[].email",
-      "source": "target-schema",
-      "notes": "Contacts V5 GA additional emails."
-    },
-    {
-      "kind": "phone",
-      "targetPath": "contact.phone.phone",
-      "source": "target-schema",
-      "notes": "Contacts V5 GA main phone."
-    },
-    {
-      "kind": "phone",
-      "targetPath": "contact.additionalPhones[].phone",
-      "source": "target-schema",
-      "notes": "Contacts V5 GA additional phones."
-    }
-  ],
-  "fallbacks": [
-    {
-      "classification": "cms",
-      "when": "Use for source CRM fields that should not or cannot live in contact extended fields."
-    }
-  ],
-  "reliability": {
-    "status": "partially-reliable",
-    "flags": []
-  },
-  "pitfalls": [
-    {
-      "code": "created-date-server-controlled",
-      "severity": "warning",
-      "summary": "Original contact created dates are not writable as native createdDate."
-    },
-    {
-      "code": "consent-sensitive",
-      "severity": "blocker",
-      "summary": "Only import subscription status with proof of consent."
-    },
-    {
-      "code": "member-create-reuses-a-contact-by-phone-match",
-      "severity": "blocker",
-      "summary": "VERIFIED LIVE 2026-09-06, from the member side: Create Member's phone-based contact dedup is not just a bulk-upsert risk -- it fires on ordinary Create Member calls too, and on an ORPHANED contact (one whose member was deleted; the contact itself is never deleted with it). Two different source customers who share a phone number (a shared line, a placeholder store number, a data-entry error) silently become one Wix contact, the second person's name overwriting the first's. See rp-target-wix/lib/customer-member.js and wix-writers.js ensureMember for the guard this project uses (query Contacts by phone before create, EVERY phone in the array; drop the phone(s) rather than merge)."
-    },
-    {
-      "code": "bulk-correlation-and-readback",
-      "severity": "blocker",
-      "summary": "Bulk Upsert results must use itemMetadata.originalIndex with unique in-range indexes. Missing/duplicate indexes, invalid IDs and undetailed failures retain unresolved source identities. HTTP success and balanced counts do not certify crosswalks; importContacts verifies identity and intended values before publication."
-    },
-    {
-      "code": "primary-phone-can-match-with-email",
-      "severity": "blocker",
-      "summary": "V5 matches externalId, main email and main phone; phone can match even when an email is supplied. Reconcile target candidates before upsert. Phone-only identity and distinct source keys sharing one target block and report in the shared importer."
-    },
-    {
-      "code": "extensions-require-surface-specific-evidence",
-      "severity": "warning",
-      "summary": "V5 declares extendedFields.namespaces, not V4 info.extendedFields/items. Contact DES is named by the V5 schema but absent from the DES supported-objects table; shared provisioning supports orders only. Existing basic-contact evidence does not prove extension persistence. Compare selected values and enforce their actual field schema; no undocumented global 200-character cap or silent V4 fallback."
-    },
-    {
-      "code": "source-email-can-fail-the-target-validator",
-      "severity": "warning",
-      "summary": "VERIFIED LIVE: Wix's contact-email validation is STRICTER than the source's, so an address the source stored and used for years is not necessarily writable. The shape observed live is a local part that begins with a dot -- `.<digits>@<provider>` -- which the source accepted and Wix rejected with a 400 on the contact write. Never transcribe a real address into this repo or into a run artifact as an example; the shape is the whole fact. It appears on live customer data, not in testing: a source can carry a long tail of these, and a sample of clean records may not contain one. Checking source emails against the target's rules before the write is useful to FLAG likely rejections (warn, and plan them into the report), never to remove, rewrite or repair an address: a local check alone is not grounds to change customer data. A contact Wix actually refuses is a failed record: lib/contact-import.js records the error per row, whether it came back per item or for the whole call, and keeps the source row for a rerun. Do not write that contact without its address or with a stand-in; automatic removal is approved only for the order import's named-field retry (ecom/order order-contact-field-refused-fails-whole-order), not for contacts. The same address carried on an order follows that order rule. Only the leading-dot local part has been observed live: treat it as one instance of a class (leading/trailing/doubled dots, embedded spaces, quoted local parts) and do not report any other shape as tested."
-    },
-    {
-      "code": "contact-permission-failure",
-      "severity": "warning",
-      "summary": "An empty-body 403 establishes authorization failure, not specifically token expiry. Preserve partial outcomes and reconcile before retrying uncertain writes. Set updateMember only for an intended member update; changing login email belongs to Members."
-    }
-  ],
-  "mappingGuidance": [
-    "WooCommerce guest-checkout buyers are not WP users and never appear in /wc/v3/customers (guest orders carry customer_id: 0) — also derive contacts from order billing/shipping details on /wc/v3/orders, deduped by email via Bulk Upsert, so every imported order can carry a crosswalked buyerInfo.contactId.",
-    "Prefer contact extended fields for source CRM metadata before CMS fallback.",
-    "Use Contacts V5 (GA) as the default contact writer surface; the GA contact shape is flat (main email/phone + additionalEmails/additionalPhones, addresses[] with nested address, company object) — never emit the V4 info wrapper to V5 endpoints.",
-    "For contact custom fields, setup must define the Data Extension Schema (FQDN wix.contacts.*.contact) and carry the returned key into contact writers under extendedFields.namespaces._user_fields.",
-    "Source labels map to V5 tags (tags.privateTags.tagIds via the Tags API, FQDN wix.contacts.*.contact); resolve the tag/label story during setup before planning post-import label-wave automations.",
-    "Standard contact imports use lib/contact-import.js with stable source keys and per-record safe-mode options. Reuse the same wrapper on reruns; a crosswalk hit is not proof of identity. Field comparisons use a closed rule set: main email trim/lowercase, other mapped values exact.",
-    "LIVE-VERIFIED 2026-09-16: importing a contact does not create a Wix Member, and this repo's order/blog import passes deliberately stub memberCrosswalk to always return null -- so a contact-only import, safe-mode or not, leaves every customer with no login identity. If the merchant needs migrated customers to be able to log in, promoting a contact to a real email + Member is a distinct, separate write: read the contact's current revision, PATCH its email/phone from the real source values (only ever over a contact whose CURRENT email still matches the safe-mode mock pattern -- never blind-overwrite one already real), then call ensureMember() with the same real loginEmail. Doing the contact-email-update BEFORE ensureMember() is what makes the created Member land on the SAME existing contact (verified live: member.contactId === the pre-existing contact id) rather than a duplicate. See rp-execute-import/SKILL.md's 'Contacts/Members disposition' section for the required upfront question and status-reporting contract this implies."
-  ],
-  "setupRequirements": [
-    "Contact extended fields when source-only CRM fields are preserved natively.",
-    "Data Extension Schema setup (FQDN wix.contacts.*.contact) before contact writers emit extendedFields values; verify live given the DES supported-objects docs inconsistency.",
-    "Basic safe-mode bulk upsert/query-back evidence does not verify single create/update, member changes, or extensions. Report the actual operation and field verification scope."
-  ],
-  "evidence": [
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/contact-object"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/bulk-upsert-contacts"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/extended-fields/introduction"
-    },
-    {
-      "type": "live-run",
-      "path": "anonymized-live-verification",
-      "note": "Verified live: create + query-back readback, safe mode on — contacts via Contacts V5 bulk upsert (emails/phones were safe-mode mocks — real-value delivery path still unexercised)"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/contacts-v5/matching-contacts"
-    }
-  ],
-  "intendedFields": [
-    {
-      "targetPath": "contact.name.first",
-      "sourcePaths": [
-        "first_name",
-        "firstName"
-      ]
-    },
-    {
-      "targetPath": "contact.name.last",
-      "sourcePaths": [
-        "last_name",
-        "lastName"
-      ]
-    },
-    {
-      "targetPath": "contact.email.email",
-      "sourcePaths": [
-        "email"
-      ]
-    },
-    {
-      "targetPath": "contact.phone.phone",
-      "sourcePaths": [
-        "phone"
-      ]
-    },
-    {
-      "targetPath": "contact.addresses[]",
-      "sourcePaths": [
-        "addresses[]"
-      ]
-    }
-  ],
-  "readBackProjection": {
-    "identity": "contactIdentity",
-    "serverOwned": [
-      {
-        "path": "contact.revision",
-        "reason": "server revision"
-      }
-    ],
-    "read": "GET /contacts/v5/contacts/{id}"
-  }
-}

package/skills/wix-replatform/resources/rp-target-wix/domains/crm/entities/email-subscription.json

@@ -1,105 +0,0 @@
-{
-  "schemaVersion": 1,
-  "domain": "crm",
-  "entity": "email-subscription",
-  "displayName": "Email Subscription",
-  "capability": "crm.email-subscription",
-  "target": {
-    "classification": "native",
-    "nativeEntity": "Email Subscription",
-    "verifiedFqdn": null,
-    "idPolicy": "server-assigned",
-    "crosswalkRequired": true
-  },
-  "dependsOn": [],
-  "sourceAliases": [
-    {
-      "sourceSystem": "wordpress",
-      "sourceEntity": "newsletter_subscription",
-      "routes": [
-        "plugin-specific subscription routes (e.g. Mailchimp/MailPoet list-membership tables) -- not yet mapped by this repo"
-      ],
-      "confidence": "medium"
-    },
-    {
-      "sourceSystem": "woocommerce",
-      "sourceEntity": "order.meta_data",
-      "routes": ["/wc/v3/orders -- meta_data entries with a checkout-consent-checkbox key, value '1'"],
-      "confidence": "high",
-      "note": "LIVE-VERIFIED 2026-09-16: a source store's marketing-consent checkout checkbox is recorded as ORDER meta, not on the customer object, and the key is present only when checked -- absence means not consented (or not asked), never an explicit '0'. Applies identically to registered-customer and guest-checkout orders, so scan orders, not customers, and match back to a customer_id when present."
-    },
-    {
-      "sourceSystem": "wix",
-      "sourceEntity": "emailSubscription",
-      "routes": [
-        "Email Subscriptions API"
-      ],
-      "confidence": "high"
-    }
-  ],
-  "preferredWrite": {
-    "surface": "Email Subscriptions",
-    "endpoint": "POST /email-marketing/v1/email-subscriptions/bulk",
-    "writerId": "bulkUpsertEmailSubscriptions",
-    "verification": "verified-live",
-    "importSafe": false,
-    "bulk": true,
-    "decision": "The MECHANICAL write is live-verified: keyed by EMAIL ADDRESS, not contactId, so it covers guest-checkout consent with no Contact behind it just as well as a known contact; a live batch of both known-customer and guest emails landed with subscriptionStatus SUBSCRIBED on query-back; the write only sets a status and does not itself send any confirmation/marketing email, so it is safe to run even while the site's notifications are muted. NOT YET CLEARED FOR USE regardless: importSafe stays false until the order-to-contact fold rule and the API-choice pitfalls below are each resolved as an explicit, recorded product decision -- a working writer is not the same thing as an authorized one, and this entity was flipped to importSafe once before without either decision being made, which is the mistake this note exists to prevent repeating."
-  },
-  "fallbacks": [
-    {
-      "classification": "cms",
-      "when": "Use for consent evidence and source subscription audit history."
-    }
-  ],
-  "reliability": {
-    "status": "reliable",
-    "flags": []
-  },
-  "pitfalls": [
-    {
-      "code": "consent-proof-required",
-      "severity": "blocker",
-      "summary": "Only set subscribed states when the migration has consent evidence. A real per-order checkout-consent-checkbox flag (see the woocommerce order.meta_data sourceAlias above) is sufficient evidence; do not infer consent from mere presence as a customer or from having placed an order with no consent flag."
-    },
-    {
-      "code": "bulk-endpoint-caps-at-100-per-call",
-      "severity": "warning",
-      "summary": "bulkUpsertEmailSubscriptions accepts 1-100 subscriptions per call and returns per-item results with `metadata.totalSuccess`/`totalFailure` -- batch upstream past 100 and check each item's `error` field rather than trusting an overall 200."
-    },
-    {
-      "code": "order-scoped-consent-has-no-decided-fold-rule",
-      "severity": "blocker",
-      "summary": "A per-ORDER consent signal (see the woocommerce order.meta_data sourceAlias above) is not the same shape as a per-subscriber-record consent field: the same buyer can place several orders over time, possibly agreeing on one and staying silent on later ones. Nothing here has decided how multiple orders for one email reduce to a single Wix subscription state -- 'any consenting order ever sets it, and a later silent order never auto-revokes it' is one defensible rule, 'most recent order's answer wins' is another, and picking one is a real product decision, not an implementation detail an importer should invent silently. Do not write SUBSCRIBED for an email from order-scoped consent data until this fold rule is decided and recorded as product guidance here, and do not treat 'it happened to work when tried once' as that decision."
-    },
-    {
-      "code": "email-subscriptions-vs-marketing-consent-api-unresolved",
-      "severity": "blocker",
-      "summary": "A separate, newer Wix Marketing Consent API models an actual proof-of-consent trail (state CONFIRMED/PENDING/REVOKED, optInLevel single-vs-double-confirmation, and a lastConfirmationActivity source+timestamp record) rather than the bare subscribed/unsubscribed flag this entity's Email Subscriptions surface models. Which one is authoritative for real send-eligibility, and which one (if not both) a migration should write to, has not been confirmed against both APIs' full method schemas -- only informally suggested (an identity-team comment that a sign-up form's consent checkbox is copied onto the Contact, which is what email marketing reads from, favoring Email Subscriptions). Treat that as a lead, not a resolved comparison. Confirm which surface Wix's own contact-eligibility logic actually consults before choosing one, the same evidentiary bar this repo holds every other corrected API-choice claim to."
-    }
-  ],
-  "mappingGuidance": [
-    "Dedupe by lowercased email BEFORE writing: the same address can appear as both a known customer's email and a guest order's billing email across different orders. Prefer the known-customer identity when both exist for the same address.",
-    "Keep consent evidence and source timestamps available for review."
-  ],
-  "setupRequirements": [
-    "Consent policy decision before subscription writes."
-  ],
-  "evidence": [
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/crm/communication/email-subscriptions/emailsubscription-object",
-      "note": "object page (docs-survey sweep 2026-08-11)"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/crm/communication/email-subscriptions/bulk-upsert-email-subscription.md",
-      "note": "confirmed endpoint, batch cap and per-item result shape, 2026-09-16"
-    },
-    {
-      "type": "live-verification",
-      "path": "anonymized-live-verification",
-      "note": "the full set of a store's checkout-consent-flagged orders (registered customers and guests) written via bulkUpsertEmailSubscriptions and confirmed by queryEmailSubscriptions read-back, zero failures"
-    }
-  ]
-}

package/skills/wix-replatform/resources/rp-target-wix/domains/crm/entities/label.json

@@ -1,77 +0,0 @@
-{
-  "schemaVersion": 1,
-  "domain": "crm",
-  "entity": "label",
-  "displayName": "CRM Label",
-  "capability": "crm.label",
-  "target": {
-    "classification": "native",
-    "nativeEntity": "Contact Label",
-    "verifiedFqdn": null,
-    "idPolicy": "server-assigned",
-    "crosswalkRequired": true
-  },
-  "sourceAliases": [
-    {
-      "sourceSystem": "woocommerce",
-      "sourceEntity": "customer_tag",
-      "routes": [
-        "customer metadata",
-        "segments"
-      ],
-      "confidence": "low"
-    },
-    {
-      "sourceSystem": "wix",
-      "sourceEntity": "contactLabel",
-      "routes": [
-        "Contacts Labels"
-      ],
-      "confidence": "high"
-    }
-  ],
-  "dependsOn": [],
-  "preferredWrite": {
-    "surface": "Contacts Labels",
-    "endpoint": null,
-    "writerId": null,
-    "verification": "verified-live",
-    "importSafe": true,
-    "bulk": false
-  },
-  "fallbacks": [
-    {
-      "classification": "cms",
-      "when": "Use for source segmentation rules that are not contact labels."
-    }
-  ],
-  "reliability": {
-    "status": "partially-reliable",
-    "flags": []
-  },
-  "pitfalls": [
-    {
-      "code": "source-segment-semantics",
-      "severity": "warning",
-      "summary": "Do not collapse dynamic segments or marketing automation state into static labels without review."
-    }
-  ],
-  "mappingGuidance": [
-    "Dependencies: no other modeled record must exist first; labels are standalone CRM objects and are created before contacts consume them.",
-    "Create labels before assigning them to contacts."
-  ],
-  "setupRequirements": [],
-  "evidence": [
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/crm/members-contacts/contacts/labels/label-object",
-      "note": "object page (docs-survey sweep 2026-08-11)"
-    },
-    
-    {
-      "type": "live-run",
-      "path": "anonymized-live-verification",
-      "note": "Verified live: create + query-back readback, safe mode on — 3/3 labels (MailPoet segments) created and read back"
-    }
-  ]
-}