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

package/package.json

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

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

@@ -100,6 +100,7 @@ Bonnes pratiques :
 - Le 429 (rate limiting) est géré automatiquement par les hooks : rejeu avec backoff exponentiel respectant l'en-tête `Retry-After` (cf. `useInwinkApi.ts`). Ne pas le ré-implémenter.
 - Au-delà de 429, une réponse non-OK lève une `InwinkApiError` (`status`, `body`) — à présenter via `ErrorState` ou un toast.
 - Pour propager l'annulation, passer le `signal` reçu de `useAsync` dans `init` : `eventApi.get(path, { signal })`.
+- Verbes disponibles : `get`, `post`, `put`, `patch`, `del`, plus `request` pour le reste. Une réponse OK sans corps — un 204, ou un 200 comme en renvoient les écritures de template d'entité — résout sur `undefined`.
 - Ne déclarer dans `permissions.platform` que les scopes réellement utilisés.
 - Déclarer les hôtes externes dans `permissions.externalHosts` (HTTPS uniquement).
 

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

@@ -16,6 +16,7 @@ This document explains how to consume inwink APIs. It is intended as a reference
 | 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) |
 
 ---
 

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

@@ -0,0 +1,236 @@
+◂ Retour à [README](./README.md)
+
+# InWink APIs — Assets (guide d'utilisation de l'API)
+
+> **But.** Décrire comment **créer**, **rechercher**, **modifier**, **supprimer**, **classer**
+> et **référencer** des assets via les APIs d'administration InWink (EventAPI / CommunityAPI /
+> CustomerAPI). Tout est décrit au niveau HTTP : verbe + route + corps JSON + réponse JSON.
+>
+> Auth : jeton porteur (Bearer) avec le claim `{scope}asset` (valeur `read` en lecture,
+> `edit` en écriture). Le flux d'upload de fichier réutilise celui décrit dans
+> la section `file-fields` — s'y référer pour le détail du lien d'upload signé.
+>
+> Convention JSON : corps de requête acceptés en casse insensible ; réponses en `camelCase`.
+
+---
+
+## 1. Principe (à lire en premier)
+
+Un **asset** est une entrée de bibliothèque médias, scopée à un événement, une communauté ou
+un tenant. Contrairement à un simple champ fichier, un asset a une identité propre, un titre,
+un type, une miniature, peut être rangé dans un dossier et **référencé par d'autres contenus**
+via le schéma `inwinkasset://`.
+
+**Forme d'un asset (en lecture)** :
+
+```json
+{
+  "id": "3fa85f64-....",
+  "title": "Logo principal",          // localisable (peut être un objet multi-langues)
+  "assetType": 0,                       // voir table ci-dessous
+  "file": { "blobName": "...", "container": "...", "url": "...", "mimeType": "...", "size": 123 },
+  "thumbnail": { ... },                 // objet fichier ou null
+  "folderId": "....",                   // ou null
+  "createdAt": "2026-07-01T10:00:00Z",
+  "applicationScope": "...",
+  "applicationScopeId": "..."
+}
+```
+
+**Types d'asset (`assetType`)** : `0`=Image, `1`=Video, `2`=Document, `3`=Audio, `4`=Font, `5`=Model3D.
+
+> ⚠️ **Le type d'asset n'est jamais dans le corps de requête** : il est déterminé par la
+> **route typée** sur laquelle on POST (`image-asset` → Image, `video-asset` → Video, …).
+
+Les champs `file` et `thumbnail` sont alimentés par le **même flux d'upload temporaire** que
+les champs fichier (voir la section `file-fields`) : on passe le **nom du blob temporaire** à la
+création, et l'API le transfère puis le sérialise en objet fichier.
+
+---
+
+## 2. Routes de base par API
+
+| API | Base CRUD typée | Base recherche (tous types) |
+|-----|-----------------|-----------------------------|
+| EventAPI | `{eventId}/{type}-asset` | `{eventId}/asset` |
+| CommunityAPI | `{communityId}/{type}-asset` | `{communityId}/asset` |
+| CustomerAPI | `{customerId}/audience/{tenantId}/{type}-asset` | `.../asset` |
+
+`{type}` ∈ `image`, `video`, `audio`, `document`, `font`, `model3d` (selon l'API — EventAPI
+expose les 6, CommunityAPI 4, CustomerAPI 3).
+
+Dans la suite, `{base}` = la base CRUD typée (ex. `{eventId}/image-asset`).
+
+---
+
+## 3. Créer un asset (upload + création)
+
+### Étape 1 — Téléverser le fichier (flux temporaire)
+
+Les endpoints d'upload sont disponibles sous la base de l'asset :
+
+```
+POST {base}/file               { "type": "image/png", "name": "logo.png" }   → objet d'accès temporaire
+   (puis PUT des octets sur url+container+blobName+sas — voir section file-fields §2)
+POST {base}/file/renew         { "blobName": "...", "sas": "..." }            → renouvellement
+POST {base}/file/try-renew     { "blobName": "...", "sas": "..." }            → renouvellement si expiré
+POST {base}/file/finalize-tmp  { "blobName": "...", "sas": "..." }            → 200
+```
+
+Répéter pour la miniature si on en fournit une.
+
+### Étape 2 — Créer l'asset en référençant les blobs temporaires
+
+```
+POST {base}
+Content-Type: application/json
+
+{
+  "title": "Logo principal",
+  "file": "<blobName_du_fichier>",        // nom du blob temporaire (obligatoire)
+  "thumbnail": "<blobName_miniature>",     // optionnel
+  "folderId": "3fa85f64-....",             // optionnel
+  "applicationScope": "...",
+  "applicationScopeId": "..."
+}
+```
+
+Réponse `200` — l'asset créé (voir forme §1). L'API transfère le blob temporaire vers son
+emplacement définitif et remplit `file` / `thumbnail` avec l'objet fichier résultant.
+
+---
+
+## 4. Rechercher / compter
+
+```
+POST {base}/query
+{
+  "applicationScope": "...",
+  "applicationScopeId": "...",     // optionnel
+  "folderId": "3fa85f64-....",     // optionnel — la présence de la clé active le filtre par dossier
+  "id": "....",                    // optionnel — un asset précis
+  "search": "logo",                // optionnel — recherche dans le titre
+  "fileUrl": "...",                // optionnel — recherche par URL de fichier
+  "page": { "index": 0, "size": 20 },   // ou { "skip": 0, "take": 20 }
+  "orders": [ { "desc": true, "value": { "createdAt": {} } } ]
+}
+→ 200  liste paginée d'assets
+```
+
+```
+POST {base}/count      (même corps)   → 200  <nombre entier>
+```
+
+Le filtrage inclut toujours le scope de l'application et le type de la route.
+
+> Pour lister **tous types confondus**, utiliser la base recherche `{scopeId}/asset/query`.
+
+---
+
+## 5. Modifier / supprimer / déplacer
+
+```
+POST {base}/{assetId}          (édition partielle)
+```
+- Champs absents = inchangés. `file`/`thumbnail` optionnels (omettre = conserver).
+- `thumbnail` **présent mais vide** = supprime la miniature.
+- `folderId`/`title` mis à jour seulement si présents dans le corps.
+
+```
+POST {base}/delete/{assetId}                             → 200
+POST {base}/delete       { "assetIds": ["...", "..."] }  → 200  (suppression en masse)
+POST {base}/movetofolder { "assetIds": ["..."], "folderId": "..." }   → 200
+```
+
+La suppression retire aussi les fichiers (principal + miniature + cache).
+
+---
+
+## 6. Dossiers d'assets
+
+Un dossier a la forme `{ name, parentFolderId?, assetType }` et est hiérarchique.
+
+- **Le CRUD des dossiers passe par les endpoints d'entité génériques** (pas par les routes
+  d'assets) : création / recherche / suppression standard sur `{scopeId}/{folderEntity}`
+  (ex. `{eventId}/eventassetfolder`, `{communityId}/communityassetfolder`,
+  `{customerId}/audience/{tenantId}/authtenantassetfolder`).
+- **Route spécifique** — supprimer un dossier en **conservant** son contenu (sous-dossiers/assets) :
+  ```
+  POST {scopeId}/{folderEntity}/delete/{folderId}/keepSubContent
+  ```
+- **Contrainte** : le dossier ciblé lors d'une création/déplacement doit exister et avoir le
+  **même type** que l'asset, sinon `400` (« Folder type does not match asset type »).
+
+---
+
+## 7. Référencer un asset depuis un contenu (`inwinkasset://`)
+
+Pour lier un asset à un autre contenu (typiquement le contenu d'un ContentTemplate / page
+builder), on **stocke une chaîne de référence** dans le champ concerné :
+
+```
+inwinkasset://{assetId}                  // asset du scope courant
+inwinkasset://{assetId}/{shardId}        // asset d'un autre tenant (cross-tenant)
+```
+
+**Ne pas** y écrire un objet fichier ni une URL directe : juste la chaîne `inwinkasset://{id}`.
+
+À la lecture du contenu, l'API remplace automatiquement chaque référence par **l'objet asset
+complet** (`{ id, tenantId, title, assetType, thumbnail, file, applicationScope, validFrom }`).
+Les références **non résolvables sont retirées** de la sortie. Lors d'une copie d'événement,
+les références sont remappées vers les nouveaux identifiants.
+
+---
+
+## 8. Livraison publique (lecture anonyme)
+
+Le binaire d'un asset est servi et redimensionné en accès public :
+
+```
+GET event/{eventId}/asset/{assetId}/file[/{language}/{fileName}]
+GET event/{eventId}/asset/{assetId}/thumbnail[/{language}/{fileName}]
+   (préfixes équivalents : tenant/{tenantId}/..., community/{communityId}/...)
+```
+
+Paramètres de requête (optionnels) : `mw` (largeur max), `mh` (hauteur max), `q` (qualité),
+`b` (flou), `o` (format de sortie), `nocache`. Les images sont redimensionnées à la volée
+(cache 30 jours + ETag). Les fichiers non-image sont streamés ou **redirigés (302)** vers le CDN.
+
+---
+
+## 9. Exemples
+
+- **Recherche** :
+  ```
+  POST {eventId}/image-asset/query
+  { "orders": [ { "desc": true, "value": { "createdAt": {} } } ] }
+  → 200  liste d'assets
+  ```
+- **Recherche par dossier** : ajouter `"folderId": "<guid>"` au corps.
+- **Création** (après upload du fichier temporaire) :
+  ```
+  POST {eventId}/image-asset
+  { "title": "Bannière", "file": "<blobName>", "applicationScope": "...", "applicationScopeId": "..." }
+  → 200  asset créé
+  ```
+- **Téléchargement public** : `GET event/{eventId}/asset/{assetId}/file` → `200` (image) ou
+  `302` (redirection, ex. vidéo).
+- **Suppression de dossier en conservant le contenu** :
+  `POST {eventId}/eventassetfolder/delete/{folderId}/keepSubContent`.
+
+---
+
+## 10. Points d'attention
+
+- **Pas de contrôle du MIME par type d'asset** à la création : l'API vérifie seulement que le
+  contenu correspond à son MIME déclaré (parmi les MIME supportés), pas qu'il correspond au
+  type de la route. Le type d'asset ne change que l'emplacement de stockage et le rendu public
+  (seules les images sont redimensionnées ; les autres sont streamées/redirigées).
+- **Busting de cache** : à chaque changement de fichier, un nouvel emplacement est généré,
+  donc l'URL du fichier change — ne pas mettre en cache un objet fichier d'asset au-delà d'une édition.
+- **`title`** peut être localisé (objet multi-langues).
+- **`file` obligatoire à la création**, `thumbnail` optionnel ; à l'édition les deux sont optionnels.
+
+---
+
+*Voir aussi : `file-fields` (détail du flux d'upload temporaire réutilisé ici), `mutations`, `entities`.*

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

@@ -1,189 +1,313 @@
 ◂ Retour à [README](./README.md)
+# InWink APIs — Champs de type fichier (guide d'utilisation de l'API)
+
+> **But.** Décrire comment **envoyer**, **lire**, **remplacer** et **supprimer** un fichier
+> porté par un champ d'entité, via les APIs d'administration InWink (EventAPI / CommunityAPI /
+> CustomerAPI). Tout est décrit au niveau HTTP : verbe + route + corps JSON + réponse JSON.
+>
+> Auth : jeton porteur (Bearer) avec les claims du scope. La FrontAPI publique (participant,
+> anonyme) a des routes différentes et n'est pas couverte (note en fin de document).
+>
+> Convention JSON : les corps de requête sont acceptés en casse insensible ; les réponses
+> sont en `camelCase`. Les exemples ci-dessous utilisent `camelCase`.
 
-# Manipuler les fichiers d'entites (champs de type `file`)
+---
 
-## Regle d'architecture
+## 1. Principe (à lire en premier)
 
-Une extension backoffice ne doit pas appeler le serveur MCP en runtime depuis le navigateur. Le MCP sert uniquement a Claude Code / l'assistant IA pour decouvrir les endpoints et les schemas pendant le developpement. Le code final de l'extension doit appeler directement les APIs inwink avec le Bearer token utilisateur.
+Un « champ de type fichier » est un champ d'entité (ex. `prop3` sur `person`,
+`videofile` sur `vod`, `audiofile` sur `podcast`…) dont le type déclaré dans le template
+est l'un de :
 
