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

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

@@ -0,0 +1,238 @@
+◂ Back to [README](./README.md)
+
+# Endpoint `aggregate` — native GROUP BY
+
+Generic endpoint to **group and aggregate** inwink entities, pushed down to SQL (`GROUP BY`).
+
+## Principle
+
+- **Route**: `POST <entity-route>/aggregate` (same base as `query`/`count`, e.g. `…/person/aggregate`,
+  `…/order/aggregate`). Available on every entity that exposes `query`.
+- **Body**: a JSON object (`ExpressionEntityAggregateModel`). Response: `{ data, count, totalGroups }`.
+- The computation is **pushed down to SQL** (`GROUP BY`); global filters and rights/scopes are applied automatically.
+- `filters` use the same language as `query`. However, **`groupBy` keys and aggregate values are more
+  restrictive** than the fields accepted elsewhere: see "Referencing a field" below before grouping on
+  anything other than a field of the entity itself.
+
+## Payload structure
+
+```jsonc
+{
+  "filters":   { /* MongoDB-like predicate, optional, applied BEFORE grouping (WHERE) */ },
+  "groupBy":   [ /* 0..N grouping keys (empty or absent = global aggregate, a single row) */ ],
+  "aggregates":[ /* 1..N aggregated values per group (required) */ ],
+  "having":    [ /* 0..N filters AFTER grouping (HAVING), optional */ ],
+  "orders":    [ /* 0..N sorts, optional */ ],
+  "limit":     100   /* required, positive integer, capped (default 1000) */
+}
+```
+
+### `filters`
+Same syntax as `query`: `{ "field": { "$eq": value } }`. Applied before grouping.
+The operator list in [query-language.md](./query-language.md#filters) is authoritative: refer to it rather than guessing a name; an
+operator outside that list returns 400.
+
+### `groupBy[]` — grouping keys
+```jsonc
+{
+  "name":  "month",                       // output name of the column (result key)
+  "value": { "registrationDate": {} },    // field reference (see "Referencing a field")
+  "dateTrunc": "month",                   // optional: truncates a DATE (year|quarter|month|week|day|hour)
+  "bucketSize": 100                        // optional: buckets a NUMERIC (exclusive with dateTrunc)
+}
+```
+- `dateTrunc`: `year`, `quarter`, `month`, `week` (Monday), `day`, `hour`. The returned key is the truncated date (start of the bucket).
+- `bucketSize`: for a numeric field, key = lower bound `floor(value / size) * size`.
+- `dateTrunc` and `bucketSize` are **mutually exclusive**.
+- A key can be a **multi-valued** field (multiselectlist/multiselecttree): the array is **denormalized**
+  (an entity `["a","b"]` counts in group `a` AND group `b`). **At most 3** multi-valued keys (Cartesian product).
+
+### `aggregates[]` — aggregation functions
+```jsonc
+{ "name": "total",    "op": "count" }                          // count(*): no "value"
+{ "name": "distinct", "op": "countDistinct", "value": { "company": {} } }
+{ "name": "sumHt",    "op": "sum",  "value": { "totalHt": {} } }
+{ "name": "avgHt",    "op": "avg",  "value": { "totalHt": {} } }
+{ "name": "minHt",    "op": "min",  "value": { "totalHt": {} } }
+{ "name": "maxDate",  "op": "max",  "value": { "registrationDate": {} } }
+{ "name": "stdHt",    "op": "stdDevSamp", "value": { "totalHt": {} } }
+```
+Operations (`op`):
+
+| op | description | field type | output type |
+|---|---|---|---|
+| `count` | number of rows in the group (no `value`) | — | integer |
+| `countDistinct` | number of distinct values | scalar | integer |
+| `sum` | sum | numeric | decimal (nullable) |
+| `avg` | average | numeric | decimal (nullable) |
+| `min` / `max` | min / max | scalar (num/date/text) | field type |
+| `stdDevPop` / `stdDevSamp` | population / sample standard deviation | numeric | double (nullable) |
+| `varPop` / `varSamp` | population / sample variance | numeric | double (nullable) |
+
+> `*Samp` (sample) returns `null` if the group has fewer than 2 values.
+
+### `having[]` — post-grouping filters (SQL HAVING)
+```jsonc
+{ "name": "total", "op": "gte", "value": 5 }   // keeps only groups where total >= 5
+```
+- `op`: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`.
+- `name` references an output name (`groupBy` key OR aggregate). Multiple entries = **AND**.
+- Prefer `filters` (before grouping) when filtering on a field value; reserve `having` for **aggregates**.
+
+### `orders[]`
+```jsonc
+{ "name": "total", "desc": true }   // name = output name of a key or an aggregate
+```
+A deterministic secondary sort on the keys is added automatically (reproducible paging).
+
+### `limit`
+Required, integer > 0, capped by `AggregateMaxGroups` (default 1000). Exceeding it → 400.
+
+## Referencing a field (`value`)
+Syntax: `{ "<fieldName>": {} }`. A navigation is written by nesting: `{ "member": { "lastname": {} } }`.
+- Works for **static** fields (entity properties) **and dynamic** fields (stored as JSON); case-insensitive.
+- For a `selectlist`/`selecttree` field (single value), the returned key is the stored **option key** (e.g. `v1`), not the label.
+- For a `multiselectlist`/`multiselecttree` field, see the denormalization described in `groupBy`.
+- A **localizable** field (`title`, `description` — object `{ "fr": …, "en": … }`) used as a key returns the
+  label resolved in the default language, **provided it belongs to the root entity**.
+
+### What can be traversed, and what cannot
+
+`aggregate` does not accept every path that `filters` accepts. The table applies to `groupBy[].value`
+and to `aggregates[].value`:
+
+| Key | Example | Result |
+|---|---|---|
+| Entity field, scalar | `{ "pinned": {} }` | ✅ |
+| Entity field, localizable | `{ "title": {} }` | ✅ resolved label |
+| **to-one** relation + scalar field | `{ "forum": { "status": {} } }` | ✅ |
+| **to-one** relation + **localizable** field | `{ "forum": { "title": {} } }` | ❌ 400 |
+| **to-many** relation (scalar or localizable) | `{ "categorySubjects": { "id": {} } }` | ❌ 400 |
+
+Both failing cases return the same message, which **names the last segment of the path** (`property
+resolution error for title`) even though the field does exist on the related entity: it is the **traversal**
+that is rejected, not the field. Do not go looking for another field name, and do not retry the same path in dot
+notation (`"forum.title"`) — the two forms are strictly equivalent on the server side.
+
+**Working around a to-many relation:** there is no native `groupBy`. Two options, both server-side:
+- one `count` per value, with the `$any` quantifier in `filters` (see [query-language.md](./query-language.md#collection-operators)):
+  `{ "categorySubjects": { "$any": { "title": { "$eq": "Archived" } } } }`;
+- or `query` requesting the relation in `selects`, then grouping client-side.
+
+**Working around a to-one localizable field:** group on the foreign key (`{ "forumId": {} }`) then resolve
+the labels with an `query` on the related entity.
+
+## Response
+```jsonc
+{
+  "data": [ { "<key1>": …, "<key2>": …, "<agg1>": …, "<agg2>": … }, … ],
+  "count": 2,         // number of rows returned (after limit)
+  "totalGroups": 2    // total number of distinct groups (independent of limit)
+}
+```
+- **Global aggregate** (no `groupBy`) → a single row. On an empty set → one row `{ count: 0, … : null }`.
+
+## Constraints / errors (400)
+- `sum`/`avg`/`var*`/`stdDev*` require a **numeric** field.
+- A multi-valued field is allowed as a **key** (denormalized) but **not** as an aggregate value.
+- At most **3** multi-valued keys.
+- `limit` required and ≤ cap.
+- Field not found, inconsistent op×type, `dateTrunc` on a non-date, `bucketSize` on a non-numeric → 400 with message.
+- **Not supported**: a key traversing a **to-many** relation, or a **localizable** field reached through
+  a relation (see "What can be traversed") → 400 `property resolution error for <last segment>`.
+- **Not supported**: median / percentiles (limitation of the SQL `GROUP BY` translation).
+
+## Examples
+
+### 1. Registrations per month (date bucket) + average, filtered
+```json
+{
+  "filters": { "registrationStatus": { "$eq": "registered" } },
+  "groupBy": [ { "name": "month", "value": { "registrationDate": {} }, "dateTrunc": "month" } ],
+  "aggregates": [
+    { "name": "total", "op": "count" },
+    { "name": "avgScore", "op": "avg", "value": { "score": {} } }
+  ],
+  "orders": [ { "name": "month", "desc": false } ],
+  "limit": 100
+}
+```
+
+### 2. Facets: values of a multi-select field + count
+```json
+{
+  "filters": { "country": { "$eq": "FR" } },
+  "groupBy": [ { "name": "choice", "value": { "testselect": {} } } ],
+  "aggregates": [ { "name": "total", "op": "count" } ],
+  "orders": [ { "name": "total", "desc": true } ],
+  "limit": 100
+}
+```
+
+### 3. Cross-tab: country × month
+```json
+{
+  "groupBy": [
+    { "name": "country", "value": { "country": {} } },
+    { "name": "month",   "value": { "registrationDate": {} }, "dateTrunc": "month" }
+  ],
+  "aggregates": [ { "name": "total", "op": "count" } ],
+  "limit": 500
+}
+```
+
+### 4. Amount ranges (numeric bucket) with HAVING
+```json
+{
+  "groupBy": [ { "name": "bucket", "value": { "totalHt": {} }, "bucketSize": 100 } ],
+  "aggregates": [
+    { "name": "nbOrders", "op": "count" },
+    { "name": "sumHt", "op": "sum", "value": { "totalHt": {} } }
+  ],
+  "having": [ { "name": "nbOrders", "op": "gte", "value": 5 } ],
+  "orders": [ { "name": "bucket", "desc": false } ],
+  "limit": 100
+}
+```
+
+### 5. Global statistics (no grouping)
+```json
+{
+  "aggregates": [
+    { "name": "count",  "op": "count" },
+    { "name": "avgHt",  "op": "avg", "value": { "totalHt": {} } },
+    { "name": "minHt",  "op": "min", "value": { "totalHt": {} } },
+    { "name": "maxHt",  "op": "max", "value": { "totalHt": {} } },
+    { "name": "stdHt",  "op": "stdDevSamp", "value": { "totalHt": {} } }
+  ],
+  "limit": 1
+}
+```
+
+### 6. Distinct + sort by aggregate
+```json
+{
+  "groupBy": [ { "name": "country", "value": { "country": {} } } ],
+  "aggregates": [
+    { "name": "members", "op": "count" },
+    { "name": "companies", "op": "countDistinct", "value": { "company": {} } }
+  ],
+  "orders": [ { "name": "members", "desc": true } ],
+  "limit": 50
+}
+```
+
+### 7. Grouping on a to-one relation
+```json
+{
+  "groupBy": [ { "name": "author", "value": { "member": { "lastname": {} } } } ],
+  "aggregates": [ { "name": "n", "op": "count" } ],
+  "orders": [ { "name": "n", "desc": true } ],
+  "limit": 50
+}
+```
+The `null` group gathers the entities whose relation is empty.
+
+---
+
+*See also: [query-language.md](./query-language.md) (WHERE predicates, sorting), [entities.md](./entities.md).*

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

@@ -1,236 +1,236 @@
-◂ Retour à [README](./README.md)
+◂ Back to [README](./README.md)
 
-# InWink APIs — Assets (guide d'utilisation de l'API)
+# InWink APIs — Assets (API usage guide)
 
-> **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.
+> **Purpose.** Describe how to **create**, **search**, **update**, **delete**, **organize**
+> and **reference** assets through the InWink admin APIs (EventAPI / CommunityAPI /
+> CustomerAPI). Everything is described at the HTTP level: verb + route + JSON body + JSON response.
 >
-> 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é.
+> Auth: Bearer token with the `{scope}asset` claim (value `read` for reads,
+> `edit` for writes). The file upload flow reuses the one described in
+> [files.md](./files.md) — refer to it for details on the signed upload link.
 >
-> Convention JSON : corps de requête acceptés en casse insensible ; réponses en `camelCase`.
+> JSON convention: request bodies are accepted case-insensitively; responses are in `camelCase`.
 
 ---
 
-## 1. Principe (à lire en premier)
+## 1. Principle (read first)
 
-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://`.
+An **asset** is a media library entry, scoped to an event, a community or
+a tenant. Unlike a plain file field, an asset has its own identity, a title,
+a type, a thumbnail, can be placed in a folder and **referenced by other content**
+through the `inwinkasset://` scheme.
 
-**Forme d'un asset (en lecture)** :
+**Shape of an asset (on read)**:
 
 ```json
 {
   "id": "3fa85f64-....",
-  "title": "Logo principal",          // localisable (peut être un objet multi-langues)
-  "assetType": 0,                       // voir table ci-dessous
+  "title": "Main logo",          // localizable (can be a multi-language object)
+  "assetType": 0,                       // see table below
   "file": { "blobName": "...", "container": "...", "url": "...", "mimeType": "...", "size": 123 },
-  "thumbnail": { ... },                 // objet fichier ou null
-  "folderId": "....",                   // ou null
+  "thumbnail": { ... },                 // file object or null
+  "folderId": "....",                   // or 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.
+**Asset types (`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, …).
+> ⚠️ **The asset type is never in the request body**: it is determined by the
+> **typed route** you POST to (`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.
+The `file` and `thumbnail` fields are populated by the **same temporary upload flow** as
+file fields (see [files.md](./files.md)): you pass the **temporary blob name** at
+creation, and the API moves it and then serializes it as a file object.
 
 ---
 
-## 2. Routes de base par API
+## 2. Base routes per API
 
-| API | Base CRUD typée | Base recherche (tous types) |
+| API | Typed CRUD base | Search base (all 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).
+`{type}` ∈ `image`, `video`, `audio`, `document`, `font`, `model3d` (depending on the API — EventAPI
+exposes all 6, CommunityAPI 4, CustomerAPI 3).
 
-Dans la suite, `{base}` = la base CRUD typée (ex. `{eventId}/image-asset`).
+Below, `{base}` = the typed CRUD base (e.g. `{eventId}/image-asset`).
 
 ---
 
-## 3. Créer un asset (upload + création)
+## 3. Create an asset (upload + creation)
 
-### Étape 1 — Téléverser le fichier (flux temporaire)
+### Step 1 — Upload the file (temporary flow)
 
-Les endpoints d'upload sont disponibles sous la base de l'asset :
+The upload endpoints are available under the asset base:
 
 ```
-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               { "type": "image/png", "name": "logo.png" }   → temporary access object
+   (then PUT the bytes to url+container+blobName+sas — see section file-fields §2)
+POST {base}/file/renew         { "blobName": "...", "sas": "..." }            → renewal
+POST {base}/file/try-renew     { "blobName": "...", "sas": "..." }            → renewal if expired
 POST {base}/file/finalize-tmp  { "blobName": "...", "sas": "..." }            → 200
 ```
 
-Répéter pour la miniature si on en fournit une.
+Repeat for the thumbnail if you provide one.
 
-### Étape 2 — Créer l'asset en référençant les blobs temporaires
+### Step 2 — Create the asset referencing the temporary blobs
 
 ```
 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
+  "title": "Main logo",
+  "file": "<file_blobName>",        // temporary blob name (required)
+  "thumbnail": "<thumbnail_blobName>",     // optional
+  "folderId": "3fa85f64-....",             // optional
   "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.
+Response `200` — the created asset (see shape §1). The API moves the temporary blob to its
+final location and fills `file` / `thumbnail` with the resulting file object.
 
 ---
 
-## 4. Rechercher / compter
+## 4. Search / count
 
 ```
 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 }
+  "applicationScopeId": "...",     // optional
+  "folderId": "3fa85f64-....",     // optional — the presence of the key enables folder filtering
+  "id": "....",                    // optional — a specific asset
+  "search": "logo",                // optional — search in the title
+  "fileUrl": "...",                // optional — search by file URL
+  "page": { "index": 0, "size": 20 },   // or { "skip": 0, "take": 20 }
   "orders": [ { "desc": true, "value": { "createdAt": {} } } ]
 }
-→ 200  liste paginée d'assets
+→ 200  paginated list of assets
 ```
 
 ```
-POST {base}/count      (même corps)   → 200  <nombre entier>
+POST {base}/count      (same body)   → 200  <integer>
 ```
 
-Le filtrage inclut toujours le scope de l'application et le type de la route.
+Filtering always includes the application scope and the route's type.
 
-> Pour lister **tous types confondus**, utiliser la base recherche `{scopeId}/asset/query`.
+> To list **all types combined**, use the search base `{scopeId}/asset/query`.
 
 ---
 
-## 5. Modifier / supprimer / déplacer
+## 5. Update / delete / move
 
 ```
-POST {base}/{assetId}          (édition partielle)
+POST {base}/{assetId}          (partial edit)
 ```
-- 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.
+- Missing fields = unchanged. `file`/`thumbnail` optional (omit = keep).
+- `thumbnail` **present but empty** = removes the thumbnail.
+- `folderId`/`title` updated only if present in the body.
 
 ```
 POST {base}/delete/{assetId}                             → 200
-POST {base}/delete       { "assetIds": ["...", "..."] }  → 200  (suppression en masse)
+POST {base}/delete       { "assetIds": ["...", "..."] }  → 200  (bulk delete)
 POST {base}/movetofolder { "assetIds": ["..."], "folderId": "..." }   → 200
 ```
 
-La suppression retire aussi les fichiers (principal + miniature + cache).
+Deletion also removes the files (main + thumbnail + cache).
 
 ---
 
-## 6. Dossiers d'assets
+## 6. Asset folders
 
-Un dossier a la forme `{ name, parentFolderId?, assetType }` et est hiérarchique.
+A folder has the shape `{ name, parentFolderId?, assetType }` and is hierarchical.
 
-- **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`,
+- **Folder CRUD goes through the generic entity endpoints** (not through the asset
+  routes): standard create / search / delete on `{scopeId}/{folderEntity}`
+  (e.g. `{eventId}/eventassetfolder`, `{communityId}/communityassetfolder`,
   `{customerId}/audience/{tenantId}/authtenantassetfolder`).
-- **Route spécifique** — supprimer un dossier en **conservant** son contenu (sous-dossiers/assets) :
+- **Specific route** — delete a folder while **keeping** its content (subfolders/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 »).
+- **Constraint**: the folder targeted during a create/move must exist and have the
+  **same type** as the asset, otherwise `400` ("Folder type does not match asset type").
 
 ---
 
-## 7. Référencer un asset depuis un contenu (`inwinkasset://`)
+## 7. Reference an asset from content (`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é :
+To link an asset to other content (typically the content of a ContentTemplate / page
+builder), you **store a reference string** in the relevant field:
 
 ```
-inwinkasset://{assetId}                  // asset du scope courant
-inwinkasset://{assetId}/{shardId}        // asset d'un autre tenant (cross-tenant)
+inwinkasset://{assetId}                  // asset of the current scope
+inwinkasset://{assetId}/{shardId}        // asset of another tenant (cross-tenant)
 ```
 
-**Ne pas** y écrire un objet fichier ni une URL directe : juste la chaîne `inwinkasset://{id}`.
+**Do not** write a file object or a direct URL there: just the `inwinkasset://{id}` string.
 
-À 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.
+When the content is read, the API automatically replaces each reference with the **full asset
+object** (`{ id, tenantId, title, assetType, thumbnail, file, applicationScope, validFrom }`).
+**Unresolvable references are removed** from the output. When an event is copied,
+references are remapped to the new identifiers.
 
 ---
 
-## 8. Livraison publique (lecture anonyme)
+## 8. Public delivery (anonymous read)
 
-Le binaire d'un asset est servi et redimensionné en accès public :
+An asset's binary is served and resized with public access:
 
 ```
 GET event/{eventId}/asset/{assetId}/file[/{language}/{fileName}]
 GET event/{eventId}/asset/{assetId}/thumbnail[/{language}/{fileName}]
-   (préfixes équivalents : tenant/{tenantId}/..., community/{communityId}/...)
+   (equivalent prefixes: 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.
+Query parameters (optional): `mw` (max width), `mh` (max height), `q` (quality),
+`b` (blur), `o` (output format), `nocache`. Images are resized on the fly
+(30-day cache + ETag). Non-image files are streamed or **redirected (302)** to the CDN.
 
 ---
 
-## 9. Exemples
+## 9. Examples
 
-- **Recherche** :
+- **Search**:
   ```
   POST {eventId}/image-asset/query
   { "orders": [ { "desc": true, "value": { "createdAt": {} } } ] }
-  → 200  liste d'assets
+  → 200  list of assets
   ```
-- **Recherche par dossier** : ajouter `"folderId": "<guid>"` au corps.
-- **Création** (après upload du fichier temporaire) :
+- **Search by folder**: add `"folderId": "<guid>"` to the body.
+- **Creation** (after uploading the temporary file):
   ```
   POST {eventId}/image-asset
-  { "title": "Bannière", "file": "<blobName>", "applicationScope": "...", "applicationScopeId": "..." }
-  → 200  asset créé
+  { "title": "Banner", "file": "<blobName>", "applicationScope": "...", "applicationScopeId": "..." }
+  → 200  created asset
   ```
-- **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** :
+- **Public download**: `GET event/{eventId}/asset/{assetId}/file` → `200` (image) or
+  `302` (redirect, e.g. video).
+- **Folder deletion keeping the content**:
   `POST {eventId}/eventassetfolder/delete/{folderId}/keepSubContent`.
 
 ---
 
-## 10. Points d'attention
+## 10. Caveats
 
-- **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.
+- **No MIME check per asset type** at creation: the API only checks that the
+  content matches its declared MIME (among supported MIMEs), not that it matches the
+  route's type. The asset type only changes the storage location and the public rendering
+  (only images are resized; the others are streamed/redirected).
+- **Cache busting**: on every file change, a new location is generated,
+  so the file URL changes — do not cache an asset file object beyond an edit.
+- **`title`** can be localized (multi-language object).
+- **`file` required at creation**, `thumbnail` optional; on edit both are optional.
 
 ---
 
-*Voir aussi : `file-fields` (détail du flux d'upload temporaire réutilisé ici), `mutations`, `entities`.*
+*See also: [files.md](./files.md) (details of the temporary upload flow reused here), [create.md](./create.md), [entities.md](./entities.md).*

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

@@ -1,4 +1,4 @@
-◂ Retour à [README](./README.md)
+◂ Back to [README](./README.md)
 
 # Create
 
@@ -16,6 +16,6 @@ POST {api}/{shardId}/{entity}
 ```
 
 - `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)).
+- `selects` — optional. Controls which properties are returned on success (see [query-language.md](./query-language.md#projection-selects)).
 
-> Pour créer plusieurs entités efficacement, préférer [import.md](./import.md).
+> To create several entities efficiently, prefer [import.md](./import.md).

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

@@ -1,4 +1,4 @@
-◂ Retour à [README](./README.md)
+◂ Back to [README](./README.md)
 
 # Delete & Massdelete
 
@@ -18,4 +18,6 @@ No body required.
 POST {api}/{shardId}/{entity}/massdelete
 ```
 
-Bulk DELETE like `DELETE … WHERE` in SQL. S'appuie sur un filtre (voir [query-language.md](./query-language.md)).
+Bulk DELETE, like `DELETE … WHERE` in SQL. Relies on a filter (see [query-language.md](./query-language.md#filters)).
+
+> A deleted "With History" entity remains readable through `history/removed/query` (see [history.md](./history.md)).