zinkee 0.1.0

package/AGENTS.md

@@ -0,0 +1,46 @@
+# Zinkee CLI Notes
+
+This repository contains a TypeScript ESM CLI for Zinkee API v2.
+
+## Source Of Truth
+
+Use this order when reasoning about behavior:
+
+1. live command registration in `src/index.ts`
+2. command modules in `src/commands`
+3. docs in `README.md`
+
+## Key Runtime Rules
+
+- Existing config compatibility is mandatory: `~/.config/zinkee/config.toml`
+- `--read-only` must block write/destructive commands before network calls
+- `--example <command path>` should return concrete usage examples without running the command
+- `--json` must keep stdout machine-readable
+- success JSON shape is `{ data, meta }`
+- error JSON shape is `{ error, meta }`
+
+## Current Command Groups
+
+- `profiles`
+- `config`
+- `files`
+- `schemas`
+- `records`
+- `comments`
+- `navigation`
+- `teamspace`
+- `displays`
+- `automations`
+
+## Implementation Shape
+
+- REST transport lives in `src/api`
+- commander commands live in `src/commands`
+- shared config/runtime lives in `src/config.ts` and `src/runtime-context.ts`
+- JSON/table output helpers live in `src/utils/output.ts`
+- shared CLI error handling lives in `src/utils/errors.ts`
+- parsers live in `src/parsers`
+
+## Testing
+
+Prefer focused command tests and parser/client unit tests.

package/README.md

