@wix/agent-skills 1.15.0 → 1.16.0

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

@@ -0,0 +1,131 @@
+{
+  "schemaVersion": 1,
+  "domain": "crm",
+  "entity": "contact",
+  "displayName": "CRM Contact",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "Contact",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "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": "unverified",
+    "importSafe": true,
+    "bulk": true,
+    "releaseStatus": "ga",
+    "decision": "Contacts V5 is GA (docs verified 2026-08-04; FR-014 resolved). The GA contact shape is flat: main email/phone + additionalEmails/additionalPhones, addresses[] with postal fields nested under `address`, company as { name, jobTitle }; no `info` wrapper. Bulk upsert (100/call, synchronous, per-item results, externalId set-once) is the import path; createContact/updateContact cover single-record needs. Live create/query/update verification is still pending a token with Contacts permissions (2026-07-26 probe got 403)."
+  },
+  "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"
+    ]
+  },
+  "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." }
+  ],
+  "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."
+  ],
+  "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.",
+    "V5 writers remain UNVERIFIED in execution reports until a live contract test with Contacts permissions promotes create/query/update."
+  ],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.md" },
+    {
+      "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"
+    }
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "domain": "crm",
+  "entity": "email-subscription",
+  "displayName": "Email Subscription",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Email Subscription",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "wordpress", "sourceEntity": "newsletter_subscription", "routes": ["plugin-specific subscription routes"], "confidence": "medium" },
+    { "sourceSystem": "wix", "sourceEntity": "emailSubscription", "routes": ["Email Subscriptions API"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "Email Subscriptions",
+    "endpoint": null,
+    "writerId": null,
+    "verification": "docs",
+    "importSafe": false,
+    "bulk": true
+  },
+  "fallbacks": [
+    { "classification": "cms", "when": "Use for consent evidence and source subscription audit history." }
+  ],
+  "reliability": { "status": "partially-reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "consent-proof-required", "severity": "blocker", "summary": "Only set subscribed states when the migration has consent evidence." }
+  ],
+  "mappingGuidance": ["Keep consent evidence and source timestamps available for review."],
+  "setupRequirements": ["Consent policy decision before subscription writes."],
+  "evidence": [
+    { "type": "repo-research", "path": "research/source-entity-import-suitability-wordpress-woocommerce-wix.md" }
+  ]
+}

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

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "domain": "crm",
+  "entity": "label",
+  "displayName": "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" }
+  ],
+  "preferredWrite": {
+    "surface": "Contacts Labels",
+    "endpoint": null,
+    "writerId": null,
+    "verification": "unverified",
+    "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": ["Create labels before assigning them to contacts."],
+  "setupRequirements": [],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/domain.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "displayName": "Wix eCommerce",
+  "ownerHint": "eCommerce Orders, refunds, checkout, and order-history domain owners",
+  "wixAppsRequired": ["Wix Stores"],
+  "defaultImportOrder": ["order", "order-line-item", "order-refund"],
+  "sideEffectNotes": [
+    "Historical order writes are blocked unless setup verification proves side-effect behavior."
+  ],
+  "evidence": [
+    {
+      "type": "repo-research",
+      "path": "research/import-api-suitability/orders-contacts-members.md"
+    },
+    {
+      "type": "repo-research",
+      "path": "research/source-entity-import-suitability-wordpress-woocommerce-wix.md"
+    }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/order-line-item.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order-line-item",
+  "displayName": "eCommerce Order Line Item",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "eCommerce Order Line Item",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "order_line_item", "routes": ["/wc/v3/orders"], "confidence": "high" },
+    { "sourceSystem": "wix", "sourceEntity": "ecomOrderLineItem", "routes": ["eCommerce Orders API"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "eCom Orders",
+    "endpoint": "POST /ecom/v1/orders",
+    "writerId": "createOrder",
+    "verification": "unverified",
+    "importSafe": false,
+    "bulk": false
+  },
+  "fallbacks": [
+    { "classification": "cms", "when": "Use when source line-item metadata cannot fit native order line fields or extended fields." }
+  ],
+  "reliability": { "status": "unknown", "flags": ["IMPORT_UNRELIABLE"] },
+  "pitfalls": [
+    { "code": "parent-order-write", "severity": "blocker", "summary": "Line items are written through their parent order; do not create standalone duplicates." }
+  ],
+  "mappingGuidance": ["Preserve source line-item IDs in extended fields or CMS shadow data."],
+  "setupRequirements": ["Order data extension schema if line-item extended fields are used."],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/order-refund.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order-refund",
+  "displayName": "eCommerce Order Refund",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "eCommerce Order Refund",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "order_refund", "routes": ["/wc/v3/orders/{id}/refunds"], "confidence": "high" },
+    { "sourceSystem": "wix", "sourceEntity": "ecomOrderRefund", "routes": ["eCommerce Orders API"], "confidence": "medium" }
+  ],
+  "preferredWrite": {
+    "surface": "eCom Orders",
+    "endpoint": "POST /ecom/v1/orders",
+    "writerId": "createOrder",
+    "verification": "unverified",
+    "importSafe": false,
+    "bulk": false
+  },
+  "fallbacks": [
+    { "classification": "cms", "when": "Use for refund history when the order writer cannot preserve refund details." }
+  ],
+  "reliability": { "status": "partially-reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "refund-schema-unverified", "severity": "warning", "summary": "Verify whether the selected order write shape preserves refund amounts, reasons, dates, and line references." }
+  ],
+  "mappingGuidance": ["Map refunds with their parent order and preserve source refund IDs."],
+  "setupRequirements": ["Side-effect verification before historical order execution."],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/order.json

