@flowrunner/cli 0.1.16 → 0.1.18
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/ai-docs/instructions/service-code-format/02-zod-types.md +87 -29
- package/ai-docs/instructions/service-code-format/03-parameters.md +3 -1
- package/ai-docs/instructions/service-code-format/05-dictionaries.md +8 -2
- package/ai-docs/instructions/service-code-format/07-actions.md +5 -1
- package/ai-docs/instructions/service-code-format/14-reference-service.md +1 -1
- package/ai-docs/instructions/service-code-format/16-gotchas.md +90 -0
- package/ai-docs/instructions/service-code-format/18-test-recipes.md +2 -1
- package/ai-docs/instructions/service-code-format/README.md +1 -1
- package/dist/cli.js +61 -47
- package/dist/cli.js.map +3 -3
- package/dist/index.js +60 -46
- package/dist/index.js.map +3 -3
- package/dist/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
- package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -11
- package/dist/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
- package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +9 -19
- package/dist/types/flow-extension-runner/src/v2/types.d.ts +1 -1
- package/package.json +1 -1
- package/runtime/index.js +60 -46
- package/runtime/index.js.map +3 -3
- package/runtime/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +1 -1
- package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +4 -11
- package/runtime/types/flow-extension-runner/src/v2/params/widget-types.d.ts +1 -1
- package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +9 -19
- package/runtime/types/flow-extension-runner/src/v2/types.d.ts +1 -1
|
@@ -8,12 +8,12 @@ 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.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)) |
|
|
16
|
+
| `z.looseObject({...})` | nested form — **keeps** the keys it does not declare; see [`z.object` or `z.looseObject`](#zobject-or-zlooseobject) | | | | |
|
|
17
17
|
| `z.array(inner)` | list | | `.labels({ value: 'Label' })` | `z.enum` | UI shows the label; the flow stores and `execute` receives the VALUE |
|
|
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)) | | | | |
|
|
@@ -58,38 +58,59 @@ Notes:
|
|
|
58
58
|
(There is no `.map({ Label: value })` — it took its argument the other way round, treating labels as the
|
|
59
59
|
accepted values. It throws when the service loads, naming `.labels()`.)
|
|
60
60
|
|
|
61
|
-
##
|
|
61
|
+
## The widget follows the type — there is no override
|
|
62
62
|
|
|
63
|
-
|
|
64
|
-
|
|
63
|
+
There is no option for choosing a widget. The type you declare decides **both** the widget and the value
|
|
64
|
+
your handler receives. When the vendor wants something the obvious declaration doesn't give you, choose by
|
|
65
|
+
what the **handler** needs, and convert in the handler:
|
|
66
|
+
|
|
67
|
+
| You need | Declare | Why not the obvious spelling |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| 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 |
|
|
70
|
+
| Any value from the flow (text, a number, an object, a list) passed through as given | `z.unknown()` (`.required()` if it must be set) | — |
|
|
71
|
+
| 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)) | — |
|
|
72
|
+
| Several lines of text | `z.text()` | — |
|
|
73
|
+
| 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)) |
|
|
74
|
+
|
|
75
|
+
**`z.json()` is not supported.** It fails when the extension loads, with a message naming the two declarations
|
|
76
|
+
above. A value whose shape you don't declare is `z.unknown()`. One you do know is the shape itself, which
|
|
77
|
+
also accepts JSON text, so nothing is lost. `z.unknown()` passes text through **as text**: if the author may
|
|
78
|
+
type JSON into it, parse it yourself.
|
|
79
|
+
|
|
80
|
+
## `z.object` or `z.looseObject`
|
|
81
|
+
|
|
82
|
+
Both draw the same nested form and publish the same model. They differ in what your handler receives. A
|
|
83
|
+
`z.object()` **drops every key it does not declare**: silently, with nothing refused and nothing logged. A
|
|
84
|
+
`z.looseObject()` checks and converts the keys it declares and passes the rest through untouched.
|
|
65
85
|
|
|
66
86
|
```js
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
}
|
|
87
|
+
z.array(z.object({ name: z.string() })) // [{ name: 'a', fields: [1] }] → [{ name: 'a' }]
|
|
88
|
+
z.array(z.looseObject({ name: z.string() })) // [{ name: 'a', fields: [1] }] → [{ name: 'a', fields: [1] }]
|
|
74
89
|
```
|
|
75
90
|
|
|
76
|
-
|
|
77
|
-
but the runtime parses it before your handler runs, and `execute` receives the parsed value. **Never call
|
|
78
|
-
`JSON.parse` on it yourself.**
|
|
91
|
+
Choose by what the handler does with the object:
|
|
79
92
|
|
|
80
|
-
- **
|
|
81
|
-
|
|
82
|
-
-
|
|
83
|
-
|
|
84
|
-
|
|
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.
|
|
93
|
+
- **It forwards the object to the API as is → `z.looseObject({ … })`.** Declare the fields the form should
|
|
94
|
+
draw. Everything else the caller sends, including fields the vendor adds later, still reaches the API. A
|
|
95
|
+
free-form map with no fields to draw is `z.looseObject({})`.
|
|
96
|
+
- **It reads named fields and builds its own request → `z.object({ … })`.** Dropping an undeclared key is the
|
|
97
|
+
point there: the object is a whitelist.
|
|
89
98
|
|
|
90
|
-
|
|
91
|
-
`z.object({
|
|
92
|
-
`
|
|
99
|
+
The forwarding case is easy to get wrong when you first declare a shape. For example, a list of tables is
|
|
100
|
+
sent to the API, but its element is declared as `z.object({ name })` to draw a *Name* field. Every table then
|
|
101
|
+
reaches the API as `{ name }`. The API creates tables with no columns and reports success.
|
|
102
|
+
|
|
103
|
+
Looseness applies to **one level**. A `z.looseObject()` inside a `z.object()` keeps its own extra keys, but the
|
|
104
|
+
outer object still drops its own. Declare each level that is forwarded as loose.
|
|
105
|
+
|
|
106
|
+
`z.record(z.string(), v)` adds something only when **each value** must be checked against `v`:
|
|
107
|
+
`z.record(z.string(), z.number())` converts `{ a: '1' }` to `{ a: 1 }`. A `z.record(z.string(), z.unknown())`
|
|
108
|
+
behaves exactly like `z.looseObject({})`. They publish the same model and pass the same values through, so
|
|
109
|
+
prefer the shorter one.
|
|
110
|
+
|
|
111
|
+
The top-level `params` object is the exception. It is always a `z.object()`, and its undeclared fields are
|
|
112
|
+
dropped unless the action declares `dynamicParams` (see [07-actions.md](07-actions.md)). Looseness is for the
|
|
113
|
+
objects **inside** it.
|
|
93
114
|
|
|
94
115
|
## The type list is CLOSED
|
|
95
116
|
|
|
@@ -115,6 +136,9 @@ dropped out of type coercion, so the string values a flow supplies were never co
|
|
|
115
136
|
under an unrecognised modifier therefore handed `execute` `false` for an explicit `'true'`. A deploy that
|
|
116
137
|
stops is better than a parameter that looks fine and is wrong.
|
|
117
138
|
|
|
139
|
+
`z.json()` is refused too, even earlier: the call itself throws, naming `z.unknown()` and the declared
|
|
140
|
+
shape (see [The widget follows the type](#the-widget-follows-the-type--there-is-no-override)).
|
|
141
|
+
|
|
118
142
|
These modifiers are looked THROUGH — the parameter publishes and coerces as the type underneath:
|
|
119
143
|
|
|
120
144
|
| Modifier | Published as |
|
|
@@ -257,7 +281,7 @@ The two other differences are structural:
|
|
|
257
281
|
|
|
258
282
|
| Declared in `configItems` | What happens |
|
|
259
283
|
|---|---|
|
|
260
|
-
| `z.object({...})`, `z.array(inner)` | **
|
|
284
|
+
| `z.object({...})`, `z.array(inner)` | **a plain text box** that takes the value as JSON text (`{"region":"eu"}`, `["a","b"]`), parsed and checked like any object or list — see [Text and structures](#text-and-structures). Usable, but a poor form: prefer a param for structured input |
|
|
261
285
|
| `.dictionary(ref)` | **ignored** — a config value is resolved before any method runs, so there is no invocation to fetch options for. Use `z.enum([...])` for a fixed set of choices |
|
|
262
286
|
|
|
263
287
|
`z.date()` in a config field is a date, with no time of day. Declare a string if you need one.
|
|
@@ -267,6 +291,37 @@ conversion.** `z.coerce.*` does not add to it, so `z.coerce.number()` and `z.num
|
|
|
267
291
|
as do the boolean and string forms. The one exception is `z.date()` — declare **`z.coerce.date()`** when your handler wants a real `Date`
|
|
268
292
|
instance rather than the string or epoch-millis the caller sent.
|
|
269
293
|
|
|
294
|
+
### Text and structures
|
|
295
|
+
|
|
296
|
+
Text and structured values convert into each other, so a value survives a trip through a text box or an
|
|
297
|
+
expression either way:
|
|
298
|
+
|
|
299
|
+
- **A text field takes any value.** An object or a list given to `z.string()`, `z.text()` or a format becomes
|
|
300
|
+
its JSON text. `null` and a missing value are still blanks, never the text `'null'`.
|
|
301
|
+
- **An object or list field takes JSON text.** Text given to `z.object()`, `z.looseObject()`, `z.record()` or
|
|
302
|
+
`z.array()` is parsed when it is JSON of the matching kind — `{…}` for an object or record, `[…]` for a list —
|
|
303
|
+
and then converted and checked like any other value.
|
|
304
|
+
|
|
305
|
+
```js
|
|
306
|
+
note : z.string() // { a: 1 } → '{"a":1}'
|
|
307
|
+
title: z.string().max(5) // { a: 1 } → «Title» must be at most 5 (checks run on the text)
|
|
308
|
+
point: z.object({ x: z.number() }) // '{"x":"1"}' → { x: 1 }
|
|
309
|
+
ids : z.array(z.number()) // '[1,"2"]' → [1, 2]
|
|
310
|
+
ids : z.array(z.number()) // '1,2' → «Ids» must be an array (not JSON — not split)
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
Anything that is not JSON of the right kind is refused as before: a comma-separated value is not split for
|
|
314
|
+
you, and `'{a:1}'` (unquoted key) is not JSON. `''` is still a blank; `'{}'` and `'[]'` are values.
|
|
315
|
+
|
|
316
|
+
In a union, a value that already fits a branch is kept (see above), and an object or a list is **never** turned
|
|
317
|
+
into text through a `z.string()` branch: it takes a branch of its own kind or the union's error, so a malformed
|
|
318
|
+
object is reported rather than sent as JSON text.
|
|
319
|
+
|
|
320
|
+
The flip side: an object bound by mistake to a plain text field (a subject, a name) is sent as JSON text
|
|
321
|
+
rather than refused. The same applies to a list bound to a text param: it arrives as `'["1","5"]'`, not
|
|
322
|
+
`'1,5'`. So a param that holds several values is a `z.array(…)`, never comma-separated text the handler
|
|
323
|
+
splits. See [16-gotchas.md](16-gotchas.md#a-list-is-a-zarray-never-comma-separated-text-you-split).
|
|
324
|
+
|
|
270
325
|
### What a boolean accepts
|
|
271
326
|
|
|
272
327
|
A `z.boolean()` is rarely filled in by hand — its value usually arrives from a spreadsheet column, a CSV
|
|
@@ -282,12 +337,15 @@ booleans `true`/`false` and the numbers `1`/`0`:
|
|
|
282
337
|
So `'YES'`, `' Off '` and `'Enabled'` all work.
|
|
283
338
|
|
|
284
339
|
**Anything else is a validation error, not a guess.** `'maybe'`, `'2'`, `'tr'`, a list or an object each
|
|
285
|
-
fail with `«Field»
|
|
340
|
+
fail with `«Field» must be true or false`. That matters more than the width of the list: a
|
|
286
341
|
conversion that quietly turned an unrecognised value into `false` would read an explicit *on* as *off* and
|
|
287
342
|
never say so.
|
|
288
343
|
|
|
289
344
|
A blank is absence rather than `false` — see [16-gotchas.md](16-gotchas.md).
|
|
290
345
|
|
|
346
|
+
This list applies to **params** only. A vendor's response is never converted: compare a response flag with the
|
|
347
|
+
value the vendor documents — see [16-gotchas.md](16-gotchas.md#conversion-runs-on-the-way-in-never-on-the-way-back).
|
|
348
|
+
|
|
291
349
|
If you need a spelling that is not listed, the test for adding one is that **it has an unambiguous opposite
|
|
292
350
|
and the pair is added together.** A word with no opposite is a status, not a boolean, and belongs in a
|
|
293
351
|
`z.enum([...])`.
|
|
@@ -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
|
|
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
|
|
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
|
|
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()`.
|
|
@@ -104,6 +104,10 @@ execute: async ({ params, apiRequest }) => {
|
|
|
104
104
|
The same applies to a list endpoint: return the items **and** the paging fields around them, not a bare
|
|
105
105
|
array. Adding a derived field is fine — spread the response and add to it — but the original fields stay.
|
|
106
106
|
|
|
107
|
+
A response is not converted the way params are: a vendor's `"0"` arrives as the string `"0"`, which is truthy.
|
|
108
|
+
Branch on a response flag by comparing it with the value the vendor documents — see
|
|
109
|
+
[16-gotchas.md](16-gotchas.md#conversion-runs-on-the-way-in-never-on-the-way-back).
|
|
110
|
+
|
|
107
111
|
## `execute` context bag
|
|
108
112
|
|
|
109
113
|
The same bag is passed to actions, dictionaries, triggers, and result-loaders (accessed via arguments,
|
|
@@ -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 {
|
|
@@ -156,6 +156,96 @@ The general rule: when one value is reachable in more than one form, either deri
|
|
|
156
156
|
place, or make the derivation itself idempotent to the difference. This applies to anything `initContext`
|
|
157
157
|
touches — a base URL with or without a trailing slash, an id as a string or a number.
|
|
158
158
|
|
|
159
|
+
## Conversion runs on the way in, never on the way back
|
|
160
|
+
|
|
161
|
+
A `z.boolean()` **param** accepts `yes`, `on`, `1`, `'false'` and the rest of the list in
|
|
162
|
+
[02-zod-types.md](02-zod-types.md#what-a-boolean-accepts). Nothing like that happens to what a **vendor** sends
|
|
163
|
+
back: a response is not declared, so it reaches your code exactly as the API serialized it. A flag sent as the
|
|
164
|
+
string `"0"` is truthy:
|
|
165
|
+
|
|
166
|
+
```js
|
|
167
|
+
note: record.is_active ? 'Active' : 'Archived' // ✗ "0" → 'Active'
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
That shipped as a disconnected device badged *Online*, unverified senders offered as verified, and archived
|
|
171
|
+
projects labelled *Active* — and in a dictionary's `note` or `label` it is a wrong choice made by a person,
|
|
172
|
+
with nothing anywhere to catch it.
|
|
173
|
+
|
|
174
|
+
**Compare the flag strictly against the value the vendor documents**, at the point you branch on it:
|
|
175
|
+
|
|
176
|
+
| The vendor documents | Branch on |
|
|
177
|
+
|---|---|
|
|
178
|
+
| a JSON boolean | `entry.toll_free === true` |
|
|
179
|
+
| `'1'` / `'0'` | `form.is_active === '1'` |
|
|
180
|
+
| `'true'` / `'false'` | `rule.hidden === 'true'` |
|
|
181
|
+
|
|
182
|
+
- **Read the vendor's docs (or a real response) per field** for the form it sends, and test with that form.
|
|
183
|
+
- **Widen only where the vendor really varies** — one endpoint answering `1` and another `"1"`:
|
|
184
|
+
`[1, '1'].includes(entry.active)`. Not a helper that knows ten spellings.
|
|
185
|
+
- **A pass-through is not this trap.** `list.counts.subscribed ?? 0` forwards a value; only a *branch* on a
|
|
186
|
+
flag can invert one.
|
|
187
|
+
- **An input flag is a param, not a response flag.** A flag that reaches you as a param — a criterion, a
|
|
188
|
+
value bound from a template — is declared `z.boolean()`, and the runtime converts it.
|
|
189
|
+
|
|
190
|
+
## An object you forward must be a `z.looseObject`
|
|
191
|
+
|
|
192
|
+
A `z.object({ … })` drops every key it does not declare, at every depth. Nothing is refused and nothing is
|
|
193
|
+
logged: your handler simply receives a smaller object than the caller sent. If the handler then forwards
|
|
194
|
+
that object to the API, the request is missing every field the schema did not name, and the call still
|
|
195
|
+
succeeds.
|
|
196
|
+
|
|
197
|
+
```js
|
|
198
|
+
// ✗ forwarded as is: each table reaches the API as { name }, so its columns are lost
|
|
199
|
+
tables: z.array(z.object({ name: z.string().label('Name') })).label('Tables'),
|
|
200
|
+
|
|
201
|
+
// ✓ the form still draws Name; fields, description and anything the vendor adds pass through
|
|
202
|
+
tables: z.array(z.looseObject({ name: z.string().label('Name') })).label('Tables'),
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
- **The handler forwards the object → `z.looseObject({ … })`.** Declare only the fields the form should draw.
|
|
206
|
+
- **The handler reads named fields and builds its own request → `z.object({ … })`.** There the dropping is a
|
|
207
|
+
whitelist, which is what you want.
|
|
208
|
+
- **It is easiest to get wrong when you first declare a shape**, for example an element described only in
|
|
209
|
+
prose until now. Adding the shape also adds a filter on every key you did not think to list.
|
|
210
|
+
- **Each level is separate.** A loose object inside a plain one keeps its own extra keys, but the outer object
|
|
211
|
+
still drops its own.
|
|
212
|
+
|
|
213
|
+
Details in [02-zod-types.md](02-zod-types.md#zobject-or-zlooseobject).
|
|
214
|
+
|
|
215
|
+
## A list is a `z.array`, never comma-separated text you split
|
|
216
|
+
|
|
217
|
+
A param that holds several values, such as ids, emails or tags, is declared as a list of its element type. Do
|
|
218
|
+
not declare it as a "comma-separated" `z.string()` that the handler splits:
|
|
219
|
+
|
|
220
|
+
```js
|
|
221
|
+
// ✗ a bound list arrives as JSON text: '["1","5"]'.split(',') → ['["1"', '"5"]'] → parseInt → [NaN, NaN],
|
|
222
|
+
// which the API receives as [null, null], and the call still succeeds
|
|
223
|
+
listIds: z.string().label('List IDs').describe('Comma-separated list IDs (e.g. \'1,5,12\').').optional(),
|
|
224
|
+
…
|
|
225
|
+
if (listIds) payload.listIds = listIds.split(',').map(id => parseInt(id.trim(), 10))
|
|
226
|
+
|
|
227
|
+
// ✓ every element is converted and checked before execute runs
|
|
228
|
+
listIds: z.array(z.number()).label('List IDs').describe('IDs of the contact lists to add the contact to.').optional(),
|
|
229
|
+
…
|
|
230
|
+
if (listIds?.length) payload.listIds = listIds
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
- **The handler gets a real array of the declared type.** `['1', '5']` arrives as `[1, 5]`, and `[1, 'x']` is
|
|
234
|
+
refused with `«List IDs item 2» must be a number`. Do not split, trim or `parseInt` it again.
|
|
235
|
+
- **Choose the element type from the vendor's API docs:** `z.number()` for integer ids, `z.string()` for string
|
|
236
|
+
ids and tags, `z.email()`, `z.url()`, or `z.enum([...])` for a fixed set of values.
|
|
237
|
+
- **A vendor that wants comma text on the wire** (`?fields=a,b`) still gets a `z.array(...)` param. Join it
|
|
238
|
+
with `.join(',')` where you build the request, and nowhere else.
|
|
239
|
+
- **Text is not split for you.** `'1,5,12'` given to a list param is refused with `«List IDs» must be an
|
|
240
|
+
array`. JSON text (`'[1,5,12]'`) is parsed.
|
|
241
|
+
- **Keep the elements required.** A `null` or missing element is then refused with
|
|
242
|
+
`«List IDs item 2» is required`, so no gap reaches the handler. Under `z.string().optional()`,
|
|
243
|
+
`.nullable()` or `z.unknown()` elements, and in any list a vendor sends back, a gap does get through. There,
|
|
244
|
+
turn an element into text with `String(x ?? '')`. `String(x)` gives `'null'` / `'undefined'`, and `x || ''`
|
|
245
|
+
also erases `0` and `false`.
|
|
246
|
+
|
|
247
|
+
Details in [02-zod-types.md](02-zod-types.md#text-and-structures).
|
|
248
|
+
|
|
159
249
|
## A schema slot must be a `z.object`, or the method quietly has no inputs
|
|
160
250
|
|
|
161
251
|
`params`, `criteria` and `configItems` are containers of named fields. Hand one anything else and there is
|
|
@@ -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
|
|
package/dist/cli.js
CHANGED
|
@@ -14508,7 +14508,7 @@ var require_package = __commonJS({
|
|
|
14508
14508
|
"package.json"(exports2, module2) {
|
|
14509
14509
|
module2.exports = {
|
|
14510
14510
|
name: "@flowrunner/cli",
|
|
14511
|
-
version: "0.1.
|
|
14511
|
+
version: "0.1.18",
|
|
14512
14512
|
publishConfig: {
|
|
14513
14513
|
access: "public"
|
|
14514
14514
|
},
|
|
@@ -15904,9 +15904,6 @@ function literalType(core) {
|
|
|
15904
15904
|
}
|
|
15905
15905
|
function deriveWidget(ins) {
|
|
15906
15906
|
const { coreType, core, meta } = ins;
|
|
15907
|
-
if (meta.frJson) {
|
|
15908
|
-
return { paramType: "STRING", uiComponent: { type: FlowExtensionParamWidgetTypes.MULTI_LINE_TEXT } };
|
|
15909
|
-
}
|
|
15910
15907
|
switch (coreType) {
|
|
15911
15908
|
case "string":
|
|
15912
15909
|
if (meta.frWidget === FlowExtensionParamWidgetTypes.MULTI_LINE_TEXT) {
|
|
@@ -16296,7 +16293,6 @@ function declaredAbsence(schema) {
|
|
|
16296
16293
|
function coerces(schema) {
|
|
16297
16294
|
return inspect(schema).core?._zod?.def?.coerce === true;
|
|
16298
16295
|
}
|
|
16299
|
-
var parsesJson = (schema) => !!inspect(schema).meta.frJson;
|
|
16300
16296
|
var OPEN_TYPES = /* @__PURE__ */ new Set(["unknown", "any"]);
|
|
16301
16297
|
var isOpenType = (schema) => OPEN_TYPES.has(inspect(schema).coreType);
|
|
16302
16298
|
function requiredOpenType(schema) {
|
|
@@ -16318,7 +16314,7 @@ function requiredOpenType(schema) {
|
|
|
16318
16314
|
return false;
|
|
16319
16315
|
}
|
|
16320
16316
|
function probeAbsence(schema) {
|
|
16321
|
-
if (coerces(schema)
|
|
16317
|
+
if (coerces(schema)) {
|
|
16322
16318
|
return declaredAbsence(schema);
|
|
16323
16319
|
}
|
|
16324
16320
|
if (requiredOpenType(schema)) {
|
|
@@ -16345,7 +16341,7 @@ function absenceOf(schema) {
|
|
|
16345
16341
|
if (cached2) {
|
|
16346
16342
|
return cached2;
|
|
16347
16343
|
}
|
|
16348
|
-
const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema)
|
|
16344
|
+
const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema) };
|
|
16349
16345
|
probeCache.set(schema, probed);
|
|
16350
16346
|
return probed;
|
|
16351
16347
|
}
|
|
@@ -16379,8 +16375,29 @@ function toStringValue(value) {
|
|
|
16379
16375
|
if (typeof value === "boolean") {
|
|
16380
16376
|
return ok(String(value));
|
|
16381
16377
|
}
|
|
16378
|
+
if (value !== null && typeof value === "object") {
|
|
16379
|
+
return ok(value instanceof Date ? value.toISOString() : JSON.stringify(value));
|
|
16380
|
+
}
|
|
16382
16381
|
return typeof value === "number" && Number.isFinite(value) ? ok(String(value)) : fail2("string");
|
|
16383
16382
|
}
|
|
16383
|
+
var OPENS = { array: "[", object: "{" };
|
|
16384
|
+
function parseContainerText(value, kind) {
|
|
16385
|
+
if (typeof value !== "string") {
|
|
16386
|
+
return value;
|
|
16387
|
+
}
|
|
16388
|
+
const text2 = value.trim();
|
|
16389
|
+
if (!text2.startsWith(OPENS[kind])) {
|
|
16390
|
+
return value;
|
|
16391
|
+
}
|
|
16392
|
+
try {
|
|
16393
|
+
const parsed = JSON.parse(text2);
|
|
16394
|
+
const isList = Array.isArray(parsed);
|
|
16395
|
+
const fits = kind === "array" ? isList : parsed !== null && typeof parsed === "object" && !isList;
|
|
16396
|
+
return fits ? parsed : value;
|
|
16397
|
+
} catch {
|
|
16398
|
+
return value;
|
|
16399
|
+
}
|
|
16400
|
+
}
|
|
16384
16401
|
function toNumberValue(value) {
|
|
16385
16402
|
if (typeof value === "number") {
|
|
16386
16403
|
return Number.isFinite(value) ? ok(value) : fail2("number");
|
|
@@ -16420,16 +16437,6 @@ function toBooleanValue(value) {
|
|
|
16420
16437
|
const lowered = value.trim().toLowerCase();
|
|
16421
16438
|
return TRUE.has(lowered) ? ok(true) : FALSE.has(lowered) ? ok(false) : fail2("boolean");
|
|
16422
16439
|
}
|
|
16423
|
-
function toJsonValue(value) {
|
|
16424
|
-
if (typeof value !== "string") {
|
|
16425
|
-
return ok(value);
|
|
16426
|
-
}
|
|
16427
|
-
try {
|
|
16428
|
-
return ok(JSON.parse(value));
|
|
16429
|
-
} catch {
|
|
16430
|
-
return fail2("json");
|
|
16431
|
-
}
|
|
16432
|
-
}
|
|
16433
16440
|
function coerceValue(value, coreType) {
|
|
16434
16441
|
if (coreType === "string") {
|
|
16435
16442
|
return toStringValue(value);
|
|
@@ -16463,7 +16470,11 @@ function coerceUnion(value, branches) {
|
|
|
16463
16470
|
if (branches.some((branch) => accepts(branch, value))) {
|
|
16464
16471
|
return value;
|
|
16465
16472
|
}
|
|
16473
|
+
const isStructure = value !== null && typeof value === "object";
|
|
16466
16474
|
for (const branch of branches) {
|
|
16475
|
+
if (isStructure && inspect(branch).coreType === "string") {
|
|
16476
|
+
continue;
|
|
16477
|
+
}
|
|
16467
16478
|
const coerced = coerceDeep(value, branch);
|
|
16468
16479
|
if (accepts(branch, coerced)) {
|
|
16469
16480
|
return coerced;
|
|
@@ -16488,22 +16499,25 @@ function coerceDeep(value, schema) {
|
|
|
16488
16499
|
}
|
|
16489
16500
|
if (ins.coreType === "array") {
|
|
16490
16501
|
const element = ins.core?._zod?.def?.element;
|
|
16491
|
-
|
|
16502
|
+
const list = parseContainerText(value, "array");
|
|
16503
|
+
return Array.isArray(list) ? list.map((item) => coerceDeep(item, element)) : list;
|
|
16492
16504
|
}
|
|
16493
16505
|
if (ins.coreType === "record") {
|
|
16494
|
-
|
|
16495
|
-
|
|
16506
|
+
const map = parseContainerText(value, "object");
|
|
16507
|
+
if (typeof map !== "object" || Array.isArray(map)) {
|
|
16508
|
+
return map;
|
|
16496
16509
|
}
|
|
16497
16510
|
const valueType = ins.core?._zod?.def?.valueType;
|
|
16498
16511
|
return Object.fromEntries(
|
|
16499
|
-
Object.entries(
|
|
16512
|
+
Object.entries(map).map(([key, item]) => [key, coerceDeep(item, valueType)])
|
|
16500
16513
|
);
|
|
16501
16514
|
}
|
|
16502
16515
|
if (ins.coreType === "object") {
|
|
16503
|
-
|
|
16504
|
-
|
|
16516
|
+
const parsed = parseContainerText(value, "object");
|
|
16517
|
+
if (typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
16518
|
+
return parsed;
|
|
16505
16519
|
}
|
|
16506
|
-
const source =
|
|
16520
|
+
const source = parsed;
|
|
16507
16521
|
const coerced = { ...source };
|
|
16508
16522
|
for (const [name, property] of shapeEntries(ins.core)) {
|
|
16509
16523
|
if (name in source) {
|
|
@@ -16520,9 +16534,6 @@ function coerceLeaf(value, ins) {
|
|
|
16520
16534
|
if (ins.branches) {
|
|
16521
16535
|
return ok(coerceUnion(value, ins.branches));
|
|
16522
16536
|
}
|
|
16523
|
-
if (ins.meta.frJson) {
|
|
16524
|
-
return toJsonValue(value);
|
|
16525
|
-
}
|
|
16526
16537
|
const format = formatOf(ins);
|
|
16527
16538
|
if (ins.coreType === "string" && isConvertibleIso(format)) {
|
|
16528
16539
|
const iso = toIso(value, format);
|
|
@@ -16616,8 +16627,8 @@ var EXPECTED = {
|
|
|
16616
16627
|
date: "a date",
|
|
16617
16628
|
object: "an object",
|
|
16618
16629
|
array: "an array",
|
|
16619
|
-
// `z.
|
|
16620
|
-
|
|
16630
|
+
// zod's own token for `z.record()`, which the author declared as a map — to a person it is an object.
|
|
16631
|
+
record: "an object"
|
|
16621
16632
|
};
|
|
16622
16633
|
var requiredMessage = (plan2) => `\xAB${plan2.label}\xBB is required`;
|
|
16623
16634
|
var invalidTypeMessage = (plan2, expected) => `\xAB${plan2.label}\xBB must be ${EXPECTED[expected] ?? expected}`;
|
|
@@ -17035,10 +17046,9 @@ function text() {
|
|
|
17035
17046
|
return import_zod3.z.string().meta({ frWidget: FlowExtensionParamWidgetTypes.MULTI_LINE_TEXT });
|
|
17036
17047
|
}
|
|
17037
17048
|
function json() {
|
|
17038
|
-
|
|
17039
|
-
|
|
17040
|
-
|
|
17041
|
-
});
|
|
17049
|
+
throw new Error(
|
|
17050
|
+
"`z.json()` is not supported \u2014 declare `z.unknown()` for any value passed as given (`.required()` to make it required), or declare the shape: `z.object({ \u2026 })` / `z.array(\u2026)` also accept JSON text and parse it."
|
|
17051
|
+
);
|
|
17042
17052
|
}
|
|
17043
17053
|
var namespace = Object.create(import_zod3.z);
|
|
17044
17054
|
Object.defineProperties(namespace, {
|
|
@@ -17052,7 +17062,7 @@ Object.defineProperties(namespace, {
|
|
|
17052
17062
|
var z2 = namespace;
|
|
17053
17063
|
|
|
17054
17064
|
// ../../flow-extension-runner/src/v2/params/json/values.ts
|
|
17055
|
-
function
|
|
17065
|
+
function toJsonValue(value) {
|
|
17056
17066
|
if (typeof value === "bigint") {
|
|
17057
17067
|
return { $bigint: value.toString() };
|
|
17058
17068
|
}
|
|
@@ -17060,10 +17070,10 @@ function toJsonValue2(value) {
|
|
|
17060
17070
|
return { $date: value.toISOString() };
|
|
17061
17071
|
}
|
|
17062
17072
|
if (Array.isArray(value)) {
|
|
17063
|
-
return value.map(
|
|
17073
|
+
return value.map(toJsonValue);
|
|
17064
17074
|
}
|
|
17065
17075
|
if (value && typeof value === "object") {
|
|
17066
|
-
return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key,
|
|
17076
|
+
return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, toJsonValue(inner)]));
|
|
17067
17077
|
}
|
|
17068
17078
|
return value;
|
|
17069
17079
|
}
|
|
@@ -17098,18 +17108,18 @@ function encodeCheck(check) {
|
|
|
17098
17108
|
switch (def.check) {
|
|
17099
17109
|
// strings and arrays
|
|
17100
17110
|
case "min_length":
|
|
17101
|
-
return at("min",
|
|
17111
|
+
return at("min", toJsonValue(def.minimum));
|
|
17102
17112
|
case "max_length":
|
|
17103
|
-
return at("max",
|
|
17113
|
+
return at("max", toJsonValue(def.maximum));
|
|
17104
17114
|
case "length_equals":
|
|
17105
|
-
return at("length",
|
|
17115
|
+
return at("length", toJsonValue(def.length));
|
|
17106
17116
|
// numbers and bigints
|
|
17107
17117
|
case "greater_than":
|
|
17108
|
-
return at("min",
|
|
17118
|
+
return at("min", toJsonValue(def.value), def.inclusive ? void 0 : true);
|
|
17109
17119
|
case "less_than":
|
|
17110
|
-
return at("max",
|
|
17120
|
+
return at("max", toJsonValue(def.value), def.inclusive ? void 0 : true);
|
|
17111
17121
|
case "multiple_of":
|
|
17112
|
-
return at("multipleOf",
|
|
17122
|
+
return at("multipleOf", toJsonValue(def.value));
|
|
17113
17123
|
case "number_format":
|
|
17114
17124
|
return def.format === "safeint" || def.format === "int32" ? at("int") : void 0;
|
|
17115
17125
|
// the string sub-formats that are checks rather than types
|
|
@@ -17270,7 +17280,7 @@ function encodeMeta(meta, field, scope2, loaderId) {
|
|
|
17270
17280
|
if (hasFunction(source)) {
|
|
17271
17281
|
throw new Error(`Cannot encode "${field}": its metadata holds a function, which has no wire form.`);
|
|
17272
17282
|
}
|
|
17273
|
-
const encoded =
|
|
17283
|
+
const encoded = toJsonValue(source);
|
|
17274
17284
|
return Object.keys(encoded).length ? encoded : void 0;
|
|
17275
17285
|
}
|
|
17276
17286
|
function isLoose(core) {
|
|
@@ -17280,11 +17290,11 @@ function isLoose(core) {
|
|
|
17280
17290
|
function encodeValues(core, type) {
|
|
17281
17291
|
if (type === "enum") {
|
|
17282
17292
|
const entries = core?._zod?.def?.entries ?? {};
|
|
17283
|
-
return Object.values(entries).map(
|
|
17293
|
+
return Object.values(entries).map(toJsonValue);
|
|
17284
17294
|
}
|
|
17285
17295
|
if (type === "literal") {
|
|
17286
17296
|
const values = core?._zod?.def?.values ?? [];
|
|
17287
|
-
return values.map(
|
|
17297
|
+
return values.map(toJsonValue);
|
|
17288
17298
|
}
|
|
17289
17299
|
return void 0;
|
|
17290
17300
|
}
|
|
@@ -17314,7 +17324,7 @@ function encodeField(name, schema, seen = /* @__PURE__ */ new Set(), loaderId, s
|
|
|
17314
17324
|
...format ? { format } : {},
|
|
17315
17325
|
...optional ? { optional: true } : {},
|
|
17316
17326
|
...nullable ? { nullable: true } : {},
|
|
17317
|
-
...hasDefault ? { default:
|
|
17327
|
+
...hasDefault ? { default: toJsonValue(defaultValue) } : {},
|
|
17318
17328
|
...checks.length ? { checks } : {},
|
|
17319
17329
|
...values?.length ? { values } : {},
|
|
17320
17330
|
...meta ? { meta } : {},
|
|
@@ -17991,6 +18001,10 @@ var DictionaryMethod = class extends ExtensionMethod {
|
|
|
17991
18001
|
return this.criteria.keys();
|
|
17992
18002
|
}
|
|
17993
18003
|
// ── runtime ────────────────────────────────────────────────────────────────
|
|
18004
|
+
// `search` is always text, trimmed (FR-3910): `''` when the author typed nothing — the console then sends no
|
|
18005
|
+
// `search` at all — or only spaces. So a handler never guards it: `search ? { q: search } : undefined`, and
|
|
18006
|
+
// `search.toLowerCase()` as is. Surrounding spaces never mean anything to a lookup.
|
|
18007
|
+
//
|
|
17994
18008
|
// Two-stage: the `{ search, cursor, criteria }` envelope the runtime owns, then the author-declared
|
|
17995
18009
|
// criteria through the shared pipeline — reported as a criteria failure so the console can point at the
|
|
17996
18010
|
// dependent fields rather than the whole call.
|
|
@@ -17999,7 +18013,7 @@ var DictionaryMethod = class extends ExtensionMethod {
|
|
|
17999
18013
|
const payload = input.parseField("payload", DictionaryPayloadSchema);
|
|
18000
18014
|
const criteria = this.criteria.normalize(this.#resolveAliases(payload.criteria), input.invalidCriteria());
|
|
18001
18015
|
return {
|
|
18002
|
-
search: payload.search,
|
|
18016
|
+
search: payload.search?.trim() ?? "",
|
|
18003
18017
|
cursor: payload.cursor,
|
|
18004
18018
|
criteria
|
|
18005
18019
|
};
|