@flowrunner/cli 0.1.17 → 0.1.18-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.
Files changed (40) hide show
  1. package/ai-docs/instructions/service-code-format/02-zod-types.md +173 -41
  2. package/ai-docs/instructions/service-code-format/03-parameters.md +3 -1
  3. package/ai-docs/instructions/service-code-format/05-dictionaries.md +8 -2
  4. package/ai-docs/instructions/service-code-format/07-actions.md +1 -1
  5. package/ai-docs/instructions/service-code-format/11-output-model.md +3 -0
  6. package/ai-docs/instructions/service-code-format/14-reference-service.md +1 -1
  7. package/ai-docs/instructions/service-code-format/16-gotchas.md +89 -6
  8. package/ai-docs/instructions/service-code-format/18-test-recipes.md +2 -1
  9. package/ai-docs/instructions/service-code-format/README.md +1 -1
  10. package/dist/cli.js +646 -89
  11. package/dist/cli.js.map +4 -4
  12. package/dist/index.js +645 -88
  13. package/dist/index.js.map +4 -4
  14. package/dist/types/flow-extension-runner/src/v2/context/execution-context.d.ts +8 -0
  15. package/dist/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
  16. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +2 -0
  17. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +2 -0
  18. package/dist/types/flow-extension-runner/src/v2/params/schema/date-format.d.ts +80 -0
  19. package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -10
  20. package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -2
  21. package/dist/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +8 -0
  22. package/dist/types/flow-extension-runner/src/v2/params/schema/notices.d.ts +15 -0
  23. package/dist/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
  24. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +30 -19
  25. package/dist/types/flow-extension-runner/src/v2/types.d.ts +1 -1
  26. package/package.json +1 -1
  27. package/runtime/index.js +652 -89
  28. package/runtime/index.js.map +4 -4
  29. package/runtime/types/flow-extension-runner/src/v2/context/execution-context.d.ts +8 -0
  30. package/runtime/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
  31. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +2 -0
  32. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +2 -0
  33. package/runtime/types/flow-extension-runner/src/v2/params/schema/date-format.d.ts +80 -0
  34. package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -10
  35. package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -2
  36. package/runtime/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +8 -0
  37. package/runtime/types/flow-extension-runner/src/v2/params/schema/notices.d.ts +15 -0
  38. package/runtime/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
  39. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +30 -19
  40. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +1 -1
@@ -8,12 +8,13 @@ and behaviors.
8
8
  |---|---|---|---|---|---|
9
9
  | `z.string()` | single-line | | `.label(text)` | any field | display label (native `meta.title`) |
10
10
  | `z.text()` | multi-line | | `.describe(text)` | any field | description / config hint |
11
- | `z.json()` | multi-line — arbitrary JSON, **parsed for you** | | | | |
12
11
  | `z.number()` | numeric stepper | | `.example(v)` | field / result | sample value (native `meta.examples`) |
13
12
  | `z.boolean()` | toggle | | `.optional()` | any field | not required (required is default) |
14
13
  | `z.enum([...])` | dropdown | | `.default(v)` | any field | default value |
15
14
  | `z.date()` | date picker | | `.shared()` | config field | `shared:true` (OAuth client id/secret) |