-Workflow a suivre pendant la generation du code :
+| Type de champ | Effet |
+|---------------|-------|
+| `file` | fichier générique (document, etc.) |
+| `image` | image (miniatures générées automatiquement) |
+| `filevideo` | vidéo (encodage + transcripts déclenchés) |
 
-1. Utiliser `inwink_mcp_get_entity_description` pour identifier le champ de type `file` et sa forme exacte.
-2. Utiliser `inwink_mcp_find_api_endpoint` pour trouver l'endpoint d'upload ou de renouvellement SAS adapte au type de fichier.
-3. Generer dans l'extension des appels directs aux APIs inwink, jamais des appels au MCP.
+**La valeur du champ change de forme selon le sens :**
 
----
+- **En écriture** : une simple **chaîne = le nom du blob temporaire** (`blobName`) obtenu à
+  l'étape d'upload.
+- **En lecture** : un **objet fichier** JSON complet
+  (`{ blobName, container, url, fileName, mimeType, size, ... }`).
+
+**L'upload suit un pattern « lien d'upload direct » en 4 temps.** L'API n'est jamais dans le
+chemin des octets : elle délivre une URL d'upload signée (SAS), et **le client envoie les
+octets directement sur le stockage**.
+
+```
+1. POST .../file            → l'API crée un emplacement temporaire, renvoie une URL signée
+2. PUT des octets            → le client téléverse directement sur l'URL signée
+3. POST .../file/finalize-tmp → l'API valide et fige le fichier temporaire
+4. PATCH/PUT de l'entité      → on met la valeur du champ = nom du blob ; l'API le déplace
+                                vers son emplacement définitif et réécrit la valeur en objet fichier
+```
+
+> ⚠️ **Point crucial** : il n'existe **aucun endpoint « attacher un fichier »**. On référence
+> le nom du blob temporaire dans le champ, puis **on sauvegarde l'entité via son endpoint
+> d'édition habituel**. C'est cette sauvegarde qui matérialise le fichier.
 
