@inwink-mcp/backoffice-extension-helpers 1.0.10 → 1.0.12

package/package.json

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

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

@@ -60,15 +60,19 @@ Les outils MCP donnent les endpoints/champs **exacts** ; la doc statique dans `d
 
 | 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)`.
 
@@ -100,6 +104,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).
 
@@ -129,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
@@ -231,5 +238,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,82 @@
-# 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.
+> **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.
 
-## Sommaire
+## Contents
 
-| Tâche | Fichier |
+| 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 |

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).*