zinkee 0.1.0 → 0.1.1

package/README.md

@@ -8,9 +8,9 @@ Implemented command groups:
 
 - `profiles`
 - `config`
-- `files`
 - `schemas`
 - `records`
+- `files`
 - `comments`
 - `navigation`
 - `teamspace`
@@ -37,7 +37,7 @@ npm test
 
 ## Configuration
 
-The CLI is compatible with the existing config file:
+The CLI uses a TOML config file:
 
 ```text
 ~/.config/zinkee/config.toml
@@ -55,303 +55,488 @@ base_url = "https://api.zinkee.com"
 
 ## Global Options
 
-- `--profile <name>`
-- `--base-url <url>`
-- `--api-key <token>`
-- `--read-only`
-- `--example <command path>`
-- `--json`
+| Option | Description |
+|---|---|
+| `--profile <name>` | Select a profile from config |
+| `--base-url <url>` | Override the configured base URL |
+| `--api-key <token>` | Override the configured API key |
+| `--read-only` | Run in read-only mode |
+| `--example` | Show examples for a command |
+| `--json` | Emit JSON output |
 
 ## JSON Contract
 
 Successful commands emit:
 
 ```json
-{
-  "data": {},
-  "meta": {}
-}
+{ "data": {}, "meta": {} }
 ```
 
 Failing commands emit:
 
 ```json
-{
-  "error": {},
-  "meta": {}
-}
+{ "error": {}, "meta": {} }
 ```
 
-## Quick Examples
+---
+
+## Schemas
+
+### Create a schema
+
+```bash
+zinkee schemas create --name "Projects" --slug projects --auditable --commentable
+```
+
+### List and get schemas
 
 ```bash
-zinkee profiles list
-zinkee --json config validate
 zinkee --json schemas list
-zinkee --json schemas get tareas
-zinkee --json records list contacts --limit 50 --offset 0
-zinkee --json records query contacts --where "status eq active"
-zinkee --json files storage
-zinkee --json automations list
-zinkee --example records query
-zinkee --json --example automations create
-zinkee --json --example automations trigger set
-zinkee --json --example automations actions add
-zinkee --json --example automations webhook set
-zinkee --json --example automations connections create
+zinkee --json schemas get projects
 ```
 
-## Automations
+### Create fields
 
-The `automations` group manages the full public automation surface:
+Simple field types use `--type`, `--slug`, `--label`:
+
+```bash
+zinkee schemas fields create projects --type text --slug name --label "Name"
+zinkee schemas fields create projects --type number --slug budget --label "Budget"
+zinkee schemas fields create projects --type date --slug start-date --label "Start Date"
+zinkee schemas fields create projects --type file --slug attachment --label "Attachment"
+zinkee schemas fields create projects --type autoincremental --slug code --label "Code"
+zinkee schemas fields create projects --type member --slug owner --label "Owner"
+```
 
-- automation folders
-- automation metadata
-- triggers
-- actions
-- flow wiring
-- webhook endpoint configuration
-- plugins
-- stored connections for HTTP actions
+Valid types: `text`, `number`, `date`, `file`, `autoincremental`, `member`, `option`, `reference`, `formula`.
 
-If you are scripting, prefer `--json`. If you are discovering the CLI, prefer `--example <command path>`.
+Complex types require `--raw`:
 
-### Before You Start
+```bash
+# Option field
+zinkee schemas fields create projects --raw '{
+  "type":"option","slug":"status","label":"Status",
+  "options":[
+    {"id":1,"name":"Open","color":"default"},
+    {"id":2,"name":"In Progress","color":"primary"},
+    {"id":3,"name":"Done","color":"success"}
+  ]
+}'
+
+# Reference field (targetSchema and targetDisplayField must be UUIDs)
+zinkee schemas fields create tasks --raw '{
+  "type":"reference","slug":"project","label":"Project",
+  "targetSchema":"<schema-uuid>",
+  "targetDisplayField":"<field-uuid>",
+  "deleteBehavior":"SET_NULL"
+}'
+
+# Formula field (use formulaText, not expression)
+zinkee schemas fields create projects --raw '{
+  "type":"formula","slug":"code","label":"Code",
+  "formulaText":"concat(\"PRJ-\", <_id-field-uuid>)"
+}'
+```
 
-- `automations create` requires `--name` and a valid trigger.
-- For `record_created` and `record_changed`, `--trigger-schema` accepts a real schema UUID or schema slug from your workspace.
-- For `record_changed`, every `--trigger-field` must be a real field UUID or field slug from that schema.
-- `--condition` uses the format `<field:comparator:value>`.
-- `--condition-json` accepts a full JSON condition object when you need structured `rawValue/source` entries.
-- For record-based automation values, the CLI sends `{ rawValue, source }` objects to the API v2 contract.
-- The `scheduled` trigger uses a six-field cron expression, for example `0 15 10 * * 1`.
+### Update field config
 
-Useful discovery commands:
+Config properties must be wrapped inside a `config` key:
 
 ```bash
