@inwink-mcp/backoffice-extension-helpers 1.0.14 → 1.0.16

package/package.json

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

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

@@ -20,6 +20,7 @@ Reference for consuming the inwink APIs from the extension. Calls always go thro
 | 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) |
+| Entities defined by the organizer (custom entities) | [custom-entities.md](./custom-entities.md) |
 | `file` fields (upload / download) | [files.md](./files.md) |
 | Handle `assets` (media library) | [assets.md](./assets.md) |
 

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

@@ -0,0 +1,120 @@
+◂ Back to [README](./README.md)
+
+# Custom entities
+
+Organizers define their **own entities** (custom entities, "objets personnalisés" in the back office):
+job offers, vehicles, parking spots, sponsorship deals… Each one has a key, labels, fields and relations,
+and holds **records**. Users name them in their own words ("my job offers"), never as "custom entities".
+
+They exist on events (`eventapi`), communities (`communityapi`), customers and audiences (`customerapi`).
+On the public website (front API), only **event** custom entities are served.
+
+## Names
+
+| Where | Name | Example |
+|---|---|---|
+| Record routes | `customentity/{key}` | `{eventId}/customentity/joboffer/query` |
+| Relation target, CMS entity kind | `customentity.{key}` | `"target": "customentity.joboffer"` |
+| Definition | `key` | `joboffer` (`^[a-z][a-z0-9_]{1,31}$`, cannot change after creation) |
+
+An unknown key answers `404`. Keys are unique per event / community / customer, not across them.
+
+## Definitions
+
+`{shard}/customentitydefinition` (on an audience: `{customerId}/audience/{tenantId}/authtenantcustomentitydefinition`) — generic routes: `query`, `count`, create (`POST` with `{ "entity": {…} }`),
+update (`POST {id}`), `delete`.
+
+| Field | Role |
+|---|---|
+| `key` | Technical name, fixed after creation |
+| `labels`, `pluralLabels` | Display names per language, e.g. `{ "fr": "Offre d'emploi", "en": "Job offer" }` |
+| `description` | What the entity holds |
+| `icon` | Back-office icon |
+| `status` | `Active` or `Disabled` (hidden from the back-office menu; records stay readable) |
+| `displayLabelPattern` | How a record is named, with merge tags: `{{title}} – {{company}}` |
+| `accessClaimType` | Optional right that replaces the generic custom entity right |
+| `frontAccess` | Website access: `read` (`None` = not on the site, `Anonymous`, `Authenticated`), `write` (owner kinds allowed to write: `Person`, `Exhibitor`…), `publication` (records are published one by one), `visibleToOwnersOf` (relation keys whose target owner can read the records) |
+
+The fields are **not** in the definition: they live in the template of the records (below).
+A definition cannot be deleted while it has records, or while another definition has a relation to it.
+
+## Fields (template)
+
+The fields of a custom entity are a regular entity template, read and written on the record routes:
+
+| Verb | Route | Role |
+|---|---|---|
+| `GET` | `{shard}/customentity/{key}/worktemplate` | Fields, relations and scopes |
+| `PATCH` | `{shard}/customentity/{key}/template` | Partial edit — see [entity-template.md](./entity-template.md) |
+| `POST` | `{shard}/customentity/{key}/updateentitytemplate` | Full replacement |
+
+All field types work, files and images included. **Relation** fields (type `Relation`, 51) link a record to
+another entity:
+
+```json
+{
+  "key": "company",
+  "type": "Relation",
+  "labels": { "fr": "Exposant", "en": "Exhibitor" },
+  "relation": {
+    "target": "Exhibitor",
+    "cardinality": "ManyToOne",
+    "inverseKey": "jobOffers",
+    "inverseLabels": { "fr": "Offres d'emploi", "en": "Job offers" },
+    "isOwner": true
+  }
+}
+```
+
+- `target`: a native entity of the same container (`Person`, `Exhibitor`, `Session`, `Room`, `Member`…) or
+  `customentity.{key}`.
+- `cardinality`: `ManyToOne`, `OneToOne`, `OneToMany` or `ManyToMany`.
+- `inverseKey`: the field added on the target side (`exhibitor.jobOffers`). It is computed, returned only when
+  selected, and writing it relinks the records.
+- `isOwner`: the target owns the record (at most one per entity, towards `Person`, `Member`, `Exhibitor`,
+  `Company` or an audience contact). The owner edits its records on the website when `frontAccess.write` allows it.
+
+Field **scopes**: `public` (shown on the website), `own` (the owner sees it), `related`, `private` (back office only).
+
+## Records
+
+`{shard}/customentity/{key}` — the generic entity routes: `query`, `count`, `aggregate`, create, `GET/POST {id}`,
+`delete`, `massupdate`, `massdelete`, `export`, `history/query`, `history/removed/query|count`, `file`.
+
+Technical fields: `id`, `externalId` (≤ 200 characters, unique per entity), `status` (`0` draft, `1` published —
+meaningful when `frontAccess.publication` is on), `creationDate`, `validFrom`.
+
+Relations are returned as `{ "id": "…" }` and loaded only when selected:
+
+```json
+{ "selects": { "$all": true, "company": { "$all": true } } }
+```
+
+Filter on a to-one relation directly (`{ "owner": { "id": "…" } }`), on a to-many relation with `$any` / `$all` (see [query-language.md](./query-language.md)). Write a relation with `{ "id": "…" }`
+(single) or `[{ "id": "…" }]` (many).
+
+**Upsert by external id** — create or update in one call:
+
+```
+POST {shard}/customentity/{key}/upsert
+{ "externalId": "OFFER-042", "entity": { "title": "Data engineer", "company": { "id": "…" } } }
+```
+
+## Website (front API, events only)
+
+| Route | Role |
+|---|---|
+| `GET {eventId}/customentitydefinition` | Active definitions |
+| `POST {eventId}/customentity/{key}/query`, `count`, `GET {id}` | Public fields; published records only when publication is on |
+| `GET {eventId}/customentity/{key}/worktemplate` | Public template |
+| `{eventId}/customentity/{key}/me/…` | The connected person's own records (`query`, create, update, delete, `worktemplate`) |
+| `{eventId}/customentity/{key}/related/{relationKey}/…` | Records received through a relation (read only) |
+| `GET …/me/{id}/file/{field}`, `GET …/related/{relationKey}/{id}/file/{field}` | Temporary link to a private file (own or received records only) |
+
+`read: None` answers `404`; `Authenticated` answers `401` to visitors.
+
+---
+
+*See also: [entities.md](./entities.md), [entity-template.md](./entity-template.md), [query.md](./query.md), [query-language.md](./query-language.md).*
+
+The key and the fields of a custom entity are discovered with `inwink_mcp_get_entity_description` and the shardId (`customEntities.matches`).

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

@@ -11,6 +11,7 @@
 - **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).
+- **Custom Entity** — an entity defined by the organizer (job offers, vehicles…), on events, communities, customers and audiences. Its records use the name `customentity/{key}` in the routes (`{shardId}/customentity/joboffer/query`) and its fields are in its own template. Users name it in their own words. See [custom-entities.md](./custom-entities.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).
 
@@ -28,6 +29,7 @@
 | 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) |
+| Upsert (custom entity) | `POST {api}/{shardId}/customentity/{key}/upsert` | Create or update a record by its `externalId` — see [custom-entities.md](./custom-entities.md) |
 | Export | | Returns entities as an Excel file |
 | File | | File upload — see [files.md](./files.md) |