@lunnoa/client 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "TypeScript SDK for building applications on top of Lunnoa Automate — typed client for the Public API (agents, workflows, executions, entities, knowledge, queues), SSE agent chat streaming, and deployment-specific codegen",
   "type": "module",
   "main": "./dist/index.cjs",

package/skills/lunnoa-client/SKILL.md

@@ -222,7 +222,8 @@ await lunnoa.tables.upsertBySlug({
 - A workflow's manual-trigger input fields live on
   `workflows.get(id, { expansion: ['triggerNode'] })` →
   `triggerNode.value.customInputConfig` (each field: `id`, `label`,
-  `inputType`, `required`, `selectOptions`).
+  `inputType`, `required`, `selectOptions`). Declare them at deploy time
+  with `defineTrigger({ id: 'flow-control_trigger_manual', inputs })`.
 - `workflowApps.list()` resolves `executionPath` step `appId`/`actionId`
   pairs to human-readable names and icons.
 
@@ -351,11 +352,13 @@ Pure typed config (no network):
 import {
   defineAction,
   defineAgent,
+  defineTrigger,
   defineWorkflow,
 } from '@lunnoa/client';
 
 export const ping = defineWorkflow({
   slug: 'ping',
+  // Omit trigger for Manually Run with no input fields.
   steps: [
     {
       use: defineAction({
@@ -366,6 +369,24 @@ export const ping = defineWorkflow({
   ],
 });
 
+export const syncOrders = defineWorkflow({
+  slug: 'sync-orders',
+  trigger: defineTrigger({
+    id: 'flow-control_trigger_manual',
+    inputs: [
+      { id: 'invoiceId', label: 'Invoice', inputType: 'text', required: true },
+    ],
+  }),
+  steps: [
+    {
+      use: defineAction({
+        id: 'http_action_send-request',
+        input: { method: 'GET', url: 'https://example.com/orders' },
+      }),
+    },
+  ],
+});
+
 export const triage = defineAgent({
   slug: 'support-triage',
   // models[].id from `npx @lunnoa/client ai-connections list --json`
@@ -375,25 +396,42 @@ export const triage = defineAgent({
 });
 ```
 
-Ad-hoc multi-step run (one Execution, `source: SDK`):
+Ad-hoc multi-step run (one Execution, `source: SDK`). `runs.start` sends
+steps only. A `trigger` on the definition is ignored. Deploy to persist it.
 
 ```typescript
 const result = await lunnoa.runs.start(ping);
 // or lunnoa.runs.startAndWait(ping)
 ```
 
+One catalogue trigger per deployed workflow:
+
+- **Manually Run** (`flow-control_trigger_manual`): `inputs` is the caller
+  form. It is stored as `customInputConfig`. `workflows.execute(id, { invoiceId })`
+  passes those keys.
+- **Listen for Webhook** (`flow-control_trigger_listen-for-webhook`):
+  `input: { method: 'POST' }` (`PUT` or `GET` too).
+- **Recurring Schedule** (`flow-control_trigger_recurring-schedule`): `input`
+  from the catalogue (`start`, `rrule`). A schedule that cannot compute its
+  next run fails the deploy.
+- **Any other trigger:** `id` from `apps get`, optional `connection`, and
+  `input` copied from that trigger's `inputConfig`. Do not invent ids.
+
 Discover the catalogue **before** writing `defineAction` (do not guess ids):
 
 ```bash
 npx @lunnoa/client tools list --json --for-agent
 npx @lunnoa/client tools search email --json --for-agent
 npx @lunnoa/client tools get http_action_send-request --json
+npx @lunnoa/client apps get flow-control --json
 npx @lunnoa/client connections list --app gmail --json
 npx @lunnoa/client ai-connections list --json
 ```
 
 `tools get` returns `inputConfig` / `inputFields` and a `defineAction` sketch.
-`tools list` is compact; use `get` for the schema. `--json` is for coding agents.
+`tools list` is compact; use `get` for the schema. `apps get --json` returns
+`triggers[]` with `triggerId`, `inputFields`, and a `defineTrigger` sketch.
+`--json` is for coding agents. Do not invent trigger ids.
 
 `ai-connections list` returns the AI connections this key can assign to an
 agent. Set `defineAgent({ model })` to a `models[].id` from that JSON
@@ -554,7 +592,7 @@ with emails (capped; not Azure object IDs).
 3. Call `discovery.enabledFeatures()` and hide unsupported areas.
 4. Build forms/tables from `attributeSchema` / `customInputConfig` (or the generated types).
 5. Render workflow progress from `executionPath`; handle `NEEDS_INPUT` with `submitInput`.
-6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Deploy with `npx @lunnoa/client workflows|agents deploy`. Discover catalogue via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`). Discover agent models via `npx @lunnoa/client ai-connections list --json` (or `aiConnections.list()`).
+6. For single-action calls, use `actions.run`; for linear multi-step, use `runs.start` / `defineWorkflow`. Deploy with `npx @lunnoa/client workflows|agents deploy`. Discover actions via `npx @lunnoa/client tools list|get|search` (or `workflowApps.list()`). Discover triggers via `apps get <appId> --json` and pass `defineTrigger` on `defineWorkflow` (omit it for Manually Run with no fields). `runs.start` does not save the trigger. Discover agent models via `npx @lunnoa/client ai-connections list --json` (or `aiConnections.list()`).
 7. For Request Approval nodes, use `approvals.inbox` / `approvals.decide` (or `executions.submitApproval`).
 8. Chat: stream via SSE, handle resume (reconnects) and stop, load history from the task.
 9. Handle `LunnoaApiError`: 401 → re-auth; 403 → hide the capability; 429 → back off.

package/skills/lunnoa-solution-design/SKILL.md

@@ -85,7 +85,7 @@ interrogation.
 |---|---|---|
 | One catalogue call | `actions.run` | One-step Execution (`source: SDK`) |
 | Linear multi-step, experiment | `runs.start` / `defineWorkflow` then run | One Execution; optional later deploy |
-| Reusable automation + triggers | Saved **Workflow** (UI or CLI deploy) | Schedules/webhooks live on workflows |
+| Reusable automation + triggers | Saved **Workflow** (`defineWorkflow` + `defineTrigger`, or the UI) | Discover trigger ids with `apps get <appId> --json`. Omit `trigger` for Manually Run with no fields. `runs.start` ignores the trigger. |
 | Reasoning + tools + conversation | **Agent** | Tools = workflows, actions, knowledge |
 | Structured CRUD / portals | **Entities** + schemas | Codegen for typed accessors |
 | Reference / lookup data | **Tables** | `tables.upsertBySlug`; workflows use the Tables Lookup action |
@@ -115,9 +115,12 @@ interrogation.
 3. **Connections stay on Lunnoa.** Definitions only reference connection ids
    (or omit for sole/default resolution). Never ask the partner to put OAuth
    secrets in their app.
-4. **Do not invent catalogue actions or model ids.** Discover actions with
+4. **Do not invent catalogue action, trigger, or model ids.** Discover actions with
    `npx @lunnoa/client tools list|get|search --json` (or `workflowApps.list()`
-   / codegen). Discover models with
+   / codegen). Discover triggers with `npx @lunnoa/client apps get <appId> --json`
+   and use `triggers[].triggerId` in `defineTrigger`. `input` is that trigger's
+   catalogue config. On Manually Run, `inputs` is the caller form
+   (`customInputConfig`). Discover models with
    `npx @lunnoa/client ai-connections list --json` and use a returned
    `models[].id` (Lunnoa LLMs uses catalogue ids such as
    `deepseek-ai/DeepSeek-V4-Pro`). Client `defineAction` binds existing
@@ -142,6 +145,7 @@ interrogation.
 - Using `@lunnoa/toolkit` to build a customer portal
 - Designing a local LangChain loop instead of Lunnoa-hosted agents
 - Hardcoding `model: 'gpt-4o'` without reading `ai-connections list`
+- Inventing a trigger id, or expecting `runs.start` to save a webhook or schedule
 
 ---
 
@@ -162,6 +166,7 @@ can execute. Use this shape:
 
 ### Discovery (run first)
 - [ ] `npx @lunnoa/client tools list --json --for-agent` then `tools get <id>`
+- [ ] `npx @lunnoa/client apps get <appId> --json` before `defineTrigger`
 - [ ] `npx @lunnoa/client ai-connections list --json` before choosing an agent model
 - [ ] agents / workflows / entity-types / tables list — reuse before create
 - [ ] codegen — if building typed entity/workflow accessors