-zinkee --json schemas list
-zinkee --json schemas get <schema-uuid-or-slug>
-zinkee --json schemas fields list <schema-uuid-or-slug>
-zinkee --json automations plugins list
-zinkee --json automations connections list
+# Number formatting
+zinkee schemas fields update projects budget --raw '{
+  "config":{
+    "defaultValue":"0",
+    "formatOptions":{
+      "format":"number","decimals":2,"thousandsSeparator":true,
+      "symbolEnabled":true,"symbolValue":" €","symbolPosition":"right"
+    }
+  }
+}'
+
+# Date formatting
+zinkee schemas fields update projects start-date --raw '{
+  "config":{"formatOptions":{"format":"date","dateFormat":"L","showTime":false}}
+}'
+
+# Text type (valid values: NORMAL, LONG)
+zinkee schemas fields update projects description --raw '{"config":{"textType":"LONG"}}'
 ```
 
-### Trigger Types
+### Formula syntax
+
+Formulas reference fields by UUID **without brackets**:
 
-Valid trigger types are:
+```
+concat("PRJ-", f1e1d000-0000-0000-0000-000000000005)
+if(8e73e31d-c47d-4123-a14c-331991c39c0e > 10, "High", "Low")
+date_format(44b72f55-3fc3-40f4-88bb-343bb4a6270c, "AAAA-MM")
+```
 
-- `scheduled`
-- `record_created`
-- `record_changed`
-- `webhook`
+- Field references: UUID without brackets (no `[uuid]`)
+- Date masks are in Spanish: `AAAA`, `MM`, `DD`, `MMMM`, `DDDD`, etc.
+- Date masks must be quoted: `"AAAA-MM"`
+- Functions: `concat`, `if`, `date_format`, `datetime_diff`, arithmetic (`+`,`-`,`*`,`/`)
+- Invalid formulas are created with status `DRAFT` and evaluate to `null`
 
-Minimal scheduled automation:
+---
+
+## Records
+
+### CRUD operations
 
 ```bash
-zinkee --json automations create \
-  --name "Nightly invoice sync" \
-  --trigger-type scheduled \
-  --cron "0 15 10 * * 1"
+# Create
+zinkee records create projects \
+  --set name="Website Redesign" \
+  --set budget=25000 \
+  --set start-date="2026-01-15T00:00:00.000Z" \
+  --set status=1
+
+# List and query
+zinkee --json records list projects --limit 50
+zinkee --json records query projects --limit 10 --sort "_id:desc"
+
+# Get
+zinkee --json records get projects <record-uuid>
+
+# Update
+zinkee records update projects <record-uuid> --set status=2
+
+# Delete
+zinkee records delete projects <record-uuid>
 ```
 
-Record-created automation using a schema slug:
+Option values are written as numbers (`--set status=1`) but returned as strings (`"1"`). Number values are stored and returned as strings.
+
+---
+
+## Files
 
 ```bash
