rp-target-wix

Adaptateur target Wix. Maîtrise la surface d'écriture côté Wix que chaque migration partage — vérifiée une seule fois ici pour que les étapes agnostiques de la plateforme et la génération de code par projet ne la re-dérivent jamais (et ne la re-cassent). C'est le pendant symétrique de rp-source-wordpress : cet adaptateur maîtrise la lecture d'une plateforme source ; celui-ci maîtrise l'écriture vers Wix.

Quand ce skill est utilisé

Pas une étape du flux — une référence + une bibliothèque partagée consultée par :

rp-import-codegen intègre lib/wix-writers.js dans le projet (comme le transport wp-http) et génère des writers qui appellent ces primitives, en fournissant uniquement des mappages de champs par projet. La génération de code ne réemet pas la tuyauterie API Wix.
rp-setup-discovery / rp-execute-setup consultent les notes « Verified endpoints » et « Provisioning » pour l'installation d'app / Wix-Data / mécaniques de collection.

Comme la surface Wix est identique entre les plateformes source, ajouter une nouvelle source (rp-source-shopify, …) ne requiert aucune modification ici.

Contrat d'écriture (la surface Wix vérifiée)

lib/wix-writers.js expose des constructeurs de requête purs (build*Request) + des exécuteurs. Les formes marquées VERIFIED ont été validées par un vrai appel contre un site en direct, pas juste lues dans la doc. Les formes marquées UNVERIFIED sont des primitives de bootstrap issues du schéma doc/MCP qui doivent être surfacées dans les plans d'exécution jusqu'à ce qu'un appel de contrat en direct les promeuve. Elle exporte aussi sendDirectRest et notifyMissingWriter pour les chemins REST natifs générés quand Wix a une entité native mais cet adaptateur ne livre pas encore de primitive dédiée.

Capability	Endpoint	Notes / traps
HTML → contenu riche	`POST /ricos/v1/ricos-document/convert/to-ricos`	VERIFIED. L'enum `options.plugins` est en MAJUSCULES — l'exemple doc montre minuscules et 400s (FR-007).
Importer média depuis URL	`POST /site-media/v1/files/import`	VERIFIED. Async : la réponse est `PENDING` ; poll `GET /site-media/v1/files/{id}` pour `READY` avant de référencer.
Catégorie blog	`POST /blog/v3/categories`	VERIFIED. Body `{ category: { label, slug, description } }`.
Tag blog	`POST /blog/v3/tags`	VERIFIED. Le body est top-level `{ label, language }` — PAS `{ tag: { label, slug } }` ; slug est dérivé.
Article blog	`POST /blog/v3/draft-posts` → `…/{id}/publish`	VERIFIED. `memberId` requis (tiers). L'image vedette est `heroImage.id` (GUID WixMedia), pas `media.wixMedia.image.id`.
Item CMS	`POST /wix-data/v2/items`	VERIFIED. `{ dataCollectionId, dataItem: { data } }`. Requiert Wix Data activé (sinon `WDE0110`).
Membres	`GET`/`POST /members/v1/members`	VERIFIED. Dédupliqué par `loginEmail` (PII contrôlé ; utiliser un membre fallback si absent).
Produit Stores	`POST /stores/v3/products`, `POST /stores/v3/products/query`	UNVERIFIED bootstrap schéma doc. Le payload produit est spécifique au projet ; promouvoir seulement après succès de create/query en sandbox.
Fallback Stores product Catalog V1	`POST /stores/v1/products`, `POST /stores/v1/products/query`	TEMPORARY fallback FR-013. Utiliser seulement quand le site destination rapporte `CATALOG_V1` ; supprimer cette ligne et le bloc de code correspondant quand FR-013 est résolu et les installations Stores fraîches sont toujours Catalog V3.
Fallback Stores collection Catalog V1	`POST /stores/v1/collections`, `POST /stores/v1/collections/query`	TEMPORARY fallback FR-013 pour catégories produit Woo sur sites Catalog V1. Utiliser comme cible de groupement Stores native au lieu du CMS. Supprimer avec FR-013.
Catégorie Stores	`POST /categories/v1/categories`	UNVERIFIED bootstrap schéma doc/artefact projet. Confirmer la sémantique catégorie Stores destination avant import live.
Contacts	`POST /contacts/v4/contacts`, `POST /contacts/v4/contacts/query`	VERIFIED (2026-06-16). Les champs liste V4 sont des objets wrapper : `emails.items`, `phones.items`, `addresses.items` ; les arrays directement sous `info` retournent 400. La gestion des doublons dépend toujours de `allowDuplicates`.
Coupons	`POST /stores/v2/coupons`, `POST /stores/v2/coupons/query`	UNVERIFIED bootstrap. Préférer les coupons Wix natifs car Wix a une entité coupon native ; ne pas ranger les coupons dans le CMS juste par prudence ou parce que le scope doit être mappé. Le fallback n'est que pour la sémantique source sans représentation native.
Commande eCom	`POST /ecom/v1/orders`, `POST /ecom/v1/orders/query`	UNVERIFIED bootstrap schéma doc. Traiter comme bloqué sauf si la vérification setup prouve que la création de commandes historiques est sans effet secondaire.
REST natif direct	tout chemin REST Wix dérivé par codegen	UNVERIFIED chemin généré pour entités Wix natives manquant d'un writer adaptateur dédié. Doit logger, appeler `notifyMissingWriter`, et être montré dans le plan d'exécution.

Accessibilité URL source de l'import média

La primitive média importe par URL : les serveurs Wix récupèrent l'sourceUrl fournie. Les URLs HTTPS publiques sont attendues ; localhost, 127.0.0.1, les hôtes Docker-only, et autres URLs privées-seulement ne sont pas accessibles par Wix pendant un import live. C'est une préparation source optionnelle et, autant que nous le savons, affecte l'import média seulement.

