@inwink-mcp/backoffice-extension-helpers 1.0.11 → 1.0.13

package/README.md

@@ -75,7 +75,21 @@ Contrôles effectués :
 - `extension.manifest.json` présent, `name` (slug) et `version` (semver) valides ;
 - `dist/` contient `index.html` + `extension.manifest.json` à la racine + `assets/` ;
 - le zip contient `index.html` et `extension.manifest.json` à la racine, sans `node_modules/`, `src/` ni `dist/` ;
-- avertissements : `base: './'` absent de `vite.config.ts`, usage de `BrowserRouter`.
+- avertissements : `base: './'` absent de `vite.config.ts`, usage de `BrowserRouter`, `docs/inwink-api/` différent de la doc de cette version de la CLI.
+
+### `update-docs`
+
+Met à jour la doc API d'une extension **déjà générée** : `docs/inwink-api/` est remplacé en miroir par celui de cette version (fichiers ajoutés, modifiés, et supprimés s'ils ont disparu du template). Rien d'autre n'est touché, la commande peut être relancée sans risque.
+
+```bash
+npx @inwink-mcp/backoffice-extension-helpers@latest update-docs
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dir <path>` | Dossier du projet (défaut : dossier courant) |
+
+Ce dossier appartient à la CLI : une modification locale est écrasée au prochain `update-docs`. `AGENTS.md` et le code du squelette ne sont pas mis à jour.
 
 ## Templates
 

package/dist/cli.js

@@ -340,12 +340,70 @@ function bootstrap(opts) {
 }
 
 // src/commands/pack.ts
-import path7 from "path";
+import path8 from "path";
 
 // src/lib/verify.ts
+import fs5 from "fs";
+import path6 from "path";
+import AdmZip from "adm-zip";
+
+// src/lib/docs.ts
 import fs4 from "fs";
 import path5 from "path";