-zinkee --json automations create \
-  --name "Lead welcome" \
-  --trigger-type record_created \
-  --trigger-schema leads
+# Upload
+zinkee --json files upload /path/to/document.pdf
+
+# Download
+zinkee files download <file-uuid> --output /path/to/download.pdf
+
+# Attach to a record's FileField
+zinkee records update projects <record-uuid> \
+  --set-json 'attachment=[{"id":"<file-uuid>","name":"doc.pdf","contentType":"application/pdf"}]'
+
+# Detach
+zinkee records update projects <record-uuid> --set-json 'attachment=[]'
+
+# Delete (storage only — does NOT clean record references)
+zinkee files delete <file-uuid>
+
+# Storage info
+zinkee --json files storage
 ```
 
-Record-changed automation using schema and field slugs:
+> **Important**: deleting a file does not remove references from records. Manually clear the FileField before or after deleting.
+
+---
+
+## Comments
+
+Requires schemas with `commentable: true`.
 
 ```bash
-zinkee --json automations create \
-  --name "Order status sync" \
-  --trigger-type record_changed \
-  --trigger-schema orders \
-  --trigger-field status
+zinkee comments create <schema-slug> <record-uuid> --text "This is a comment"
+zinkee comments list <schema-slug> <record-uuid>
 ```
 
-Replace the trigger on an existing automation:
+---
+
+## Navigation
+
+Organize schemas into database folders.
 
 ```bash
-zinkee --json automations trigger set automation-1 \
-  --trigger-type record_changed \
-  --trigger-schema orders \
-  --trigger-field status
+# List folders with contents
+zinkee --json navigation folders list
+
+# Create folder
+zinkee navigation folders create --name "CRM" --order 1
+
+# Move a schema into a folder
+zinkee navigation resources move <schema-uuid> --type SCHEMA --to "CRM"
+
+# Delete folder (resources move back to root silently)
+zinkee navigation folders delete "CRM"
 ```
 
-Add trigger conditions:
+Root folder cannot be deleted.
+
+---
+
+## Teamspace
+
+Publish resources (schemas, displays) to the teamspace visible to non-admin users.
 
 ```bash
-zinkee --json automations trigger set automation-1 \
-  --trigger-type record_changed \
-  --trigger-schema orders \
-  --trigger-field status \
-  --condition status:eq:approved
+# Create teamspace folder
+zinkee teamspace folders create --name "Dashboards" --order 1
+
+# Publish a schema (accepts UUID or slug)
+zinkee teamspace resources publish projects --to "Dashboards"
+
+# Publish a display
+zinkee teamspace resources publish <display-uuid> --to "Dashboards"
+
+# Unpublish
+zinkee teamspace resources unpublish <resource-uuid>
+
+# List folders with resources
+zinkee --json teamspace folders list --include-resources
+
+# Re-publishing moves the resource to the new folder
+zinkee teamspace resources publish projects --to "Other Folder"
 ```
 
-For `record_created` and `record_changed`, trigger conditions are always sent as literal values under the new `{ rawValue, source }` shape. Trigger conditions do not support `source`.
+---
+
+## Displays
 
-### Actions
+Displays are dashboards composed of widgets that visualize data from schemas.
 
-Valid action types are:
+### Creation flow
 
-- `create_record`
-- `update_record`
-- `search_records`
-- `send_message`
-- `http_request`
-- `execute_plugin`
+1. Create the display
+2. Create context variables
+3. Create widgets with `variableMap` bindings
+4. Set freeform layout positions
 
-Notes:
+### Templates
 
-- `schema` references inside `automations` are standardized to accept either a UUID or a slug.
-- `field` references inside `automations` are standardized to accept either a UUID or a slug.
-- `pluginId` for `execute_plugin` must be an active plugin id from `zinkee --json automations plugins list`.
+- `freeform` — grid with `x/y/w/h` positioning (recommended)
+- `single_view` — single widget view
+- `widget_row` — stacked rows
+- `widget_row_tabs` — rows with tabs
+- `side_tabs_widgets` — tabs with sidebar
 
-Create-record action:
+### Create a freeform display
 
 ```bash
-zinkee --json automations actions add automation-1 \
-  --type create_record \
-  --name "Create follow-up" \
-  --target-schema followups \
-  --map status=pending \
-  --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}'
+zinkee --json displays create --name "Project Dashboard" --template freeform
 ```
 
-The CLI wraps `--map field=value` literals as:
+### Add a context variable
 
-```json
-{
-  "rawValue": "value",
-  "source": null
-}
+```bash
+zinkee --json displays variables create <display-uuid> \
+  --type reference \
+  --name "Project" \
+  --source-schema projects \
+  --source-field project-name
 ```
 