-## Lire ou telecharger un fichier prive
+### Forme des routes
 
-### Problème
+Le point d'entrée fichier d'une entité est `{scopeId}/{entity}/file`. Exemples :
+`{eventId}/person/file`, `{eventId}/session/file`, `{communityId}/vod/file`.
 
-Les champs de type `file` retournés par l'API inwink (par exemple `url` dans `ExhibitorTaskAnswer`, `photo` dans `Person`, etc.) contiennent une URL Azure Blob Storage directe (ex. `https://[account].blob.core.windows.net/[container]/[path]`). Ces blobs sont **privés** : ils nécessitent une authentification Azure StorageSharedKey ou un token SAS signé par la clé du compte de stockage.
+`{scopeId}` selon l'API :
+- EventAPI : `{eventId}`
+- CommunityAPI : `{communityId}`
+- CustomerAPI : `{customerId}/audience/{tenantId}` (ou `{customerId}`)
 
-**Ce qui ne fonctionne pas** : envoyer le token Bearer inwink (`Authorization: Bearer …`) directement sur l'URL du blob. Azure Blob Storage ne reconnaît pas les JWT inwink — il retourne `403 Forbidden`.
+---
 
-### Solution : endpoint `try-renew`
+## 2. Envoyer un fichier dans un champ d'entité (flux complet)
 
