@flowrunner/cli 0.1.8 → 0.1.9-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +8 -8
  2. package/ai-docs/instructions/service-code-format/01-service-structure.md +4 -3
  3. package/ai-docs/instructions/service-code-format/02-zod-types.md +8 -0
  4. package/ai-docs/instructions/service-code-format/03-parameters.md +166 -10
  5. package/ai-docs/instructions/service-code-format/04-http-requests.md +19 -15
  6. package/ai-docs/instructions/service-code-format/05-dictionaries.md +14 -0
  7. package/ai-docs/instructions/service-code-format/06-oauth2.md +1 -5
  8. package/ai-docs/instructions/service-code-format/07-actions.md +18 -13
  9. package/ai-docs/instructions/service-code-format/11-output-model.md +42 -6
  10. package/ai-docs/instructions/service-code-format/12-service-readme.md +1 -1
  11. package/ai-docs/instructions/service-code-format/14-reference-service.md +5 -4
  12. package/ai-docs/instructions/service-code-format/15-unit-tests.md +2 -1
  13. package/ai-docs/instructions/service-code-format/16-gotchas.md +31 -1
  14. package/ai-docs/instructions/service-code-format/17-client-certificates.md +5 -3
  15. package/ai-docs/instructions/service-code-format/README.md +1 -1
  16. package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +1 -1
  17. package/dist/cli.js +285 -42
  18. package/dist/cli.js.map +3 -3
  19. package/dist/index.js +284 -41
  20. package/dist/index.js.map +3 -3
  21. package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  22. package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  23. package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  24. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  25. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  26. package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  27. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  28. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  29. package/dist/types/flow-extension-runner/src/v2/types.d.ts +21 -9
  30. package/dist/types/shared/src/constants/activity-log.d.ts +1496 -0
  31. package/dist/types/shared/src/constants/docs.d.ts +2 -0
  32. package/dist/types/shared/src/constants/notification-types.d.ts +11 -5
  33. package/dist/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  34. package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  35. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  36. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  37. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  38. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  39. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  40. package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  41. package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  42. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  43. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  44. package/package.json +1 -1
  45. package/runtime/index.js +267 -41
  46. package/runtime/index.js.map +3 -3
  47. package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
  48. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
  49. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
  50. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
  51. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
  52. package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
  53. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
  54. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
  55. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +21 -9
  56. package/runtime/types/shared/src/constants/activity-log.d.ts +1496 -0
  57. package/runtime/types/shared/src/constants/docs.d.ts +2 -0
  58. package/runtime/types/shared/src/constants/notification-types.d.ts +11 -5
  59. package/runtime/types/shared/src/scheme/activity-log-base.d.ts +35 -0
  60. package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
  61. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
  62. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
  63. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
  64. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
  65. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
  66. package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
  67. package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
  68. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
  69. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
  70. package/templates/blank/files/src/index.js +1 -1
  71. package/templates/demo-todo-list/files/src/index.js +7 -7
  72. package/templates/qa-test/files/src/index.js +33 -4
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # flowrunner-cli
1
+ # @flowrunner/cli
2
2
 
