@flowrunner/cli 0.1.12-dev.2 → 0.1.13-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/ai-docs/instructions/service-code-format/02-zod-types.md +3 -1
  2. package/ai-docs/instructions/service-code-format/05-dictionaries.md +59 -1
  3. package/ai-docs/instructions/service-code-format/06-oauth2.md +9 -0
  4. package/ai-docs/instructions/service-code-format/11-output-model.md +6 -0
  5. package/dist/cli.js +10558 -65
  6. package/dist/cli.js.map +4 -4
  7. package/dist/index.js +10527 -58
  8. package/dist/index.js.map +4 -4
  9. package/dist/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +1 -0
  10. package/dist/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +4 -2
  11. package/dist/types/flow-extension-runner/src/v2/model/params-model.d.ts +2 -2
  12. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +1 -0
  13. package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +7 -1
  14. package/dist/types/flow-extension-runner/src/v2/params/schema/dictionary-binding.d.ts +37 -0
  15. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +7 -5
  16. package/dist/types/flow-extension-runner/src/v2/types.d.ts +1 -0
  17. package/dist/types/shared/src/constants/error-codes.d.ts +3 -0
  18. package/dist/types/shared/src/constants/index.d.ts +1 -0
  19. package/dist/types/shared/src/constants/notification-types.d.ts +59 -0
  20. package/dist/types/shared/src/constants/oauth-connection-error.d.ts +3 -0
  21. package/dist/types/shared/src/errors/api.d.ts +11 -0
  22. package/dist/types/shared/src/errors/index.d.ts +1 -0
  23. package/dist/types/shared/src/errors/oauth-connection.d.ts +4 -0
  24. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +26 -0
  25. package/dist/types/shared/src/scheme/integration-connection/dto.d.ts +46 -4
  26. package/dist/types/shared/src/scheme/notifications/dto.d.ts +1 -0
  27. package/dist/types/shared/src/scheme/notifications/rest.d.ts +2 -0
  28. package/dist/types/shared/src/scheme/shared-extensions/list.d.ts +52 -11
  29. package/dist/types/shared/src/scheme/shared-extensions/workspace-stack.d.ts +2 -2
  30. package/package.json +1 -4
  31. package/runtime/index.js +10516 -37
  32. package/runtime/index.js.map +4 -4
  33. package/runtime/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +1 -0
  34. package/runtime/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +4 -2
  35. package/runtime/types/flow-extension-runner/src/v2/model/params-model.d.ts +2 -2
  36. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +1 -0
  37. package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +7 -1
  38. package/runtime/types/flow-extension-runner/src/v2/params/schema/dictionary-binding.d.ts +37 -0
  39. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +7 -5
  40. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +1 -0
  41. package/runtime/types/shared/src/constants/error-codes.d.ts +3 -0
  42. package/runtime/types/shared/src/constants/index.d.ts +1 -0
  43. package/runtime/types/shared/src/constants/notification-types.d.ts +59 -0
  44. package/runtime/types/shared/src/constants/oauth-connection-error.d.ts +3 -0
  45. package/runtime/types/shared/src/errors/api.d.ts +11 -0
  46. package/runtime/types/shared/src/errors/index.d.ts +1 -0
  47. package/runtime/types/shared/src/errors/oauth-connection.d.ts +4 -0
  48. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +26 -0
  49. package/runtime/types/shared/src/scheme/integration-connection/dto.d.ts +46 -4
  50. package/runtime/types/shared/src/scheme/notifications/dto.d.ts +1 -0
  51. package/runtime/types/shared/src/scheme/notifications/rest.d.ts +2 -0
  52. package/runtime/types/shared/src/scheme/shared-extensions/list.d.ts +52 -11
  53. package/runtime/types/shared/src/scheme/shared-extensions/workspace-stack.d.ts +2 -2
@@ -40,7 +40,9 @@ Notes:
40
40
  It has no effect anywhere else: not on `z.text()`, which has no password mode, and not on an action or
41
41
  trigger param, whose value lives in the flow definition and is readable through the API — masking that
42
42
  input would suggest a protection that is not there. Put credentials in a `z.string()` config item.