-L'API inwink expose des endpoints de renouvellement SAS pour chaque type d'asset. Pour la majorité des fichiers uploadés (PDF, Word, images, ZIP…), utiliser :
+### Étape 1 — Créer l'emplacement temporaire
 
 ```
-POST {eventAPI}/{eventId}/document-asset/file/try-renew
-Authorization: Bearer {inwink_token}
+POST {scopeId}/{entity}/file
 Content-Type: application/json
 
 {
-  "BlobName": "{container}/{path/to/blob}",
-  "Sas": "{existing_sas_query_string_or_empty_string}"
+  "entity": "person",        // nom de l'entité
+  "field": "prop3",          // clé du champ fichier
+  "type": "image/png",       // type MIME du fichier
+  "name": "photo.png",       // nom de fichier
+  "blobType": "Block"        // "Block" (défaut) | "append" | "page"
 }
 ```
 
-- **`BlobName`** : le chemin du blob **sans le hostname ni le `?`**. Correspond à `url.pathname.slice(1)` sur l'URL Azure.
-- **`Sas`** : le query string existant **sans le `?`** (`url.search.slice(1)`), ou `""` si l'URL ne contient pas de SAS.
+Réponse `200` — objet d'accès temporaire :
 
-Le serveur inwink (qui possède la clé du compte de stockage) retourne une **URL signée SAS** fraîche. Cette URL peut ensuite être utilisée **sans aucun header `Authorization`** — le token SAS est intégré dans les query params.
+```json
+{
+  "url": "https://<stockage>.blob.core.windows.net",
+  "container": "tmp",
+  "blobName": "a7f3c1e0-....png",
+  "sas": "?sv=...&sig=..."
+}
+```
 
