@docyrus/docyrus 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",

package/resources/pi-agent/skills/docyrus-platform/references/automation-and-workflows.md

@@ -2,29 +2,52 @@
 
 ## Automation Engine
 
-Define event-driven workflows with triggers and action chains:
-
-**Triggers:**
-
-- Record created, modified, or deleted
-- Time-based (after a period, recurring interval)
-- Webhook (external event)
-- Button activation (user action)
-- Previous action (chaining)
-- AI agent (agent-triggered)
-
-**Actions:**
-
-- Send email
-- Send notification
-- Create record
-- Update records
-- Request input
-- Request approval
-- Trigger HTTP request
-- AI prompt
-- AI agent execution
-- Data source query
-- Custom query execution
-
-Automations support conditional flows, action chains, and soft-delete (archiving).
+Define event-driven workflows with triggers and action chains. Each automation belongs to a tenant app and combines one or more triggers with a graph of typed action nodes.
+
+## Trigger Types
+
+The runtime supports ten trigger types. The dev API exposes each as a typed endpoint, and the CLI exposes the same set under `docyrus automation create-trigger --type <kebab-case>`.
+
+- `record-created` — fires when a record is inserted into the source data source
+- `record-modified` — fires when specific columns change (with `all` / `any` match mode)
+- `record-deleted` — fires when a record is removed from the source data source
+- `recurrence` — fires on a cron-like schedule (hour / day / week / month / year, with run-at time and weekday/month-day options)
+- `app-event` — fires from a connector or core data-provider event (with optional webhook binding)
+- `webhook` — fires when an external HTTP webhook is received
+- `emailhook` — fires when a tenant-bound inbound email is received
+- `webform` — fires when a public webform is submitted
+- `button-activation` — fires when a user activates an in-UI button on a record
+- `manual-activation` — fires when a record is manually activated via the UI
+
+The platform also tracks `max_run_per_record` for record-* and recurrence triggers to prevent re-firing on the same record.
+
+## Action Node Types
+
+Action nodes are the building blocks of an automation's execution graph. The dev API exposes each as a typed endpoint, and the CLI exposes the same set under `docyrus automation create-node --type <kebab-case>`.
+
+- `external-action` — invokes a registered `core_action` against a connector (requires `action_type_id`; backend validates payload against `core_action.input_json_schema` and provisions the `tenant_action` row)
+- `send-email` — sends an email through a tenant email account or template
+- `send-notification` — pushes an in-app or device notification
+- `create-record` — inserts a record into a target data source
+- `update-records` — bulk-updates records in a target data source (optionally pivoted on a target field)
+- `request-approval` — opens an approval cycle against an input data source
+- `request-input` — collects ad-hoc input from a user via the input data source
+- `http-request` — fires an HTTP request (supports batch mode, transformers, and connection auth)
+- `data-source-query` — runs a data source query and emits the result into the chain
+- `custom-query` — runs a saved custom SQL query
+- `generate-document` — renders an HTML/PDF/DOCX template against a record
+- `ai-prompt` — runs a stored prompt against an AI provider
+- `ai-agent` — invokes a Docyrus AI agent
+- `execute-script` — runs a sandboxed JavaScript snippet
+- `wait-for` — bridge action that delays the next step. Does no work itself; forwards input data unchanged and queues the next step(s) with `tenant_job_queue.process_after = clock_timestamp() + delaySeconds` so the worker defers execution. Configure via `data.delaySeconds` (integer, ≤ 30 days) or the `data.delayValue` + `data.delayUnit` (`seconds`/`minutes`/`hours`/`days`) pair.
+
+## Composition Features
+
+- Conditional branches via per-node `condition` payloads
+- Action chains with parent/child wiring (`parent` node id)
+- Field mappings (`field_mapping`, `dynamic_field_mapping`) for record-shaped nodes
+- Request lifecycle hooks (`pre_action_request`, `post_action_request`) on external-action nodes
+- Input/output transformers (`input_template`, `input_transformer`, `output_transformer`, `batch_transformer`, `error_transformer`) on http-request nodes
+- Custom headers (`custom_headers`) for http-request nodes
+- Target data source conditions (`target_data_source_condition`) on update-records and external-action nodes
+- Soft-delete (archiving) for both automations and individual nodes