@@ -0,0 +1,395 @@
+# Zinkee CLI
+
+Command-line interface for Zinkee Public API v2.
+
+## Status
+
+Implemented command groups:
+
+- `profiles`
+- `config`
+- `files`
+- `schemas`
+- `records`
+- `comments`
+- `navigation`
+- `teamspace`
+- `displays`
+- `automations`
+
+## Requirements
+
+- Node.js 20+
+
+## Install Dependencies
+
+```bash
+npm install
+```
+
+## Development
+
+```bash
+npm run build
+npm run typecheck
+npm test
+```
+
+## Configuration
+
+The CLI is compatible with the existing config file:
+
+```text
+~/.config/zinkee/config.toml
+```
+
+Example:
+
+```toml
+default_profile = "prod"
+
+[profiles.prod]
+api_key = "token"
+base_url = "https://api.zinkee.com"
+```
+
+## Global Options
+
+- `--profile <name>`
+- `--base-url <url>`
+- `--api-key <token>`
+- `--read-only`
+- `--example <command path>`
+- `--json`
+
+## JSON Contract
+
+Successful commands emit:
+
+```json
+{
+  "data": {},
+  "meta": {}
+}
+```
+
+Failing commands emit:
+
+```json
+{
+  "error": {},
+  "meta": {}
+}
+```
+
+## Quick Examples
+
+```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
+```
+
+## Automations
+
+The `automations` group manages the full public automation surface:
+
+- automation folders
+- automation metadata
+- triggers
+- actions
+- flow wiring
+- webhook endpoint configuration
+- plugins
+- stored connections for HTTP actions
+
+If you are scripting, prefer `--json`. If you are discovering the CLI, prefer `--example <command path>`.
+
+### Before You Start
+
+- `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`.
+
+Useful discovery commands:
+
+```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
+```
+
+### Trigger Types
+
+Valid trigger types are:
+
+- `scheduled`
+- `record_created`
+- `record_changed`
+- `webhook`
+
+Minimal scheduled automation:
+
+```bash
+zinkee --json automations create \
+  --name "Nightly invoice sync" \
+  --trigger-type scheduled \
+  --cron "0 15 10 * * 1"
+```
+
+Record-created automation using a schema slug:
+
+```bash
+zinkee --json automations create \
+  --name "Lead welcome" \
+  --trigger-type record_created \
+  --trigger-schema leads
+```
+
+Record-changed automation using schema and field slugs:
+
+```bash
+zinkee --json automations create \
+  --name "Order status sync" \
+  --trigger-type record_changed \
+  --trigger-schema orders \
+  --trigger-field status
+```
+
+Replace the trigger on an existing automation:
+
+```bash
+zinkee --json automations trigger set automation-1 \
+  --trigger-type record_changed \
+  --trigger-schema orders \
+  --trigger-field status
+```
+
+Add trigger conditions:
+
+```bash
+zinkee --json automations trigger set automation-1 \
+  --trigger-type record_changed \
+  --trigger-schema orders \
+  --trigger-field status \
+  --condition status:eq:approved
+```
+
+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`.
+
+### Actions
+
+Valid action types are:
+
+- `create_record`
+- `update_record`
+- `search_records`
+- `send_message`
+- `http_request`
+- `execute_plugin`
+
+Notes:
+
+- `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`.
+
+Create-record action:
+
+```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"}}'
+```
+
+The CLI wraps `--map field=value` literals as:
+
+```json
+{
+  "rawValue": "value",
+  "source": null
+}
+```
+
+For source-based values, pass the full object through `--map-json`. Valid `source.type` values are `TRIGGER` and `PREVIOUS_ACTION`.
+
+Search-records action with a trigger-based condition:
+
+```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"}}]}'
+```
+
+Update-record action using the trigger record:
+
+```bash
+zinkee --json automations actions add automation-1 \
+  --type update_record \
+  --name "Update trigger record" \
+  --target-schema followups \
+  --map status=ready \
+  --use-trigger-record
+```
+
+When `--use-trigger-record` is enabled, the CLI does not send `conditions`.
+
+HTTP request action:
+
+```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
+```
+
+HTTP request action with stored auth:
+
+```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
+```
+
+Execute-plugin action:
+
+```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}'
+```
+
+Update an existing action:
+
+```bash
+zinkee --json automations actions update automation-1 action-1 \
+  --type update_record \
+  --name "Update trigger record" \
+  --target-schema followups \
+  --map status=ready \
+  --use-trigger-record
+```
+
+### Flow Wiring
+
+Use `flow set` after you have action ids:
+
+```bash
+zinkee --json automations flow set automation-1 \
+  --entry action-1 \
+  --transition action-1:action-2 \
+  --transition action-2:action-3
+```
+
+The resulting payload uses:
+
+- `entryActionIds`
+- `transitions[].fromActionId`
+- `transitions[].toActionId`
+
+### Webhook Automations
+
+The webhook endpoint configuration is a separate resource from the trigger itself.
+
+Configure webhook ingestion for an automation:
+
+```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"}'
+```
+
+Read the generated endpoint details:
+
+```bash
+zinkee --json automations webhook get automation-1
+```
+
+If you want the automation trigger itself to be webhook-based:
+
+```bash
+zinkee --json automations trigger set automation-1 --trigger-type webhook
+```
+
+### Stored Connections
+
+Create a stored connection for `http_request` actions:
+
+```bash
+zinkee --json automations connections create \
+  --name "ERP API Key" \
+  --type api_key \
+  --scope workspace \
+  --config '{"headerName":"Authorization"}' \
+  --secret apiKey=super-secret \
+  --active
+```
+
+Patch a stored connection:
+
+```bash
+zinkee --json automations connections update connection-1 \
+  --raw '{"set":{"name":"ERP API Key Updated","config":{"headerName":"Authorization"}}}'
+```
+
+### Patching Automations
+
+`automations update` uses the backend patch contract with `set` and `unset`.
+
+```bash
+zinkee --json automations update automation-1 \
+  --raw '{"set":{"description":"Updated by CLI docs"},"unset":["folderId"]}'
+```
+
+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/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+
+interface CommandIo {
+    write(chunk: string): unknown;
+}
+interface BuildProgramOptions {
+    configPath?: string;
+    stdout?: CommandIo;
+}
+declare function buildProgram(options?: BuildProgramOptions): Command;
+
+export { type BuildProgramOptions, buildProgram };