43
- - `.dictionary(ref)` binds a param to a dictionary for dynamic options and auto-derives its `dependsOn`.
43
+ - `.dictionary(ref)` binds a param to a dictionary for dynamic options and auto-derives its `dependsOn` — the
44
+ dictionary's criteria keys, or their `criteriaAliases` where the method calls them differently (see
45
+ [05-dictionaries.md](05-dictionaries.md#one-dictionary-differently-named-params)).
44
46
  - `.dynamicProps({ dependsOn, execute })` loads the **inner fields** of an object param at design time, from
45
47
  the values of the sibling params named in `dependsOn`. It is allowed on **top-level action params only**
46
48
  (not on trigger params, config items, dictionary `criteria`, nested fields or an array's element), and the
@@ -2,7 +2,8 @@
2
2
 
3
3
  Dictionaries provide **dynamic options** for a param dropdown. `ext.dictionary(props)` returns a ref used
4
4
  via `.dictionary(ref)` on a param (see [02-zod-types.md](02-zod-types.md)). A dictionary declares its
5
- `criteria` once, and consumers auto-derive their `dependsOn` from it.
5
+ `criteria` once, and consumers auto-derive their `dependsOn` from it — as the names of their own params, through
6
+ `criteriaAliases` when those differ (see [One dictionary, differently named params](#one-dictionary-differently-named-params)).
6
7
 
7
8
  | Property | Type | Description |
8
9
  |---|---|---|
@@ -11,6 +12,7 @@ via `.dictionary(ref)` on a param (see [02-zod-types.md](02-zod-types.md)). A di
11
12
  | `label` | string | **Human-readable name** → `operationName`. Dictionaries are shown in the UI and exposed to AI tools, so **always set a label**. Falls back to `id` when omitted. |
12
13
  | `description` | string | Description. |
13
14
  | `criteria` | `z.object` | Optional dependency inputs (become `dependsOn` on consumers). Omit when the dictionary depends on nothing; declared ⇒ must be a `z.object` (see [03-parameters.md](03-parameters.md)). |
15
+ | `criteriaAliases` | `{ [criteriaKey]: string[] }` | Optional. Other param names a criteria key may be fed by, so one dictionary serves actions that call the same input differently. See [One dictionary, differently named params](#one-dictionary-differently-named-params). |
14
16
  | `result` | `{ items, cursor }` \| `z.` schema | Optional sample output → `metaInfo.sampleResult` + `OBJECT` `returnType`. Omit → `sampleResult: null`, `returnType: OBJECT`. |
15
17
  | `execute` | fn | see below. |
16
18
 
@@ -61,6 +63,62 @@ const tableIdParam = z.string()
61
63
  - **The `id` starts with `get` and ends with `Dictionary`**, and the const holding the ref carries the same
62
64
  name — so the declaration and every `.dictionary(ref)` read alike.
63
65
 
66
+ ## One dictionary, differently named params
67
+
68
+ A consumer's `dependsOn` is the dictionary's criteria keys, so by default **a criteria key must have the same
69
+ name as the param that feeds it**. When actions call the same input differently — most of them say
70
+ `documentId`, but a copy action has a `sourceDocumentId` and a `targetDocumentId` — do not declare a second
71
+ dictionary and do not rename the params. Name the other params in `criteriaAliases`:
72
+
73
+ ```js
74
+ const getSheetsDictionary = ext.dictionary({
75
+ id : 'getSheetsDictionary',
76
+ label : 'Sheets',
77
+ criteria : z.object({ documentId: z.string().optional() }),
78
+ criteriaAliases: { documentId: ['sourceDocumentId'] },
79
+ execute : async ({ search, criteria, apiRequest }) => {
80
+ // always `criteria.documentId`, whichever param the user filled in
81
+ },
82
+ })
83
+
84
+ // every consumer binds it the same way:
85
+ sheetId: z.number().label('Sheet').dictionary(getSheetsDictionary)
86
+ ```
87
+
88
+ - **Publishing.** Each consumer's `dependsOn` names whichever of `[key, ...aliases]` its own method declares:
89
+ `['documentId']` on an action with a `documentId` param, `['sourceDocumentId']` on the copy action. The
90
+ dropdown waits for, and reloads on, the param that is actually on the form. A consumer whose method declares
91
+ none of the names keeps the key, as without aliases.
92
+ - **Invoking.** Before `criteria` is validated, a blank key (`undefined`, `null` or `''`) is filled from the
93
+ first non-blank alias, in declaration order; a filled key wins. The aliases are then dropped with the other
94
+ undeclared fields, so **`execute` only ever sees the criteria key**.
95
+ - **What "declares" means.** A top-level param sees the method's top-level params. A field inside an object
96
+ sees the fields next to it **and** the method's top-level params — the same values the Flow Builder sends as
97
+ criteria. A field loaded by `.dynamicProps()` / `dynamicParams` sees the action's params too.
98
+
99
+ **A field must not see two names of one key.** If an action declares both `documentId` and its alias
100
+ `sourceDocumentId`, the Flow Builder sends both, and the dictionary cannot tell which document the user meant.
101
+ The service fails to load:
102
+
103
+ > `` action "copySheet": `params.sheetId` uses dictionary "getSheetsDictionary", whose criteria "documentId"
104
+ > can come from "documentId" or "sourceDocumentId" — and this field can see all of them, so the dictionary
105
+ > cannot tell which one is meant. ``
106
+
107
+ Rename one of the params, or bind that field to a dictionary without the alias.
108
+
109
+ `criteriaAliases` itself is checked when the service loads. Each of these fails with `FR_EXT_INVALID_SCHEMA`:
110
+
111
+ | Mistake | Message (after `dictionary "<id>": `) |
112
+ |---|---|
113
+ | not an object | `` `criteriaAliases` must be an object of `{ criteriaKey: ['otherParamName'] }`. `` |
114
+ | a key that is not in `criteria` | `` `criteriaAliases` names "x", which is not a key of its `criteria`. `` |
115
+ | an empty list, or a name that is not a non-empty string | `` `criteriaAliases.x` must be a non-empty array of param names. `` |
116
+ | an alias that is itself a criteria key | `` `criteriaAliases.x` names "y", which is itself a key of `criteria`. `` |
117
+ | one alias under two keys | `` "y" is an alias of both "x" and "z" — an alias may feed one criteria key only. `` |
118
+
119
+ Aliases never reach the published definition: `dependsOn` carries the consumer's names, and nothing else on
120
+ the wire changes.
121
+
64
122
  ## Browse versus resolve — a dictionary does not need a listing endpoint
65
123
 
66
124
  `execute` receives **`search`**, the text the flow author has typed. That makes two different dictionaries
@@ -44,6 +44,15 @@ refreshToken: async ({ refreshToken, config, oauth }) => {
44
44
  },
45
45
  ```
46
46
 
47
+ ## Refresh failures
48
+
49
+ When a refresh fails, the platform shows the connection as needing a reconnect, fails the step with a
50
+ "reconnect it" error and notifies the workspace team. Any error from the refresh does this, as does a refresh that
51
+ returns no `token`: an outage, a timeout and a refused refresh token all ask the user to sign in again.
52
+
53
+ Nothing to do in the service: with the built-in refresh (declarative `tokenUrl`) or a custom `refreshToken`, let any
54
+ error propagate.
55
+
47
56
  ## Using OAuth in handlers
48
57
 
49
58
  `oauth` derives only from the `oauth-access-token` header → `oauth = { accessToken, token? }` (`token` =
@@ -70,6 +70,12 @@ All params are body params (`queryParams` is always `[]`). A param's information
70
70
  **Nested object properties are the exception** — they inline their display metadata (`label`, `uiComponent`,
71
71
  `dictionary`, `dependsOn`) directly on the property.
72
72
 
73
+ **A dictionary-bound field's `dependsOn` names the consumer's own params.** It is the dictionary's criteria keys,
74
+ each replaced by the alias the field's method declares when the dictionary has `criteriaAliases`
75
+ ([05-dictionaries.md](05-dictionaries.md#one-dictionary-differently-named-params)). The same names appear in
76
+ `metaInfo.args`, on nested properties, and in `paramsSchema` as `meta.frDictionary: { id, dependsOn }`. The
77
+ aliases themselves are never published.
78
+
73
79
  **A platform param group is the other exception.** `z.filesUploadOptions([…])` and its siblings
74
80
  (see [03-parameters.md](03-parameters.md)) publish their `uiComponent` token on the param *as well as* in
75
81
  `metaInfo.args`, at every depth. That token says what the param **is**, not how one control should look, so a