-For source-based values, pass the full object through `--map-json`. Valid `source.type` values are `TRIGGER` and `PREVIOUS_ACTION`.
+Variables accept slugs for `--source-schema` and `--source-field`.
 
-Search-records action with a trigger-based condition:
+### Add widgets
 
-```bash
-zinkee --json automations actions add automation-1 \
-  --type search_records \
-  --name "Find duplicates" \
-  --target-schema followups \
-  --condition-json '{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'
-```
+Every widget MUST include a `variableMap` that maps each display variable to a field in the widget's schema:
 
-Update-record action using the trigger record:
+- **Same schema as variable**: bind to the same display field (e.g., `project-name`)
+- **Different schema**: bind to the ReferenceField pointing to the variable's schema (e.g., `task-project`)
+- **No filtering**: set to `null`
 
 ```bash
-zinkee --json automations actions add automation-1 \
-  --type update_record \
-  --name "Update trigger record" \
-  --target-schema followups \
-  --map status=ready \
-  --use-trigger-record
+# Table widget (--field accepts slugs)
+zinkee --json displays widgets create <display-uuid> \
+  --type TABLE_OR_SUBTABLE \
+  --name "Tasks" \
+  --origin-resource <tasks-schema-uuid> \
+  --field task-code \
+  --field task-title \
+  --field task-status \
+  --raw '{"bindings":{"variableMap":{"<variable-uuid>":"<task-project-field-uuid>"}}}'
+
+# KPI widget
+zinkee --json displays widgets create <display-uuid> \
+  --type KPI \
+  --name "Total Hours" \
+  --origin-resource <hours-schema-uuid> \
+  --raw '{
+    "bindings":{"variableMap":{"<variable-uuid>":"<hours-project-field-uuid>"}},
+    "kpi":{"typeCalc":"SUM","fieldCalc":"hours-field-slug"}
+  }'
+
+# Chart widget (valid types: lines, bars, stackedBars, combined)
+zinkee --json displays widgets create <display-uuid> \
+  --type CHART \
+  --name "Hours by Employee" \
+  --origin-resource <hours-schema-uuid> \
+  --chart-type bars \
+  --x-axis-field employee-field-slug \
+  --raw '{
+    "bindings":{"variableMap":{"<variable-uuid>":"<hours-project-field-uuid>"}},
+    "chart":{"yAxisSeries":[{"typeCalc":"SUM","fieldCalc":"hours-field-slug","axisType":"PRIMARY"}]}
+  }'
+
+# KANBAN, TIMELINE, DETAIL also supported
 ```
 
-When `--use-trigger-record` is enabled, the CLI does not send `conditions`.
+Widget types: `TABLE_OR_SUBTABLE`, `DETAIL`, `KPI`, `CHART`, `TIMELINE`, `KANBAN`, `HIERARCHY`.
 
-HTTP request action:
+### Set freeform layout
+
+After creating widgets, position them on a 12-column grid:
 
 ```bash
-zinkee --json automations actions add automation-1 \
-  --type http_request \
-  --name "Notify ERP" \
-  --method POST \
-  --url https://example.com/integrations/order-status \
-  --header X-Demo=cli \
-  --body '{"event":"order.status.changed"}' \
-  --content-type application/json \
-  --timeout-ms 5000
+zinkee displays layout update <display-uuid> --template freeform --freeform-layouts '{
+  "lg": [
+    {"i":"<kpi-widget-uuid>","x":0,"y":0,"w":3,"h":4},
+    {"i":"<kpi-widget-uuid>","x":3,"y":0,"w":3,"h":4},
+    {"i":"<table-widget-uuid>","x":0,"y":4,"w":12,"h":10}
+  ]
+}'
 ```
 
