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

package/package.json

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

package/templates/test-app/src/components/EventApiTester.tsx

@@ -1,54 +1,66 @@
-import { useEffect, useState } from 'react';
-import { FiRefreshCw } from 'react-icons/fi';
+import { FiRefreshCw, FiTrash2 } from 'react-icons/fi';
 import { useInwinkEventApi } from '../hooks/useInwinkEventApi';
+import { useAsync } from '../hooks/useAsync';
+import { useToast } from '../hooks/useToast';
+import { useConfirm } from '../hooks/useConfirm';
+import Spinner from './feedback/Spinner';
+import ErrorState from './feedback/ErrorState';
+import EmptyState from './feedback/EmptyState';
 
-// Composant de test (overlay "test-app") : exerce useInwinkEventApi en lançant
-// l'appel automatiquement au montage. N'est monté que lorsque l'utilisateur est
-// authentifié (cf. HomePage), mais l'appel passe de toute façon par le gate
-// `whenReady` du hook, qui attend la résolution d'auth avant de lire le token.
+// Payload de requête de sessions (cf. docs/inwink-api/query.md).
+const SESSION_QUERY = {
+  selects: { id: true, title: true, status: true, startDate: true, endDate: true },
+  orders: [{ desc: true, value: { validFrom: {} } }],
+  page: { index: 0, size: 50 },
+};
+
+// Composant de test (overlay "test-app") : exerce d'un coup les building blocks
+// useAsync (chargement/erreur/annulation), Spinner/ErrorState/EmptyState,
+// useToast et useConfirm — et force leur compilation dans le build de test.
 export default function EventApiTester() {
   const eventApi = useInwinkEventApi();
-  const [result, setResult] = useState<string>('');
-  const [error, setError] = useState<string>('');
-  const [isLoading, setIsLoading] = useState(false);
+  const toast = useToast();
+  const confirm = useConfirm();
+
+  const { data, error, isLoading, refetch } = useAsync(
+    (signal) =>
+      eventApi.post<{ data?: unknown[] }>(
+        '/dae274d9-e86e-f011-8dca-0022488a3cad/session/query',
+        SESSION_QUERY,
+        { signal },
+      ),
+    [eventApi],
+  );
 
-  async function callEventApi(signal?: { aborted: boolean }) {
-    setError('');
-    setResult('');
-    setIsLoading(true);
-    try {
-      const data = await eventApi.post('/dae274d9-e86e-f011-8dca-0022488a3cad/session/query', {
-        "selects": { "id": true, "title": true, "status": true, "moderators": { "person": { "id": true, "firstname": true, "lastname": true, "company": true, "mail": true } }, "startDate": true, "endDate": true, "room": { "name": true, "id": true }, "speakers": { "id": true, "firstname": true, "lastname": true, "company": true, "mail": true }, "exhibitors": { "id": true, "name": true }, "infos": { "registered": true, "attended": true, "attendedOnsite": true, "attendedOnlineLive": true, "attendedOnlineReplay": true } },
-        "orders": [{ "desc": true, "value": { "validFrom": {} } }],
-        "page": { "index": 0, "size": 200 }
-      });
-      if (!signal?.aborted) setResult(JSON.stringify(data, null, 2));
-    } catch (err) {
-      if (!signal?.aborted) setError(err instanceof Error ? err.message : String(err));
-    } finally {
-      if (!signal?.aborted) setIsLoading(false);
-    }
+  async function handleFakeDelete() {
+    const ok = await confirm({
+      title: 'Action de test',
+      message: 'Confirmer cette action factice ? (aucune suppression réelle)',
+      confirmLabel: 'Confirmer',
+    });
+    if (ok) toast.success('Action confirmée (démo).');
   }
 
-  // Appel automatique au montage ; on ignore le résultat si le composant est
-  // démonté entre-temps (évite un setState sur composant démonté).
-  useEffect(() => {
-    const signal = { aborted: false };
-    void callEventApi(signal);
-    return () => {
-      signal.aborted = true;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+  if (isLoading) return <Spinner label="Appel de l'API Event…" />;
+  if (error) return <ErrorState error={error} onRetry={refetch} />;
+
+  const sessions = data?.data ?? [];
 
   return (
     <section>
-      <button disabled={isLoading} onClick={() => void callEventApi()}>
+      <button onClick={refetch}>
         <FiRefreshCw aria-hidden />
-        {isLoading ? 'Appel en cours…' : "Rappeler l'API Event"}
+        Rappeler l'API Event
+      </button>
+      <button onClick={() => void handleFakeDelete()}>
+        <FiTrash2 aria-hidden />
+        Action de test (confirm + toast)
       </button>
-      {result && <pre>{result}</pre>}
-      {error && <p role="alert">Erreur : {error}</p>}
+      {sessions.length === 0 ? (
+        <EmptyState message="La requête n'a retourné aucune session." />
+      ) : (
+        <pre>{JSON.stringify(data, null, 2)}</pre>
+      )}
     </section>
   );
 }

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

@@ -54,6 +54,22 @@ Avant d'écrire **tout** appel API, utilise les outils MCP inwink pour découvri
 
 **Ne devine jamais une route ou un format de payload.** Le MCP est un outil de développement : l'extension n'appelle jamais le serveur MCP en runtime.
 
+### 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 :
+
+| Tâche | Fichier |
+|-------|---------|
+| 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) |
+| 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) |
+| 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) |
+
 ## Appeler l'API inwink
 
 **N'appelle jamais `fetch` directement.** Utilise les hooks dédiés (`useInwinkEventApi`, `useInwinkCommunityApi`, `useInwinkCustomerApi`). Ils encapsulent l'envoi du Bearer token, le renouvellement automatique sur 401 (`signinSilent` puis rejeu, sinon login interactif) et la gestion d'erreurs (`InwinkApiError`).
@@ -81,10 +97,90 @@ Pour appeler un **hôte externe déclaré** (hors API inwink), utilise le hook g
 Bonnes pratiques :
 - Toujours passer par un hook `useInwink*Api` — jamais de `fetch` direct.
 - Le 401 est géré automatiquement (renouvellement puis reconnexion) ; ne pas le ré-implémenter.
-- Gérer le 429 (rate limiting) avec un backoff exponentiel côté appelant si nécessaire.
+- 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 })`.
 - Ne déclarer dans `permissions.platform` que les scopes réellement utilisés.
 - Déclarer les hôtes externes dans `permissions.externalHosts` (HTTPS uniquement).
 
+## Building blocks fournis
+
+Le squelette inclut des primitives réutilisables. **Réutilise-les** plutôt que de les ré-implémenter :
+
+| Bloc | Import | Rôle |
+|------|--------|------|
+| `useAsync(fn, deps)` | `hooks/useAsync` | Exécute une opération async → `{ data, error, isLoading, refetch }`, avec annulation (`AbortSignal`) et déduplication des réponses obsolètes. Moyen canonique de consommer un `useInwink*Api` dans un composant. |
+| `useInwinkPagedQuery(loadPage, getId)` | `hooks/useInwinkPagedQuery` | Pagination offset-based pour les endpoints `/query` (load more, dédup par id). |
+| `useToast()` | `hooks/useToast` | `toast.success/error/info(message)` — notifications transitoires. |
+| `useConfirm()` | `hooks/useConfirm` | `await confirm({ title, message })` → `boolean`. À utiliser avant toute action destructrice. |
+| `Spinner`, `EmptyState`, `ErrorState` | `components/feedback/*` | États standard de chargement / liste vide / erreur (gère `InwinkApiError`). |
+| `ErrorBoundary` | `components/ErrorBoundary` | Capture les erreurs de **rendu** (déjà monté autour de l'`Outlet`). |
+| `Modal` | `components/Modal` | Boîte modale (overlay, focus trap, Échap) pour des dialogues custom. |
+
+`ToastProvider` et `ConfirmProvider` sont déjà montés dans `main.tsx`.
+
+## Lire le contexte inwink
+
+Le contexte d'exécution (`eventid` / `communityid` / `tenantid`) est extrait de l'URL au chargement, **persisté en sessionStorage** (le callback OIDC nettoie la query string) et exposé via `useInwinkContext()` :
+
+```typescript
+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.
+}
+```
+
+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
+
+**Charger et afficher une liste :**
+
+```tsx
+const eventApi = useInwinkEventApi();
+const { eventId } = useInwinkContext();
+const { data, error, isLoading, refetch } = useAsync(
+  (signal) => eventApi.post<{ data: Session[] }>(`/${eventId}/session/query`, QUERY, { signal }),
+  [eventApi, eventId],
+);
+
+if (isLoading) return <Spinner />;
+if (error) return <ErrorState error={error} onRetry={refetch} />;
+if (!data?.data.length) return <EmptyState message="Aucune session." />;
+return <ul>{data.data.map((s) => <li key={s.id}>{s.title}</li>)}</ul>;
+```
+
+**Créer / modifier puis notifier :**
+
+```tsx
+const toast = useToast();
+async function save(values: Partial<Session>) {
+  try {
+    await eventApi.post(`/${eventId}/session`, { entity: values, selects: { $all: true } });
+    toast.success('Enregistré.');
+  } catch (err) {
+    toast.error(err instanceof InwinkApiError ? `Échec (${err.status}).` : 'Échec.');
+  }
+}
+```
+
+**Action destructrice avec confirmation :**
+
+```tsx
+const confirm = useConfirm();
+const toast = useToast();
+async function remove(id: string) {
+  if (!(await confirm({ title: 'Supprimer ?', message: 'Action irréversible.' }))) return;
+  await eventApi.post(`/${eventId}/session/delete/${id}`);
+  toast.success('Supprimé.');
+}
+```
+
+**Ajouter une page/route :** créer le composant dans `pages/`, puis ajouter une `<Route>` dans `App.tsx` (sous le `Layout`, encadrée par `ProtectedRoute` si l'auth est requise).
+
 ## Règles et contraintes
 
 | Règle | Détail |
@@ -130,3 +226,10 @@ npx @inwink-mcp/backoffice-extension-helpers@latest verify    # vérification de
 - Les appels API passent **toujours** par un hook `useInwink*Api` ; jamais de `fetch` direct dans les composants.
 - Les icônes proviennent de **`react-icons`** (ex. `react-icons/fi`, `react-icons/md`) ; pas de SVG inline ni d'images d'icônes.
 - Le squelette (auth, api, config, structure) est généré par la CLI helper — ne pas le régénérer à la main. Ajouter la logique métier dans `App.tsx` et de nouveaux composants/hooks.
+
+## Consignes opérationnelles pour l'agent IA
+
+> Ces consignes s'appliquent à **tout** assistant IA / outil agentique qui manipule cette extension, quel qu'il soit.
+
+- **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

@@ -0,0 +1,42 @@
+# inwink API Reference
+
+This document explains how to consume inwink APIs. It is intended as a reference for building API calls programmatically.
+
+> **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.
+
+## Sommaire
+
+| Tâche | Fichier |
+|---|---|
+| 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) |
+
+---
+
+## 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.
+
+---
+
+## HTTP Status Codes
+
+| Code | Meaning |
+|---|---|
+| 200 | Success — parse body as JSON |
+| 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 |
+| 503 | Transient infrastructure error — retry later |

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

@@ -0,0 +1,21 @@
+◂ Retour à [README](./README.md)
+
+# Create
+
+```
+POST {api}/{shardId}/{entity}
+```
+
+**Request body:**
+
+```json
+{
+  "entity": { "mail": "user@example.com", "firstname": "John" },
+  "selects": { "$all": true }
+}
+```
+
+- `entity` — **required**. The object to create. Missing required properties cause a 400 error.
+- `selects` — optional. Controls which properties are returned on success (voir [query-language.md](./query-language.md)).
+
+> Pour créer plusieurs entités efficacement, préférer [import.md](./import.md).

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

@@ -0,0 +1,21 @@
+◂ Retour à [README](./README.md)
+
+# Delete & Massdelete
+
+## Delete
+
+```
+POST {api}/{shardId}/{entity}/delete/{entityId}
+```
+
+No body required.
+
+---
+
+## Massdelete
+
+```
+POST {api}/{shardId}/{entity}/massdelete
+```
+
+Bulk DELETE like `DELETE … WHERE` in SQL. S'appuie sur un filtre (voir [query-language.md](./query-language.md)).

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

@@ -0,0 +1,68 @@
+◂ Retour à [README](./README.md)
+
+# Entity Contracts, Schemas & Other Endpoints
+
+> Les champs exacts d'une entité se découvrent via `inwink_mcp_get_entity_description`. Les schémas ci-dessous sont indicatifs.
+
+## Other Endpoints
+
+| Endpoint | Pattern | Purpose |
+|---|---|---|
+| Worktemplate | `GET {api}/{shardId}/{entity}/worktemplate` | Returns the entity template (list of properties, types, required flags, localization info) |
+| History | `POST {api}/{shardId}/{entity}/history/query` | Query past modifications (same body as query). Use sparingly — filter by `id` for performance. |
+| Massupdate | `POST {api}/{shardId}/{entity}/massupdate` | Bulk EDIT like `UPDATE … WHERE` in SQL (voir [update.md](./update.md)) |
+| Massdelete | `POST {api}/{shardId}/{entity}/massdelete` | Bulk DELETE like `DELETE … WHERE` in SQL (voir [delete.md](./delete.md)) |
+| Export | Returns entities as an Excel file | |
+| File | Upload files (voir [files.md](./files.md)) | |
+
+---
+
+## Entity Contracts
+
+### Event Entity
+
+Scoped to EventAPI. Always has an `eventId` property. URL uses `{eventId}` as shardId.
+
+### Customer Entity
+
+Scoped to CustomerAPI. Always has a `customerId` property. URL uses `{customerId}` as shardId.
+
+### Dynamic Entity
+
+Can have custom properties added via backoffice or template API. Custom properties behave identically to built-in properties in all endpoints.
+
+### With Publication Status
+
+Has a `status` property (string, case-insensitive): `Draft`, `Preview`, `Published`, `Canceled`, `Rejected`.
+
+### With History
+
+Tracked modifications. Read-only properties: `validFrom` (last modification date, UTC), `modifiedById` (UUID), `modifiedByDisplayName` (string).
+
+---
+
+## Common Entities & Schemas
+
+### Person (EventAPI)
+
+Contracts: Event entity, Dynamic, With Publication Status, With History.
+
+Key properties: `id` (uuid), `mail`, `firstname`, `lastname`, `company`, `jobTitle`, `preferredLanguage`, `isRegistered` (bool), `hasAttended` (bool), `status`, `registrationDate`, `registrationMode` (enum: BackOffice, Website, OnSite, Order, Invitation, ExhibitorAccount), `checkinDate`, `kinds` (string[]), `badgeRef`, `userId`, `contactId`, `description` (localizable), `photo` (file ref).
+
+Expandable relations: `exhibitor`, `infos`, `roomingInfos`, `exhibitorAccounts`, `orders`, `hotelRoomNights`, `sessions`, `favoriteExhibitors`, `animatedSessions`, `orderItems`, `personScans`, `tasks`, `meetingPersons`, `availabilities`, `agenda`, `activityView`.
+
+### EventDetail (EventAPI)
+
+Contracts: Event entity, With History.
+
+Key properties: `id`, `eventId`, `eventType` (array: Onsite/Online), `configuration`, `agenda`, `previewHost`.
+
+Expandable relations: `sessions`, `exhibitors`.
+
+### Event (CustomerAPI)
+
+Contracts: Customer entity, Dynamic, With History.
+
+Key properties: `id`, `customerId`, `title`, `description` (localizable), `startDate`, `endDate`, `city`, `country`, `eventKey`, `computedUrl`, `status` (Active/Archived/Deleted), `eventType`, `isMaster`, `timeZone`, `parentEventId`, `goalRegistered`, `goalAttendees`, `goalSales`.
+
+Expandable relations: `stat`, `authTenant`, `eventHttpHostAliases`, `websites`.

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

@@ -0,0 +1,189 @@
+◂ Retour à [README](./README.md)
+
+# Manipuler les fichiers d'entites (champs de type `file`)
+
+## Regle d'architecture
+
+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.
+
+Workflow a suivre pendant la generation du code :
+
+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.
+
+---
+
+## Lire ou telecharger un fichier prive
+
+### Problème
+
+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.
+
+**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`
+
+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 :
+
+```
+POST {eventAPI}/{eventId}/document-asset/file/try-renew
+Authorization: Bearer {inwink_token}
+Content-Type: application/json
+
+{
+  "BlobName": "{container}/{path/to/blob}",
+  "Sas": "{existing_sas_query_string_or_empty_string}"
+}
+```
+
+- **`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.
+
+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.
+
+### Endpoints disponibles selon le type de fichier
+
+| 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` |
+
+En cas de doute sur le type, utiliser `document-asset` en premier (fonctionne pour la majorité des uploads exposants).
+
+### Pattern d'implémentation
+
+```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) : '';
+
+  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 */ }
+
+  return absoluteUrl;
+}
+
+// Puis télécharger SANS header Authorization :
+const signedUrl = await getSignedFileUrl(fileField.url, eventId);
+const response = await fetch(signedUrl); // pas de Bearer token ici
+```
+
+---
+
+## Uploader puis associer un fichier a une entite
+
+L'upload d'un nouveau fichier se fait en deux etapes :
+
+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.
+
+Requetes MCP a utiliser avant de generer le code :
+
+```text
+inwink_mcp_find_api_endpoint:
+  targetApi: eventapi
+  shardId: {eventId}
+  query: "upload an image asset file and return the file reference"
+
+inwink_mcp_get_entity_description:
+  targetApi: eventapi
+  shardId: {eventId}
+  query: "person photo file field"
+```
+
+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;
+}
+
+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,
+        },
+      }),
+    },
+  );
+}
+```
+
+Exemple JSON correct pour associer un fichier a une entite :
+
+```json
+{
+  "entity": {
+    "photo": "BLOBID"
+  },
+  "selects": {
+    "$all": true
+  }
+}
+```
+
+Exemple a ne pas faire :
+
+```json
+{
+  "entity": {
+    "photo": {
+      "url": "..."
+    }
+  }
+}
+```
+
+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.
+
+## Remplacer, supprimer ou conserver un fichier existant
+
+- 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.
+
+## Erreurs frequentes
+
+| 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 |

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

@@ -0,0 +1,24 @@
+◂ Retour à [README](./README.md)
+
+# Import (bulk create/update)
+
+```
+POST {api}/{shardId}/{entity}/import
+```
+
+**Request body:**
+
+```json
+{
+  "entities": [
+    { "mail": "user0@mail.com" },
+    { "id": "existing-uuid", "mail": "user1@mail.com" }
+  ],
+  "identifiers": { "mail": {} },
+  "selects": { }
+}
+```
+
+- If an entity includes `id`, it's treated as an **update**.
+- If no `id` is present, the `identifiers` map is used as a unique constraint to determine create vs. update. In the example above, `mail` is used to match existing records.
+- This is much more performant than individual create/edit calls.