-### Endpoints disponibles selon le type de fichier
+### Étape 2 — Téléverser les octets directement (hors API)
 
-| Type de fichier | Endpoint |
-|---|---|
-| Documents (PDF, Word, ZIP…) | `/{eventId}/document-asset/file/try-renew` |
-| Images | `/{eventId}/image-asset/file/try-renew` |
-| Vidéos | `/{eventId}/video-asset/file/try-renew` |
-| Audio | `/{eventId}/audio-asset/file/try-renew` |
+Le client construit l'URL cible et **envoie les octets** dessus (droits lecture/écriture sur
+l'emplacement temporaire) :
 
-En cas de doute sur le type, utiliser `document-asset` en premier (fonctionne pour la majorité des uploads exposants).
+```
+PUT {url}/{container}/{blobName}{sas}
+x-ms-blob-type: BlockBlob
+Content-Type: image/png
 
-### Pattern d'implémentation
+<octets du fichier>
+```
 
-```typescript
-async function getSignedFileUrl(absoluteUrl: string, eventId: string): Promise<string> {
-  const parsed = new URL(absoluteUrl);
-  const blobName = parsed.pathname.slice(1); // ex: "events/xxx/file.pdf"
-  const sas = parsed.search ? parsed.search.slice(1) : '';
+Pour un upload long, renouveler le lien signé si besoin :
 
-  try {
-    const result = await inwinkApiService.makeApiCall<any>(
-      `/${eventId}/document-asset/file/try-renew`,
-      { method: 'POST', body: JSON.stringify({ BlobName: blobName, Sas: sas }) }
-    );
-    if (typeof result === 'string' && result.startsWith('http')) return result;
-    if (result?.url) return result.url;
-    if (result?.Url) return result.Url;
-  } catch { /* fallback sur l'URL d'origine */ }
+```
+POST {scopeId}/{entity}/file/renew        { "blobName": "...", "sas": "..." }   → nouvel objet d'accès
+POST {scopeId}/{entity}/file/try-renew    { "blobName": "...", "sas": "..." }   → renouvelé si expiré
+```
 
-  return absoluteUrl;
-}
+### Étape 3 — Finaliser le fichier temporaire
 
-// Puis télécharger SANS header Authorization :
-const signedUrl = await getSignedFileUrl(fileField.url, eventId);
-const response = await fetch(signedUrl); // pas de Bearer token ici
+```
+POST {scopeId}/{entity}/file/finalize-tmp
+{ "blobName": "a7f3c1e0-....png", "sas": "?sv=...&sig=..." }
 ```
 
----
+- `200` : le contenu correspond au type MIME déclaré ; le fichier temporaire est figé.
+- `400` avec corps `101` : le contenu ne correspond pas au MIME annoncé (rejet).
+- `400` avec corps `102` : type de fichier non supporté.
 
-## Uploader puis associer un fichier a une entite
+### Étape 4 — Sauvegarder l'entité en référençant le fichier
 
-L'upload d'un nouveau fichier se fait en deux etapes :
+Via l'**endpoint d'édition habituel de l'entité**, mettre la valeur du champ = le `blobName` :
 
-1. Uploader le binaire sur l'endpoint d'asset approprie (`document-asset`, `image-asset`, `video-asset`, `audio-asset`). L'endpoint exact et le nom du champ multipart doivent etre recuperes avec `inwink_mcp_find_api_endpoint` avant de coder.
-2. Patcher l'entite avec le `BLOBID` retourne par l'upload. Ne pas envoyer le contenu binaire, du base64, ni un objet `{ url: ... }` dans le payload de l'entite sauf si l'endpoint decouvert l'exige explicitement.
+```
+PATCH {scopeId}/person/{personId}
+{ "prop3": "a7f3c1e0-....png" }
+```
 
-Requetes MCP a utiliser avant de generer le code :
+À la sauvegarde, l'API valide (taille, MIME autorisés, cohérence du contenu), **déplace le
+fichier vers son emplacement définitif**, **réécrit la valeur** du champ en objet fichier
+complet, et déclenche les traitements associés (encodage vidéo, miniatures, analyse de document).
 
-```text
-inwink_mcp_find_api_endpoint:
-  targetApi: eventapi
-  shardId: {eventId}
-  query: "upload an image asset file and return the file reference"
+La valeur relue devient par exemple :
 
