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

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

@@ -1,68 +1,32 @@
-◂ Retour à [README](./README.md)
+◂ Back to [README](./README.md)
 
-# Entity Contracts, Schemas & Other Endpoints
+# Entity contracts & other endpoints
 
-> Les champs exacts d'une entité se découvrent via `inwink_mcp_get_entity_description`. Les schémas ci-dessous sont indicatifs.
+> The exact fields of an entity are discovered with `inwink_mcp_get_entity_description`: this page lists no schema.
 
-## Other Endpoints
+## Entity contracts
 
-| 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).
+- **Event Entity** — scoped to EventAPI. Always has an `eventId` property. The URL uses `{eventId}` as shardId.
+- **Community Entity** — scoped to CommunityAPI. Always has a `communityId` property. The URL uses `{communityId}` as shardId. Community entities (members, forums, discussion subjects…) are **not** reachable through EventAPI: an event and a community are two separate containers.
+- **Customer Entity** — scoped to CustomerAPI. Always has a `customerId` property. The URL uses `{customerId}` as shardId.
+- **Auth Tenant Entity** — scoped to an **audience** (tenant) of a customer, on CustomerAPI. Its name starts with `authtenant` (`authtenantcommunity`, `authtenantcontact`, `authtenantcompany`, `authtenantmailtemplate`…). The URL takes two segments: `{customerId}/audience/{tenantId}` — see [README.md](./README.md#audience-scoped-entities-customerapi).
+- **Dynamic Entity** — can have custom properties added through the backoffice or the template API. Custom properties declared on the entity's own template (the one `inwink_mcp_get_entity_description` returns) behave exactly like native properties on every endpoint. Some fields are declared by a parent record instead: they resolve only on the routes scoped to that parent record, and fail elsewhere with `400 … property resolution error`, like an unknown name. To declare a custom property from the extension, see [entity-template.md](./entity-template.md).
+- **With Publication Status** — has a `status` property (string, case-insensitive): `Draft`, `Preview`, `Published`, `Canceled`, `Rejected`.
+- **With History** — modifications are tracked in a history table (see [history.md](./history.md)). Read-only properties: `validFrom` (start of validity of the current version = last modification date, UTC), `validTo` (end of validity; on the current table, an "infinity" sentinel value), `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.
+## Other endpoints
 
-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`.
+| Endpoint | Pattern | Purpose |
+|---|---|---|
+| Worktemplate | `GET {api}/{shardId}/{entity}/worktemplate` | Returns the entity template (properties, types, required flags, localization) — see [entity-template.md](./entity-template.md) |
+| Template (patch) | `PATCH {api}/{shardId}/{entity}/template` | Adds/edits/removes **one** custom field without touching the others — see [entity-template.md](./entity-template.md) |
+| Template (replace) | `POST {api}/{shardId}/{entity}/updateentitytemplate` | Replaces the **whole** custom template: whatever is missing from the body is lost — see [entity-template.md](./entity-template.md) |
+| Aggregate | `POST {api}/{shardId}/{entity}/aggregate` | Grouping / aggregation (GROUP BY) — see [aggregate.md](./aggregate.md) |
+| History | `POST {api}/{shardId}/{entity}/history/query` | Past versions (same body as query). Always filter by `id` — see [history.md](./history.md) |
+| Removed | `POST {api}/{shardId}/{entity}/history/removed/query` | Deleted entities (+ `/history/removed/count`) — see [history.md](./history.md) |
+| Massupdate | `POST {api}/{shardId}/{entity}/massupdate` | Bulk EDIT, like `UPDATE … WHERE` in SQL — see [update.md](./update.md) |
+| Massdelete | `POST {api}/{shardId}/{entity}/massdelete` | Bulk DELETE, like `DELETE … WHERE` in SQL — see [delete.md](./delete.md) |
+| Export | | Returns entities as an Excel file |
+| File | | File upload — see [files.md](./files.md) |

package/templates/vite-extension/docs/inwink-api/entity-template.md

@@ -0,0 +1,201 @@
+◂ Back to [README](./README.md)
+
+# Entity template (custom fields)
+
+The **template** of a dynamic entity describes its custom fields: the ones the backoffice
+(or an extension) adds on top of the native columns. Once declared in the
+template, a custom field behaves exactly like a native field on `query`,
+`count`, mutations, export…
+
+Three routes, all scoped by the usual `shardId`:
+
+| Verb | Route | Role |
+|---|---|---|
+| `GET` | `{api}/{shardId}/{entity}/worktemplate` | Read the consolidated template (native + custom) |
+| `PATCH` | `{api}/{shardId}/{entity}/template` | **Partial edit** — touch only the named fields |
+| `POST` | `{api}/{shardId}/{entity}/updateentitytemplate` | **Full replacement** of the custom template |
+
+If the entity is also exposed under a nested route (e.g.
+`{communityId}/forums/{forumId}/subjects/`), the three suffixes exist there too.
+
+> ⚠️ **Writing to the template of a production community or event changes a
+> customer's data model.** To declare a field, use `PATCH`: it is the only one
+> of the two writes that cannot erase custom fields you did not write.
+
+`inwink_mcp_find_api_endpoint` publishes the PATCH body, typed, with the list of accepted
+field types: call it for the exact payload shape. This page covers what it does not
+say — the compared semantics of the three routes, and their blind spots.
+
+---
+
+## PATCH — add / modify / remove a field (preferred)
+
+```
+PATCH {api}/{shardId}/{entity}/template
+```
+
+```json
+{
+  "replaceFields": {
+    "feedbackType": {
+      "type": "selectlist",
+      "labels": { "fr": "Type de retour", "en": "Feedback type" },
+      "valuesList": [
+        { "key": "bug", "labels": { "fr": "Anomalie", "en": "Bug" } },
+        { "key": "idea", "labels": { "fr": "Idée", "en": "Idea" } }
+      ]
+    }
+  },
+  "scopes": { "feedbackType": ["private"] }
+}
+```
+
+The API reads the stored template, applies the patch to it, then writes it back. **Any key not
+mentioned in the patch is left as is** — this is what makes the operation safe without
+having to read the template beforehand.
+
+- `replaceFields` — map `field key → definition`. The entry fully **replaces** the
+  field definition (no property-by-property merge): send the complete
+  field definition, not just the property that changes. A key absent from the template is
+  added to it.
+- `replaceFields: { "myKey": null }` — **removes** the field from the template. Two side effects:
+  its entry in `scopes` remains, and the key is not recorded in `oldKeys`, which the
+  PATCH body does not carry.
+- `scopes` — map `field key → array of scopes`. Each entry **overwrites** the scopes array
+  of that key; a patch cannot remove an entry from `scopes`. A patch that
+  contains only `scopes` is valid: it is used to expose or hide a field, including a
+  native field, without redefining any field.
+- A field added by a patch is placed at the end of `fields`.
+- The dictionary key is authoritative: a `key` property inside the definition is
+  overwritten with it.
+- Response: `200` with no body; `204` if the body is empty.
+
+### What is outside the scope of PATCH
+
+The PATCH body carries only `replaceFields` and `scopes`, and expresses deletion only
+on fields. Three needs therefore require POST:
+
+- **removing an entry from `scopes`** — a patch rewrites it, never removes it;
+- **setting `oldKeys`** — absent from the PATCH body;
+- **resetting a template**, or **enforcing the order of `fields`**.
+
+None of these three needs comes up when declaring a custom field: stay on PATCH.
+
+## POST — replace the whole template
+
+```
+POST {api}/{shardId}/{entity}/updateentitytemplate
+```
+*(`POST {api}/{shardId}/{entity}/template` is a second endpoint, with the same body and the same
+effect.)*
+
+```json
+{
+  "fields": [
+    { "key": "feedbackType", "type": "selectlist", "valuesList": [] }
+  ],
+  "scopes": { "feedbackType": ["private"] },
+  "oldKeys": []
+}
+```
+
+The body **becomes** the stored template: any custom field absent from `fields` is lost, and
+any scope absent from `scopes` along with it. Note that `fields` is here an **array** whose every
+element carries its own `key`, whereas `PATCH` and `GET worktemplate` use a **map**.
+
+Use `POST` only if you own the entire template, or for one
+of the three needs listed above. In particular, **the result of `GET worktemplate` cannot be
+sent back as is**: the shape of `fields` differs and the response contains the native
+fields, which the write rejects.
+
+## GET worktemplate — read
+
+```
+GET {api}/{shardId}/{entity}/worktemplate
+```
+
+```json
+{
+  "fields":  { "mail": { "key": "mail", "type": "Mail" } },
+  "scopes":  { "mail": ["bo"] },
+  "oldKeys": ["id", "eventId", "mail"],
+  "version": "2026-09-21T09:14:22Z"
+}
+```
+
+- `fields` — consolidated map of **native fields + custom fields**, in display shape
+  (`display`, `validation`, `file`…), different from the write shape.
+- `oldKeys` — the keys of the entity's **static** fields (its native columns), in
+  camelCase. This is the list of names already taken: a custom field cannot reuse them.
+- `version` — date of the template's last modification. Neither of the two writes takes
+  this token as input: there is no optimistic concurrency control, hence the value of
+  `PATCH`, whose read-write window stays server-side.
+
+---
+
+## Rejected fields
+
+Some keys or some types cannot be saved as a custom field. By
+default the API **silently ignores them** and responds `200`. To have them reported,
+add the header:
+
+```
+iwk-Validation: strict
+```
+
+The request then responds `400` with, per offending key,
+`errors.<key> = "forbidden field: <reason>"`:
+
+| Reason | Cause |
+|---|---|
+| `MissingKey` | empty key |
+| `StaticField` | the key is a native column of the entity (see `oldKeys`) |
+| `LockedField` | the key is a dynamic field locked by the platform |
+| `DeclaredAsStatic` | you set `isStatic: true` on the field |
+| `DeclaredAsLocked` | you set `isLocked: true` on the field |
+| `UnsupportedType` | `type` missing, unknown, or reserved for the platform |
+
+On `POST`, the rejected field is removed but its entry in `scopes` is kept.
+
+## Field definition
+
+`type` is written by its name (`Text`, `SelectList`, `Bool`…). **The list of types accepted
+for a custom field is the one published by `inwink_mcp_find_api_endpoint`** in the `type`
+enumeration of the PATCH body: the API reads it from its own validator, so it cannot diverge —
+do not copy it from here.
+
+The numeric value is accepted too, and that is the form in which the type may appear
+elsewhere (notably in the output of `inwink_mcp_get_entity_description`): `Text` 1,
+`MultiLineText` 2, `SelectList` 3, `MultiSelectList` 4, `Regex` 5, `Mail` 6, `Date` 7,
+`Number` 8, `Bool` 9, `NullableBool` 10, `File` 11, `Time` 12, `Picture` 13, `Image` 14,
+`FileVideo` 15, `SelectTree` 16, `MultiSelectTree` 17, `NestedEntity` 50, `Object` 95,
+`Document` 113.
+
+Common properties:
+
+- Shared — `isMandatory`, `isLocalizable`, `isPersonalData`, `isTechnical`,
+  `isCollection`, `defaultValue`, `defaultDisplay`.
+- Display, per language — `labels`, `placeholders`, `descriptions`, `remarks`:
+  `{ "fr": "…", "en": "…" }`.
+- `Number` — `min`, `max`, `nbDecimalLimit`. `Regex` — `regex`.
+- `SelectList` / `MultiSelectList` / `*Tree` — `valuesList`, a list of entries
+  `{ "key": "…", "labels": { "fr": "…" }, "valuesList": [] }` (nested `valuesList` for
+  trees), plus `valuesListSort` for display order. On native fields,
+  `GET worktemplate` marks these entries `isSelectable: true`.
+- Files (`File`, `Image`, `FileVideo`, `Document`) — `isPublicFile`, `maxSize`,
+  `mimeTypes`, `aspectRatio`. See [files.md](./files.md) for uploading values.
+
+Do not set `isStatic` or `isLocked`: these flags describe what the platform
+declares itself and cause the field to be rejected.
+
+## scopes
+
+`scopes` maps a field key to an array of scope names, which decides who sees the
+field (`public`, `bo`, `private`, `own`… depending on the API and the entity). These are strings
+interpreted by the entity's configuration, not a closed enumeration: to find out
+which ones are meaningful on a given entity, look at the `scopes` that `GET worktemplate`
+already returns for its fields.
+
+---
+
+*See also: [update.md](./update.md), [entities.md](./entities.md), [files.md](./files.md).*