16
- | `z.object({...})` | nested form | | `.dictionary(ref)` | param field | dynamic options + auto `dependsOn` (see [05-dictionaries.md](05-dictionaries.md)) |
15
+ | `z.iso.date()`, `z.iso.datetime({ local: true })`, `z.iso.time()` | date / date-and-time / time picker that stores **text** — see [Dates](#dates--an-instant-or-a-date-as-text) | | `.dateFormat(pattern)` | those three | the text `execute` receives: `'dd/MM/yyyy'` → `'31/01/2024'` |
16
+ | `z.object({...})` | nested form — **drops** the keys it does not declare | | `.dictionary(ref)` | param field | dynamic options + auto `dependsOn` (see [05-dictionaries.md](05-dictionaries.md)) |
17
+ | `z.looseObject({...})` | nested form — **keeps** the keys it does not declare; see [`z.object` or `z.looseObject`](#zobject-or-zlooseobject) | | | | |
17
18
  | `z.array(inner)` | list | | `.labels({ value: 'Label' })` | `z.enum` | UI shows the label; the flow stores and `execute` receives the VALUE |
18
19
  | `z.union([...])` | the **first** branch's widget — see below | | | | |
19
20
  | `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)) | | | | |
@@ -58,39 +59,149 @@ Notes:
58
59
  (There is no `.map({ Label: value })` — it took its argument the other way round, treating labels as the
59
60
  accepted values. It throws when the service loads, naming `.labels()`.)
60
61
 
61
- ## `z.json()` — a JSON value typed into a textarea
62
+ ## The widget follows the type — there is no override
62
63
 
63
- Use it for a parameter whose shape you do not want to declare: a request body to pass through, a bag of
64
- options an API takes verbatim.
64
+ There is no option for choosing a widget. The type you declare decides **both** the widget and the value
65
+ your handler receives. When the vendor wants something the obvious declaration doesn't give you, choose by
66
+ what the **handler** needs, and convert in the handler:
67
+
68
+ | You need | Declare | Why not the obvious spelling |
69
+ |---|---|---|
70
+ | A checkbox, and the vendor wants the text `'true'` / `'false'` | `z.boolean()`, and send `String(params.flag)` (or the spelling the vendor documents) | `z.string()` draws a text box. `z.enum(['true', 'false'])` draws a dropdown |
71
+ | Any value from the flow (text, a number, an object, a list) passed through as given | `z.unknown()` (`.required()` if it must be set) | — |
72
+ | An object or list whose shape you know, which the author may also supply as JSON text | `z.object({ … })` / `z.array(…)`: they draw a real form **and** accept JSON text (see [Text and structures](#text-and-structures)) | — |
73
+ | Several lines of text | `z.text()` | — |
74
+ | Several values (ids, emails, tags), even when the vendor wants them comma-separated | `z.array(<element>)`, and `.join(',')` at the request if the vendor needs text | A comma-separated `z.string()` gets a bound list as JSON text, which `.split(',')` breaks ([16-gotchas.md](16-gotchas.md#a-list-is-a-zarray-never-comma-separated-text-you-split)) |
75
+ | A calendar date or a wall-clock time the vendor wants as text (`20/05/2026`, `2026-05-20`, `10:00`) | `z.iso.date().dateFormat('dd/MM/yyyy')` (or `z.iso.datetime({ local: true })` / `z.iso.time()`) — see [Dates](#dates--an-instant-or-a-date-as-text) | `z.date()` hands you an instant; formatting it yourself needs a time zone you do not have, and is a day early for an author east of UTC ([16-gotchas.md](16-gotchas.md#a-date-the-vendor-wants-as-text-is-dateformat-never-a-zdate-you-format)) |
76
+
77
+ **`z.json()` is not supported.** It fails when the extension loads, with a message naming the two declarations
78
+ above. A value whose shape you don't declare is `z.unknown()`. One you do know is the shape itself, which
79
+ also accepts JSON text, so nothing is lost. `z.unknown()` passes text through **as text**: if the author may
80
+ type JSON into it, parse it yourself.
81
+
82
+ ## `z.object` or `z.looseObject`
83
+
84
+ Both draw the same nested form and publish the same model. They differ in what your handler receives. A
85
+ `z.object()` **drops every key it does not declare**: silently, with nothing refused and nothing logged. A
86
+ `z.looseObject()` checks and converts the keys it declares and passes the rest through untouched.
65
87
 
66
88
  ```js
67
- params: z.object({
68
- payload: z.json().label('Payload').describe('Sent as the request body.'),
69
- }),
70
- execute: async ({ params }) => {
71
- // `params.payload` is already a JSON VALUE — an object, an array, a number. Not text.
72
- return apiRequest({ url: '/items', method: 'POST', body: params.payload })
73
- }
89
+ z.array(z.object({ name: z.string() })) // [{ name: 'a', fields: [1] }] → [{ name: 'a' }]
90
+ z.array(z.looseObject({ name: z.string() })) // [{ name: 'a', fields: [1] }] → [{ name: 'a', fields: [1] }]
74
91
  ```
75
92
 
76
- The field renders as a textarea and the caller supplies **text**, so the parameter publishes as a string —
77
- but the runtime parses it before your handler runs, and `execute` receives the parsed value. **Never call
78
- `JSON.parse` on it yourself.**
79
-
80
- - **Text that will not parse is rejected** the way any wrong-typed value is: the user sees
81
- `«Payload» must be valid JSON` against the field, before your handler is reached.
82
- - **A value that is already a structure passes through untouched** — a flow can bind the parameter to an
83
- expression that evaluates to an object rather than to text, and both work.
84
- - **Every JSON value is accepted**, not just objects and arrays: `42`, `"text"`, `true` and `null` all parse.
85
- Bare words do not — JSON wants a string quoted, so `hello` is refused and `"hello"` is accepted.
86
- - **Required by default**, like every other field; add `.optional()` if it is not.
87
- - Its inferred TypeScript type is `unknown`, because that is honestly what arbitrary JSON is. Narrow it in
88
- your handler before reading properties off it.
89
-
90
- `z.json()` declares nothing about the value's SHAPE. When you do know the shape, declare it — a
91
- `z.object({ … })` gives the user a real form and gives you a checked value, where this gives a textarea and
92
- `unknown`. A declared `z.object()` / `z.array()` also takes JSON text (see
93
- [Text and structures](#text-and-structures)), so you lose nothing by declaring the shape.
93
+ Choose by what the handler does with the object:
94
+
95
+ - **It forwards the object to the API as is → `z.looseObject({ … })`.** Declare the fields the form should
96
+ draw. Everything else the caller sends, including fields the vendor adds later, still reaches the API. A
97
+ free-form map with no fields to draw is `z.looseObject({})`.
98
+ - **It reads named fields and builds its own request → `z.object({ … })`.** Dropping an undeclared key is the
99
+ point there: the object is a whitelist.
100
+
101
+ The forwarding case is easy to get wrong when you first declare a shape. For example, a list of tables is
102
+ sent to the API, but its element is declared as `z.object({ name })` to draw a *Name* field. Every table then
103
+ reaches the API as `{ name }`. The API creates tables with no columns and reports success.
104
+
105
+ Looseness applies to **one level**. A `z.looseObject()` inside a `z.object()` keeps its own extra keys, but the
106
+ outer object still drops its own. Declare each level that is forwarded as loose.
107
+
108
+ `z.record(z.string(), v)` adds something only when **each value** must be checked against `v`:
109
+ `z.record(z.string(), z.number())` converts `{ a: '1' }` to `{ a: 1 }`. A `z.record(z.string(), z.unknown())`
110
+ behaves exactly like `z.looseObject({})`. They publish the same model and pass the same values through, so
111
+ prefer the shorter one.
112
+
113
+ The top-level `params` object is the exception. It is always a `z.object()`, and its undeclared fields are
114
+ dropped unless the action declares `dynamicParams` (see [07-actions.md](07-actions.md)). Looseness is for the
115
+ objects **inside** it.
116
+
117
+ ## Dates — an instant, or a date as text
118
+
119
+ Two different things are called "a date", and they are declared differently:
120
+
121
+ | The vendor wants | Declare | Widget | `execute` receives |
122
+ |---|---|---|---|
123
+ | an **instant** — a moment, the same everywhere (`scheduled_at: 2026-05-20T07:00:00Z`) | `z.date()` (the value as sent) or `z.coerce.date()` (a `Date`) | date picker | what the caller sent / a `Date` |
124
+ | a **calendar date** as text | `z.iso.date()` | date picker | `'2024-01-31'` |
125
+ | | `z.iso.date().dateFormat('dd/MM/yyyy')` | date picker | `'31/01/2024'` |
126
+ | a **wall-clock date and time** as text, read in the vendor's zone | `z.iso.datetime({ local: true })` | date-and-time picker | `'2024-01-31T13:45'` |
127
+ | | `z.iso.datetime({ local: true }).dateFormat('dd/MM/yy HH:mm')` | date-and-time picker | `'31/01/24 13:45'` |
128
+ | a **time of day** as text | `z.iso.time()` | time picker | `'13:45'` |
129
+ | | `z.iso.time().dateFormat('h:mm a')` | time picker | `'1:45 PM'` |
130
+
131
+ A date as text is **text from end to end**: the picker builds it from the day and time the author clicked, the
132
+ flow stores it as text, and your handler receives it in your pattern. Nothing converts it through a time zone,
133
+ so 31 January picked in UTC+3 stays 31 January. `z.iso.datetime()` **without** `{ local: true }` is an instant
134
+ with a zone and stays a text box.
135
+
136
+ ### `.dateFormat(pattern)`
137
+
138
+ The pattern uses these tokens, and only these:
139
+
140
+ | Token | Meaning | 31 Jan 2024, 13:45:30 |
141
+ |---|---|---|
142
+ | `yyyy` / `yy` | year | `2024` / `24` |
143
+ | `MM` / `M` | month | `01` / `1` |
144
+ | `dd` / `d` | day of the month | `31` / `31` |
145
+ | `HH` / `H` | hour, 0–23 | `13` / `13` |
146
+ | `hh` / `h` | hour, 1–12 — needs `a` | `01` / `1` |
147
+ | `mm` | minute | `45` |
148
+ | `ss` | second | `30` |
149
+ | `a` | AM / PM | `PM` |
150
+ | `'text'` | literal text | `'at'` → `at` |
151
+
152
+ Any other character that is not a letter (`/ - . : , space`) is written as is. Without `.dateFormat()` the
153
+ value is ISO: `yyyy-MM-dd`, `yyyy-MM-ddTHH:mm` (with seconds when the value had them), `HH:mm`.
154
+
155
+ **Checked when the extension loads**, naming the parameter — so a mistake stops `flowrunner deploy`:
156
+
157
+ | You wrote | Refused because |
158
+ |---|---|
159
+ | `'DD/MM/YYYY'`, `'dd/mm/YYYY'` | `YYYY` is the week-numbering year, `DD` the day of the year, `mm` minutes — the message suggests `dd/MM/yyyy` |
160
+ | `'dd/MM/yyyy HH:mm'` on `z.iso.date()` | a date has no time of day — declare `z.iso.datetime({ local: true })` |
161
+ | `'dd/MM'` on `z.iso.time()`, `'MM/yyyy'` on `z.iso.date()` | a time has no date; every part of a date must be in its pattern |
162
+ | `'hh:mm'` | a 12-hour clock without `a` cannot be read back — add `a`, or use `HH` |
163
+ | `'HH:mm a'` | a 24-hour clock with `a` writes `13:45 PM`, which cannot be read back — use `hh:mm a` or `HH:mm` |
164
+ | `.dateFormat()` on `z.string()`, `z.date()`, or `z.iso.datetime()` without `{ local: true }` | only the three wall-clock types take a format |
165
+ | `.default('2024-01-31')` with `.dateFormat('dd/MM/yyyy')` | a default is handed to `execute` as written, so write it in the field's own format: `.default('31/01/2024')` |
166
+
167
+ ### What a date-as-text field accepts
168
+
169
+ A value picked in the editor already has your pattern. A value **bound from another block** may be any text,
170
+ and is reshaped from the characters as written:
171
+
172
+ | Declared `.dateFormat('dd/MM/yyyy')`, given | `execute` receives |
173
+ |---|---|
174
+ | `'31/01/2024'` | `'31/01/2024'` |
175
+ | `'2024-01-31'`, `'2024-01-31T23:30:00+03:00'`, `'2024-01-31T23:30:00Z'` | `'31/01/2024'` — the date **as written**; a zone is dropped, never applied |
176
+ | `'31/02/2024'`, `'1/1/2024'`, `'01/31/2024'` | refused: `«Due Date» must be a date in dd/MM/yyyy, e.g. 31/01/2024` |
177
+ | a timestamp (`1706659200000`) | refused, with the same message — a timestamp is an instant, and turning it into a day needs a time zone. A field that takes one is `z.date()` |
178
+
179
+ - **Strict.** The text must be exactly what the pattern writes — `1/1/2024` is not `dd/MM/yyyy`, `1:45 pm` is not
180
+ `h:mm a`, and `31/02/2024` or `24:00` is no date at all.
181
+ - **Nothing is invented.** A date alone is refused by a date-and-time or a time field, rather than given a
182
+ midnight nobody picked.
183
+ - **An ISO value with `Z`** keeps its UTC date: `new Date().toISOString()` just after midnight in UTC+3 is still
184
+ yesterday's date in UTC. If the local day matters, format it in the zone you mean before it reaches the field.
185
+ - **Blank is "not set"**, as on a number: `''`, `null` and a missing value follow `.optional()` / `.nullable()` /
186
+ `.default()`. `.min()` / `.max()` are not available on these types.
187
+ - **A pattern made only of digits** (`yyyyMMdd`, `HHmm`) is fine: `20240131` is read as that date, and a value
188
+ that is no date in it (`20241331`) is refused like any other.
189
+ - **To let a flow clear a date**, declare a union with an empty branch:
190
+ `z.union([z.iso.date().dateFormat('dd/MM/yyyy'), z.literal('')]).optional()` (or with `z.date()`). The picker
191
+ stays; `''` (the flow sets the field to Empty Text, or binds an empty value) reaches `execute` as `''`, and an
192
+ untouched field arrives as `undefined`. Map `''` to the vendor's clear in the handler. **Never use `null` as
193
+ the clear signal**: a field left empty in a block arrives as `null`, so `.nullable()` would clear the date on
194
+ every run. This holds for `z.date()` as well — see [Clearing a value](#clearing-a-value).
195
+ - Inside an object or a list it behaves the same, and a failure names the property (`«Days item 2» must be …`).
196
+
197
+ ### Moving a field from `z.date()` to a date as text
198
+
199
+ A flow saved against `z.date()` holds the old picker's **timestamp**. When an author opens the block, the
200
+ console converts it to your pattern **in the author's own time zone** — the day they originally picked — and
201
+ notes *"Converted from an older saved value — check it and save."* Ask your users to open and save the flows
202
+ that use the field. A flow that is never re-saved keeps sending the timestamp: for a transition period the
203
+ runtime still accepts it, reading it in **UTC** (a day early for an author east of UTC), and after that it is
204
+ refused like any other timestamp.
94
205
 
95
206
  ## The type list is CLOSED
96
207
 
@@ -116,6 +227,9 @@ dropped out of type coercion, so the string values a flow supplies were never co
116
227
  under an unrecognised modifier therefore handed `execute` `false` for an explicit `'true'`. A deploy that
117
228
  stops is better than a parameter that looks fine and is wrong.
118
229
 
230
+ `z.json()` is refused too, even earlier: the call itself throws, naming `z.unknown()` and the declared
231
+ shape (see [The widget follows the type](#the-widget-follows-the-type--there-is-no-override)).
232
+
119
233
  These modifiers are looked THROUGH — the parameter publishes and coerces as the type underneath:
120
234
 
121
235
  | Modifier | Published as |
@@ -206,7 +320,7 @@ converted:
206
320
  ```js
207
321
  limit: z.union([z.number(), z.literal('max')]) // '5' → 5 'max' → 'max'
208
322
  mode : z.union([z.boolean(), z.literal('auto')]) // 'false' → false 'auto' → 'auto'
209
- scope: z.union([z.number(), z.enum(['all', 'none'])]) // '5' → 5 'all' → 'all' 'x' → «Scope» is invalid
323
+ scope: z.union([z.number(), z.enum(['all', 'none'])]) // '5' → 5 'all' → 'all' 'x' → «Scope» must be a number, or one of: "all", "none"
210
324
  ```
211
325
 
212
326
  Keep `z.string()` in a union only when free text really is one of the forms, and convert in the handler if
@@ -216,17 +330,33 @@ you need a number out of it. For a value that must pass through untouched whatev
216
330
  A constraint is part of "fits": `z.union([z.number().min(10), z.string()])` given `5` hands over `'5'`,
217
331
  because the number branch refuses it and the string branch takes it converted.
218
332
 
219
- ### A blank means "not set"
333
+ A value no branch accepts is refused with what **every** branch expects, in declared order: `«Scope» must be a
334
+ number, or one of: "all", "none"`. Text values are quoted (`"auto"` is text, `true` a boolean), and a
335
+ `z.literal('')` branch is left out, so a `''` union reads like its other branch.
336
+
337
+ ### Clearing a value
338
+
339
+ A flow sends three kinds of "nothing", and only one of them is deliberate:
340
+
341
+ | In the block | `execute` receives |
342
+ |---|---|
343
+ | the field left untouched, or cleared | `null` → absence (`undefined` under `.optional()`) |
344
+ | the **Empty Text** chip, or a bound `''` | `''` |
345
+ | a cleared text box in the **config dialog** | `''` |
220
346
 
221
- `''` is a real value on a plain `z.string()`, which is why a cleared text box fails an optional formatted
222
- field. On a union it is absence, and that is the spelling to reach for:
347
+ `''` is a value on a plain `z.string()`. On every other type it is absence — unless you declare it with a
348
+ `z.literal('')` branch, which keeps it as a value. That is how a field lets a flow **clear** something:
223
349
 
224
350
  ```js
225
- webhookUrl: z.url().optional() // blank → «Webhook URL» is invalid — expects a URL
226
- webhookUrl: z.union([z.url(), z.literal('')]).optional() // blank → not provided
351
+ dueDate : z.union([z.date(), z.literal('')]).optional() // untouched → undefined Empty Text → '' a date → the date
352
+ webhookUrl: z.url().optional() // '' → «Webhook URL» is invalid — expects a URL
353
+ webhookUrl: z.union([z.url(), z.literal('')]).optional() // '' → '' untouched → undefined
227
354
  ```
228
355
 
229
- See [16-gotchas.md](16-gotchas.md) for the rest of that trap.
356
+ The handler decides what `''` means for the vendor: send the vendor's clear (`body.dueDate = null` when
357
+ `params.dueDate === ''`), or leave the field out (`params.webhookUrl || undefined`). Never make `null` the
358
+ clear signal — an untouched field arrives as `null`, so the vendor's value would be cleared on every run. See
359
+ [16-gotchas.md](16-gotchas.md) for the rest of that trap.
230
360
 
231
361
  ## Config fields publish a smaller set of types
232
362
 
@@ -292,11 +422,12 @@ you, and `'{a:1}'` (unquoted key) is not JSON. `''` is still a blank; `'{}'` and
292
422
 
293
423
  In a union, a value that already fits a branch is kept (see above), and an object or a list is **never** turned
294
424
  into text through a `z.string()` branch: it takes a branch of its own kind or the union's error, so a malformed
295
- object is reported rather than sent as JSON text. `z.json()` is unchanged — use it for JSON whose shape you do
296
- not declare.
425
+ object is reported rather than sent as JSON text.
297
426
 
298
427
  The flip side: an object bound by mistake to a plain text field (a subject, a name) is sent as JSON text
299
- rather than refused.
428
+ rather than refused. The same applies to a list bound to a text param: it arrives as `'["1","5"]'`, not
429
+ `'1,5'`. So a param that holds several values is a `z.array(…)`, never comma-separated text the handler
430
+ splits. See [16-gotchas.md](16-gotchas.md#a-list-is-a-zarray-never-comma-separated-text-you-split).
300
431
 
301
432
  ### What a boolean accepts
302
433
 
@@ -335,7 +466,8 @@ field by its `.label()`:
335
466
  ```
336
467
  «Retries» must be at least 1
337
468
  «Site» is invalid — expects a URL, e.g. https://example.com
338
- «Region» must be one of: us, eu
469
+ «Region» must be one of: "us", "eu"
470
+ «Scope» must be a number, or one of: "all", "none"
339
471
  ```
340
472
 
341
473
  The console checks the *same* schema while the form is being filled in, so a config dialog reports the same
@@ -160,7 +160,9 @@ rather than quietly publishing an empty settings panel.
160
160
  > hands the flow nothing. If your action's result carries a URL, leave `generateUrl` out of the whitelist and
161
161
  > pass `true` yourself — the flow author has no way to know that turning it off breaks the block.
162
162
 
163
- **The group is also the contract at runtime.** A `z.object` strips what it does not declare, so
163
+ **The group is also the contract at runtime.** A `z.object` strips what it does not declare (here that is
164
+ the point; an object you forward to an API wants `z.looseObject()`, see
165
+ [02-zod-types.md](02-zod-types.md#zobject-or-zlooseobject)), so
164
166
  `z.filesUploadOptions(['scope'])` hands your handler `{ scope }` and nothing else, with the platform default
165
167
  already filled in. Anything you did not expose is yours to pass:
166
168
 
@@ -59,6 +59,12 @@ const tableIdParam = z.string()
59
59
 
60
60
  - The `execute` bag is the shared handler context (see [07-actions.md](07-actions.md)) plus `search`,
61
61
  `cursor`, and the resolved `criteria`.
62
+ - **`search` is always text, trimmed.** It is `''` when the author opened the dropdown without typing or typed
63
+ only spaces, and never `undefined` or `null`. So never guard or convert it: no `String(search)`,
64
+ `search?.trim()` or `(search || '')`. Check it with `if (search)`.
65
+ ⚠️ **Never send it to the API as is.** A query key or body field set to `''` is sent as an empty filter
66
+ (`?name=`), which some APIs read as "name is empty" and answer with nothing. Leave it out when nothing was
67
+ typed: `query: { name: search || undefined }`.
62
68
  - Return `{ items, cursor }` for paginated sources, or a bare `items` array when there is no pagination.
63
69
  - **The `id` starts with `get` and ends with `Dictionary`**, and the const holding the ref carries the same
64
70
  name — so the declaration and every `.dictionary(ref)` read alike.
@@ -145,12 +151,12 @@ const getChatsDictionary = ext.dictionary({
145
151
  description: 'Type a numeric chat ID or @username to resolve the chat.',
146
152
  result : { items: [{ label: 'Team Standup (group)', value: '-1001234567890' }], cursor: null },
147
153
  execute : async ({ search, apiRequest }) => {
148
- if (!search?.trim()) {
154
+ if (!search) {
149
155
  return { items: [], cursor: null }
150
156
  }
151
157
 
152
158
  try {
153
- const chat = await apiRequest({ url: '/getChat', query: { chat_id: search.trim() } })
159
+ const chat = await apiRequest({ url: '/getChat', query: { chat_id: search } })
154
160
 
155
161
  return { items: [{ label: `${ chat.title ?? chat.username } (${ chat.type })`, value: String(chat.id) }] }
156
162
  } catch (error) {
@@ -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 `z.looseObject()` keeps the keys it does not declare, which is how a `.dynamicProps()` field keeps its loaded fields). 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; see [02-zod-types.md](02-zod-types.md#zobject-or-zlooseobject) for which one a nested object needs). 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()`.
@@ -94,6 +94,9 @@ There is no `.uiComponent()`; the widget follows the zod type (after unwrapping
94
94
  | `z.number()` | `NUMBER` | `NUMERIC_STEPPER` |
95
95
  | `z.boolean()` | `BOOLEAN` | `TOGGLE` |
96
96
  | `z.date()` | `STRING` | `DATE_PICKER` |
97
+ | `z.iso.date()` | `STRING` | `DATE_PICKER` + `valueKind: 'string'` + `format` (the `.dateFormat()` pattern, else `yyyy-MM-dd`) |
98
+ | `z.iso.datetime({ local: true })` | `STRING` | `DATE_TIME_PICKER` + `valueKind: 'string'` + `format` (else `yyyy-MM-dd'T'HH:mm`) |
99
+ | `z.iso.time()` | `STRING` | `TIME_PICKER` + `valueKind: 'string'` + `format` (else `HH:mm`) |
97
100
  | `z.enum([...])` | `STRING` | `DROPDOWN` — `{ value, label }` pairs when `.labels()` is declared, else the enum values |
98
101
  | `z.object({...})` | `OBJECT` | — (recurses into `properties`) |
99
102
  | `z.array(inner)` | `LIST` | — (`items.type` from the element) |
@@ -101,7 +101,7 @@ const getBoardsDictionary = ext.dictionary({
101
101
  execute : async ({ search, cursor, criteria, apiRequest }) => {
102
102
  const response = await apiRequest({
103
103
  url : `/workspaces/${ criteria.workspaceId }/boards`,
104
- query: { q: search, cursor },
104
+ query: { q: search || undefined, cursor }, // '' when nothing was typed: no filter, not an empty one
105
105
  })
106
106
 
107
107
  return {
@@ -25,7 +25,8 @@ builder that prunes `''` makes the documented "leave it blank to clear it" behav
25
25
  error anywhere.
26
26
 
27
27
  **The inverse is equally sharp, and appears the moment you fix the first half.** Once `''` reaches the wire,
28
- every optional string param sends one when the flow author leaves it blank — and for an API where an absent
28
+ every optional string param sends one whenever a flow passes an empty value (a cleared config field, the Empty
29
+ Text chip, a bound `''`; a block field left untouched arrives as `null`, which is absence) — and for an API where an absent
29
30
  field means *keep the current value*, a blank one now **overwrites** it. Copy/duplicate endpoints are the
30
31
  usual place this bites: an absent caption keeps the original, an empty caption erases it.
31
32
 
@@ -41,15 +42,17 @@ documentation.
41
42
  ### The same `''` fails a format-constrained field
42
43
 
43
44
  Because `''` is a value, it reaches the format check and fails it — and `.optional()` does not help, since
44
- the field WAS provided. A cleared text box is what sends it, so this fires the first time a flow author
45
- leaves an optional URL or email blank:
45
+ the field WAS provided. A cleared config text box sends it, and so does a flow passing an empty value, so this
46
+ fires the first time someone clears an optional URL or email:
46
47
 
47
48
  ```js
48
- webhookUrl: z.url().optional().label('Webhook URL') // blank → «Webhook URL» is invalid — expects a URL
49
- webhookUrl: z.union([z.url(), z.literal('')]).optional().label('Webhook URL') // blank → not provided
49
+ webhookUrl: z.url().optional().label('Webhook URL') // '' → «Webhook URL» is invalid — expects a URL
50
+ webhookUrl: z.union([z.url(), z.literal('')]).optional().label('Webhook URL') // '' → '' (a value)
50
51
  ```
51
52
 
52
- Declare the union wherever blank has to mean "not set". A non-empty value still has to satisfy the format.
53
+ Declare the union wherever an empty value must be accepted, then decide in the handler what `''` means:
54
+ `params.webhookUrl || undefined` when empty means "not set", the vendor's clear when it means "clear it". A
55
+ non-empty value still has to satisfy the format.
53
56
 
54
57
  ## An optional object the author never filled in is absent — but may still arrive as `{}`
55
58
 
@@ -187,6 +190,85 @@ with nothing anywhere to catch it.
187
190
  - **An input flag is a param, not a response flag.** A flag that reaches you as a param — a criterion, a
188
191
  value bound from a template — is declared `z.boolean()`, and the runtime converts it.
189
192
 
193
+ ## An object you forward must be a `z.looseObject`
194
+
195
+ A `z.object({ … })` drops every key it does not declare, at every depth. Nothing is refused and nothing is
196
+ logged: your handler simply receives a smaller object than the caller sent. If the handler then forwards
197
+ that object to the API, the request is missing every field the schema did not name, and the call still
198
+ succeeds.
199
+
200
+ ```js
201
+ // ✗ forwarded as is: each table reaches the API as { name }, so its columns are lost
202
+ tables: z.array(z.object({ name: z.string().label('Name') })).label('Tables'),
203
+
204
+ // ✓ the form still draws Name; fields, description and anything the vendor adds pass through
205
+ tables: z.array(z.looseObject({ name: z.string().label('Name') })).label('Tables'),
206
+ ```
207
+
208
+ - **The handler forwards the object → `z.looseObject({ … })`.** Declare only the fields the form should draw.
209
+ - **The handler reads named fields and builds its own request → `z.object({ … })`.** There the dropping is a
210
+ whitelist, which is what you want.
211
+ - **It is easiest to get wrong when you first declare a shape**, for example an element described only in
212
+ prose until now. Adding the shape also adds a filter on every key you did not think to list.
213
+ - **Each level is separate.** A loose object inside a plain one keeps its own extra keys, but the outer object
214
+ still drops its own.
215
+
216
+ Details in [02-zod-types.md](02-zod-types.md#zobject-or-zlooseobject).
217
+
218
+ ## A list is a `z.array`, never comma-separated text you split
219
+
220
+ A param that holds several values, such as ids, emails or tags, is declared as a list of its element type. Do
221
+ not declare it as a "comma-separated" `z.string()` that the handler splits:
222
+
223
+ ```js
224
+ // ✗ a bound list arrives as JSON text: '["1","5"]'.split(',') → ['["1"', '"5"]'] → parseInt → [NaN, NaN],
225
+ // which the API receives as [null, null], and the call still succeeds
226
+ listIds: z.string().label('List IDs').describe('Comma-separated list IDs (e.g. \'1,5,12\').').optional(),
227
+ …
228
+ if (listIds) payload.listIds = listIds.split(',').map(id => parseInt(id.trim(), 10))
229
+
230
+ // ✓ every element is converted and checked before execute runs
231
+ listIds: z.array(z.number()).label('List IDs').describe('IDs of the contact lists to add the contact to.').optional(),
232
+ …
233
+ if (listIds?.length) payload.listIds = listIds
234
+ ```
235
+
236
+ - **The handler gets a real array of the declared type.** `['1', '5']` arrives as `[1, 5]`, and `[1, 'x']` is
237
+ refused with `«List IDs item 2» must be a number`. Do not split, trim or `parseInt` it again.
238
+ - **Choose the element type from the vendor's API docs:** `z.number()` for integer ids, `z.string()` for string
239
+ ids and tags, `z.email()`, `z.url()`, or `z.enum([...])` for a fixed set of values.
240
+ - **A vendor that wants comma text on the wire** (`?fields=a,b`) still gets a `z.array(...)` param. Join it
241
+ with `.join(',')` where you build the request, and nowhere else.
242
+ - **Text is not split for you.** `'1,5,12'` given to a list param is refused with `«List IDs» must be an
243
+ array`. JSON text (`'[1,5,12]'`) is parsed.
244
+ - **Keep the elements required.** A `null` or missing element is then refused with
245
+ `«List IDs item 2» is required`, so no gap reaches the handler. Under `z.string().optional()`,
246
+ `.nullable()` or `z.unknown()` elements, and in any list a vendor sends back, a gap does get through. There,
247
+ turn an element into text with `String(x ?? '')`. `String(x)` gives `'null'` / `'undefined'`, and `x || ''`
248
+ also erases `0` and `false`.
249
+
250
+ Details in [02-zod-types.md](02-zod-types.md#text-and-structures).
251
+
252
+ ## A date the vendor wants as text is `.dateFormat()`, never a `z.date()` you format
253
+
254
+ A `z.date()` value is an **instant**. Turning it into the text a vendor wants (`20/05/2026`, `10:00`) needs a
255
+ time zone, and your handler has none — so the usual code is wrong for every author east of UTC:
256
+
257
+ ```js
258
+ // ✗ the picker stores local midnight: 20 May picked in UTC+3 is 2026-05-19T21:00:00Z
259
+ dueDate: z.date()
260
+ // …
261
+ body.due = new Date(params.dueDate).toISOString().slice(0, 10) // '2026-05-19' — a day early
262
+
263
+ // ✓ the picker stores the day the author clicked, as text in your pattern
264
+ dueDate: z.iso.date().dateFormat('dd/MM/yyyy')
265
+ // …
266
+ body.due = params.dueDate // '20/05/2026'
267
+ ```
268
+
269
+ The same goes for `getUTCDate()` / `getUTCHours()` and hand-rolled `pad2` helpers. Keep `z.date()` for a field
270
+ whose vendor wants an instant. Details in [02-zod-types.md](02-zod-types.md#dates--an-instant-or-a-date-as-text).
271
+
190
272
  ## A schema slot must be a `z.object`, or the method quietly has no inputs
191
273
 
192
274
  `params`, `criteria` and `configItems` are containers of named fields. Hand one anything else and there is
@@ -301,6 +383,7 @@ Do not restate these here; they are covered where they belong.
301
383
  | A binary download is `.toBuffer()`, not a response encoding — an encoded body is parsed and corrupted | [04-http-requests.md](04-http-requests.md) |
302
384
  | `ResponseError.message` is the response *body*, so it can be an object | [04-http-requests.md](04-http-requests.md) |
303
385
  | A blank (`''`) fails `z.url().optional()` — `.optional()` does not cover it | this document |
386
+ | A `.dateFormat()` pattern is checked at load; `YYYY`, `DD`, and `hh` without `a` are refused | [02-zod-types.md](02-zod-types.md#dateformatpattern) |
304
387
  | Secrets in logs, credentials in the URL, credentials or caller headers sent to an origin the service didn't choose, upload MIME type | [19-security.md](19-security.md) |
305
388
  | `.default()` is not applied to realtime-trigger `match` params | [13-runtime-contracts.md](13-runtime-contracts.md) |
306
389
  | `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) |
@@ -11,7 +11,8 @@ touches a file does not need *Files API*.
11
11
 
12
12
  `{ search?, cursor?, criteria? }` in, `{ items: [{ label, value, note? }], cursor }` out
13
13
  ([05-dictionaries.md](05-dictionaries.md)). Cover the mapping, a case-insensitive search, an absent
14
- `search` listing everything, and empty data answering `{ items: [], cursor: null }`.
14
+ `search` listing everything, and empty data answering `{ items: [], cursor: null }`. For an absent `search`,
15
+ assert the exact request too: `execute` receives it as `''`, and the filter must be left out, not sent empty.
15
16
 
16
17
  **A dictionary is invoked through a single `payload` param** — the runner synthesizes it, you never declare
17
18
  it ([05-dictionaries.md](05-dictionaries.md)). So `methodData` wraps the whole `{ search, cursor, criteria }`
@@ -62,7 +62,7 @@ conditional groups that apply, together.
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 |
65
- | 7 | [16-gotchas.md](16-gotchas.md) | Cross-cutting traps that fail *silently* — empty-string params, lookup tables keyed by user input, dictionary error handling. Deliberately short |
65
+ | 7 | [16-gotchas.md](16-gotchas.md) | Cross-cutting traps that fail *silently* — empty-string params, lookup tables keyed by user input, dictionary error handling, a forwarded object that drops its keys, a list declared as comma-separated text. Deliberately short |
66
66
  | 8 | [19-security.md](19-security.md) | Four silent security mistakes: secrets in logs, credentials in the URL, credentials or headers sent where the service didn't choose, upload MIME type. Short — check a service against it before calling it done |
67
67
  | 9 | [14-reference-service.md](14-reference-service.md) | A complete verified service exercising the whole surface — **read this instead of the CLI templates** |
68
68