@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/guides/add-an-entity.md

@@ -0,0 +1,170 @@
+---
+title: Add an entity
+audience: tenant
+---
+
+# Add an entity
+
+## What you're doing
+
+An **entity** is a database table you declare instead of writing SQL. You list
+its **fields** and their **data types**; the platform's Entity Engine generates
+the `CREATE TABLE`, the CRUD REST endpoints (`/api/v1/entities/<name>/records`),
+the grid query endpoint, and single-record reads. Zero persistence code.
+
+One entity = one file under `spk-assembly/metadata/entities/`.
+
+## The complete example
+
+`spk-assembly/metadata/entities/oeq_equipment.json` from the tutorial module —
+[the real file](../tutorial/example-plugin/spk-assembly/metadata/entities/oeq_equipment.json):
+
+```json
+{
+  "entity": {
+    "name": "oeq_equipment",
+    "tableName": "oeq_equipment",
+    "label": "{\"en\":\"Equipment\"}",
+    "category": "office-equipment",
+    "icon": "devices",
+    "color": "#2563EB",
+    "pkStrategy": "identity"
+  },
+  "fields": [
+    { "fieldName": "asset_tag", "label": "\"Asset Tag\"", "dataType": "text", "nullable": false, "required": true, "isUnique": true, "isIndexed": true, "isDisplayField": true, "displayOrder": 1 },
+    { "fieldName": "name", "label": "\"Name\"", "dataType": "text", "nullable": false, "required": true, "displayOrder": 2 },
+    { "fieldName": "category_id", "label": "\"Category Id\"", "dataType": "long", "nullable": true, "required": false, "isIndexed": true, "displayOrder": 3 },
+    { "fieldName": "category_name", "label": "\"Category\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 4 },
+    { "fieldName": "serial_number", "label": "\"Serial Number\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 5 },
+    { "fieldName": "status", "label": "\"Status\"", "dataType": "enum", "nullable": false, "required": true, "isIndexed": true, "defaultValue": "AVAILABLE", "typeParams": "{\"enumValues\":[\"AVAILABLE\",\"ASSIGNED\",\"MAINTENANCE\",\"RETIRED\"]}", "displayOrder": 6 },
+    { "fieldName": "purchase_date", "label": "\"Purchase Date\"", "dataType": "date", "nullable": true, "required": false, "displayOrder": 7 },
+    { "fieldName": "warranty_expiry_date", "label": "\"Warranty Expiry Date\"", "dataType": "date", "nullable": true, "required": false, "displayOrder": 8 },
+    { "fieldName": "notes", "label": "\"Notes\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 9 }
+  ]
+}
+```
+
+## Line by line
+
+### The `entity` block
+
+- **`name`** — lowercase, `snake_case`, starts with a letter. This is the table
+  name and the id in every REST path. **Prefix it** (`oeq_`) so it never
+  collides with another plugin's table.
+- **`label`** — this column is stored as JSON in the database, so the *string*
+  must itself be valid JSON: `"{\"en\":\"Equipment\"}"` (an i18n object) — **not**
+  `"Equipment"`. A bare string fails the install with `invalid input syntax for
+  type json`. This is the single most common entity mistake.
+- **`pkStrategy`** — `identity` gives an auto-incrementing integer `id`.
+  `snowflake` gives a distributed 64-bit id. Use `identity` unless you have a
+  reason not to.
+- **`icon` / `color` / `category`** — cosmetic, used by Studio's explorer tree.
+
+### Each `field`
+
+- **`fieldName`** — `snake_case`, starts with a letter.
+- **`label`** — **also pre-stringified JSON.** `"\"Asset Tag\""` is the JSON
+  string literal `"Asset Tag"`. A bare `"Asset Tag"` fails the install.
+- **`dataType`** — accepted case-insensitively; every shipped file uses
+  lowercase. The ones you'll actually use:
+
+  | `dataType` | Postgres | notes |
+  | --- | --- | --- |
+  | `text` | `text` | any string, short or long. **Not `long`** — that's the 64-bit integer type. |
+  | `integer` | `int` | 32-bit |
+  | `long` | `bigint` | 64-bit; use for foreign-key id columns |
+  | `decimal` / `currency` | `numeric` | money |
+  | `boolean` | `boolean` | |
+  | `date` | `date` | |
+  | `datetime` | `timestamptz` | |
+  | `enum` | `text` + check | needs `typeParams` (below) |
+
+- **`typeParams`** — **also a pre-stringified JSON string.** For an enum:
+  `"{\"enumValues\":[\"AVAILABLE\",\"ASSIGNED\"]}"`.
+- **`nullable` / `required`** — a `required: true` field **must** also be
+  `nullable: false`. A `required: false` field **must** be `nullable: true`. A
+  mismatched pair produces a broken `ALTER TABLE` on a table that already has
+  rows.
+- **`isUnique`**, **`isIndexed`** — add a unique constraint / index (scoped to
+  the tenant).
+- **`isDisplayField: true`** — marks the human-readable "name" column. Pick
+  exactly one.
+- **`defaultValue`** — always a string, even for numbers/booleans:
+  `"10"`, `"true"`, `"AVAILABLE"`.
+
+### Foreign keys and automatic labels
+
+`category_id` is a `long` holding another table's `id`. Two ways to show a name
+instead of a raw number:
+
+1. **Denormalize** — also store `category_name` and write both when you create a
+   row (what the tutorial does — simplest).
+2. **`reference` flag** — add
+   `"flags": "{\"reference\":{\"entityType\":\"Employee\"}}"` to the id field.
+   Every read then gains a sibling `<field>_label` key
+   (`employee_id` → `employee_id_label`) resolved automatically, batched once per
+   page load. `entityType` must be a **registered** provider — `"Employee"` is
+   the only one shipped today. See
+   [resolved reference column](../recipes/resolved-reference-grid-column.md).
+
+The tutorial's `oeq_checkout` entity uses the `reference` flag on `employee_id`
+and it was verified live to return `"employee_id_label": "Aria Chen"`.
+
+## Ground yourself first
+
+```bash
+erp schema pull entity-definition        # the full contract
+```
+
+Or over MCP: `erp_get_schema {"name":"entity-definition"}`.
+
+## Two file shapes both validate
+
+- **`{ "entity": { ... }, "fields": [ ... ] }`** — the packaged artifact shape,
+  used in `spk-assembly/metadata/entities/`. Use this.
+- **flat** (`{ "name": ..., "label": ..., "fields": [ ... ] }`) — the live
+  `POST /api/v1/entities` request body. Only matters if you're calling the API
+  directly.
+
+## How to verify it worked
+
+```bash
+erp schema validate spk-assembly/metadata/entities/oeq_equipment.json --schema entity-definition
+```
+
+```
+OK — spk-assembly/metadata/entities/oeq_equipment.json matches schema "entity-definition"
+```
+
+After publishing, the table is live:
+
+```bash
+erp api get "/api/v1/entities/oeq_equipment/records/query?size=5"
+```
+
+```json
+{ "rows": [], "total": 0 }
+```
+
+And a record you create comes back with audit columns the engine added for free:
+
+```json
+{ "id": 1, "created_by": "you@example.com", "created_at": "2026-09-10T08:08:33.282+00:00",
+  "asset_tag": "LAP-001", "name": "Dell Latitude 7440", "status": "AVAILABLE" }
+```
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| install fails `invalid input syntax for type json` | `label` is a bare string | make it `"{\"en\":\"...\"}"` (entity) or `"\"...\""` (field) |
+| a field silently missing after install | `required:false` without `nullable:true` on a table with rows | pair them correctly, bump version, republish |
+| big text truncated / rejected | `dataType: "long"` | that's the integer type; use `"text"` |
+| enum column rejects every value | `typeParams` is a nested object, not a string | pre-stringify it |
+| grid shows a raw number for a person | bound to `employee_id` not `employee_id_label` | add the `reference` flag and bind the `_label` |
+
+## What to read next
+
+- [Add a data provider](./add-a-data-provider.md) — so a grid can read the table
+- [Build a page](./build-a-page.md)
+- [Seed reference data on install](./seed-data-on-install.md)