-inwink_mcp_get_entity_description:
-  targetApi: eventapi
-  shardId: {eventId}
-  query: "person photo file field"
+```json
+{
+  "blobName": "prop3/9f...png",
+  "container": "3fa85f64-...._person-prop3",
+  "url": "https://<stockage>.blob.core.windows.net/...",
+  "fileName": "photo.png",
+  "mimeType": "image/png",
+  "size": 20481,
+  "contentMD5": "..."
+}
 ```
 
-Pattern TypeScript, a adapter aux champs exacts retournes par la discovery :
-
-```typescript
-async function uploadImageAsset(eventId: string, file: File) {
-  const form = new FormData();
-  form.append('file', file, file.name);
-
-  const uploaded = await inwinkApiService.makeApiCall<any>(
-    `/${eventId}/image-asset/file`,
-    {
-      method: 'POST',
-      body: form,
-      // Ne pas forcer Content-Type ici : le navigateur ajoute le boundary multipart/form-data.
-    },
-  );
+---
 
-  // Adapter la lecture ci-dessous a la forme exacte retournee par l'endpoint.
-  return uploaded?.blobId ?? uploaded?.BlobId ?? uploaded?.id ?? uploaded;
-}
+## 3. Lire / télécharger un fichier
 
-async function updatePersonPhoto(eventId: string, personId: string, file: File) {
-  const uploadedBlobId = await uploadImageAsset(eventId, file);
-
-  return inwinkApiService.makeApiCall<any>(
-    `/${eventId}/person/${personId}`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        entity: {
-          // Pour un champ file, l'API attend ici le BLOBID retourne par l'upload.
-          photo: uploadedBlobId,
-        },
-        selects: {
-          $all: true,
-          photo: true,
-        },
-      }),
-    },
-  );
-}
+```
+GET {scopeId}/{entity}/file/{entityId}/{field}?lang=fr&withoutExpiration=false
 ```
 
-Exemple JSON correct pour associer un fichier a une entite :
+Réponse `200` — objet fichier avec lien d'accès :
 
 ```json
 {
-  "entity": {
-    "photo": "BLOBID"
-  },
-  "selects": {
-    "$all": true
-  }
+  "url": "https://<stockage>.blob.core.windows.net",
+  "container": "3fa85f64-...._person-prop3",
+  "blobName": "prop3/9f...png",
+  "fileName": "photo.png",
+  "mimeType": "image/png",
+  "size": 20481,
+  "sas": "?sv=...&sig=...",
+  "lastModified": "2026-07-01T10:00:00Z"
 }
 ```
 
-Exemple a ne pas faire :
+Le client télécharge ensuite les octets directement sur **`url` + `/{container}/{blobName}` + `sas`**.
+
+- `404` si le champ n'a pas de fichier.
+- `lang` : langue pour un champ localisé (défaut = langue par défaut du scope).
+- `withoutExpiration=true` : lien d'accès de longue durée.
+
+**Fichier d'une sous-entité (collection)** :
+```
+GET {scopeId}/{entity}/file/{entityId}/{nestedField}/{index}/{field}?lang=&withoutExpiration=
+```
+
+**Champ vidéo** : la réponse est enrichie (voir §5).
+
+---
+
+## 4. Remplacer / ré-éditer / supprimer un fichier
+
+**Récupérer une copie éditable** du fichier actuel dans l'espace temporaire, puis reprendre
+le flux finalize + save :
+```
+GET {scopeId}/{entity}/file/{entityId}/{field}/copytotmp?lang=fr
+→ 200  { "blobName": "...", "container": "tmp", ... }
+```
+
+**Remplacer** : téléverser un nouveau fichier temporaire (§2) et ré-éditer l'entité avec le
+nouveau `blobName`. L'ancien fichier est automatiquement retiré.
+
+**Supprimer** : éditer l'entité en mettant le champ à `null`.
+
+---
+
+## 5. Champs vidéo — fonctionnalités avancées
+
+Les champs `filevideo` déclenchent un encodage et exposent transcripts et analyse de document.
+Toutes les routes sont sous `{scopeId}/{entity}/file/...`.
+
+### Lecture d'un champ vidéo
+`GET {scopeId}/{entity}/file/{entityId}/{field}` renvoie, quand la vidéo est prête :
 
 ```json
 {
-  "entity": {
-    "photo": {
-      "url": "..."
-    }
-  }
+  "url": "...", "blobName": "...", "container": "...", "fileName": "...",
+  "sas": "?...", "mimeType": "video/mp4", "size": 123456,
+  "token": null,
+  "transcripts": { "fr": { "url": "...", "sas": "?..." } },
+  "transcriptsEnabled": true,
+  "dashEnabled": true,
+  "hlsEnabled": true
 }
 ```
 
-Important : l'URL d'upload ci-dessus est un exemple de pattern. Toujours remplacer par l'endpoint exact retourne par `inwink_mcp_find_api_endpoint`. Selon le type d'asset ou l'API cible, le chemin, le nom du champ multipart ou le DTO de retour peuvent differer.
+### Encodage
+```
+POST {scopeId}/{entity}/file/video/{entityId}/{field}/encoding/retry?lang=fr   → relance l'encodage
+GET  {scopeId}/{entity}/file/{entityId}/{field}/status?lang=fr                 → statut d'encodage
+```
 
-## Remplacer, supprimer ou conserver un fichier existant
+### Transcripts (requiert une licence IA)
+```
+POST {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/enabled         → active le traitement
+GET  {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/status          → { status, progress, duration }
+GET  {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/manifest?language=fr
+POST {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/manifest?language=fr   (corps = manifeste)
+GET  {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/{language}
+POST {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/{language}             (corps = transcript)
+POST {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/{language}/delete       (corps = transcript)
+POST {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/reset/from-artifacts
+GET  {scopeId}/{entity}/file/video/{entityId}/{field}/transcripts/artifacts/{data}        (redirection 302 vers le fichier)
+```
+`status` ∈ `NotSet`, `Pending`/`Processing`, `Ready`. Un `Ready` non enregistré est
+persisté automatiquement au premier appel de `status`/`manifest`/`get`.
 
-- Remplacer un fichier : uploader le nouveau fichier, puis patcher uniquement le champ `file` avec le nouveau `BLOBID`.
-- Supprimer un fichier associe a une entite : patcher le champ avec `null` si le schema le permet.
-- Conserver un fichier existant : ne pas inclure le champ dans le payload de patch. Inclure un champ `file` incomplet peut effacer des metadonnees ou provoquer un `400`.
-- Champs multi-fichiers : si le schema indique une collection, envoyer le tableau complet attendu par l'API, pas seulement le nouvel element.
+### Analyse de document (requiert une licence IA)
+```
+GET  {scopeId}/{entity}/file/document/{entityId}/{field}/analysis         → statut de l'opération
+POST {scopeId}/{entity}/file/document/{entityId}/{field}/analysis/start   → démarre l'analyse
+```
+
+---
 
-## Erreurs frequentes
+## 6. Formes JSON de référence
+
+**Corps de requête**
+- Créer l'emplacement temporaire : `{ entity, field, type, name, blobType }`
+- Renouveler / finaliser : `{ blobName, sas }`
+
+**Réponses**
+- Objet d'accès temporaire (create/renew) : `{ url, container, blobName, sas }`
+- Objet fichier avec lien d'accès (get/download) :
+  `{ url, container, blobName, fileName, size, mimeType, sas, lastModified }`
+- Objet fichier persisté (valeur du champ) :
+  `{ url, container, blobName, fileName, size, mimeType, linkedBlobs, contentMD5, properties }`
+  - Image : ajoute `thumb`, `thumbSmall`, `thumbLarge` (chacun un objet fichier).
+  - Vidéo : ajoute `video { id, isReady, transcriptsEnabled, transcripts, transcriptData }`
+    et `encodings { <provider>: { hlsUrl, dashUrl, status, progress, timestamp } }`.
+
+**Codes d'erreur de transfert** (corps de la réponse `400`) : `101` = fichier invalide
+(contenu ≠ MIME), `102` = type de fichier non supporté.
+
+---
+
+## 7. Exemple de bout en bout
+
+Entité `person`, champ `prop3` de type `file`.
+
+1. Créer l'emplacement temporaire :
+   ```
+   POST {eventId}/person/file
+   { "entity": "person", "field": "prop3", "name": "photo.jpg", "type": "image/jpeg" }
+   → 200  { "blobName": "<blobName>", "container": "tmp", "url": "...", "sas": "..." }
+   ```
+2. Téléverser les octets sur `url + /tmp/<blobName> + sas`.
+3. Finaliser : `POST {eventId}/person/file/finalize-tmp { "blobName": "<blobName>", "sas": "..." }` → `200`.
+4. Éditer la personne : `PATCH {eventId}/person/<personId> { "prop3": "<blobName>" }` → `200`.
+   → le fichier est déplacé de `tmp` vers le conteneur `{eventId}_person-prop3`, et la valeur
+   du champ est relue comme objet fichier complet.
+
+---
+
+## 8. Points d'attention
+
+- **Double validation MIME** : au `finalize-tmp` (contenu vs MIME déclaré) **et** à la
+  sauvegarde de l'entité (taille max, MIME autorisés du champ, cohérence du contenu, sûreté
+  SVG). Un fichier invalide fait échouer/vider le champ.
+- **Emplacement définitif** = conteneur `{scopeId}_{entity}-{field}` (minuscules) — utile
+  pour interpréter les URLs retournées.
+- **Langue** : pour un champ localisé, transmettre `lang` en lecture.
+- **`withoutExpiration=true`** : lien de longue durée (à réserver aux usages qui le justifient).
+- **Remplacement** : ré-uploader et ré-éditer suffit ; l'ancien fichier est nettoyé automatiquement.
+
+---
+
+## Note — FrontAPI (hors périmètre)
+
+Côté public/participant, un flux équivalent existe mais avec des routes et une auth
+différentes : `POST {scopeId}/file` (+ `/renew`, `/try-renew`, `/finalize-tmp`), lecture
+`GET community/{communityId}/file/{Entity}/{entityId}/{field}`, en accès anonyme avec
+contrôles par droits/groupes (peut renvoyer `403` selon l'appartenance).
+
+---
 
-| Symptome | Cause probable | Correction |
-|---|---|---|
-| `403 Forbidden` sur une URL `blob.core.windows.net` | Le Bearer inwink est envoye au blob Azure | Appeler `try-renew`, puis fetch l'URL signee sans header `Authorization` |
-| `401 Unauthorized` sur l'endpoint inwink | Token inwink expire ou absent | Relancer l'auth OIDC de l'extension, puis rejouer l'appel API |
-| `400 Bad Request` au patch de l'entite | Forme du champ `file` incorrecte | Relire `get_entity_description` et utiliser le `BLOBID` retourne par l'upload, pas un objet `{ url: ... }` |
-| CORS ou auth impossible en appelant `/mcp` depuis l'extension | Le MCP n'est pas une API runtime d'extension | Appeler directement les APIs inwink ; reserver le MCP a la generation/discovery |
-| Upload multipart vide ou casse | `Content-Type` force manuellement | Avec `FormData`, ne pas definir `Content-Type`; laisser le navigateur ajouter le boundary |
+*Voir aussi : `assets` (bibliothèque médias — mêmes primitives d'upload, avec identité propre et `inwinkasset://`), `mutations`.*

package/templates/vite-extension/src/hooks/useInwinkApi.ts

@@ -17,6 +17,7 @@ export interface InwinkApi {
   get: <T = unknown>(path: string, init?: RequestInit) => Promise<T>;
   post: <T = unknown>(path: string, body?: unknown, init?: RequestInit) => Promise<T>;
   put: <T = unknown>(path: string, body?: unknown, init?: RequestInit) => Promise<T>;
+  patch: <T = unknown>(path: string, body?: unknown, init?: RequestInit) => Promise<T>;
   del: <T = unknown>(path: string, init?: RequestInit) => Promise<T>;
 }
 
@@ -115,10 +116,11 @@ export function useInwinkApi(baseUrl: string): InwinkApi {
         throw new InwinkApiError(response.status, await safeBody(response));
       }
 
-      if (response.status === 204) {
-        return undefined as T;
-      }
-      return (await response.json()) as T;
+      // Une réponse OK peut ne porter aucun corps : un 204, mais aussi un 200 — les endpoints
+      // d'écriture du template d'entité répondent ainsi. `response.json()` lève sur un corps
+      // vide, d'où la lecture en texte avant de tenter le parse.
+      const text = await response.text();
+      return (text ? (JSON.parse(text) as T) : (undefined as T));
     }
 
     const withBody =
@@ -136,6 +138,7 @@ export function useInwinkApi(baseUrl: string): InwinkApi {
         request<T>(path, { ...init, method: 'GET' }),
       post: withBody('POST'),
       put: withBody('PUT'),
+      patch: withBody('PATCH'),
       del: <T = unknown>(path: string, init?: RequestInit) =>
         request<T>(path, { ...init, method: 'DELETE' }),
     };