@dwexo/plugin-sdk

Le contrat des applications et widgets de la marketplace DWEXO — types TypeScript et générateur de projet.

npx @dwexo/plugin-sdk mon-widget

npx create-dwexo-widget ne fonctionne pas : npx résout un nom de paquet, et le générateur est un binaire à l'intérieur de @dwexo/plugin-sdk. Un paquet séparé create-dwexo-widget reste à publier pour offrir la forme courte, comme le font create-vite ou create-react-app.

Ce que vous pouvez écrire

| | Application DWEXO | Application tierce | |---|---|---| | Code serveur | oui | non — front uniquement | | Exécution | dans la page (INLINE) | bac à sable (IFRAME) | | Publication | catalogue DWEXO | revue, puis catalogue public — ou lien privé | | Modèle commercial | identique | identique |

La distinction est technique, pas commerciale : une application tierce se vend, s'installe et s'abonne exactement comme une application DWEXO.

Les deux modes d'exécution

Ils n'exposent pas le même contrat. Choisissez avant de publier : basculer une application déjà installée la casse chez ses clients.

IFRAME — le mode des applications tierces

Le code tourne dans une iframe à origine opaque. Il ne voit ni le DOM de DWEXO, ni son stockage, ni ses cookies, et n'appelle jamais le serveur lui-même : il demande, DWEXO relaie avec un jeton propre à l'application. Le jeton de session de l'utilisateur n'entre jamais dans l'iframe.

window.dwexo.context                        // { manifest, inputs, theme }
await window.dwexo.call('contact.search', { q: 'dupont' })
window.dwexo.emit('dwexo:navigate', { path: '/crm/contacts' })
window.dwexo.resize()                       // après chaque changement de contenu

Ce n'est pas une brimade : c'est ce qui permet à un client de vous installer sans vous auditer. Le même isolement vous protège — vous ne pouvez pas casser l'écran d'un autre.

INLINE — code de confiance

Un custom element monté dans la page, qui reçoit le contexte en propriété DOM. Réservé au code DWEXO ou à un partenaire audité : rien n'y empêche le widget d'ignorer la façade et d'appeler les API directement.

import type { DwexoPluginContext } from '@dwexo/plugin-sdk';

@Input() set context(ctx: DwexoPluginContext) {
  if (!ctx) { return; }                      // Angular affecte undefined d'abord
  this.couleur = ctx.theme.primary;          // jamais de couleur en dur
  ctx.api.call('contact.search', { size: 5 }).then(/* … */);
}

Les actions

Un widget ne tape pas dans les API de l'ERP. Il appelle une action : une opération nommée, publiée par le serveur, avec une permission et des rôles.

Trois contrôles sont refaits côté serveur à chaque appel :

1. l'action existe au catalogue ;
2. votre application est installée et activée chez ce client ;
3. la permission qu'elle exige figure dans les permissions de votre fiche — lues en base, jamais reçues de l'appel — et l'utilisateur a les rôles.

Inutile de reproduire ces contrôles chez vous, et inutile d'essayer de les contourner. La liste des actions se lit sur GET /studio/gateway, ou dans DWEXO : Marketplace → Référence.

Livrer

• À un client précis — l'éditeur génère un lien d'installation privée depuis la fiche (Sécurité & accès). Le client ouvre le lien et installe. Rien ne passe par le catalogue public, aucune revue. C'est la voie du développement sur mesure.
• À tout le monde — Proposer au catalogue public, puis revue DWEXO. Chaque nouvelle version est revue à son tour : les clients continuent d'être servis avec la dernière version approuvée pendant l'examen.

Un client peut épingler une version : si votre mise à jour lui pose problème, il revient en arrière chez lui sans impacter vos autres clients.

Développement du paquet lui-même

src/index.ts est généré. La source de vérité est src/app/platform/plugins/plugin-sdk.ts dans cherry-erp-front-v2 — c'est le fichier que le front compile, donc c'est lui qui est vrai.

npm run build      # sync depuis l'ERP, puis tsc

Éditer src/index.ts à la main est sans effet : il est écrasé. Deux copies éditées séparément divergeraient, et une divergence de contrat ne se voit pas — elle se manifeste chez un éditeur tiers, en production.