@flowrunner/cli 0.1.9 → 0.1.10-dev.2
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.
- package/README.md +8 -8
- package/ai-docs/instructions/service-code-format/01-service-structure.md +3 -2
- package/ai-docs/instructions/service-code-format/02-zod-types.md +8 -0
- package/ai-docs/instructions/service-code-format/03-parameters.md +181 -10
- package/ai-docs/instructions/service-code-format/04-http-requests.md +2 -2
- package/ai-docs/instructions/service-code-format/05-dictionaries.md +14 -0
- package/ai-docs/instructions/service-code-format/07-actions.md +5 -4
- package/ai-docs/instructions/service-code-format/11-output-model.md +42 -6
- package/ai-docs/instructions/service-code-format/12-service-readme.md +1 -1
- package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +4 -1
- package/ai-docs/instructions/service-code-format/15-unit-tests.md +2 -1
- package/ai-docs/instructions/service-code-format/16-gotchas.md +39 -1
- package/ai-docs/instructions/service-code-format/README.md +1 -1
- package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +1 -1
- package/dist/cli.js +10663 -71
- package/dist/cli.js.map +4 -4
- package/dist/index.js +10632 -64
- package/dist/index.js.map +4 -4
- package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
- package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
- package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
- package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
- package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
- package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
- package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
- package/dist/types/flow-extension-runner/src/v2/types.d.ts +20 -8
- package/dist/types/shared/src/constants/activity-log.d.ts +1496 -0
- package/dist/types/shared/src/constants/docs.d.ts +2 -0
- package/dist/types/shared/src/constants/notification-types.d.ts +9 -3
- package/dist/types/shared/src/constants/shared-extensions.d.ts +12 -0
- package/dist/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
- package/dist/types/shared/src/scheme/access-keys/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/activity-log-base.d.ts +35 -0
- package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
- package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
- package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
- package/dist/types/shared/src/scheme/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
- package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
- package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
- package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
- package/dist/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
- package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
- package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
- package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
- package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
- package/package.json +1 -4
- package/runtime/index.js +10621 -43
- package/runtime/index.js.map +4 -4
- package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +13 -9
- package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +52 -7
- package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +4 -6
- package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -2
- package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +10 -2
- package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +1 -0
- package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +29 -0
- package/runtime/types/flow-extension-runner/src/v2/types.d.ts +20 -8
- package/runtime/types/shared/src/constants/activity-log.d.ts +1496 -0
- package/runtime/types/shared/src/constants/docs.d.ts +2 -0
- package/runtime/types/shared/src/constants/notification-types.d.ts +9 -3
- package/runtime/types/shared/src/constants/shared-extensions.d.ts +12 -0
- package/runtime/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
- package/runtime/types/shared/src/scheme/access-keys/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/activity-log-base.d.ts +35 -0
- package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +2 -3
- package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +20 -0
- package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -0
- package/runtime/types/shared/src/scheme/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
- package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +5 -0
- package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +147 -0
- package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +20 -0
- package/runtime/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
- package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +33 -1
- package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +1 -0
- package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +15 -0
- package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +10 -0
- package/templates/demo-todo-list/files/src/index.js +6 -6
- package/templates/qa-test/files/README.md +23 -8
- package/templates/qa-test/files/src/index.js +368 -37
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# flowrunner
|
|
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
|
|
21
|
-
npx flowrunner
|
|
22
|
-
npx flowrunner
|
|
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
|
|
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
|
|
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/
|
|
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/
|
|
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
|
|
|
@@ -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`,
|
|
89
|
-
`foo_DynamicParams`,
|
|
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
|
|
58
|
-
`
|
|
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,188 @@ 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.
|
|
269
|
+
|
|
270
|
+
- **When they load.** Once every **required** param in `dependsOn` has a value; an optional one may stay
|
|
271
|
+
empty. Until then the param says which ones to fill in first. Only a value typed or picked in the block
|
|
272
|
+
counts: a dependency bound to an earlier step's output has no value at design time, so it counts as empty —
|
|
273
|
+
a required one keeps the param waiting ("Fill in … first"), an optional one is left out of `criteria`.
|
|
274
|
+
- **When a dependency changes**, the fields load again, and the values the author already entered are **kept
|
|
275
|
+
for every field the new list still returns**. A value whose field is no longer returned stays saved in the
|
|
276
|
+
param — it is not shown, but it still reaches your handler until the param is edited — so do not treat every
|
|
277
|
+
key in the object as one the current loader returned.
|
|
278
|
+
- **When the load fails**, the error is shown in place of the fields and nothing entered is removed.
|
|
279
|
+
|
|
280
|
+
On an **AI Agent tool** that calls your action, the model is offered the loaded fields too. When the agent
|
|
281
|
+
runs, the tool calls your loaders with the values set by hand in the tool's panel as `criteria`, and adds what
|
|
282
|
+
they return to the tool's input: the fields inside a `.dynamicProps()` param, and the extra params of
|
|
283
|
+
`dynamicParams`, with their labels. Fields set by hand stay fixed — inside a `.dynamicProps()` param they are
|
|
284
|
+
merged key by key with what the model fills in, so pinning one field leaves the others to the model. Without a
|
|
285
|
+
hand-set value for a required dependency nothing is loaded, and if a loader fails the tool is offered only the
|
|
286
|
+
declared params.
|
|
287
|
+
|
|
288
|
+
> **Loaded fields are not validated at run time.** The loaders run only while the inputs are being
|
|
289
|
+
> configured. When the action executes, your handler receives the loaded keys as the flow supplied them:
|
|
290
|
+
> a `required` loaded field the author left empty is **not** rejected, and a loaded field's `.min()` or enum
|
|
291
|
+
> is not re-checked. Validate in `execute` anything your handler cannot do without. Static keys — those
|
|
292
|
+
> declared in the `z.looseObject({ … })` — are validated as usual.
|
|
293
|
+
>
|
|
294
|
+
> **A loaded field's `.default()` is not applied at run time either.** A loaded field the author left empty
|
|
295
|
+
> reaches your handler absent or empty, not as its default. Apply the fallback in `execute`.
|
|
296
|
+
|
|
179
297
|
## Dynamic params — `dynamicParams`
|
|
180
298
|
|
|
181
|
-
|
|
299
|
+
Where `.dynamicProps()` loads the fields **inside one param**, `dynamicParams` loads **extra top-level params of
|
|
300
|
+
the action** — fields that sit next to the static ones and depend on a chosen resource.
|
|
301
|
+
|
|
302
|
+
```js
|
|
303
|
+
ext.addAction({
|
|
304
|
+
category: 'Records',
|
|
305
|
+
id : 'addRow',
|
|
306
|
+
// …
|
|
307
|
+
params : z.object({
|
|
308
|
+
tableName: z.string().label('Table'),
|
|
309
|
+
}),
|
|
310
|
+
dynamicParams: {
|
|
311
|
+
dependsOn: ['tableName'],
|
|
312
|
+
execute : async ({ criteria, context, apiRequest }) => {
|
|
313
|
+
const columns = await apiRequest({ url: `/tables/${ criteria.tableName }/columns`, context })
|
|
314
|
+
|
|
315
|
+
return Object.fromEntries(columns.map(column => [column.name, z.string().optional().label(column.title)]))
|
|
316
|
+
},
|
|
317
|
+
},
|
|
318
|
+
// …
|
|
319
|
+
})
|
|
320
|
+
```
|
|
182
321
|
|
|
183
322
|
| Property | Type | Description |
|
|
184
323
|
|---|---|---|
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
324
|
+
| `dependsOn` | `string[]` | Names of the action's **declared** `params` the loaded fields depend on. Optional; each name must exist in `params`. |
|
|
325
|
+
| `execute` | fn | `({ criteria, config, context, helpers, apiRequest, oauth, files, filesScope, logger }) => shape \| z.object({...})` — extra params merged into `params`. |
|
|
326
|
+
|
|
327
|
+
`criteria` follows the same rules as for `.dynamicProps()`: exactly the `dependsOn` values, coerced by the
|
|
328
|
+
declared schemas, `FR_EXT_INVALID_CRITERIA` when a required one is missing. `execute` may return a plain shape
|
|
329
|
+
or a `z.object`. A loaded field **may not share a name with a declared param** — it would shadow it — and
|
|
330
|
+
fails with `FR_EXT_INVALID_SCHEMA` when the loader runs.
|
|
331
|
+
|
|
332
|
+
The loaded fields reach your handler next to the static ones: an action with `dynamicParams` keeps the input
|
|
333
|
+
keys its static `params` do not declare. They are **not validated** at run time, as for `.dynamicProps()`.
|
|
334
|
+
|
|
335
|
+
The old shape `dynamicParams: { criteria, resolve }` is no longer accepted. The service fails to load with an
|
|
336
|
+
error naming the replacement — `criteria` becomes `dependsOn` (a list of names), `resolve` becomes `execute`,
|
|
337
|
+
and it returns a shape or a `z.object`.
|
|
338
|
+
|
|
339
|
+
### The loader's response
|
|
340
|
+
|
|
341
|
+
Both loaders answer with the loaded fields twice, built from the same schema so they cannot disagree:
|
|
342
|
+
|
|
343
|
+
```json
|
|
344
|
+
{
|
|
345
|
+
"paramsSchema": { "v": 1, "fields": [ { "name": "name", "type": "string", "meta": { "title": "Name" } } ] },
|
|
346
|
+
"params": [ { "name": "name", "required": true, "description": "", "type": "STRING", "label": "Name" } ]
|
|
347
|
+
}
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
`paramsSchema` is the same encoded zod an action publishes for its own params; `params` is the field list with
|
|
351
|
+
the display metadata (label, widget, dictionary) inline. The loader's registered method is generated for you —
|
|
352
|
+
`<actionId>_DynamicParams` and `<actionId>_<param>_DynamicProps`, see
|
|
353
|
+
[01-service-structure.md](01-service-structure.md) — and is never listed in the service README.
|
|
354
|
+
|
|
355
|
+
### Which one to use
|
|
187
356
|
|
|
188
|
-
|
|
189
|
-
|
|
357
|
+
| You want | Use |
|
|
358
|
+
|---|---|
|
|
359
|
+
| A fixed set of top-level params, some with a list of choices | static `params`; `.dictionary(ref)` for the choices |
|
|
360
|
+
| One object (or list of objects) whose inner fields depend on other params | `.dynamicProps()` on that param |
|
|
361
|
+
| Extra top-level params that appear next to the static ones | `dynamicParams` |
|
|
190
362
|
|
|
191
|
-
`
|
|
192
|
-
|
|
193
|
-
until the resolver runs.
|
|
363
|
+
`.dictionary()` offers **values** for one field; `.dynamicProps()` and `dynamicParams` define **fields**. See
|
|
364
|
+
[05-dictionaries.md](05-dictionaries.md).
|
|
@@ -276,8 +276,8 @@ A non-2xx **rejects** with a `ResponseError`:
|
|
|
276
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`. |
|
|
277
277
|
|
|
278
278
|
Because `message` is the raw body for most JSON APIs, reading it as a string used to produce an unreadable
|
|
279
|
-
`[object Object]`. The platform now renders an unhandled failure as the provider's response body —
|
|
280
|
-
|
|
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]` —
|
|
281
281
|
so a service that does nothing still fails legibly.
|
|
282
282
|
|
|
283
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).
|
|
@@ -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` |
|
|
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,7 +19,7 @@ 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()`.
|
|
@@ -29,9 +29,10 @@ declare:
|
|
|
29
29
|
|
|
30
30
|
| Slot | Required fields | Unknown fields |
|
|
31
31
|
|---|---|---|
|
|
32
|
-
| Action `params`, SYSTEM invocations | enforced — `FR_EXT_INVALID_METHOD_INPUT` | stripped (kept with `dynamicParams`) |
|
|
32
|
+
| Action `params`, SYSTEM invocations | enforced — `FR_EXT_INVALID_METHOD_INPUT` | stripped (kept with `dynamicParams`; kept inside a `z.looseObject()`) |
|
|
33
33
|
| Dictionary `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | dropped |
|
|
34
|
-
| Sample-result
|
|
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 |
|
|
35
36
|
| Polling trigger `params` | enforced — `FR_EXT_INVALID_METHOD_INPUT`, target `triggerData` | ride through |
|
|
36
37
|
|
|
37
38
|
So a sample-result loader resolves only once its owner's required params are filled.
|
|
@@ -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
|
-
##
|
|
140
|
+
## Dynamic fields — `.dynamicProps()` and `dynamicParams`
|
|
140
141
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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
|
|
@@ -172,8 +172,11 @@ Driving these methods from a *suite* rather than a scratch script is the same ca
|
|
|
172
172
|
| Action `execute` params | ✓ |
|
|
173
173
|
| Dictionary `criteria` | ✓ |
|
|
174
174
|
| Realtime trigger `match` params — object **and** function form | ✗ |
|
|
175
|
+
| Fields loaded by `.dynamicProps()` / `dynamicParams` | ✗ |
|
|
175
176
|
|
|
176
|
-
An action's params are parsed, so `execute` sees defaults filled in
|
|
177
|
+
An action's params are parsed, so `execute` sees defaults filled in — except fields loaded by
|
|
178
|
+
`.dynamicProps()` or `dynamicParams`, which exist only while the inputs are configured and are passed through
|
|
179
|
+
as the flow supplied them. A trigger's `match` receives the
|
|
177
180
|
**persisted instance config verbatim**: no defaults.
|
|
178
181
|
|
|
179
182
|
`.labels()` needs no path at all — it is display metadata, so the value the element stored is already the
|
|
@@ -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,43 @@ 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
|
+
- **A loaded field's `.default()` is not applied when the action runs.** A loaded field left empty reaches
|
|
222
|
+
the handler absent or empty. Apply the fallback in `execute`.
|
|
223
|
+
- **A `.dynamicProps()` object may hold keys the loader no longer returns.** When a dependency changes, values
|
|
224
|
+
of fields that are gone stay saved in the param until it is edited, and reach the handler. Read the keys you
|
|
225
|
+
expect rather than iterating all of them.
|
|
226
|
+
- **A dependency bound to an earlier step's output counts as empty.** It has no value while the block is
|
|
227
|
+
configured: a required one keeps the fields from loading (the param asks for it first), an optional one is
|
|
228
|
+
left out of `criteria`.
|
|
229
|
+
- **`dynamicProps` is not `dynamicParams`.** `.dynamicProps()` is a method on one param and loads the fields
|
|
230
|
+
*inside* it; `dynamicParams` is an action property and loads extra *top-level* params.
|
|
231
|
+
- **`dynamicParams: { criteria, resolve }` is gone.** It fails when the service loads, naming
|
|
232
|
+
`{ dependsOn, execute }`.
|
|
233
|
+
|
|
197
234
|
## Where a fact already lives
|
|
198
235
|
|
|
199
236
|
Do not restate these here; they are covered where they belong.
|
|
@@ -210,4 +247,5 @@ Do not restate these here; they are covered where they belong.
|
|
|
210
247
|
| `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
248
|
| `FLOW`/`EXECUTION` file scopes fail in a method that runs outside a flow execution | [10-files-api.md](10-files-api.md) |
|
|
212
249
|
| Unresolvable dictionary *input* is an empty list, not an error | [05-dictionaries.md](05-dictionaries.md) |
|
|
213
|
-
| `
|
|
250
|
+
| 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) |
|
|
251
|
+
| `.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) |
|
|
@@ -58,7 +58,7 @@ conditional groups that apply, together.
|
|
|
58
58
|
|---|----------|--------|
|
|
59
59
|
| 1 | [01-service-structure.md](01-service-structure.md) | `Flowrunner.createExtension(props)`: id/name/logo/colors, `usesFileStorage`, `configItems`, `initContext`, `apiRequest`, `helpers`; folder layout |
|
|
60
60
|
| 2 | [02-zod-types.md](02-zod-types.md) | zod types & plugins — widget derived from type; `.label`/`.describe`/`.example`/`.optional`/`.default`/`.shared`/`.dictionary`/`.map` |
|
|
61
|
-
| 3 | [03-parameters.md](03-parameters.md) | `params` (all body params), the platform's own file-options groups — one per Files call — and `dynamicParams` (
|
|
61
|
+
| 3 | [03-parameters.md](03-parameters.md) | `params` (all body params), the platform's own file-options groups — one per Files call — `.dynamicProps()` (an object param's inner fields, loaded at design time) and `dynamicParams` (extra top-level params, loaded the same way) |
|
|
62
62
|
| 4 | [04-http-requests.md](04-http-requests.md) | the shared `apiRequest` helper, and the `Flowrunner.Request` client under it — sending model, methods, query, headers, bodies, multipart, responses, `ResponseError` |
|
|
63
63
|
| 5 | [05-dictionaries.md](05-dictionaries.md) | `ext.dictionary(props)` — dynamic param options; `label` (→ `operationName`, always set it), `criteria` → auto `dependsOn`, optional `result` sample |
|
|
64
64
|
| 6 | [07-actions.md](07-actions.md) | `ext.addAction(props)`, the shared `execute` context bag, and input validation |
|
|
@@ -62,7 +62,7 @@ Requirements, not preferences. A suite that breaks one is wrong even when it is
|
|
|
62
62
|
`global.Flowrunner`, never reach for an internal. Behaviour unreachable through a method call is not the
|
|
63
63
|
service's contract and not yours to test.
|
|
64
64
|
2. **Group by `registerAs`.** Top-level groups are exactly `Actions`, `Dictionaries`, `OAuth`,
|
|
65
|
-
`Polling Triggers`, `RealTime Triggers`, `DynamicResults`, `DynamicParams`. A method's group comes from
|
|
65
|
+
`Polling Triggers`, `RealTime Triggers`, `DynamicResults`, `DynamicParams`, `DynamicProps`. A method's group comes from
|
|
66
66
|
its registration, never its subject matter — `sendPhoto` and `getChannel` are both `Actions`. Never
|
|
67
67
|
invent a group (`Media`, `Messaging`…). **SYSTEM trigger methods are the one kind with no group and no
|
|
68
68
|
`describe` of their own** — see rule 10.
|