@@ -0,0 +1,97 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order",
+  "displayName": "eCommerce Order",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "eCommerce Order",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "order", "routes": ["/wc/v3/orders"], "confidence": "high" },
+    { "sourceSystem": "wix", "sourceEntity": "ecomOrder", "routes": ["eCommerce Orders API"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "eCom Orders",
+    "endpoint": "POST /ecom/v1/orders/import",
+    "writerId": "importOrder",
+    "verification": "unverified",
+    "importSafe": true,
+    "bulk": false,
+    "releaseStatus": "beta",
+    "decision": "Import Order is the dedicated migration path (ECOM-01): settable purchasedDate/createdDate/number, values stored as-is, no side effects (no buyer notifications, no inventory adjustment, no contact/invoice/receipt/subscription creation; only the OrderImported event fires). Beta, single-order only (no bulk endpoint), no SHOPIFY/WOOCOMMERCE channel enums (use OTHER_PLATFORM), analytics inclusion not suppressible. Rollback via Bulk Delete Imported Orders; re-send with the same id fully replaces."
+  },
+  "alternateWrites": [
+    {
+      "surface": "eCom Orders",
+      "endpoint": "POST /ecom/v1/orders",
+      "writerId": "createOrder",
+      "verification": "unverified",
+      "importSafe": false,
+      "bulk": false,
+      "when": "Live-commerce order creation only — NEVER for historical import: decrements inventory, sends buyer confirmation email, auto-creates a contact (ECOM-02)."
+    }
+  ],
+  "safeModeContactFields": [
+    {
+      "kind": "email",
+      "targetPath": "billingInfo.email",
+      "source": "target-schema",
+      "notes": "Historical order billing email on the order object; codegen must resolve request wrappers."
+    },
+    {
+      "kind": "phone",
+      "targetPath": "billingInfo.phone",
+      "source": "target-schema",
+      "notes": "Historical order billing phone on the order object; codegen must resolve request wrappers."
+    },
+    {
+      "kind": "email",
+      "targetPath": "shippingInfo.email",
+      "source": "target-schema",
+      "notes": "Historical order shipping email on the order object when present."
+    },
+    {
+      "kind": "phone",
+      "targetPath": "shippingInfo.phone",
+      "source": "target-schema",
+      "notes": "Historical order shipping phone on the order object when present."
+    },
+    {
+      "kind": "email",
+      "targetPath": "buyerInfo.email",
+      "source": "target-schema",
+      "notes": "Historical order buyer email on the order object when present."
+    },
+    {
+      "kind": "phone",
+      "targetPath": "buyerInfo.phone",
+      "source": "target-schema",
+      "notes": "Historical order buyer phone on the order object when present."
+    }
+  ],
+  "fallbacks": [
+    { "classification": "cms", "when": "Use for separate audit/history records or unsupported nested source details." }
+  ],
+  "reliability": { "status": "partially-reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "create-order-not-import-safe", "severity": "blocker", "summary": "Never route historical orders through createOrder — it decrements inventory, emails the buyer, and auto-creates contacts; importOrder is the only import-safe writer." },
+    { "code": "contact-crosswalk-sequencing", "severity": "blocker", "summary": "Import creates no contact; contacts (including guest buyers from order billing emails) must be imported first so buyerInfo.contactId can be passed." },
+    { "code": "beta-single-order", "severity": "warning", "summary": "Import Order is Beta and single-order only (no bulk endpoint); undocumented rate limits apply at scale." },
+    { "code": "analytics-not-suppressible", "severity": "warning", "summary": "Imported orders appear in sales analytics/reports with no documented exclusion flag." },
+    { "code": "imported-orders-invisible-to-events", "severity": "warning", "summary": "Only the OrderImported event fires and only eCom's own indexer consumes it — imported orders never materialize in contacts/loyalty/event-driven views." }
+  ],
+  "mappingGuidance": [
+    "Resolve product, variation, contact, and coupon crosswalks before writing orders.",
+    "Contacts import first, orders second: Import Order accepts buyerInfo.contactId (schema-checked 2026-08-04) but creates no contact itself — always pass the crosswalked contact ID, including for guest buyers derived from order billing emails (see crm/contact). The field doc's 'automatically created if one doesn't exist' text is shared with live Create Order and is unverified for the import path — do not rely on it.",
+    "Use order and line-item extended fields for source-only metadata when configured."
+  ],
+  "setupRequirements": ["Order data extension schema if extended fields are used.", "Side-effect verification before execution."],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.md" },
+    { "type": "repo-research", "path": "research/source-entity-import-suitability-wordpress-woocommerce-wix.md" }
+  ]
+}