package/resources/pi-agent/skills/docyrus-platform/references/developer-tools.md

@@ -14,7 +14,7 @@
 ## CLI
 
 - Full-featured CLI (`@docyrus/docyrus`) for terminal and AI agent use
-- Commands: environment management, authentication, data operations, record comments, record file attachments, schema management (studio), app management, API discovery, AI chat, and direct API requests
+- Commands: environment management, authentication, data operations, record comments, record file attachments, schema management (studio: data sources, fields, enums, data views, forms, webforms, HTML/PDF/DOCX export templates, email templates), automation management (automation, trigger, and action node CRUD), tenant email account discovery and transactional email send (messaging), app management, API discovery, connector discovery and provider-auth requests, AI chat, and direct API requests
 - Multi-account, multi-tenant session management
 - OpenAPI discovery with caching and fallback generation
 - Interactive TUI mode

package/resources/pi-agent/skills/docyrus-platform/references/docyrus-cli-usage.md

@@ -871,6 +871,229 @@ Same options as `create-email-template`, plus `--templateId` (required).
 
 ---
 
+## automation — Automations, Triggers, and Action Nodes
+
+Manage automations, their triggers, and their action nodes for a tenant app. All commands route through `/v1/dev/apps/:appId/automations`.
+
+**Common selector rules:**
+- App: exactly one of `--appId` or `--appSlug`
+- Automation: `--automationId` (no slug — automations and nodes are ID-only)
+- Trigger `--type` (URL kebab-case): `record-created`, `record-modified`, `record-deleted`, `recurrence`, `app-event`, `webhook`, `emailhook`, `webform`, `button-activation`, `manual-activation`
+- Node `--type` (URL kebab-case): `external-action`, `send-email`, `send-notification`, `create-record`, `update-records`, `request-approval`, `request-input`, `http-request`, `data-source-query`, `custom-query`, `generate-document`, `ai-prompt`, `ai-agent`, `execute-script`, `wait-for`
+
+**Write payload rules:**
+- Write commands accept `--data '<json>'` or `--from-file ./payload.json` (JSON only)
+- Convenience flags are camelCase and are converted to `snake_case` in the request body
+- Nested objects (trigger `data`; node `data`, `field_mapping`, `dynamic_field_mapping`, `condition`, `input_template`, `input_transformer`, `custom_headers`, `pre_action_request`, `post_action_request`, `target_data_source_condition`) must be supplied via `--data` / `--from-file` — the CLI does not flatten them
+- `delete`, `delete-trigger`, and `delete-node` return `{ deleted: true, id }` (API itself returns 204)
+
+### Automation CRUD
+
+#### `docyrus automation list`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+
+#### `docyrus automation get`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--automationId` | string | Automation ID (required) |
+
+#### `docyrus automation create`
+
+Creates an automation together with its first trigger. `--triggerType` uses camelCase (`recordCreated`, `recordModified`, `recordDeleted`, `recurrence`, `appEvent`, `webhook`, `emailhook`, `webform`, `buttonActivation`, `manualActivation`) to match `CreateAutomationDto.trigger_type`.
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--data` | string | JSON payload |
+| `--fromFile` | string | Path to JSON file |
+| `--name` | string | Automation name |
+| `--triggerType` | string | Initial trigger type (camelCase) |
+| `--status` | number | Automation status |
+| `--sourceDataSourceId` | string | Source data source ID |
+| `--triggerDataSourceId` | string | Trigger data source ID |
+| `--triggerDataProviderId` | string | Trigger data provider ID |
+| `--triggerWebhookId` | string | Trigger webhook ID |
+
+#### `docyrus automation update`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--automationId` | string | Automation ID (required) |
+| `--data / --fromFile` | string | JSON payload / file |
+| `--name` | string | Automation name |
+| `--status` | number | Automation status |
+| `--sourceDataSourceId` | string | Source data source ID |
+
+#### `docyrus automation delete`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--automationId` | string | Automation ID (required) |
+
+### Trigger CRUD
+
+#### `docyrus automation list-triggers`
+
+Derived from the automation GET response.
+
+#### `docyrus automation get-trigger`
+
+Same options as `list-triggers`, plus `--triggerId` (required).
+
+#### `docyrus automation create-trigger`
+
+Routes through `POST .../triggers/:type`.
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--automationId` | string | Automation ID (required) |
+| `--type` | string | Trigger type (kebab-case, required) |
+| `--data / --fromFile` | string | JSON payload / file |
+| `--active` | boolean | Whether the trigger is active |
+| `--sourceDataSourceId` | string | Source data source (record-*, recurrence, button/manual) |
+| `--maxRunPerRecord` | number | Max runs per record (record-*, recurrence) |
+| `--modifiedColumns` | string | Comma-separated columns (record-modified) |
+| `--modifiedColumnsCondition` | string | `all` or `any` (record-modified) |
+| `--recurrenceFrequency` | string | `hour`, `day`, `week`, `month`, `year` (recurrence) |
+| `--recurrenceInterval` | number | Recurrence interval (recurrence) |
+| `--recurrenceMinutes` | number | Minutes `0\|15\|30\|45` (recurrence) |
+| `--recurrenceWeekDays` | string | Comma-separated week days `MON,TUE,...` (recurrence) |
+| `--recurrenceMonthDays` | string | `DAY_OF_MONTH` or `DAY_OF_WEEK` (recurrence) |
+| `--recurrenceStartDate` | string | ISO date (recurrence) |
+| `--recurrenceEndDate` | string | ISO date (recurrence) |
+| `--recurrenceRunAt` | string | `HH:mm` (recurrence) |
+| `--coreDataProviderId` | string | Core data provider ID (app-event) |
+| `--coreDataProviderWebhookId` | string | Core data provider webhook ID (app-event) |
+| `--webhookId` | string | Webhook ID (webhook, emailhook) |
+| `--webhookName` | string | Name for auto-created webhook (webhook, emailhook) |
+| `--tenantWebformId` | string | Tenant webform ID (webform) |
+
+#### `docyrus automation update-trigger`
+
+Routes through `PATCH .../triggers/:type/:triggerId`. Same flags as `create-trigger`, plus `--triggerId` (required).
+
+#### `docyrus automation delete-trigger`
+
+Routes through `DELETE .../triggers/:triggerId` (type-independent).
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--automationId` | string | Automation ID (required) |
+| `--triggerId` | string | Trigger ID (required) |
+
+### Action Node CRUD
+
+#### `docyrus automation list-nodes`
+
+`GET .../nodes`
+
+#### `docyrus automation get-node`
+
+`GET .../nodes/:nodeId`
+
+#### `docyrus automation create-node`
+
+Routes through `POST .../nodes/:type`. `external-action` create requires `--actionTypeId`; the backend validates `data` against `core_action.input_json_schema` and provisions the `tenant_action` row in the same transaction.
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--automationId` | string | Automation ID (required) |
+| `--type` | string | Node type (kebab-case, required) |
+| `--data / --fromFile` | string | JSON payload / file |
+| `--name` | string | Node name |
+| `--description` | string | Node description |
+| `--subType` | string | Sub type discriminator |
+| `--parent` | string | Parent node ID |
+| `--active` | boolean | Whether the node is active |
+| `--actionTypeId` | string | Action type ID (required for external-action create; maps to `core_action.id`) |
+| `--sourceDataSourceId` | string | Source data source ID (external-action) |
+| `--targetDataSourceId` | string | Target data source ID (create-record, update-records, http-request, data-source-query, external-action) |
+| `--targetDataSourceFieldId` | string | Target data source field ID (update-records) |
+| `--connectionId` | string | Connection ID (http-request, external-action) |
+| `--connectionAccountId` | string | Connection account ID (http-request, external-action) |
+| `--webhookId` | string | Webhook ID (external-action) |
+| `--inputDataSourceId` | string | Input data source ID (request-approval, request-input) |
+| `--requestMethod` | string | HTTP method (http-request): `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
+| `--contentType` | string | HTTP content type (http-request) |
+| `--customEndpoint` | string | HTTP endpoint (http-request) |
+| `--relativeEndpoint` | boolean | Whether the endpoint is relative to the connection base URL (http-request) |
+| `--batch` | boolean | Whether to send the HTTP request in batches (http-request) |
+| `--batchSize` | number | HTTP batch size 1..10000 (http-request) |
+| `--outputTransformer` | string | Output transformer expression (http-request) |
+| `--batchTransformer` | string | Batch transformer expression (http-request) |
+| `--errorTransformer` | string | Error transformer expression (http-request) |
+
+`wait-for` nodes accept no flat convenience flags beyond the common base — supply `data.delaySeconds` (integer ≤ 30 days) or the `data.delayValue` + `data.delayUnit` pair (`seconds` / `minutes` / `hours` / `days`) via `--data` / `--from-file`. The action forwards input through unchanged and queues the next step(s) with a deferred `tenant_job_queue.process_after`.
+
+```sh
+docyrus automation create-node \
+  --appSlug crm \
+  --automationId 9c4f… \
+  --type wait-for \
+  --name "Wait 2 hours" \
+  --parent <previous-node-id> \
+  --data '{"data":{"delayValue":2,"delayUnit":"hours"}}'
+```
+
+#### `docyrus automation update-node`
+
+Routes through `PATCH .../nodes/:type/:nodeId`. Same flags as `create-node`, plus `--nodeId` (required).
+
+#### `docyrus automation delete-node`
+
+Routes through `DELETE .../nodes/:nodeId` (type-independent).
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--automationId` | string | Automation ID (required) |
+| `--nodeId` | string | Node ID (required) |
+
+---
+
+## messaging — Tenant Email Accounts and Send
+
+List tenant email accounts and send transactional emails. Routes through `/v1/messaging/email/*` and requires the `Messaging.Email.Send` OAuth2 scope. Credentials are never returned.
+
+### `docyrus messaging accounts`
+
+`GET /messaging/email/accounts`
+
+Returns active tenant email accounts. Each item exposes `id`, `name`, `provider`, `senderEmail`, `senderName`, `isUserAccessible`, `allowOverrideName`, `allowOverrideEmail`, `createdOn`.
+
+### `docyrus messaging email send`
+
+`POST /messaging/email/accounts/:accountId/send`
+
+| Option | Type | Description |
+|---|---|---|
+| `--accountId` | string | Tenant email account UUID (required) |
+| `--to` | string | Comma-separated recipient addresses |
+| `--cc` | string | Comma-separated CC addresses |
+| `--bcc` | string | Comma-separated BCC addresses |
+| `--replyTo` | string | Comma-separated reply-to addresses |
+| `--subject` | string | Subject (max 998 chars) |
+| `--body` | string | HTML or text body (max 1 000 000 chars) |
+| `--sendAsUser` | boolean | Send using the authenticated user's identity when the account allows the override |
+| `--data` | string | Full JSON payload; overrides individual flags when set |
+| `--fromFile` | string | Read full JSON payload from a JSON file |
+
+Limits: up to 50 addresses per recipient list, up to 10 attachments. Attachments are `{ filePath, fileName?, mimeType? }` with `filePath` referencing a tenant-scoped storage path.
+
+Response payload: `{ messageId, provider, accepted, rejected }`.
+
+---
+
 ## curl — Direct API Requests
 
 ### `docyrus curl <path>`

package/resources/pi-agent/skills/docyrus-platform/references/integrations-and-events.md

@@ -58,3 +58,6 @@
 - Custom HTML email templates with dynamic content
 - Email configuration management
 - Delivery tracking and webhook integration
+- Tenant email accounts with per-provider credentials, optional user-level identity override, and send-as-user enforcement
+- Send endpoint `POST /v1/messaging/email/accounts/{accountId}/send` (scope `Messaging.Email.Send`) with multi-recipient `to`/`cc`/`bcc`/`replyTo`, HTML or text body, and up to 10 storage-backed attachments
+- Account discovery via `GET /v1/messaging/email/accounts` (credentials are never returned; the response exposes provider, sender identity, and override flags)