package/bundle/docs/guides/add-business-rules.md

@@ -0,0 +1,147 @@
+---
+title: Add business rules and expressions
+audience: tenant
+---
+
+# Add business rules and expressions
+
+## What you're doing
+
+Attaching declarative logic to an entity's lifecycle: reject an invalid save,
+compute a field, kick off a job or workflow. One rule = one file under
+`spk-assembly/metadata/rules/`, evaluated by the Rule Engine at a lifecycle
+point.
+
+## When each action type fires
+
+| `triggerEvent` | fires | typical use |
+| --- | --- | --- |
+| `BEFORE_CREATE` / `BEFORE_UPDATE` | before the write | `REJECT` (validation), `SET_VALUE` (computed/defaulted field) |
+| `AFTER_CREATE` | after insert | `EXECUTE_SERVICE` (register a job on first row), `START_WORKFLOW` |
+| `AFTER_UPDATE` | after update | `START_WORKFLOW` on a status transition |
+| `AFTER_DELETE` | after delete | cleanup fan-out |
+
+## The complete example — a validation + a computed field
+
+`spk-assembly/metadata/rules/oeq_checkout_dates.json` (a standalone example,
+[real file](../examples/standalone-plugin/spk-assembly/metadata/rules/oeq_checkout_dates.json)):
+
+```json
+{
+  "entityType": "oeq_checkout",
+  "name": "oeq_checkout_dates",
+  "description": "Due date must be on or after the checkout date.",
+  "triggerEvent": "BEFORE_CREATE",
+  "conditions": { "field": "due_date", "op": "lt", "value": "${record.checkout_date}" },
+  "actions": [
+    { "type": "REJECT", "message": "Due date cannot be before the checkout date." }
+  ],
+  "priority": 10,
+  "active": true
+}
+```
+
+> In a `metadata/rules/*.json` file `conditions` and `actions` may be authored as
+> real JSON (as above) **or** as pre-stringified JSON (as the workflow-trigger
+> rule does). Both install. The stringified form matches what the live API
+> stores and returns.
+
+## Line by line
+
+- **`entityType`** — the entity `name` this rule fires against.
+- **`triggerEvent`** — one of the six lifecycle points above.
+- **`conditions`** — a condition tree. A leaf is `{ field, op, value }`. Compose
+  with `{ "all": [...] }`, `{ "any": [...] }`, `{ "not": {...} }`.
+  - **operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `in`,
+    `is_null`, `is_not_null`. `is_null` / `is_not_null` take no `value`.
+  - **`${record.<field>}`** in a `value` reads another field of the same row.
+  - **`${record.<field>__previous`}`** (in an `AFTER_UPDATE` rule) is the value
+    before the update.
+- **`actions`** — at least one:
+
+  | `type` | fields | effect |
+  | --- | --- | --- |
+  | `REJECT` | `message` | abort the write, surface `message` to the caller |
+  | `SET_VALUE` | `field`, `value` | assign a field before the write |
+  | `EXECUTE_SERVICE` | `service` (a registered handler bean) | run a named platform service |
+  | `START_WORKFLOW` | `workflowName`, `config`, `callbackUrl` | see [Add an approval workflow](./add-an-approval-workflow.md) |
+
+- **`priority`** — lower first. Put `REJECT`/`SET_VALUE` validation rules at `10`,
+  workflow triggers at `20`.
+
+## Computed fields — two ways
+
+1. **A `SET_VALUE` rule** (above) — imperative, runs at a lifecycle point.
+2. **A formula field on the entity** — declarative, computed on every read, no
+   physical column:
+
+   ```json
+   { "fieldName": "days_out", "label": "\"Days Out\"", "dataType": "formula",
+     "flags": "{\"formula\":\"daysBetween(checkout_date, now())\"}" }
+   ```
+
+   The formula language is the platform `ExpressionEvaluator` — whitelisted
+   functions only (`daysBetween`, `now`, `coalesce`, arithmetic, comparisons).
+   **No** ternary, **no** `in`, **no** `^`. The same evaluator powers
+   compliance-sweep conditions (see [Add a compliance-sweep job](./add-a-compliance-job.md)).
+
+## Registering a job on the first config row
+
+The pattern jobs use to auto-register themselves — an unconditional
+`AFTER_CREATE` `EXECUTE_SERVICE`:
+
+```json
+{
+  "entityType": "entity_aggregation_config",
+  "name": "ensure_aggregation_sweep_job_registered",
+  "triggerEvent": "AFTER_CREATE",
+  "conditions": null,
+  "actions": "[{\"type\": \"EXECUTE_SERVICE\", \"service\": \"ensureEntityAggregationSweepJobRegistered\"}]",
+  "priority": 10,
+  "active": true
+}
+```
+
+`conditions: null` means "always". See [Seed data on install](./seed-data-on-install.md).
+
+## Ground yourself first
+
+```bash
+erp schema pull entity-rule-definition
+erp examples patterns --kind entities
+```
+
+## How to verify it worked
+
+After publishing:
+
+```bash
+erp api get "/api/v1/entity-rules?entityType=oeq_checkout"
+```
+
+lists your rule with `"active": true`. Then trigger it:
+
+```bash
+erp api post "/api/v1/entities/oeq_checkout/records" \
+  --body '{"checkout_number":"CO-9","equipment_id":1,"employee_id":1,"checkout_date":"2026-09-10","due_date":"2026-09-01","status":"DRAFT"}'
+```
+
+```json
+{ "error": "Due date cannot be before the checkout date." }
+```
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| a `!= null` / `!=null` comparison never matches | action-engine quirk | use `is_not_null` |
+| rule fires on every update, not just the transition | no `__previous` guard | add `{ "field": "status__previous", "op": "neq", "value": "..." }` |
+| `SET_VALUE` doesn't stick | used `AFTER_*` (write already happened) | use `BEFORE_CREATE` / `BEFORE_UPDATE` |
+| formula field errors | used ternary / `in` / unsupported function | rewrite with whitelisted functions only |
+| install rejects the rule file | `actions` is a bare object, not an array/string | `actions` is an array (or a stringified array) |
+
+## What to read next
+
+- [Add an approval workflow](./add-an-approval-workflow.md)
+- [Add a compliance-sweep job](./add-a-compliance-job.md)
+- [Seed config and reference data on install](./seed-data-on-install.md)

package/bundle/docs/guides/add-i18n.md

@@ -0,0 +1,121 @@
+---
+title: Add translations (i18n)
+audience: tenant
+---
+
+# Add translations (i18n)
+
+## What you're doing
+
+Every user-visible string on a page is an **i18n key**, not literal text. Page
+titles, button labels, column headers, KPI labels, enum option labels — all
+keys. You supply the actual words in `spk-assembly/metadata/i18n/en.json` (and
+`fr.json`, `de.json`, … for other locales).
+
+If a key has no entry, the UI renders the raw key
+(`office-equipment.equipment-register.title`) — ugly, and flagged by the linter.
+
+## The naming convention
+
+```
+<pluginId>.<page-name>.<what>
+```
+
+Examples from the tutorial:
+
+| Key | Value |
+| --- | --- |
+| `office-equipment.equipment-register.title` | `Equipment Register` |
+| `office-equipment.equipment-register.newBtn` | `New` |
+| `office-equipment.equipment-register.column.asset_tag` | `Asset Tag` |
+| `office-equipment.equipment-register.kpi.available` | `Available` |
+| `office-equipment.equipment-register.status.AVAILABLE` | `Available` |
+| `office-equipment.equipment-checkout.status.OVERDUE` | `Overdue` |
+| `office-equipment.application.title` | `Office Equipment` |
+| `office-equipment.module.title` | `Equipment` |
+
+## The complete example
+
+`spk-assembly/metadata/i18n/en.json` (excerpt — the
+[real file](../tutorial/example-plugin/spk-assembly/metadata/i18n/en.json) has
+~70 keys):
+
+```json
+{
+  "office-equipment.application.title": "Office Equipment",
+  "office-equipment.module.title": "Equipment",
+  "office-equipment.equipment-register.title": "Equipment Register",
+  "office-equipment.equipment-register.subtitle": "Office Equipment tutorial module",
+  "office-equipment.equipment-register.newBtn": "New",
+  "office-equipment.equipment-register.exportBtn": "Export CSV",
+  "office-equipment.equipment-register.kpi.total": "Total",
+  "office-equipment.equipment-register.kpi.available": "Available",
+  "office-equipment.equipment-register.kpi.assigned": "Assigned",
+  "office-equipment.equipment-register.column.asset_tag": "Asset Tag",
+  "office-equipment.equipment-register.column.name": "Name",
+  "office-equipment.equipment-register.column.status": "Status",
+  "office-equipment.equipment-register.status.AVAILABLE": "Available",
+  "office-equipment.equipment-register.status.ASSIGNED": "Assigned",
+  "office-equipment.equipment-register.form.title": "Equipment",
+  "office-equipment.equipment-register.form.asset_tag": "Asset Tag",
+  "office-equipment.equipment-register.form.saveBtn": "Save",
+  "office-equipment.equipment-register.form.cancelBtn": "Cancel"
+}
+```
+
+It's a flat object — dotted keys, string values. No nesting.
+
+## Line by line — where each key type comes from
+
+| In a page file | i18n key referenced |
+| --- | --- |
+| `definition.title` | the page title |
+| a block's `properties.textKey` / `labelKey` (with `source: "static"`) | any static label |
+| a grid column's `headerKey` | column header |
+| a `core.select` option's `labelKey` | dropdown option label |
+| `designer.displayNameKey` / `descriptionKey` | Studio explorer label |
+| `metadata/application/*.json` `titleKey`, `metadata/module/*.json` `titleKey` | app / module name |
+
+Every one of those must have a matching entry in `en.json`.
+
+## Adding another language
+
+Add `fr.json` with the same keys, French values. Missing keys in `fr.json` fall
+back to `en.json`. The ERP picks the file by the user's locale.
+
+## Keeping it in sync automatically
+
+You don't have to hand-track keys. A small script that walks your page/menu/app
+files collecting every `*Key` / `headerKey` / static `title` value, then writes
+`en.json` with a humanised default for any missing key, is the practical
+approach — the tutorial's build uses exactly this. The linter is your safety
+net.
+
+## How to verify it worked
+
+```bash
+erp plugin test office-equipment/spk-assembly
+```
+
+A missing key is reported as:
+
+```
+I18N-001  equipment-register.json: i18n key
+          "office-equipment.equipment-register.kpi.total" not found in metadata/i18n/en.json
+```
+
+A clean run means every referenced key resolves.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| UI shows `office-equipment.x.y` literally | key missing from `en.json` | add it (linter tells you which) |
+| `en.json` is nested objects | wrong shape | flat `{ "a.b.c": "text" }` |
+| enum chips show the raw enum value | no `...status.<VALUE>` keys | add one per enum value |
+| translation not applied | `fr.json` missing keys, or wrong locale on the user | keys fall back to `en`; check the user's locale |
+
+## What to read next
+
+- [Build a page](./build-a-page.md)
+- [Validate and test a plugin](./validate-and-test.md)

package/bundle/docs/guides/add-menus.md

@@ -0,0 +1,149 @@
+---
+title: Add menus
+audience: tenant
+---
+
+# Add menus
+
+## What you're doing
+
+Putting your pages in the ERP's navigation. A **menu** is a tree of nodes, each
+pointing at a route. One file under `spk-assembly/metadata/menu/`.
+
+There is a second, easy-to-miss step: a **master menu scaffold** file that some
+deployments keep as the merged sidenav. If your plugin's module belongs to a
+larger application (e.g. HCM), you update that too — see below.
+
+## The complete example
+
+`spk-assembly/metadata/menu/office-equipment-menu.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/menu/office-equipment-menu.json):
+
+```json
+{
+  "name": "office-equipment-menu",
+  "description": "Navigation contributed by the Office Equipment plugin.",
+  "definition": {
+    "contractVersion": 1,
+    "name": "office-equipment-menu",
+    "nodes": [
+      {
+        "id": "office-equipment.equipment",
+        "name": "equipment",
+        "displayName": "Office Equipment",
+        "sequence": 0,
+        "navigation": { "route": null, "openMode": "current-tab" },
+        "visibility": { "visible": true, "enabled": true, "devices": [] },
+        "color": null,
+        "children": [
+          {
+            "id": "office-equipment.equipment.equipment-register",
+            "name": "equipment-register",
+            "displayName": "Equipment Register",
+            "sequence": 0,
+            "children": [],
+            "navigation": { "route": "/office-equipment/equipment-register", "openMode": "current-tab" },
+            "visibility": { "visible": true, "enabled": true, "devices": [] },
+            "color": null
+          },
+          {
+            "id": "office-equipment.equipment.equipment-catalog",
+            "name": "equipment-catalog",
+            "displayName": "Equipment Catalog",
+            "sequence": 1,
+            "children": [],
+            "navigation": { "route": "/office-equipment/equipment-catalog", "openMode": "current-tab" },
+            "visibility": { "visible": true, "enabled": true, "devices": [] },
+            "color": null
+          },
+          {
+            "id": "office-equipment.equipment.equipment-checkout",
+            "name": "equipment-checkout",
+            "displayName": "Equipment Checkout",
+            "sequence": 2,
+            "children": [],
+            "navigation": { "route": "/office-equipment/equipment-checkout", "openMode": "current-tab" },
+            "visibility": { "visible": true, "enabled": true, "devices": [] },
+            "color": null
+          }
+        ]
+      }
+    ]
+  },
+  "modules": ["office-equipment"]
+}
+```
+
+## Line by line
+
+- **`nodes`** — the tree. A parent node with `navigation.route: null` is a group
+  header; its `children` are the clickable items.
+- **`id`** — dotted, unique, conventionally `<pluginId>.<group>.<page>`.
+- **`name`** — a short slug.
+- **`displayName`** — the label shown. (For a translated label use
+  `displayNameKey` with an i18n key instead.)
+- **`sequence`** — sort order among siblings.
+- **`navigation.route`** — the page's `route.pattern`, *exactly*. This is the
+  internal routing key, not the browser URL.
+- **`visibility.devices`** — `[]` means all devices; `["mobile"]` restricts.
+- **`modules`** — the module id(s) this menu contributes to. Match your pages'
+  `modules`.
+
+## Scaffold with the CLI
+
+```bash
+erp menu create office-equipment office-equipment-menu \
+  --display-name "Equipment Register" --route /office-equipment/equipment-register --icon devices
+```
+
+produces a valid one-node menu you then flesh out. (Run it from PowerShell on
+Windows, or the leading `/` in `--route` gets mangled by Git Bash.)
+
+## The master-scaffold sync note
+
+Some applications (the HCM suite is the canonical case) keep a single
+hand-maintained "master menu" file — e.g. `hcm-foundation-main-menu.json` — that
+is the merged sidenav shown whether or not a given plugin is installed. If your
+module attaches to such an application, a new page needs its node added in **two
+places**:
+
+1. your own `metadata/menu/<plugin>-menu.json` (above), and
+2. the application's master menu scaffold.
+
+Skipping (2) means the item is missing from the merged sidenav for anyone who
+sees the app but hasn't installed your plugin. A **standalone** plugin that ships
+its own `metadata/application/*.json` (like the tutorial) has no master scaffold
+to sync — one menu file is enough.
+
+## Ground yourself first
+
+```bash
+erp schema pull menu
+```
+
+## How to verify it worked
+
+```bash
+erp schema validate spk-assembly/metadata/menu/office-equipment-menu.json --schema menu
+```
+
+```
+OK — ... matches schema "menu"
+```
+
+After publishing, open the ERP and confirm the group and its items appear in the
+sidenav under your application, and each item navigates to the right page.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| menu item 404s | `navigation.route` doesn't match the page's `route.pattern` | copy it exactly |
+| item appears but page is blank | page's `modules` array doesn't include this module | align them |
+| item missing from the merged app sidenav | didn't sync the master menu scaffold | add the node there too |
+| `erp menu create` route is a Windows path | Git Bash `/` mangling | run from PowerShell / `MSYS_NO_PATHCONV=1` |
+
+## What to read next
+
+- [Add translations (i18n)](./add-i18n.md)
+- [Make a plugin work on desktop, tablet, and mobile](./responsive-plugin.md)