-HTTP request action with stored auth:
+### KPI with filters
+
+The `--filter` flag doesn't work on KPI widgets. Pass filters in `--raw`:
 
 ```bash
-zinkee --json automations actions add automation-1 \
-  --type http_request \
-  --name "Notify ERP" \
-  --method POST \
-  --url https://example.com/integrations/order-status \
-  --content-type application/json \
-  --auth-mode STORED \
-  --connection 550e8400-e29b-41d4-a716-446655440001
+--raw '{"query":{"filters":[{"fieldId":"<field-uuid>","operator":"EQUALS","value":"2"}]}}'
 ```
 
-Execute-plugin action:
+### Slug support
+
+Slugs are resolved to UUIDs in: `--field`, `--source-schema`, `--source-field`, `--x-axis-field`, `kpi.fieldCalc`, `chart.xAxisFieldId`, `chart.yAxisSeries[].fieldCalc`, `bindings.variableMap` values.
+
+Display UUIDs are required for `displays widgets create/update` and `displays variables create`.
+
+---
+
+## Automations
+
+Automations execute actions in response to triggers (record events, schedules, webhooks).
+
+### Creation flow
+
+1. Create automation with trigger
+2. Add actions
+3. Wire the flow (connect trigger → actions → actions)
+4. Activate
+
+### Trigger types
 
 ```bash
-zinkee --json automations actions add automation-1 \
-  --type execute_plugin \
-  --name "Run plugin" \
-  --plugin clone-budget \
-  --arg mode=safe \
-  --arg-json payload='{"dryRun":true}'
+# Scheduled (six-field cron — includes seconds)
+zinkee --json automations create \
+  --name "Weekly report" \
+  --trigger-type scheduled \
+  --cron "0 15 10 * * 1"
+
+# Record created (requires at least one --condition)
+zinkee --json automations create \
+  --name "High priority task" \
+  --trigger-type record_created \
+  --trigger-schema tasks \
+  --condition priority:eq:3
+
+# Record changed (requires --trigger-field)
+zinkee --json automations create \
+  --name "Status change" \
+  --trigger-type record_changed \
+  --trigger-schema tasks \
+  --trigger-field status
+
+# Webhook
+zinkee --json automations create \
+  --name "External webhook" \
+  --trigger-type webhook
 ```
 
-Update an existing action:
+Valid trigger types: `scheduled`, `record_created`, `record_changed`, `webhook`.
+
+### Action types
 
 ```bash
-zinkee --json automations actions update automation-1 action-1 \
+# Create record with literal and trigger-sourced values
+zinkee --json automations actions add <automation-uuid> \
+  --type create_record \
+  --name "Create time entry" \
+  --target-schema time-entries \
+  --map description="Auto-created" \
+  --map hours=0 \
+  --map-json project='{"rawValue":null,"source":{"type":"TRIGGER","id":"<project-field-uuid>"}}'
+
+# Update the trigger record
+zinkee --json automations actions add <automation-uuid> \
   --type update_record \
-  --name "Update trigger record" \
-  --target-schema followups \
-  --map status=ready \
-  --use-trigger-record
-```
+  --name "Mark as processed" \
+  --target-schema tasks \
+  --use-trigger-record \
+  --map processed=true
 
-### Flow Wiring
+# Search records
+zinkee --json automations actions add <automation-uuid> \
+  --type search_records \
+  --name "Find related" \
+  --target-schema time-entries \
+  --condition-json '{"field":"project","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"<project-field-uuid>"}}]}'
 
-Use `flow set` after you have action ids:
+# HTTP request
+zinkee --json automations actions add <automation-uuid> \
+  --type http_request \
+  --name "Notify webhook" \
+  --method POST \
+  --url https://example.com/hook \
+  --content-type application/json \
+  --body '{"event":"task.created"}'
 
-```bash
-zinkee --json automations flow set automation-1 \
-  --entry action-1 \
-  --transition action-1:action-2 \
-  --transition action-2:action-3
+# Execute plugin
+zinkee --json automations actions add <automation-uuid> \
+  --type execute_plugin \
+  --name "Clone budget" \
+  --plugin clone-budget \
+  --arg mode=safe
 ```
 
-The resulting payload uses:
+Valid action types: `create_record`, `update_record`, `search_records`, `send_message`, `http_request`, `execute_plugin`.
 