Si le système source est local, la migration devrait soit :

exposer la source via un tunnel HTTPS public, puis passer/rewirer les URLs média vers cette URL de base publique ; soit
ignorer/différer l'import média et clairement indiquer quelles références dépendantes de média manqueront jusqu'à ce que média soit importé.

Configuration rapide Ngrok pour macOS :

brew install ngrok
ngrok config add-authtoken "<YOUR_AUTHTOKEN>"
ngrok http 8090
export WP_BASE_URL=https://<id>.ngrok-free.app

Valider par appel réel — ne pas faire confiance aux exemples doc

Les contrôles MCP doc à temps de génération confirment qu'un endpoint existe ; ils ne confirment pas que la forme de requête fonctionne. L'import wporg-news en direct a prouvé que les exemples doc peuvent être faux (plugins Ricos minuscules → 400) ou incomplets (champ image vedette, corps tag). La règle pour cet adaptateur :

Traiter une forme comme vérifiée seulement après qu'un appel réel réussisse — encoder la forme qui marche ici avec une note // VERIFIED: (ou // VERIFIED-TRAP:) et une date.
Une primitive // UNVERIFIED: est autorisée comme point de bootstrap pour code généré, mais ce n'est pas une permission d'écriture-live silencieuse. Le plan d'exécution doit la signaler, et la vérification setup doit soit la promouvoir avec une validation sandbox/live soit router vers un fallback.
Garder scripts/contract-test.js courant : il émet un appel réel par primitive contre un site sandbox et c'est le seul endroit où la dérive de schéma fait surface. Lancer depuis le répertoire skill rp-target-wix :
```
node scripts/contract-test.js
WIX_AUTH_TOKEN=... WIX_SITE_ID=... node scripts/contract-test.js
```
Lancer en cadence et après tout changement API Wix. Un test contract qui échoue — pas un import cassé d'un tiers — c'est comment on apprend que la surface a bougé.

Fallback temporaire Stores Catalog V1 (FR-013)

Supprimer cette section en entier quand les installations Wix Stores fraîches supportent fiablement les écritures produit Catalog V3 sans le fallback V1 (suivi interne : FR-013).

Les installations Wix Stores fraîches sont censées devenir Catalog V3-only. Jusqu'à ce que Wix Stores fixe ce flux, la vérification setup peut découvrir un site Stores fraîchement installé qui rapporte CATALOG_V1 quand sondé via POST /stores/v3/products/query. Dans ce cas :

Continuer à utiliser une cible Stores produit native ; ne pas router les produits au CMS juste parce que le writer V3 est inutilisable pour ce site.
Utiliser le fallback native REST Catalog V1 temporaire dans lib/wix-writers.js.
Mapper les catégories produit source à des collections Stores V1 sur sites Catalog V1 ; passer ces IDs de collection au create produit V1 comme collectionIds.
Logger le fallback via notifyMissingWriter et le surfacer dans le plan d'exécution comme un chemin natif non-vérifié.
Promouvoir le fallback V1 seulement après un succès sandbox create/query, ou le supprimer une fois FR-013 est fait.

Ce qui reste en codegen (pas ici)

Les mappages de champs par projet et l'ordre (quel champ source → quelle clé data, les maps ref média/auteur/taxonomie, upsert-by-key) vivent dans les transforms/writers générés. Cet adaptateur détient seulement les formes invariantes de requête Wix + transport. Les noms et schémas de collection (PodcastEpisodes, …) sont spécifiques au projet et viennent du plan de mapping.

Pointeurs provisioning (voir rp-execute-setup)

Les apps (Blog, Members) s'installent via l'App Installation API ; extraire appDefId du tableau officiel « Apps Created by Wix ».
Activation Wix Data (WDE0110) : installer l'app Wix Data appDefId e593b0bd-b783-45b8-97c2-873d42aacaf4 via l'App Installation API ; après POST /wix-data/v2/collections crée des collections NATIVE sans WDE0110 (vérifiée live). Fallback : une app custom avec une extension data-collections (déclare les collections à install, mais ne peut pas exprimer les champs REFERENCE).

Scope & couverture

Wix a beaucoup d'apps/entités (Stores, Bookings, Events, Restaurants, Pricing Plans, CRM, …). Cet adaptateur ne pré-construit pas tous. La couverture est demand-driven et grandit via des releases examinées. Une migration peut toujours cibler une entité Wix native avant qu'une primitive dédiée existe ; dans ce cas codegen émet un chemin REST natif utilisant sendDirectRest, log la primitive manquante, et appelle notifyMissingWriter pour que l'équipe RePlatform puisse ajouter le writer plus tard.

Échelle native target quand aucun writer dédié n'existe :

Utiliser la primitive rp-target-wix dédiée quand elle existe.
Si Wix a une entité native mais pas de primitive dédiée, générer un appel REST natif depuis MCP Wix/schéma doc, le marquer UNVERIFIED, logger, appeler notifyMissingWriter, et le surfacer dans le plan d'exécution avant toute écriture. Ce n'est pas une écriture live silencieuse.
Utiliser le CMS seulement quand il n'existe pas d'entité Wix native convenant, ou quand l'entité native est explicitement rejetée pour des raisons de fidélité/effets secondaires. Le CMS n'est pas un fallback pour un writer adaptateur manquant.
S'arrêter si ni un chemin natif ni une cible CMS/custom acceptable n'existent.

L'invariant : tout ce qui n'est pas soutenu par une primitive vérifiée est surfacé à l'utilisateur pour consentement avant exécution — jamais écrit silencieusement.