3
3
  **[FlowRunner](https://flowrunner.ai/)** is the orchestration layer for AI agents in production. Model
4
4
  providers and tools arrive as verified connectors, flows are built no-code or in code, and an agent facing a
@@ -17,9 +17,9 @@ server never has to execute extension code to model it.
17
17
  first one:
18
18
 
19
19
  ```bash
20
- npx flowrunner-cli init # set up the project in the current directory
21
- npx flowrunner-cli init -d my-extensions # ...or in ./my-extensions, creating it if needed
22
- npx flowrunner-cli init blank # ...and scaffold a first service from a template
20
+ npx @flowrunner/cli init # set up the project in the current directory
21
+ npx @flowrunner/cli init -d my-extensions # ...or in ./my-extensions, creating it if needed
22
+ npx @flowrunner/cli init blank # ...and scaffold a first service from a template
23
23
  ```
24
24
 
25
25
  Then work inside the project, where `flowrunner` is already available:
@@ -34,7 +34,7 @@ flowrunner --help
34
34
  Add the CLI to a repository you already have, then set it up in place:
35
35
 
36
36
  ```bash
37
- npm install --save-dev flowrunner-cli
37
+ npm install --save-dev @flowrunner/cli
38
38
  flowrunner init
39
39
  ```
40
40
 
@@ -44,7 +44,7 @@ repository is the same operation as starting from nothing, minus the files that
44
44
  ## Quick start
45
45
 
46
46
  ```bash
47
- npx flowrunner-cli init -d my-extensions blank # project + first service, npm install, git repo
47
+ npx @flowrunner/cli init -d my-extensions blank # project + first service, npm install, git repo
48
48
  cd my-extensions
49
49
  flowrunner login # browser authorization → .flowrunner/token
50
50
  flowrunner deploy # discover → model → hash → zip → upload
@@ -100,12 +100,12 @@ The harness is **copied** into the project, not linked, so it is yours to edit
100
100
  it. Running `flowrunner init` again in an existing project is how a project created before the harness
101
101
  existed gets one. `--no-tests` skips it.
102
102
 
103
- The full guide is in `node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/15-unit-tests.md`.
103
+ The full guide is in `node_modules/@flowrunner/cli/ai-docs/instructions/service-code-format/15-unit-tests.md`.
104
104
 
105
105
  ## Writing services with an AI agent
106
106
 
107
107
  This package ships the authoring reference itself, under
108
- `node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/`. That location is the point: the
108
+ `node_modules/@flowrunner/cli/ai-docs/instructions/service-code-format/`. That location is the point: the
109
109
  instructions your agent reads are pinned to the CLI version your project installed, so they describe the
110
110
  format this CLI actually deploys rather than whatever a model remembers about it.
111
111
 
@@ -73,7 +73,7 @@ const ext = Flowrunner.createExtension({
73
73
  configItems: z.object({ apiKey: z.string().label('API Key') }),
74
74
  initContext: ({ config, oauth }) => ({ apiKey: config.apiKey, accessToken: oauth?.accessToken }),
75
75
  apiRequest : async ({ url, method = 'get', body, query, context }) =>
76
- new Flowrunner.Request(url, method, body).set({ Authorization: `Bearer ${ context.apiKey }` }).query(query),
76
+ new Flowrunner.Request(url, method).set({ Authorization: `Bearer ${ context.apiKey }` }).query(query).send(body),
77
77
  helpers : ({ apiRequest }) => ({ collectPages: (url) => collectPages(apiRequest, url) }),
78
78
  })
79
79
  ```
@@ -85,8 +85,9 @@ const ext = Flowrunner.createExtension({
85
85
  service display label only; per-item human text is `label`.
86
86
  - **Ids must be unique across *all* kinds**, not just within one — an action and a dictionary cannot share
87
87
  an id, and registration fails with `FR_EXT_DUPLICATE_ITEM_ID` if they do. Generated loader names count
88
- too: an action `foo` with a loader `result` claims `foo_SampleResultLoader`, and `dynamicParams` claims
89
- `foo_DynamicParams`, so don't register anything under those names by hand.
88
+ too: an action `foo` with a loader `result` claims `foo_SampleResultLoader`, `dynamicParams` claims
89
+ `foo_DynamicParams`, and each param declared with `.dynamicProps()` claims `foo_<param>_DynamicProps`, so
90
+ don't register anything under those names by hand.
90
91
  - **A dictionary `id` starts with `get` and ends with `Dictionary`** — `getChatsDictionary`,
91
92
  `getBoardsDictionary`. Name the const holding the ref the same as the id, so the declaration and every
92
93
  `.dictionary(ref)` read alike.
@@ -18,6 +18,7 @@ and behaviors.
18
18
  | `z.union([...])` | the **first** branch's widget — see below | | | | |
19
19
  | `z.filesUploadOptions([...])`, `z.filesListOptions([...])`, `z.filesGetOptions([...])`, `z.filesDeleteOptions([...])` | nested form — the platform's own file-storage options, one group per Files call (see [03-parameters.md](03-parameters.md)) | | | | |
20
20
  | | | | `.secret()` | `z.string()` config field | Masks the input, with a reveal toggle. **Display only** — see below |
21
+ | | | | `.dynamicProps({ dependsOn, execute })` | top-level **action** param: `z.looseObject()` or `z.array(z.looseObject())` | the object's inner fields are loaded at design time from other params (see [03-parameters.md](03-parameters.md)) |
21
22
 
22
23
  Notes:
23
24
 
@@ -40,6 +41,13 @@ Notes:
40
41
  trigger param, whose value lives in the flow definition and is readable through the API — masking that
41
42
  input would suggest a protection that is not there. Put credentials in a `z.string()` config item.
42
43
  - `.dictionary(ref)` binds a param to a dictionary for dynamic options and auto-derives its `dependsOn`.
44
+ - `.dynamicProps({ dependsOn, execute })` loads the **inner fields** of an object param at design time, from
45
+ the values of the sibling params named in `dependsOn`. It is allowed on **top-level action params only**
46
+ (not on trigger params, config items, dictionary `criteria`, nested fields or an array's element), and the
47
+ field must be a **loose object** — `z.looseObject({...})`, or `z.array(z.looseObject({...}))` for a list
48
+ of objects — because the loaded keys are not in the declared schema and a plain `z.object()` would strip
49
+ them. Both are checked when the service loads. Not combinable with `.dictionary()` on the same field.
50
+ Details in [03-parameters.md](03-parameters.md#dynamic-properties--dynamicprops).
43
51
  - `.labels({ value: 'Label' })` gives each declared VALUE a display name. The dropdown shows the label, the
44
52
  flow element stores the value, and your handler receives the value — so **renaming a label never breaks a
45
53
  saved flow**. `.default(v)` takes a value, not a label.
@@ -54,8 +54,9 @@ item and the slot:
54
54
  received z.string(); omit `params` entirely if there is nothing to declare
55
55
  ```
56
56
 
57
- The same rule applies to every schema slot: `configItems`, a dictionary's `criteria`,
58
- `dynamicParams.criteria`, and the object `dynamicParams.resolve()` returns.
57
+ The same rule applies to every schema slot: `configItems` and a dictionary's `criteria`. What a params
58
+ loader's `execute()` returns — for `.dynamicProps()` and `dynamicParams` — is held to it too, but may also be a
59
+ plain shape of zod fields (see [Dynamic properties](#dynamic-properties--dynamicprops)).
59
60
 
60
61
  ## Shared param schemas — one plugin call per line
61
62
 
@@ -176,18 +177,173 @@ non-negotiable, and one before it is silently overridable.
176
177
 
177
178
  See [10-files-api.md](10-files-api.md) for what each option does.
178
179
 
180
+ ## Dynamic properties — `.dynamicProps()`
181
+
182
+ An object param whose **inner fields** are only known at design time — the columns of the table the user
183
+ picked, the custom fields of an account — declares them with `.dynamicProps()`. While a flow author configures
184
+ the block, the runtime calls your `execute`, and the fields it returns are drawn inside that param.
185
+
186
+ ```js
187
+ ext.addAction({
188
+ category : 'Records',
189
+ id : 'saveRecord',
190
+ label : 'Save Record',
191
+ description: 'Saves a record with the columns of the chosen table.',
192
+ params : z.object({
193
+ appId : z.string().label('App').dictionary(getAppsDictionary),
194
+ tableName: z.string().label('Table'),
195
+ fields : z.looseObject({ id: z.string().optional().label('ID') })
196
+ .label('Record Fields')
197
+ .optional()
198
+ .dynamicProps({
199
+ dependsOn: ['appId', 'tableName'],
200
+ execute : async ({ criteria, context, apiRequest }) => {
201
+ const columns = await apiRequest({ url: `/apps/${ criteria.appId }/tables/${ criteria.tableName }/columns`, context })
202
+
203
+ return Object.fromEntries(columns.map(column => [
204
+ column.name,
205
+ (column.type === 'number' ? z.number() : z.string()).optional().label(column.title),
206
+ ]))
207
+ },
208
+ }),
209
+ }),
210
+ result : { saved: {} },
211
+ execute: async ({ params }) => {
212
+ // params.fields = { id, …every loaded field the user filled in }
213
+ },
214
+ })
215
+ ```
216
+
217
+ | Property | Type | Description |
218
+ |---|---|---|
219
+ | `dependsOn` | `string[]` | Names of **sibling params** of the same `params` object whose values the loader needs. Optional — omit it (or pass `[]`) when the fields depend on nothing: the loader then runs once when the block's inputs open, and again when the connection changes. Each name must exist and may not be the field itself. |
220
+ | `execute` | fn | `({ criteria, config, context, helpers, apiRequest, oauth, files, filesScope, logger }) => shape \| z.object({...})` — the loaded fields. |
221
+
222
+ **`criteria` holds exactly the `dependsOn` values** — nothing else from the block — each validated and
223
+ coerced by that sibling's own schema, so a number arrives as a number, the same as in the action's handler.
224
+ A required sibling the user has not filled in yet fails with `FR_EXT_INVALID_CRITERIA` (the console shows the
225
+ dependency as missing instead of loading). The loader is re-run when one of the `dependsOn` values changes,
226
+ so a value your `execute` needs **must** be listed — one you read from outside `dependsOn` is never in
227
+ `criteria`.
228
+
229
+ **What `execute` returns** is a plain shape (`{ name: z.string().label('Name') }`, wrapped in `z.object()` for
230
+ you) or a `z.object({ … })`. It is held to the same rules as any params object — the same supported types and
231
+ plugins (see [02-zod-types.md](02-zod-types.md)), so `.label()`, `.optional()`, `.min()`,
232
+ `.dictionary(ref)` and the rest all work on a loaded field. Two things are refused: `.dynamicProps()` inside
233
+ the returned fields, and a key that repeats one the field already declares statically. Anything that is not a
234
+ shape or a `z.object` fails with `FR_EXT_INVALID_SCHEMA` when the loader runs — the one check that cannot
235
+ happen while the service loads, because the schema does not exist until `execute` runs.
236
+
237
+ **Static keys are kept.** Fields you declare inside the `z.looseObject({ … })` stay, validated as usual,
238
+ and are shown **first**; the loaded fields follow them.
239
+
240
+ **The field must be a loose object.** The loaded keys are not part of the declared schema, so a plain
241
+ `z.object()` would strip them before your handler sees them. `z.looseObject()` keeps them. For a **list of
242
+ objects**, put `.dynamicProps()` on the **array** and a loose object inside it:
243
+
244
+ ```js
245
+ rows: z.array(z.looseObject({})).label('Rows').dynamicProps(recordColumns)
246
+ ```
247
+
248
+ Not on the element — that is refused. Every item of the list uses the same loaded fields.
249
+
250
+ **Reuse a definition.** Hold `{ dependsOn, execute }` in a `const` and pass it to each field's
251
+ `.dynamicProps()`. The runtime generates one loader method per use and never changes the definition.
252
+
253
+ Placement and shape are checked when the service loads, so `flowrunner deploy` fails before uploading:
254
+
255
+ | Mistake | Error |
256
+ |---|---|
257
+ | Anywhere but a top-level **action** param (a nested field, an array's element, a trigger param, a config item, a dictionary's `criteria`) | `…uses \`.dynamicProps()\`, which is supported on top-level action params only.` |
258
+ | A field that is not a loose object | `…\`.dynamicProps()\` needs a loose object …` |
259
+ | `execute` missing or not a function | `…needs an \`execute\` function that returns the loaded fields.` |
260
+ | `dependsOn` not an array of strings | `…\`dependsOn\` must be an array of param names.` |
261
+ | `dependsOn` names a param that is not a sibling, or the field itself | `…depends on "x", which is not another param of this action.` |
262
+ | `.dynamicProps()` and `.dictionary()` on one field | `…declares both \`.dynamicProps()\` and \`.dictionary()\`.` |
263
+
264
+ All of them are `FR_EXT_INVALID_SCHEMA`; see [16-gotchas.md](16-gotchas.md).
265
+
266
+ ### What the flow author sees
267
+
268
+ The loaded fields render inside the param in the Flow Builder, as the fields of a dynamic schema do. When one
269
+ of the `dependsOn` values changes the fields are loaded again, and the values the author already entered are
270
+ **kept for every field the new list still returns**; only values whose field is no longer returned are
271
+ dropped, and only after the load succeeds — a failed load removes nothing.
272
+
273
+ On an **AI Agent tool** that calls your action, the loaded fields can be set by hand in the tool's panel to
274
+ pin some values; the model fills in the rest, as it does for any other param.
275
+
276
+ > **Loaded fields are not validated at run time.** The loaders run only while the inputs are being
277
+ > configured. When the action executes, your handler receives the loaded keys as the flow supplied them:
278
+ > a `required` loaded field the author left empty is **not** rejected, and a loaded field's `.min()` or enum
279
+ > is not re-checked. Validate in `execute` anything your handler cannot do without. Static keys — those
280
+ > declared in the `z.looseObject({ … })` — are validated as usual.
281
+
179
282
  ## Dynamic params — `dynamicParams`
180
283
 
181
- Generate additional top-level param fields at runtime (e.g. fields that depend on a chosen resource):
284
+ Where `.dynamicProps()` loads the fields **inside one param**, `dynamicParams` loads **extra top-level params of
285
+ the action** — fields that sit next to the static ones and depend on a chosen resource.
286
+
287
+ ```js
288
+ ext.addAction({
289
+ category: 'Records',
290
+ id : 'addRow',
291
+ // …
292
+ params : z.object({
293
+ tableName: z.string().label('Table'),
294
+ }),
295
+ dynamicParams: {
296
+ dependsOn: ['tableName'],
297
+ execute : async ({ criteria, context, apiRequest }) => {
298
+ const columns = await apiRequest({ url: `/tables/${ criteria.tableName }/columns`, context })
299
+
300
+ return Object.fromEntries(columns.map(column => [column.name, z.string().optional().label(column.title)]))
301
+ },
302
+ },
303
+ // …
304
+ })
305
+ ```
182
306
 
183
307
  | Property | Type | Description |
184
308
  |---|---|---|
185
- | `criteria` | `z.object` | Dependency inputs → become `dependsOn`. |
186
- | `resolve` | fn | `({ criteria, context, apiRequest }) => z.object({...})` — extra params merged into `params`. |
309
+ | `dependsOn` | `string[]` | Names of the action's **declared** `params` the loaded fields depend on. Optional; each name must exist in `params`. |
310
+ | `execute` | fn | `({ criteria, config, context, helpers, apiRequest, oauth, files, filesScope, logger }) => shape \| z.object({...})` — extra params merged into `params`. |
311
+
312
+ `criteria` follows the same rules as for `.dynamicProps()`: exactly the `dependsOn` values, coerced by the
313
+ declared schemas, `FR_EXT_INVALID_CRITERIA` when a required one is missing. `execute` may return a plain shape
314
+ or a `z.object`. A loaded field **may not share a name with a declared param** — it would shadow it — and
315
+ fails with `FR_EXT_INVALID_SCHEMA` when the loader runs.
316
+
317
+ The loaded fields reach your handler next to the static ones: an action with `dynamicParams` keeps the input
318
+ keys its static `params` do not declare. They are **not validated** at run time, as for `.dynamicProps()`.
319
+
320
+ The old shape `dynamicParams: { criteria, resolve }` is no longer accepted. The service fails to load with an
321
+ error naming the replacement — `criteria` becomes `dependsOn` (a list of names), `resolve` becomes `execute`,
322
+ and it returns a shape or a `z.object`.
323
+
324
+ ### The loader's response
325
+
326
+ Both loaders answer with the loaded fields twice, built from the same schema so they cannot disagree:
327
+
328
+ ```json
329
+ {
330
+ "paramsSchema": { "v": 1, "fields": [ { "name": "name", "type": "string", "meta": { "title": "Name" } } ] },
331
+ "params": [ { "name": "name", "required": true, "description": "", "type": "STRING", "label": "Name" } ]
332
+ }
333
+ ```
334
+
335
+ `paramsSchema` is the same encoded zod an action publishes for its own params; `params` is the field list with
336
+ the display metadata (label, widget, dictionary) inline. The loader's registered method is generated for you —
337
+ `<actionId>_DynamicParams` and `<actionId>_<param>_DynamicProps`, see
338
+ [01-service-structure.md](01-service-structure.md) — and is never listed in the service README.
339
+
340
+ ### Which one to use
187
341
 
188
- The `resolve` function returns a `z.object(...)` whose fields are merged into the static `params`. The
189
- declared `criteria` inputs become the `dependsOn` set that triggers re-resolution when they change.
342
+ | You want | Use |
343
+ |---|---|
344
+ | A fixed set of top-level params, some with a list of choices | static `params`; `.dictionary(ref)` for the choices |
345
+ | One object (or list of objects) whose inner fields depend on other params | `.dynamicProps()` on that param |
346
+ | Extra top-level params that appear next to the static ones | `dynamicParams` |
190
347
 
191
- `resolve` must return a `z.object` — anything else fails with `FR_EXT_INVALID_SCHEMA` when the console calls
192
- it. This is the one slot that cannot be checked while the service loads, since the schema does not exist
193
- until the resolver runs.
348
+ `.dictionary()` offers **values** for one field; `.dynamicProps()` and `dynamicParams` define **fields**. See
349
+ [05-dictionaries.md](05-dictionaries.md).
@@ -6,16 +6,16 @@ base URL, auth, envelope-unwrapping, error-normalization and redacted logging so
6
6
  declarative.
7
7
 
8
8
  ```js
9
- apiRequest: async ({ url, method = 'get', body, query, context }) =>
10
- new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
9
+ apiRequest: async ({ url, method = 'get', body, query, context }) => {
10
+ return new Flowrunner.Request(`${ context.apiUrl }${ url }`, method)
11
11
  .set({ Authorization: `Bearer ${ context.apiKey }` })
12
- .query(query),
12
+ .query(query)
13
+ .send(body)
14
+ }
13
15
  ```
14
16
 
15
- The constructor form takes the verb as a value, which is what you want when `method` arrives as an argument.
16
- Avoid `Flowrunner.Request[method.toLowerCase()](url)`: an object lookup keyed by a variable resolves
17
- inherited names such as `constructor` when the value is ever anything unexpected
18
- ([16-gotchas.md](16-gotchas.md)).
17
+ The constructor takes the verb as a value, in either case, so `method` passes straight through. Chain the
18
+ headers and query, and send the body last with `.send(body)`.
19
19
 
20
20
  ## `apiRequest` argument
21
21
 
@@ -44,10 +44,12 @@ const API_HOSTS = {
44
44
  geocode: 'https://geocoding.example.com/v1',
45
45
  }
46
46
 
47
- apiRequest: async ({ url, method = 'get', body, query, context, api = 'main' }) =>
48
- new Flowrunner.Request(`${ API_HOSTS[api] }${ url }`, method, body)
47
+ apiRequest: async ({ url, method = 'get', body, query, context, api = 'main' }) => {
48
+ return new Flowrunner.Request(`${ API_HOSTS[api] }${ url }`, method)
49
49
  .set({ Authorization: `Bearer ${ context.apiKey }` })
50
- .query(query),
50
+ .query(query)
51
+ .send(body)
52
+ }
51
53
  ```
52
54
 
53
55
  ```js
@@ -251,10 +253,12 @@ An API that requires mutual TLS needs a client certificate on **every** call, in
251
253
  request, so it belongs in `apiRequest` rather than in individual actions:
252
254
 
253
255
  ```js
254
- apiRequest: async ({ url, method = 'get', body, query, context }) =>
255
- new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
256
+ apiRequest: async ({ url, method = 'get', body, query, context }) => {
257
+ return new Flowrunner.Request(`${ context.apiUrl }${ url }`, method)
256
258
  .cert({ cert: context.clientCert, key: context.clientKey })
257
- .query(query),
259
+ .query(query)
260
+ .send(body)
261
+ }
258
262
  ```
259
263
 
260
264
  `.cert()` and its failure modes are [17-client-certificates.md](17-client-certificates.md); read it when the
@@ -272,8 +276,8 @@ A non-2xx **rejects** with a `ResponseError`:
272
276
  | `message` | the response body when there is one — **so it is not always a string** — else `Status Code <status> (<statusText>)`. A 502 is `No connection with server`. |
273
277
 
274
278
  Because `message` is the raw body for most JSON APIs, reading it as a string used to produce an unreadable
275
- `[object Object]`. The platform now renders an unhandled failure as the provider's response body — the
276
- Execute tab, a Run Block result and a flow's error exit all show that body rather than `[object Object]` —
279
+ `[object Object]`. The platform now renders an unhandled failure as the provider's response body — a method
280
+ run from the console, a Run Block result and a flow's error exit all show that body rather than `[object Object]` —
277
281
  so a service that does nothing still fails legibly.
278
282
 
279
283
  Normalising it yourself in `apiRequest` is still worth doing, and is still the main reason `apiRequest`
@@ -120,3 +120,17 @@ the parsed criteria (defaults applied, unknown fields dropped).
120
120
  `search` + `cursor` (+ a nested `criteria` object when `criteria` is declared) and puts the `"Payload"`
121
121
  label in `metaInfo.args`. You do **not** declare `search`/`cursor` yourself. See
122
122
  [11-output-model.md](11-output-model.md).
123
+
124
+ ## Dictionary or dynamic props?
125
+
126
+ Both react to other params, but they answer different questions:
127
+
128
+ | | `.dictionary(ref)` | `.dynamicProps()` / `dynamicParams` |
129
+ |---|---|---|
130
+ | Decides | the **values** one field may take (a dropdown's options) | which **fields** exist (the inner fields of an object, or extra params) |
131
+ | Runs | when the user opens the dropdown, with the typed `search` | when the block's inputs open and when a `dependsOn` value changes |
132
+ | Returns | `{ items: [{ label, value }], cursor }` | a shape or `z.object` of zod fields |
133
+
134
+ They are not combined on one field: `.dynamicProps()` and `.dictionary()` on the same param fails when the
135
+ service loads. A loaded field can itself carry `.dictionary(ref)`. See
136
+ [03-parameters.md](03-parameters.md#dynamic-properties--dynamicprops).
@@ -29,14 +29,10 @@ for the common case; any handler below overrides its step. Combined scopes = `sc
29
29
 
30
30
  `oauth` derives only from the `oauth-access-token` header → `oauth = { accessToken, token? }` (`token` =
31
31
  `deserializeToken(accessToken)`). Per-op opt-in for extra scopes: set `oauth2Scopes: ['extra.scope']` on
32
- any action, **polling** trigger, or dictionary.
32
+ any action, polling or realtime trigger, or dictionary.
33
33
 
34
34
  `token` is the one slot in the handler bag left open rather than inferred: `setupOauth2` runs after
35
35
  `createExtension` has already resolved the service shape, so a `deserializeToken` return cannot flow back
36
36
  into every handler. Annotate it where you read it if the composite shape matters.
37
37
 
38
- > Scopes declared on a **realtime** trigger are currently **not** collected into the authorize URL — the
39
- > runtime unions `scopes` with the `oauth2Scopes` of actions, polling triggers and dictionaries only. Put a
40
- > realtime trigger's scopes in the extension-level `scopes` instead.
41
-
42
38
  Client id/secret are typically `configItems` marked `.shared()` (see [02-zod-types.md](02-zod-types.md)).
@@ -9,7 +9,7 @@ Actions are the primary operations a service exposes. Register one with `ext.add
9
9
  | `label` | string | ✓ | Display name. |
10
10
  | `description` | string | ✓ | Description. |
11
11
  | `params` | `z.object` | – | Input params — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
12
- | `dynamicParams` | object | – | Runtime-generated params (see [03-parameters.md](03-parameters.md)). |
12
+ | `dynamicParams` | `{ dependsOn, execute }` | – | Extra top-level params loaded at design time (see [03-parameters.md](03-parameters.md#dynamic-params--dynamicparams)). An object param's inner fields are loaded with `.dynamicProps()` instead. |
13
13
  | `result` | sample object | ✓ | A literal sample of what `execute` returns — see below. |
14
14
  | `logo` / `appearanceColors` | – | – | Default to the extension's. |
15
15
  | `oauth2Scopes` | string[] | – | Extra OAuth scopes (unioned). |
@@ -19,23 +19,28 @@ Actions are the primary operations a service exposes. Register one with `ext.add
19
19
 
20
20
  The runtime parses the incoming input against `params` **before** `execute` runs, so a handler can trust
21
21
  what it receives: defaults are applied, values are coerced by the schema, and unknown fields are stripped
22
- (an action with `dynamicParams` keeps them — its generated fields aren't in the static schema). A violation
22
+ (an action with `dynamicParams` keeps them — its generated fields aren't in the static schema; a `z.looseObject()` keeps the keys it does not declare, which is how a `.dynamicProps()` field keeps its loaded fields). A violation
23
23
  rejects the call with `FR_EXT_INVALID_METHOD_INPUT` and the offending param paths; don't re-check required
24
24
  params by hand inside `execute`. Declare optionality honestly — a `z.string()` that the flow may legitimately
25
25
  leave empty must be `.optional()`.
26
26
 
27
- **Not every slot is equally strict**, because not every slot has the same producer. Worth knowing so you
28
- declare schemas that hold up in each:
27
+ **Every slot enforces required fields.** Slots differ only in what happens to fields the schema does not
28
+ declare:
29
29
 
30
- | Slot | Strictness |
31
- |---|---|
32
- | Action `params`, SYSTEM invocations | **strict** — required fields enforced, unknown stripped. The flow engine produces these against the published model, so a violation is a real contract break |
33
- | Dictionary `criteria` | **strict** — the console only calls a dictionary once its `dependsOn` fields are filled |
34
- | Sample-result / dynamic-params loader `criteria` | **lenient** — the schema is relaxed so nothing is required, and unknown fields ride through. These fire on every keystroke while the form is half-filled |
35
- | Polling trigger `params` | **lenient** — the runtime polls with whatever the instance was saved with; rejecting a poll would silently stop a live automation |
36
-
37
- So a loader's `result` fn must tolerate partial criteria, and a trigger's `fetch`/`poll` must tolerate a
38
- partially configured instance. Handlers reached through a strict slot need no such defence.
30
+ | Slot | Required fields | Unknown fields |
31
+ |---|---|---|
32
+ | Action `params`, SYSTEM invocations | enforced — `FR_EXT_INVALID_METHOD_INPUT` | stripped (kept with `dynamicParams`; kept inside a `z.looseObject()`) |
33
+ | Dictionary `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | dropped |
34
+ | Sample-result loader `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | ride through — the node's other params come along |
35
+ | `.dynamicProps()` / `dynamicParams` loader `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | dropped — `criteria` holds exactly the `dependsOn` params, validated by their own schemas |
36
+ | Polling trigger `params` | enforced — `FR_EXT_INVALID_METHOD_INPUT`, target `triggerData` | ride through |
37
+
38
+ So a sample-result loader resolves only once its owner's required params are filled.
39
+
40
+ **Make trigger filters optional.** A polling trigger's params are checked on every poll, against the values
41
+ the instance was saved with. A required field the user left empty fails every poll, and the trigger never
42
+ produces an event. Mark a trigger param required only when the trigger cannot work without it; declare
43
+ every filter `.optional()` and handle the empty value in `fetch`/`poll`.
39
44
 
40
45
  ## `result` — return the sample object
41
46
 
@@ -15,6 +15,7 @@ your declarations have to satisfy.
15
15
  | `result` (value/schema/loader) | `metaInfo.sampleResult` / `sampleResultLoader` |
16
16
  | `scope` (realtime) | `integrationTriggersScope` |
17
17
  | `handleTrigger*` | SYSTEM methods (runtime-generated) |
18
+ | `.dynamicProps()` on a param / `dynamicParams` | a generated `PARAM_SCHEMA_DEFINITION` method each, plus `args[].schemaLoader` / `metaInfo.dynamicParams` on the action — see [Dynamic fields](#dynamic-fields--dynamicprops-and-dynamicparams) |
18
19
 
19
20
  Platform-side identity fields are added downstream — you never author them.
20
21
 
@@ -115,14 +116,14 @@ It does not change how a handler reads the value, and a custom install has no gl
115
116
 
116
117
  ## Helper-route & SYSTEM methods carry a wrapper-param `metaInfo.args`
117
118
 
118
- Dictionaries, sample-result / dynamic-params loaders, and the trigger/polling/OAuth SYSTEM methods take a
119
+ Dictionaries, sample-result / dynamic-params / dynamic-props loaders, and the trigger/polling/OAuth SYSTEM methods take a
119
120
  **single wrapper param** (never per-field params). The model describes that wrapper so `metaInfo.args` is
120
121
  never empty — consumers (UI, AI tools) need the label:
121
122
 
122
123
  | Method kind | `bodyParams` | `metaInfo.args` |
123
124
  |---|---|---|
124
125
  | Trigger / polling / OAuth SYSTEM | `[{ invocation }]` / `[{ callbackObject }]` / `[{ refreshToken }]` | labelled from that param (e.g. `{ invocation: { label: 'invocation' } }`) |
125
- | Loaders (`*_SampleResultLoader` / `*_DynamicParams`) | `[{ payload: OBJECT }]` | `{ payload: { label: 'payload' } }` |
126
+ | Loaders (`*_SampleResultLoader` / `*_DynamicParams` / `*_<param>_DynamicProps`) | `[{ payload: OBJECT }]` | `{ payload: { label: 'payload' } }` |
126
127
  | Dictionary | synthesized `payload` OBJECT with nested `search` + `cursor` (+ `criteria` when declared) | `{ payload: { label: 'Payload' } }` |
127
128
 
128
129
  You never author these params — the runtime emits them. Dictionaries keep the extension's **service colors**
@@ -136,8 +137,43 @@ and default to `OBJECT` `returnType`.
136
137
  - **The custom type** is `z.text()` → `uiComponent: MULTI_LINE_TEXT`, `STRING`-typed — see the type table
137
138
  above.
138
139
 
139
- ## Open items
140
+ ## Dynamic fields — `.dynamicProps()` and `dynamicParams`
140
141
 
141
- - The client-side render contract for **top-level** `dynamicParams` fields. The runtime emits and serves the
142
- `PARAM_SCHEMA_DEFINITION` method today, so the authoring side works; `metaInfo.dynamicParams` is marked
143
- provisional in the model.
142
+ Both are published as a loader method the console calls while a flow author configures the block. The loader
143
+ function itself never ships; only its name does.
144
+
145
+ | Authored | Published on the action | Loader method |
146
+ |---|---|---|
147
+ | `field.dynamicProps({ dependsOn, execute })` | `metaInfo.args[field].schemaLoader` = the loader's name, `metaInfo.args[field].dependsOn` = `dependsOn` (`[]` when omitted); in `paramsSchema`, the field's `meta.frDynamicProps` = `{ id, dependsOn }` and the object carries `loose: true` | `<actionId>_<field>_DynamicProps` |
148
+ | `dynamicParams: { dependsOn, execute }` | `metaInfo.dynamicParams` = `{ methodName, dependsOn }` | `<actionId>_DynamicParams` |
149
+
150
+ - `schemaLoader` is the key a legacy (class-based) service uses for the same purpose, so a consumer reads both
151
+ the same way. The field's own `bodyParams` entry and `paramsSchema` entry stay as declared.
152
+ - `frDynamicProps` in `paramsSchema` is the plain ref `{ id, dependsOn }`, written next to the other `fr*`
153
+ meta keys (`frDictionary`, `frLabels`, …).
154
+ - `loose: true` marks an object that keeps the keys it does not declare (`z.looseObject()`); without it a
155
+ consumer rebuilding zod from `paramsSchema` would strip the loaded fields.
156
+ - Both loaders are `PARAM_SCHEMA_DEFINITION` methods with `returnType: OBJECT`, taking the same single
157
+ `payload` wrapper as the other loaders: `{ payload: { criteria } }`, where `criteria` holds exactly the
158
+ `dependsOn` values.
159
+
160
+ ### The loader response
161
+
162
+ ```json
163
+ {
164
+ "paramsSchema": { "v": 1, "fields": [ … ] },
165
+ "params": [ { "name": "price", "required": false, "description": "", "type": "NUMBER", "label": "Price", "uiComponent": { "type": "NUMERIC_STEPPER" } } ]
166
+ }
167
+ ```
168
+
169
+ | Key | Holds |
170
+ |---|---|
171
+ | `paramsSchema` | The loaded fields as encoded zod — the same encoding an action publishes for its own `params`. Console forms build their widgets and validation from it. |
172
+ | `params` | The same fields as a param list with display metadata (`label`, `uiComponent`, `dictionary`, `dependsOn`) **inline** on each entry. The Flow Builder draws the fields from it. |
173
+
174
+ Both are built from the one schema `execute` returned, so they cannot disagree. For `.dynamicProps()`, the
175
+ field's own static keys come **first** in both. A loaded field that carries `.dictionary(ref)` publishes the
176
+ dictionary on its `params` entry.
177
+
178
+ A legacy loader differs: it answers with a plain list of param definitions, not this object. Consumers accept
179
+ both.
@@ -28,7 +28,7 @@ service's `src/index.js` (the single source of truth).
28
28
  may read nothing like the current behaviour. `label` is the human text the console shows, so it is what
29
29
  belongs in a README.
30
30
  - **Exclude** everything that is not a user-facing action or trigger: `ext.dictionary(...)` registrations,
31
- `dynamicParams`, `result` loader functions, `initContext`, `apiRequest`, `helpers`, and
31
+ `dynamicParams`, `.dynamicProps()` loaders, `result` loader functions, `initContext`, `apiRequest`, `helpers`, and
32
32
  `ext.setupOauth2` / `ext.setupRealtimeTriggers` setup calls. These are internal support declarations, and
33
33
  the SYSTEM methods generated from them are never documented.
34
34
  - **The exclusion is about declarations, not consequences.** It keeps the plumbing out; it does not silence
@@ -56,10 +56,11 @@ const ext = Flowrunner.createExtension({
56
56
  logger?.debug(`[${ logTag ?? 'api' }] ${ method.toUpperCase() } ${ fullUrl }`)
57
57
 
58
58
  try {
59
- // 04: the verb is a value here, so the constructor form — never Request[method](url).
60
- const response = await new Flowrunner.Request(fullUrl, method, body)
59
+ // 04: the verb is a value here; the constructor form takes it as-is.
60
+ const response = await new Flowrunner.Request(fullUrl, method)
61
61
  .set({ Authorization: `Bearer ${ context.token }` })
62
62
  .query(query ?? {})
63
+ .send(body)
63
64
 
64
65
  return response?.data ?? response
65
66
  } catch (error) {
@@ -175,7 +176,7 @@ ext.addAction({
175
176
  },
176
177
  })
177
178
 
178
- // 08: exactly one mechanism. `params` here are lenient — tolerate a half-configured instance.
179
+ // 08: exactly one mechanism. `params` are checked on every poll, so the filter is optional — 07.
179
180
  ext.addPollingTrigger({
180
181
  category : 'Notes',
181
182
  id : 'onNoteCreated',
@@ -342,5 +343,5 @@ Things in that output worth reading twice:
342
343
  | `result` is a sample object, never a zod schema plus `.example()` | [07](07-actions.md) |
343
344
  | Every `execute` is a block body with an explicit `return` | [07](07-actions.md) |
344
345
  | `createNote` returns the API's response whole; `listBoardNotes` extends without dropping | [07](07-actions.md) |
345
- | `new Flowrunner.Request(url, method, body)` — never `Request[method](url)` | [04](04-http-requests.md) |
346
+ | `new Flowrunner.Request(url, method)` … `.send(body)` for a verb held in a variable | [04](04-http-requests.md) |
346
347
  | `Object.hasOwn` at the lookup, on a plain object literal | [16](16-gotchas.md) |
@@ -82,7 +82,8 @@ The rest of `executionContext` is filled with stable `test-*` values you can ass
82
82
  | `POLLING_TRIGGER` | `ext.addPollingTrigger(...)` | `Polling Triggers` |
83
83
  | `REALTIME_TRIGGER` | `ext.addRealtimeTrigger(...)` | `RealTime Triggers` |
84
84
  | `SAMPLE_RESULT_LOADER` | a `result` declared as a function | `DynamicResults` |
85
- | `PARAM_SCHEMA_DEFINITION` | `dynamicParams` | `DynamicParams` |
85
+ | `PARAM_SCHEMA_DEFINITION` | `dynamicParams` — the method is `<actionId>_DynamicParams` | `DynamicParams` |
86
+ | `PARAM_SCHEMA_DEFINITION` | `.dynamicProps()` on a param — the method is `<actionId>_<param>_DynamicProps` | `DynamicProps` |
86
87
  | `SYSTEM` | the runtime — trigger and OAuth seams | **no group of its own** — see below |
87
88
 
88
89
  **A SYSTEM method never gets its own `describe`.** `handleTriggerResolveEvents`,
@@ -194,6 +194,35 @@ and **the runtime's contract**:
194
194
  Either way the hedge is still the wrong answer: write the one branch that is true, and get the fact added
195
195
  to 13, which is the fix that stops the next service repeating it.
196
196
 
197
+ ## Dynamic fields load at design time, and are not validated at run time
198
+
199
+ `.dynamicProps()` and `dynamicParams` load fields while a flow author configures the block (see
200
+ [03-parameters.md](03-parameters.md#dynamic-properties--dynamicprops)). The traps:
201
+
202
+ - **A loaded field is not checked when the action runs.** The loaders run only at design time, so a
203
+ `required` loaded field the author left empty reaches your handler as absent, and a loaded `.min()` or
204
+ enum is not re-checked. Validate inside `execute` whatever the handler cannot do without. Static keys
205
+ declared in the `z.looseObject({ … })` are validated as usual.
206
+ - **The field must be a loose object.** `.dynamicProps()` on `z.object({ … })` fails when the service loads,
207
+ because a plain object would strip the loaded keys. Use `z.looseObject({ … })`, or
208
+ `z.array(z.looseObject({ … }))` for a list of objects.
209
+ - **Put it on the array, not on its element.** `z.array(z.looseObject({}).dynamicProps(…))` is refused;
210
+ `z.array(z.looseObject({})).dynamicProps(…)` is right.
211
+ - **`dependsOn` names siblings only, and `criteria` holds only those.** A value `execute` reads that is not
212
+ in `dependsOn` is never in `criteria`, and the loader is not re-run when it changes. A name that is not a
213
+ sibling param — or is the field itself — fails when the service loads.
214
+ - **`.dynamicProps()` and `.dictionary()` do not share a field.** A dictionary offers the values of one
215
+ field; dynamic props define the fields inside an object.
216
+ - **Top-level action params only.** Not on a trigger's params, a config item, a dictionary's `criteria`, a
217
+ nested field, or inside the fields a loader returns.
218
+ - **A loaded field may not repeat a declared one.** A `.dynamicProps()` loader that returns a key the object
219
+ already declares, or a `dynamicParams` loader that returns the name of a declared param, fails with
220
+ `FR_EXT_INVALID_SCHEMA` when the loader runs.
221
+ - **`dynamicProps` is not `dynamicParams`.** `.dynamicProps()` is a method on one param and loads the fields
222
+ *inside* it; `dynamicParams` is an action property and loads extra *top-level* params.
223
+ - **`dynamicParams: { criteria, resolve }` is gone.** It fails when the service loads, naming
224
+ `{ dependsOn, execute }`.
225
+
197
226
  ## Where a fact already lives
198
227
 
199
228
  Do not restate these here; they are covered where they belong.
@@ -210,4 +239,5 @@ Do not restate these here; they are covered where they belong.
210
239
  | `rawBody` is **absent**, not empty, when there is nothing to verify — hashing `''` looks like a bad signature | [09-realtime-triggers.md](09-realtime-triggers.md) |
211
240
  | `FLOW`/`EXECUTION` file scopes fail in a method that runs outside a flow execution | [10-files-api.md](10-files-api.md) |
212
241
  | Unresolvable dictionary *input* is an empty list, not an error | [05-dictionaries.md](05-dictionaries.md) |
213
- | `dynamicParams.resolve()` must return a `z.object` — checked when the loader runs, not at load | [03-parameters.md](03-parameters.md) |
242
+ | A params loader's `execute()` must return a shape or a `z.object` — checked when the loader runs, not at load | [03-parameters.md](03-parameters.md) |
243
+ | `.dynamicProps()` needs a loose object, on a top-level action param; loaded fields are not validated at run time | [Dynamic fields](#dynamic-fields-load-at-design-time-and-are-not-validated-at-run-time) |