-- `entryActionIds`
-- `transitions[].fromActionId`
-- `transitions[].toActionId`
+### Field mapping format
 
-### Webhook Automations
+- `--map field=value` → `{"rawValue":"value","source":null}` (literal)
+- `--map-json field='{"rawValue":null,"source":{"type":"TRIGGER","id":"<field-uuid>"}}'` (from trigger)
+- `source.type` values: `TRIGGER`, `PREVIOUS_ACTION`
+- `source.id` must be a field UUID — slugs are not resolved here
 
-The webhook endpoint configuration is a separate resource from the trigger itself.
+### Flow wiring
 
-Configure webhook ingestion for an automation:
+Actions are NOT auto-wired. Connect them explicitly:
 
 ```bash
-zinkee --json automations webhook set automation-1 \
-  --active \
-  --idempotency-key-path "$.id" \
-  --event-type-path "$.type" \
-  --allowed-event-type frontend.demo.created \
-  --field-mapping '{"variable":"external_id","jsonPath":"$.data.id"}'
+zinkee --json automations flow set <automation-uuid> \
+  --entry <action-1-uuid> \
+  --transition <action-1-uuid>:<action-2-uuid> \
+  --transition <action-2-uuid>:<action-3-uuid>
 ```
 
-Read the generated endpoint details:
+### Activate / deactivate
 
 ```bash
-zinkee --json automations webhook get automation-1
+zinkee automations activate <automation-uuid>
+zinkee automations deactivate <automation-uuid>
 ```
 
-If you want the automation trigger itself to be webhook-based:
+### Webhook configuration
 
 ```bash
-zinkee --json automations trigger set automation-1 --trigger-type webhook
-```
+zinkee --json automations webhook set <automation-uuid> \
+  --active \
+  --idempotency-key-path "$.id" \
+  --event-type-path "$.type" \
+  --allowed-event-type order.created \
+  --field-mapping '{"variable":"external_id","jsonPath":"$.data.id"}'
 
-### Stored Connections
+zinkee --json automations webhook get <automation-uuid>
+```
 
-Create a stored connection for `http_request` actions:
+### Stored connections
 
 ```bash
 zinkee --json automations connections create \
@@ -361,35 +546,30 @@ zinkee --json automations connections create \
   --config '{"headerName":"Authorization"}' \
   --secret apiKey=super-secret \
   --active
+
+zinkee --json automations connections list
 ```
 
-Patch a stored connection:
+### Troubleshooting
 
-```bash
-zinkee --json automations connections update connection-1 \
-  --raw '{"set":{"name":"ERP API Key Updated","config":{"headerName":"Authorization"}}}'
-```
+- `Automation payload is invalid` → trigger is missing or malformed
+- Use `scheduled` (not `schedule`) as trigger type
+- Cron must be six fields (includes seconds): `"0 15 10 * * 1"`
+- `record_created` requires at least one `--condition`
+- `record_changed` requires at least one `--trigger-field`
+- Actions must be wired with `flow set` before they execute
+- Use `--json --example automations <subcommand>` for canonical examples
 
-### Patching Automations
+---
 
-`automations update` uses the backend patch contract with `set` and `unset`.
+## Discovery
 
 ```bash
-zinkee --json automations update automation-1 \
-  --raw '{"set":{"description":"Updated by CLI docs"},"unset":["folderId"]}'
+zinkee --json schemas list
+zinkee --json schemas fields list <schema>
+zinkee --json displays list
+zinkee --json automations list
+zinkee --json automations plugins list
+zinkee --json automations connections list
+zinkee --example <command path>
 ```
-
-Supported metadata patch paths:
-
-- `name`
-- `description`
-- `folderId`
-
-### Troubleshooting
-
-- `Automation payload is invalid` during create usually means the trigger is missing or malformed.
-- `scheduled` is the correct trigger type, not `schedule`.
-- Use a six-field cron expression for `scheduled`.
-- `record_changed` requires at least one `--trigger-field`.
-- Record-based triggers only work with real schema and field UUIDs or slugs from your workspace.
-- `zinkee --json --example automations <subcommand>` returns canonical command recipes without executing the command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI for Zinkee API v2",
   "type": "module",
   "bin": {