-import AdmZip from "adm-zip";
+var DOCS_REL_DIR = "docs/inwink-api";
+var DOCS_TEMPLATE = "vite-extension";
+var UPDATE_DOCS_COMMAND = "npx @inwink-mcp/backoffice-extension-helpers@latest update-docs";
+function templateDocsDir() {
+  return path5.join(templatesRoot, DOCS_TEMPLATE, DOCS_REL_DIR);
+}
+function listFiles(root, current = root) {
+  if (!fs4.existsSync(current)) return [];
+  const files = [];
+  for (const entry of fs4.readdirSync(current, { withFileTypes: true })) {
+    const full = path5.join(current, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(root, full));
+    else files.push(path5.relative(root, full).split(path5.sep).join("/"));
+  }
+  return files.sort();
+}
+function readNormalized(file) {
+  return fs4.readFileSync(file, "utf8").replaceAll("\r\n", "\n");
+}
+function diffDocs(projectDir) {
+  const src = templateDocsDir();
+  const dest = path5.join(projectDir, DOCS_REL_DIR);
+  const srcFiles = listFiles(src);
+  const destFiles = new Set(listFiles(dest));
+  const diff = { added: [], changed: [], removed: [] };
+  for (const rel of srcFiles) {
+    if (!destFiles.has(rel)) diff.added.push(rel);
+    else if (readNormalized(path5.join(src, rel)) !== readNormalized(path5.join(dest, rel))) {
+      diff.changed.push(rel);
+    }
+    destFiles.delete(rel);
+  }
+  diff.removed = [...destFiles];
+  return diff;
+}
+function isDocsUpToDate(diff) {
+  return diff.added.length + diff.changed.length + diff.removed.length === 0;
+}
+function syncDocs(projectDir) {
+  const diff = diffDocs(projectDir);
+  const src = templateDocsDir();
+  const dest = path5.join(projectDir, DOCS_REL_DIR);
+  for (const rel of [...diff.added, ...diff.changed]) {
+    const target = path5.join(dest, rel);
+    fs4.mkdirSync(path5.dirname(target), { recursive: true });
+    fs4.copyFileSync(path5.join(src, rel), target);
+  }
+  for (const rel of diff.removed) {
+    fs4.rmSync(path5.join(dest, rel));
+  }
+  return diff;
+}
+
+// src/lib/verify.ts
 function verifyExtension(options) {
   const { projectDir, requireDist = false } = options;
   const errors = [];
@@ -366,40 +424,49 @@ function verifyExtension(options) {
   } catch (err) {
     errors.push(err.message);
   }
-  const distDir = path5.join(projectDir, "dist");
-  if (!fs4.existsSync(distDir)) {
+  const distDir = path6.join(projectDir, "dist");
+  if (!fs5.existsSync(distDir)) {
     if (requireDist) {
       errors.push("Dossier dist/ introuvable apr\xE8s le build.");
     }
   } else {
-    if (!fs4.existsSync(path5.join(distDir, "index.html"))) {
+    if (!fs5.existsSync(path6.join(distDir, "index.html"))) {
       errors.push("dist/index.html manquant.");
     }
-    if (!fs4.existsSync(path5.join(distDir, "extension.manifest.json"))) {
+    if (!fs5.existsSync(path6.join(distDir, "extension.manifest.json"))) {
       errors.push("dist/extension.manifest.json manquant (le plugin Vite doit le copier).");
     }
-    const assetsDir = path5.join(distDir, "assets");
-    if (!fs4.existsSync(assetsDir) || !fs4.statSync(assetsDir).isDirectory()) {
+    const assetsDir = path6.join(distDir, "assets");
+    if (!fs5.existsSync(assetsDir) || !fs5.statSync(assetsDir).isDirectory()) {
       warnings.push("dist/assets/ introuvable \u2014 build Vite incomplet ?");
     }
   }
   const zipPath = resolveZipPath(options, projectDir, name, version);
-  if (zipPath && fs4.existsSync(zipPath)) {
+  if (zipPath && fs5.existsSync(zipPath)) {
     verifyZip(zipPath, errors);
   } else if (options.zipPath) {
     errors.push(`Zip introuvable : ${options.zipPath}`);
   }
   checkViteBase(projectDir, warnings);
   checkRouter(projectDir, warnings);
+  checkDocs(projectDir, warnings);
   return { errors, warnings };
 }
+function checkDocs(projectDir, warnings) {
+  const diff = diffDocs(projectDir);
+  if (isDocsUpToDate(diff)) return;
+  const count = diff.added.length + diff.changed.length + diff.removed.length;
+  warnings.push(
+    `${DOCS_REL_DIR}/ diff\xE8re de la doc API actuelle (${count} fichier(s)). Mettez-la \xE0 jour avec : ${UPDATE_DOCS_COMMAND}`
+  );
+}
 function resolveZipPath(options, projectDir, name, version) {
   if (options.zipPath) {
-    return path5.isAbsolute(options.zipPath) ? options.zipPath : path5.join(projectDir, options.zipPath);
+    return path6.isAbsolute(options.zipPath) ? options.zipPath : path6.join(projectDir, options.zipPath);
   }
   if (name && version) {
-    const candidate = path5.join(projectDir, `${name}-${version}.zip`);
-    return fs4.existsSync(candidate) ? candidate : void 0;
+    const candidate = path6.join(projectDir, `${name}-${version}.zip`);
+    return fs5.existsSync(candidate) ? candidate : void 0;
   }
   return void 0;
 }
@@ -408,7 +475,7 @@ function verifyZip(zipPath, errors) {
   try {
     entries = new AdmZip(zipPath).getEntries();
   } catch (err) {
-    errors.push(`Impossible de lire le zip ${path5.basename(zipPath)} : ${err.message}`);
+    errors.push(`Impossible de lire le zip ${path6.basename(zipPath)} : ${err.message}`);
     return;
   }
   const names = entries.map((e) => e.entryName.split("\\").join("/"));
@@ -429,60 +496,60 @@ function verifyZip(zipPath, errors) {
   }
 }
 function checkViteBase(projectDir, warnings) {
-  const file = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(file)) return;
-  const content = fs4.readFileSync(file, "utf8");
+  const file = path6.join(projectDir, "vite.config.ts");
+  if (!fs5.existsSync(file)) return;
+  const content = fs5.readFileSync(file, "utf8");
   if (!/base:\s*['"]\.\/['"]/.test(content)) {
     warnings.push("vite.config.ts : `base: './'` introuvable \u2014 les assets risquent de casser apr\xE8s d\xE9ploiement.");
   }
 }
 function checkRouter(projectDir, warnings) {
-  const srcDir = path5.join(projectDir, "src");
-  if (!fs4.existsSync(srcDir)) return;
+  const srcDir = path6.join(projectDir, "src");
+  if (!fs5.existsSync(srcDir)) return;
   if (sourceUsesBrowserRouter(srcDir)) {
     warnings.push("Usage de BrowserRouter d\xE9tect\xE9 \u2014 utilisez HashRouter pour l'h\xE9bergement versionn\xE9.");
   }
 }
 function sourceUsesBrowserRouter(dir) {
-  for (const entry of fs4.readdirSync(dir, { withFileTypes: true })) {
-    const full = path5.join(dir, entry.name);
+  for (const entry of fs5.readdirSync(dir, { withFileTypes: true })) {
+    const full = path6.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (sourceUsesBrowserRouter(full)) return true;
     } else if (/\.(tsx?|jsx?)$/.test(entry.name)) {
-      if (/\bBrowserRouter\b/.test(fs4.readFileSync(full, "utf8"))) return true;
+      if (/\bBrowserRouter\b/.test(fs5.readFileSync(full, "utf8"))) return true;
     }
   }
   return false;
 }
 
 // src/lib/zip.ts
-import fs5 from "fs";
-import path6 from "path";
+import fs6 from "fs";
+import path7 from "path";
 import AdmZip2 from "adm-zip";
 function createSourceZip(projectDir) {
   const sourceZip = new AdmZip2();
-  const rootFiles = fs5.readdirSync(projectDir);
+  const rootFiles = fs6.readdirSync(projectDir);
   for (const file of rootFiles) {
     if (file === "node_modules" || file === "dist" || file.endsWith(".zip")) {
       continue;
     }
-    const filePath = path6.join(projectDir, file);
-    const stat = fs5.statSync(filePath);
+    const filePath = path7.join(projectDir, file);
+    const stat = fs6.statSync(filePath);
     if (stat.isDirectory()) {
       sourceZip.addLocalFolder(filePath, file);
     } else {
-      sourceZip.addFile(file, fs5.readFileSync(filePath));
+      sourceZip.addFile(file, fs6.readFileSync(filePath));
     }
   }
   return sourceZip.toBuffer();
 }
 function zipDist(projectDir, name, version) {
-  const distDir = path6.join(projectDir, "dist");
-  if (!fs5.existsSync(distDir)) {
+  const distDir = path7.join(projectDir, "dist");
+  if (!fs6.existsSync(distDir)) {
     throw new Error("Dossier dist/ introuvable. Lancez le build avant de zipper.");
   }
   const zipFileName = `${name}-${version}.zip`;
-  const zipFilePath = path6.join(projectDir, zipFileName);
+  const zipFilePath = path7.join(projectDir, zipFileName);
   const zip = new AdmZip2();
   zip.addLocalFolder(distDir);
   const sourceZipBuffer = createSourceZip(projectDir);
@@ -493,7 +560,7 @@ function zipDist(projectDir, name, version) {
 
 // src/commands/pack.ts
 function pack(opts) {
-  const projectDir = path7.resolve(opts.dir ?? process.cwd());
+  const projectDir = path8.resolve(opts.dir ?? process.cwd());
   let name;
   let version;
   try {
@@ -515,7 +582,7 @@ function pack(opts) {
     error(err.message);
     return 1;
   }
-  success(`Zip cr\xE9\xE9 : ${path7.basename(zipPath)}`);
+  success(`Zip cr\xE9\xE9 : ${path8.basename(zipPath)}`);
   info(`Version : ${version}`);
   info("Mise \xE0 jour de la version avec la date du jour\u2026");
   try {
@@ -531,10 +598,39 @@ function pack(opts) {
   return ok ? 0 : 1;
 }
 
+// src/commands/update-docs.ts
+import path9 from "path";
+import pc4 from "picocolors";
+function updateDocs(opts) {
+  const projectDir = path9.resolve(opts.dir ?? process.cwd());
+  try {
+    readManifest(projectDir);
+  } catch (err) {
+    error(`Projet cible invalide : ${err.message}`);
+    return 1;
+  }
+  let diff;
+  try {
+    diff = syncDocs(projectDir);
+  } catch (err) {
+    error(`\xC9chec de la mise \xE0 jour : ${err.message}`);
+    return 1;
+  }
+  if (isDocsUpToDate(diff)) {
+    success(`${DOCS_REL_DIR}/ est d\xE9j\xE0 \xE0 jour.`);
+    return 0;
+  }
+  success(`${DOCS_REL_DIR}/ mis \xE0 jour :`);
+  for (const file of diff.added) info(`  ${pc4.green("+")} ${file}`);
+  for (const file of diff.changed) info(`  ${pc4.dim("~")} ${file}`);
+  for (const file of diff.removed) info(`  ${pc4.red("-")} ${file}`);
+  return 0;
+}
+
 // src/commands/verify.ts
-import path8 from "path";
+import path10 from "path";
 function verify(opts) {
-  const projectDir = path8.resolve(opts.dir ?? process.cwd());
+  const projectDir = path10.resolve(opts.dir ?? process.cwd());
   info("V\xE9rification de conformit\xE9\u2026");
   const result = verifyExtension({ projectDir, zipPath: opts.zip });
   const ok = printVerifyResult(result);
@@ -550,6 +646,9 @@ program.command("bootstrap").description("G\xE9n\xE8re le squelette d'une extens
 program.command("apply").description("Applique un template par-dessus un projet existant (overlay).").argument("<template>", "template \xE0 appliquer (sous-dossier de templates/)").option("--dir <path>", "dossier du projet (d\xE9faut : dossier courant)").action((template, options) => {
   process.exitCode = apply(template, options);
 });
+program.command("update-docs").description("Remplace la doc API (docs/inwink-api/) d'une extension existante par celle de cette version.").option("--dir <path>", "dossier du projet (d\xE9faut : dossier courant)").action((options) => {
+  process.exitCode = updateDocs(options);
+});
 program.command("package").description("Build + zip + v\xE9rification de conformit\xE9 de l'extension.").option("--dir <path>", "dossier du projet (d\xE9faut : dossier courant)").action((options) => {
   process.exitCode = pack(options);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inwink-mcp/backoffice-extension-helpers",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "author": "inwink",
   "license": "ISC",
   "description": "CLI pour bootstrapper, packager et vérifier les extensions backoffice inwink.",

package/templates/vite-extension/AGENTS.md.tpl

@@ -56,19 +56,23 @@ Avant d'écrire **tout** appel API, utilise les outils MCP inwink pour découvri
 
 ### Référence des patterns d'API (`docs/inwink-api/`)
 
-Les outils MCP donnent les endpoints/champs **exacts** ; la doc statique dans `docs/inwink-api/` décrit les **patterns d'appel** (verbes, forme des payloads, langage de requête). Lis uniquement le fichier correspondant à ta tâche :
+Les outils MCP donnent les endpoints/champs **exacts** ; la doc statique dans `docs/inwink-api/` décrit les **patterns d'appel** (verbes, forme des payloads, langage de requête). Ce dossier est une copie de la CLI helper, figée à la génération : mets-le à jour une fois par session de travail (pas avant chaque lecture) avec `npx @inwink-mcp/backoffice-extension-helpers@latest update-docs` (ne réécrit que `docs/inwink-api/`), et ne le modifie pas à la main. Lis uniquement le fichier correspondant à ta tâche :
 
 | Tâche | Fichier |
 |-------|---------|
+| URLs de base, shardId, routes d'audience, codes HTTP & règles générales | [docs/inwink-api/README.md](docs/inwink-api/README.md) |
 | Lire / lister des entités (query, count, pagination, projection, joins) | [docs/inwink-api/query.md](docs/inwink-api/query.md) |
 | Construire un filtre / tri / projection (langage de requête JSON) | [docs/inwink-api/query-language.md](docs/inwink-api/query-language.md) |
+| Regrouper / agréger (GROUP BY, statistiques, facettes) | [docs/inwink-api/aggregate.md](docs/inwink-api/aggregate.md) |
 | Créer une entité | [docs/inwink-api/create.md](docs/inwink-api/create.md) |
 | Modifier (patch / massupdate) | [docs/inwink-api/update.md](docs/inwink-api/update.md) |
 | Supprimer (delete / massdelete) | [docs/inwink-api/delete.md](docs/inwink-api/delete.md) |
 | Import en masse (bulk create/update) | [docs/inwink-api/import.md](docs/inwink-api/import.md) |
+| Versions passées et entités supprimées | [docs/inwink-api/history.md](docs/inwink-api/history.md) |
+| Contrats d'entités, endpoints divers | [docs/inwink-api/entities.md](docs/inwink-api/entities.md) |
+| Déclarer un champ custom (template d'entité) | [docs/inwink-api/entity-template.md](docs/inwink-api/entity-template.md) |
 | Champs de type `file` (upload / download) | [docs/inwink-api/files.md](docs/inwink-api/files.md) |
-| Contrats & schémas d'entités, endpoints divers | [docs/inwink-api/entities.md](docs/inwink-api/entities.md) |
-| Codes HTTP & règles générales | [docs/inwink-api/README.md](docs/inwink-api/README.md) |
+| Manipuler les `assets` (galerie media) | [docs/inwink-api/assets.md](docs/inwink-api/assets.md) |
 
 ## Appeler l'API inwink
 
@@ -90,7 +94,7 @@ function MonComposant() {
 }
 ```
 
-Méthodes disponibles sur chaque hook : `request<T>(path, init?)`, `get<T>`, `post<T>(path, body?)`, `put<T>(path, body?)`, `del<T>`.
+Méthodes disponibles sur chaque hook : `request<T>(path, init?)`, `get<T>`, `post<T>(path, body?)`, `put<T>(path, body?)`, `patch<T>(path, body?)`, `del<T>`.
 
 Pour appeler un **hôte externe déclaré** (hors API inwink), utilise le hook générique `useInwinkApi(baseUrl)`.
 
@@ -130,10 +134,12 @@ import { useInwinkContext } from './hooks/useInwinkContext';
 function MonComposant() {
   const { scope, eventId, communityId, tenantId } = useInwinkContext();
   // scope vaut 'event' | 'community' | 'tenant' | null (priorité event > community > tenant)
-  // Utilise l'id pertinent comme shardId dans les chemins d'API.
+  // En scope 'event' ou 'community', l'id correspondant est le shardId des chemins d'API.
 }
 ```
 
+En scope `tenant`, le `tenantId` **n'est pas un shardId** : les entités d'audience (`authtenant*`) vivent sous `{customerId}/audience/{tenantId}/{entity}/...` sur l'API Customer, où le shardId reste le `customerId` (cf. [docs/inwink-api/README.md](docs/inwink-api/README.md#audience-scoped-entities-customerapi)).
+
 Pour laisser l'utilisateur **choisir** un contexte, monte un picker (`EventPicker`, `CommunityPicker`, `AudiencePicker`) — typiquement en **surchargeant le `Header`** (le `Header` par défaut est minimal et prévu pour ça). Les pickers ne sont pas montés par défaut : décide selon le besoin de l'extension.
 
 ## Recettes
@@ -217,6 +223,7 @@ Packaging et vérification via la CLI helper :
 ```powershell
 npx @inwink-mcp/backoffice-extension-helpers@latest package   # build + zip + vérification de conformité
 npx @inwink-mcp/backoffice-extension-helpers@latest verify    # vérification de conformité seule
+npx @inwink-mcp/backoffice-extension-helpers@latest update-docs   # met à jour docs/inwink-api/
 ```
 
 ## Conventions de code
@@ -232,5 +239,6 @@ npx @inwink-mcp/backoffice-extension-helpers@latest verify    # vérification de
 
 > Ces consignes s'appliquent à **tout** assistant IA / outil agentique qui manipule cette extension, quel qu'il soit.
 
+- **Langue de l'extension.** Ce guide est rédigé en français et la référence API (`docs/inwink-api/`) en anglais : cela ne dit rien de la langue de l'extension. Échange avec l'utilisateur dans sa langue. Pour le code, les commentaires et les textes d'interface, utilise la langue qu'il demande ou, à défaut, celle dans laquelle il t'écrit — pas celle de cette documentation ni des commentaires du squelette.
 - **Ne jamais publier sans validation explicite de l'utilisateur.** Le build, le packaging et la vérification **en local** sont autorisés sans demander. En revanche, toute étape qui **expose l'extension côté inwink** (upload d'une version, `publish`, promotion en `latest`) doit être **confirmée explicitement par l'utilisateur à chaque fois**. En cas de doute, demande avant d'agir.
 - **Tester dans un vrai navigateur, pas dans un aperçu intégré.** Ne lance pas l'extension dans un panneau d'aperçu ou une webview embarquée de l'outil agentique : le flux OIDC y échoue. L'authentification exige que l'origine soit le serveur de dev local — le `redirect_uri` vaut `${window.location.origin}${window.location.pathname}` et n'est enregistré côté IdP que pour `http://localhost:<port>`, alors qu'un aperçu intégré sert l'application depuis une autre origine. **Recommandé** : lancer `npm run dev` et ouvrir un **vrai onglet de navigateur** (Chrome de préférence) sur l'URL locale affichée (ex. `http://localhost:5173`).

package/templates/vite-extension/docs/inwink-api/README.md

@@ -1,43 +1,84 @@
-# inwink API Reference
+# inwink API reference
 
-This document explains how to consume inwink APIs. It is intended as a reference for building API calls programmatically.
+Reference for consuming the inwink APIs from the extension. Calls always go through the `useInwink*Api` hooks, which set the Bearer token and the base URL: the paths below are relative to that base.
 
-> **Découverte dynamique d'abord.** Cette doc décrit les *patterns* d'appel (verbes, forme des payloads, langage de requête). Les **endpoints exacts, champs et entités** se découvrent via les outils MCP (`inwink_mcp_find_api_endpoint`, `inwink_mcp_get_entity_description`) — ne devine jamais une route ou un schéma.
+> **Keep this folder current.** It is a snapshot of the helper CLI taken when the extension was generated, and it is never edited by hand. Refresh it once per working session, not before each read, with `npx @inwink-mcp/backoffice-extension-helpers@latest update-docs` (rewrites `docs/inwink-api/` only).
 
-## Sommaire
+> **Dynamic discovery first.** This documentation describes call *patterns* (verbs, payload shapes, query language). The **exact endpoints, fields and entities** are discovered with the MCP tools (`inwink_mcp_find_api_endpoint`, `inwink_mcp_get_entity_description`) — never guess a route or a schema.
 
-| Tâche | Fichier |
+## Contents
+
+| Task | File |
 |---|---|
-| Lire / lister des entités (query, count, pagination, projection, joins) | [query.md](./query.md) |
-| Construire un filtre / tri / projection (langage de requête JSON) | [query-language.md](./query-language.md) |
-| Créer une entité | [create.md](./create.md) |
-| Modifier une entité (patch / massupdate) | [update.md](./update.md) |
-| Supprimer une entité (delete / massdelete) | [delete.md](./delete.md) |
-| Import en masse (bulk create/update) | [import.md](./import.md) |
-| Contrats & schémas d'entités, endpoints divers | [entities.md](./entities.md) |
-| Champs de type `file` (upload / download) | [files.md](./files.md) |
-| Manipuler les `assets` (galerie media) | [assets.md](./assets.md) |
+| Read / list entities (query, count, pagination, projection, joins) | [query.md](./query.md) |
+| Build a filter / sort / projection (JSON query language) | [query-language.md](./query-language.md) |
+| Group / aggregate (GROUP BY, statistics, facets) | [aggregate.md](./aggregate.md) |
+| Create an entity | [create.md](./create.md) |
+| Edit an entity (patch / massupdate) | [update.md](./update.md) |
+| Delete an entity (delete / massdelete) | [delete.md](./delete.md) |
+| Bulk import (bulk create/update) | [import.md](./import.md) |
+| Past versions and deleted entities | [history.md](./history.md) |
+| Entity contracts, other endpoints | [entities.md](./entities.md) |
+| Declare a custom field (entity template) | [entity-template.md](./entity-template.md) |
+| `file` fields (upload / download) | [files.md](./files.md) |
+| Handle `assets` (media library) | [assets.md](./assets.md) |
 
 ---
 
-## General Rules
+## API Base URLs
+
+| API | Base URL | Hook | Scope |
+|---|---|---|---|
+| EventAPI | `https://api-event.inwink.com` | `useInwinkEventApi` | Entities tied to an event (persons, sessions, exhibitors…) |
+| CommunityAPI | `https://api-community.inwink.com` | `useInwinkCommunityApi` | Entities tied to a community (members, forums, forumsubjects…) |
+| CustomerAPI | `https://api-customer.inwink.com` | `useInwinkCustomerApi` | Entities tied to the customer (events, contacts…) |
+
+## URL pattern
+
+- EventAPI: `{eventAPI}/{eventId}/{entity}/...`
+- CommunityAPI: `{communityAPI}/{communityId}/{entity}/...`
+- CustomerAPI: `{customerAPI}/{customerId}/{entity}/...`
+
+The `{eventId}`, `{communityId}` or `{customerId}` is called the **shardId** — it scopes each request to one specific event, community or customer.
+
+### Audience-scoped entities (CustomerAPI)
+
+A customer holds one or more **audiences** (also called *tenants*). Entities that belong to an audience rather than to the whole customer have a name starting with `authtenant` (`authtenantcommunity`, `authtenantcontact`, `authtenantcompany`, `authtenantmailtemplate`…) and live on a two-segment route:
+
+```
+{customerAPI}/{customerId}/audience/{tenantId}/{entity}/...
+```
+
+The `{customerId}` remains the shardId; the `{tenantId}` identifies the audience. On these entities, `{shardId}` reads `{customerId}/audience/{tenantId}` in every route of this documentation. An `authtenant*` entity called without the audience segment returns 404.
+
+## Common headers
+
+Every request requires (set by the hooks):
+
+```
+Authorization: Bearer {access_token}
+Content-Type: application/json
+```
+
+---
+
+## General rules
 
 - Property names are **case-insensitive**.
 - Enum values are **case-insensitive**.
 - All IDs are UUIDs.
 - Dates are ISO 8601 / UTC.
-- All write operations (create, edit, delete, import) use **POST** method.
-
----
+- Write operations on entities (create, edit, delete, import) use the **POST** method. Only the partial edit of an entity's template uses `PATCH` (see [entity-template.md](./entity-template.md)).
 
-## HTTP Status Codes
+## HTTP codes
 
 | Code | Meaning |
 |---|---|
-| 200 | Success — parse body as JSON |
+| 200 | Success — parse the body as JSON (some writes, such as entity template writes, return 200 with no body) |
 | 204 | Success — no content |
-| 400 | Bad request — body contains error details |
-| 401 | Unauthorized — token expired or invalid |
-| 403 | Forbidden — missing rights, contact CSM |
-| 500 | Server error — may be transient, contact support if persistent |
+| 400 | Bad request — the body holds the error details |
+| 401 | Unauthorized — token expired or invalid (handled by the hooks) |
+| 403 | Forbidden — missing rights, contact the CSM |
+| 404 | Entity not found, empty body: entity name does not exist, entity exists but under another name on another API, or `authtenant*` entity called without the audience segment. Do not guess another name: run `inwink_mcp_find_api_endpoint` again with a natural-language description of the need |
+| 500 | Server error — possibly transient, contact support if it persists. Also returned for a `shardId` that does not exist: check the identifier before concluding to an outage |
 | 503 | Transient infrastructure error — retry later |