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

package/templates/vite-extension/docs/inwink-api/query-language.md

@@ -1,16 +1,16 @@
-◂ Retour à [README](./README.md)
+◂ Back to [README](./README.md)
 
-# inwink JSON Query Language
+# inwink JSON query language
 
 The query language is inspired by MongoDB syntax. Expressions are JSON objects where `$`-prefixed keys are operators and non-prefixed keys are entity property names.
 
-Utilisé par les `filters`, `orders` et `selects` des opérations [query](./query.md), [update](./update.md) (massupdate) et [delete](./delete.md) (massdelete).
+Used by the `filters`, `orders` and `selects` of the [query](./query.md), [update](./update.md) (massupdate), [delete](./delete.md) (massdelete) and [history](./history.md) operations, and by the `filters` of [aggregate](./aggregate.md).
 
-## Predicate Expressions (filters)
+## Filters
 
 ### Comparison operators
 
-| Operator | Aliases | Meaning |
+| Operator | Alias | Meaning |
 |---|---|---|
 | `$eq` | `$equal` | Equals |
 | `$neq` | `$notEqual` | Not equals |
@@ -18,38 +18,53 @@ Utilisé par les `filters`, `orders` et `selects` des opérations [query](./quer
 | `$gte` | `$greaterThanOrEqual` | Greater than or equal |
 | `$lt` | `$lessThan` | Less than |
 | `$lte` | `$lessThanOrEqual` | Less than or equal |
+| `$in` | — | In the list: `{ "p1": { "$in": ["v1", "v2"] } }` |
 
 **Implicit equality:** `{ "p1": "v1" }` is equivalent to `{ "p1": { "$eq": "v1" } }`.
 
+⚠️ **This table is exhaustive: use only these names, exactly as written.** When unsure about a negation, compose with `$not`
+(see "Logical operators") rather than guessing a name.
+
 ### Logical operators
 
 - `$and`: `{ "$and": [ { "p1": "v1" }, { "p2": "v2" } ] }`
 - `$or`: `{ "$or": [ { "p1": "v1" }, { "p2": "v2" } ] }`
 - `$not`: negates a predicate
 
-### Text operators (under `$text` namespace)
+### Text operators (`$text` namespace)
+
+**Predicates** — used directly as a filter:
+
+| Operator | Example | Returns |
+|---|---|---|
+| `$contains` | `{ "title": { "$text": { "$contains": "val" } } }` | true if `title` contains "val" |
+| `$startsWith` | `{ "title": { "$text": { "$startsWith": "val" } } }` | true if `title` starts with "val" |
+| `$endsWith` | `{ "title": { "$text": { "$endsWith": "val" } } }` | true if `title` ends with "val" |
+
+**Value expressions** — not predicates: they return a value (number or string), so they must be compared, and
+fluent chaining does not apply (see "Verbose binary operator syntax"):
 
 | Operator | Example | Returns |
 |---|---|---|
-| `$contains` | `{ "p1": { "$text.$contains": "val" } }` | true if p1 contains "val" |
-| `$startsWith` | `{ "p1": { "$text.$startsWith": "val" } }` | true if p1 starts with "val" |
-| `$endWith` | `{ "p1": { "$text.$endWith": "val" } }` | true if p1 ends with "val" |
-| `$indexOf` | `{ "p1": { "$text.$indexOf": "val" } }` | position of first occurrence, -1 if none |
-| `$substring` | `{ "p1": { "$text.$substring": { "$startIndex": 1, "$length": 3 } } }` | substring extraction |
-| `$length` | `{ "p1": { "$text.$length": {} } }` | length of the string |
+| `$length` | `{ "$gt": { "$left": { "title": { "$text": { "$length": {} } } }, "$right": 60 } }` | length of the string |
+| `$indexOf` | `{ "$gte": { "$left": { "title": { "$text": { "$indexOf": "val" } } }, "$right": 0 } }` | position of the first occurrence, -1 if none |
+| `$substring` | `{ "$eq": { "$left": { "title": { "$text": { "$substring": { "$startIndex": 1, "$length": 3 } } } }, "$right": "upl" } }` | substring |
 
-Alternate syntax: `{ "p1": { "$text": { "$contains": "val" } } }` is equivalent.
+`$substring` takes `$startIndex` (integer, 0-based, required) and `$length` (integer, optional — up to the end
+of the string if absent).
 
 ### Collection operators
 
-- `$any`: `{ "relateds": { "p1": "v1" } }` — true if at least one item in the collection matches.
-- `$all`: true if every item in the collection matches.
+To filter on a **to-many** relation, the quantifier is **required**: it sits between the collection name and
+the predicate.
 
-### Date and time operators
+- `$any`: `{ "relateds": { "$any": { "p1": "v1" } } }` — true if **at least one** item matches.
+- `$all`: `{ "relateds": { "$all": { "p1": "v1" } } }` — true if **every** item matches.
+
+### Date/time operators
 
 | Operator | Purpose |
 |---|---|
-| `$now` | Current date/time |
 | `$utcNow` | Current UTC date/time |
 | `$days`, `$hours`, `$minutes`, `$seconds`, `$milliseconds`, `$ticks`, `$timespan` | Duration construction |
 
@@ -65,24 +80,90 @@ Alternate syntax: `{ "p1": { "$text": { "$contains": "val" } } }` is equivalent.
 
 **Example — sum of two properties:** `{ "p1": { "$add": { "p2": {} } } }`
 
-## Value Expressions
+### Value expressions
 
 A property is referenced by nesting JSON keys terminated with `{}`:
 
 - `{ "p1": {} }` → value of `p1`
-- `{ "p1": { "p2": {} } }` → value of `p1.p2` (deep access)
+- `{ "p1": { "p2": {} } }` → value of `p1.p2` (deep access through a **to-one** relation)
+
+Deep access through a **to-many** relation must go through `$any` / `$all` (see "Collection operators"). And
+this deep-access syntax is **not** accepted everywhere: `aggregate` restricts it further — see the "What can be
+traversed" table in [aggregate.md](./aggregate.md).
 
-## Verbose Binary Operator Syntax
+### Verbose binary operator syntax
 
-When fluent chaining doesn't work (e.g. when an operand is a terminal expression), use:
+When fluent chaining does not work (e.g. an operand is a terminal expression):
 
 ```json
 { "$operator": { "$left": { ... }, "$right": { ... } } }
 ```
 
-## Ordering
+### Localizable properties and `$meta`
+
+Some properties (such as `title`, `description`) are localized objects: `{ "fr": "...", "en": "..." }`. By default, operations apply to the event's default language.
+
+To force a specific language, wrap the expression in `$meta`:
+
+```json
+{
+  "$meta": {
+    "lang": "en",
+    "$token": { "title": { "$text.$contains": "search term" } }
+  }
+}
+```
+
+Nested `$meta` operators are cumulative; the closest ancestor `$meta` wins when a localizable property is evaluated.
+
+### JSON fields (type `Object`, 95)
+
+A field that `inwink_mcp_get_entity_description` returns with `"type": 95` stores a JSON document. Its name depends on the entity
+(e.g. `configuration` on `MailTemplate`); the description gives that name, but not the structure of the document.
+Two filter forms apply. Below, `<field>` is the name of the JSON field.
+
+**1. Text anywhere in the document (default form).** It only needs the field name. `$meta` with
+`"as": "string"` reads the field as its serialized JSON, to which the `$text` predicates apply:
+
+```json
+{ "$meta": { "as": "string", "$token": { "<field>": { "$text": { "$contains": "searched text" } } } } }
+```
+
+Example on `MailTemplate`:
+`{ "$meta": { "as": "string", "$token": { "configuration": { "$text": { "$contains": "isRegistered" } } } } }`.
+
+The search covers the whole JSON text: it matches a template variable as well as a key name, an attribute value
+or HTML. It is case-insensitive.
+
+**2. Value at a known path in the document.** If you know the structure, the keys under `<field>` are the keys
+of the document: descend to a scalar value (string, number, boolean), without going through an array, then
+apply a comparison or a `$text` predicate. Examples on `MailTemplate`:
+
+```json
+{ "configuration": { "maildata": { "relationEntityName": "order" } } }
+{ "configuration": { "maildata": { "senderEmail": { "$text": { "$contains": "@example.com" } } } } }
+```
+
+To learn the structure, read the field on a single row (`query` with `page.size` 1 and `selects` limited to that
+field): a document can weigh tens of KB. If the searched value sits in an array of the document, or if its
+location varies from one row to another, use form 1.
+
+⚠️ **Under a JSON field, a `$`-prefixed key that is not an operator from this page is read as a document
+key.** The filter then runs without error and returns 0 results. Write the operators exactly as shown above.
+A 0 obtained with another form does not prove the value is absent.
+
+Related errors:
+
+- `400 … cannot convert value of type 'JObject' to string`: a `$text` predicate was applied to the field
+  itself. Wrap it in `$meta` `"as": "string"` (form 1) or descend to a scalar value (form 2).
+- `500` on a filter that targets a JSON field: the form used is not one of the two above. Rewrite the filter
+  using form 1 or 2.
 
-The `orders` array contains objects with `desc` (boolean) and `value` (a value expression):
+---
+
+## Sorting (orders)
+
+The `orders` array holds objects with `desc` (boolean) and `value` (a value expression):
 
 ```json
 {
@@ -92,29 +173,37 @@ The `orders` array contains objects with `desc` (boolean) and `value` (a value e
 }
 ```
 
-## Projection Expressions (selects)
+- `value` references a field using the value expression syntax: `{ "field": {} }`.
+- `desc: true` for descending order; `false` or absent for ascending.
+
+### Sorting on a related entity
+
+A **to-one** relation is traversed by nesting, including on a localizable field:
 
 ```json
-{ "$all": true, "secretField": false }
+{ "orders": [ { "desc": true, "value": { "member": { "lastname": {} } } } ] }
 ```
 
-- `true` = include, `false` = exclude.
-- `$all` sets the default for all properties.
-- Nested objects define joins/expands: `{ "sessions": { "$all": true } }`
+Entities whose relation is empty come first in ascending order.
 
-## Localizable Properties and `$meta`
+A **to-many** relation is **not** sortable.
 
-Some properties (like `title`, `description`) are localized objects: `{ "fr": "...", "en": "..." }`. By default, operations apply to the event's default language.
+---
 
-To force a specific language, wrap the expression in `$meta`:
+## Projection (selects)
 
 ```json
-{
-  "$meta": {
-    "lang": "en",
-    "$token": { "title": { "$text.$contains": "search term" } }
-  }
-}
+{ "$all": true, "secretField": false }
 ```
 
-Nested `$meta` operators are cumulative; the closest ancestor `$meta` wins when a localizable property is evaluated.
+- `true` = include, `false` = exclude.
+- `$all` sets the default for all properties.
+- Nested objects define joins/expansions: `{ "sessions": { "$all": true } }`.
+
+Related entities are **never loaded automatically** — they must be requested explicitly in `selects`.
+
+### Null values
+
+A field whose value is null can be **left out of the row**, even when it is selected by name; other null fields come back as `null`. Both mean null. An absent field is not the sign of a wrong name: a name that does not exist on the entity fails the whole request with `400 … property resolution error`. A field selected by name, with no error, and absent from the row is therefore null.
+
+To list the rows where a field is null, filter with `{ "<field>": null }`.

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

@@ -1,10 +1,10 @@
-◂ Retour à [README](./README.md)
+◂ Back to [README](./README.md)
 
 # Query & Count (read entities)
 
-Pour la syntaxe des `filters`, `orders` et `selects`, voir [query-language.md](./query-language.md).
+For the `filters`, `orders` and `selects` syntax, see [query-language.md](./query-language.md).
 
-## Query (read entities)
+## Query
 
 ```
 POST {api}/{shardId}/{entity}/query
@@ -22,19 +22,19 @@ POST {api}/{shardId}/{entity}/query
 ```
 
 - `page` — **required**. `index` starts at 0, `size` between 1 and 300 (recommended: 50).
-- `filters` — optional. A predicate expression (see "Query Language" section below).
-- `orders` — optional. An array of order clauses (see "Ordering" below). If omitted, the API sorts by `id` when available.
-- `selects` — optional. A projection expression (see "Projection" below). Defaults to `{ "$all": true }`.
+- `filters` — optional. A predicate (see [query-language.md](./query-language.md#filters)).
+- `orders` — optional. Array of sort clauses (see [query-language.md](./query-language.md#sorting-orders)). If omitted, the API sorts by `id` when possible.
+- `selects` — optional. A projection (see [query-language.md](./query-language.md#projection-selects)). Default: `{ "$all": true }`.
 
 **Response:** `{ "data": [ ...entities ] }`
 
 ### Pagination
 
-The API uses **stateless offset-based pagination** (no cursor). To fetch all records, increment `page.index` until `data.length < page.size`. Because pagination is stateless, **duplicates can occur across pages** — always deduplicate results by `id`. Missing records can also happen if the sort property is non-unique or mutable; omitting `orders` lets the API pick the safest sort.
+**Stateless offset-based** pagination (no cursor). To fetch everything, increment `page.index` until `data.length < page.size`. Because pagination is stateless, **duplicates can appear across pages** — always deduplicate by `id` (`useInwinkPagedQuery` does it). Records can also be missed if the sort property is non-unique or mutable; omitting `orders` lets the API pick the safest sort.
 
 ### Selecting specific fields
 
-Return only specific properties:
+Example on the EventAPI `person` entity — field names are specific to each entity and do not carry over from one API to another.
 
 ```json
 {
@@ -55,7 +55,7 @@ Return only specific properties:
 }
 ```
 
-Related entities are **never loaded automatically** — you must explicitly request them in `selects`.
+Related entities are **never loaded automatically** — they must be requested explicitly in `selects`.
 
 ---
 
@@ -65,4 +65,6 @@ Related entities are **never loaded automatically** — you must explicitly requ
 POST {api}/{shardId}/{entity}/count
 ```
 
-Same body as query (supports `filters` and `page`) but without `selects`. Returns a **single integer**.
+Same body as query (supports `filters` and `page`) but **without** `selects`. Returns a **single integer**.
+
+Best for "how many …" questions. For a breakdown (GROUP BY), use [aggregate.md](./aggregate.md) rather than counting page by page.

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

@@ -1,4 +1,4 @@
-◂ Retour à [README](./README.md)
+◂ Back to [README](./README.md)
 
 # Edit & Massupdate
 
@@ -17,9 +17,11 @@ POST {api}/{shardId}/{entity}/{entityId}
 }
 ```
 
-**Important:** This is a **PATCH**, not a replace. Only properties present in the payload are updated. To clear a property, explicitly set it to `null`.
+**Important:** this is a **PATCH** in meaning, sent with `POST` — not a replacement. Only the properties present in the payload are updated. To clear a property, set it explicitly to `null`.
 
-`selects` contrôle les propriétés retournées (voir [query-language.md](./query-language.md)).
+`selects` controls the returned properties (see [query-language.md](./query-language.md#projection-selects)).
+
+> Changing the **definition** of an entity's fields (adding a custom field, for instance) is not an entity edit: see [entity-template.md](./entity-template.md).
 
 ---
 
@@ -29,6 +31,6 @@ POST {api}/{shardId}/{entity}/{entityId}
 POST {api}/{shardId}/{entity}/massupdate
 ```
 
-Bulk EDIT like `UPDATE … WHERE` in SQL. S'appuie sur un filtre (voir [query-language.md](./query-language.md)).
+Bulk EDIT, like `UPDATE … WHERE` in SQL. Relies on a filter (see [query-language.md](./query-language.md#filters)).
 
-> Pour mettre à jour un lot d'entités identifiées une à une, voir aussi [import.md](./import.md).
+> To update a batch of entities identified one by one, see also [import.md](./import.md).