@flowrunner/cli 0.1.8 → 0.1.9
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/01-service-structure.md +1 -1
- package/ai-docs/instructions/service-code-format/04-http-requests.md +17 -13
- package/ai-docs/instructions/service-code-format/06-oauth2.md +1 -5
- package/ai-docs/instructions/service-code-format/07-actions.md +16 -12
- package/ai-docs/instructions/service-code-format/14-reference-service.md +5 -4
- package/ai-docs/instructions/service-code-format/17-client-certificates.md +5 -3
- package/dist/cli.js +18 -1
- package/dist/cli.js.map +2 -2
- package/dist/index.js +17 -0
- package/dist/index.js.map +2 -2
- package/dist/types/flow-extension-runner/src/v2/types.d.ts +1 -1
- package/dist/types/shared/src/constants/notification-types.d.ts +2 -2
- package/package.json +1 -1
- package/runtime/index.js.map +1 -1
- package/runtime/types/flow-extension-runner/src/v2/types.d.ts +1 -1
- package/runtime/types/shared/src/constants/notification-types.d.ts +2 -2
- package/templates/blank/files/src/index.js +1 -1
- package/templates/demo-todo-list/files/src/index.js +1 -1
- package/templates/qa-test/files/src/index.js +1 -1
|
@@ -73,7 +73,7 @@ const ext = Flowrunner.createExtension({
|
|
|
73
73
|
configItems: z.object({ apiKey: z.string().label('API Key') }),
|
|
74
74
|
initContext: ({ config, oauth }) => ({ apiKey: config.apiKey, accessToken: oauth?.accessToken }),
|
|
75
75
|
apiRequest : async ({ url, method = 'get', body, query, context }) =>
|
|
76
|
-
new Flowrunner.Request(url, method
|
|
76
|
+
new Flowrunner.Request(url, method).set({ Authorization: `Bearer ${ context.apiKey }` }).query(query).send(body),
|
|
77
77
|
helpers : ({ apiRequest }) => ({ collectPages: (url) => collectPages(apiRequest, url) }),
|
|
78
78
|
})
|
|
79
79
|
```
|
|
@@ -6,16 +6,16 @@ base URL, auth, envelope-unwrapping, error-normalization and redacted logging so
|
|
|
6
6
|
declarative.
|
|
7
7
|
|
|
8
8
|
```js
|
|
9
|
-
apiRequest: async ({ url, method = 'get', body, query, context }) =>
|
|
10
|
-
new Flowrunner.Request(`${ context.apiUrl }${ url }`, method
|
|
9
|
+
apiRequest: async ({ url, method = 'get', body, query, context }) => {
|
|
10
|
+
return new Flowrunner.Request(`${ context.apiUrl }${ url }`, method)
|
|
11
11
|
.set({ Authorization: `Bearer ${ context.apiKey }` })
|
|
12
|
-
.query(query)
|
|
12
|
+
.query(query)
|
|
13
|
+
.send(body)
|
|
14
|
+
}
|
|
13
15
|
```
|
|
14
16
|
|
|
15
|
-
The constructor
|
|
16
|
-
|
|
17
|
-
inherited names such as `constructor` when the value is ever anything unexpected
|
|
18
|
-
([16-gotchas.md](16-gotchas.md)).
|
|
17
|
+
The constructor takes the verb as a value, in either case, so `method` passes straight through. Chain the
|
|
18
|
+
headers and query, and send the body last with `.send(body)`.
|
|
19
19
|
|
|
20
20
|
## `apiRequest` argument
|
|
21
21
|
|
|
@@ -44,10 +44,12 @@ const API_HOSTS = {
|
|
|
44
44
|
geocode: 'https://geocoding.example.com/v1',
|
|
45
45
|
}
|
|
46
46
|
|
|
47
|
-
apiRequest: async ({ url, method = 'get', body, query, context, api = 'main' }) =>
|
|
48
|
-
new Flowrunner.Request(`${ API_HOSTS[api] }${ url }`, method
|
|
47
|
+
apiRequest: async ({ url, method = 'get', body, query, context, api = 'main' }) => {
|
|
48
|
+
return new Flowrunner.Request(`${ API_HOSTS[api] }${ url }`, method)
|
|
49
49
|
.set({ Authorization: `Bearer ${ context.apiKey }` })
|
|
50
|
-
.query(query)
|
|
50
|
+
.query(query)
|
|
51
|
+
.send(body)
|
|
52
|
+
}
|
|
51
53
|
```
|
|
52
54
|
|
|
53
55
|
```js
|
|
@@ -251,10 +253,12 @@ An API that requires mutual TLS needs a client certificate on **every** call, in
|
|
|
251
253
|
request, so it belongs in `apiRequest` rather than in individual actions:
|
|
252
254
|
|
|
253
255
|
```js
|
|
254
|
-
apiRequest: async ({ url, method = 'get', body, query, context }) =>
|
|
255
|
-
new Flowrunner.Request(`${ context.apiUrl }${ url }`, method
|
|
256
|
+
apiRequest: async ({ url, method = 'get', body, query, context }) => {
|
|
257
|
+
return new Flowrunner.Request(`${ context.apiUrl }${ url }`, method)
|
|
256
258
|
.cert({ cert: context.clientCert, key: context.clientKey })
|
|
257
|
-
.query(query)
|
|
259
|
+
.query(query)
|
|
260
|
+
.send(body)
|
|
261
|
+
}
|
|
258
262
|
```
|
|
259
263
|
|
|
260
264
|
`.cert()` and its failure modes are [17-client-certificates.md](17-client-certificates.md); read it when the
|
|
@@ -29,14 +29,10 @@ for the common case; any handler below overrides its step. Combined scopes = `sc
|
|
|
29
29
|
|
|
30
30
|
`oauth` derives only from the `oauth-access-token` header → `oauth = { accessToken, token? }` (`token` =
|
|
31
31
|
`deserializeToken(accessToken)`). Per-op opt-in for extra scopes: set `oauth2Scopes: ['extra.scope']` on
|
|
32
|
-
any action,
|
|
32
|
+
any action, polling or realtime trigger, or dictionary.
|
|
33
33
|
|
|
34
34
|
`token` is the one slot in the handler bag left open rather than inferred: `setupOauth2` runs after
|
|
35
35
|
`createExtension` has already resolved the service shape, so a `deserializeToken` return cannot flow back
|
|
36
36
|
into every handler. Annotate it where you read it if the composite shape matters.
|
|
37
37
|
|
|
38
|
-
> Scopes declared on a **realtime** trigger are currently **not** collected into the authorize URL — the
|
|
39
|
-
> runtime unions `scopes` with the `oauth2Scopes` of actions, polling triggers and dictionaries only. Put a
|
|
40
|
-
> realtime trigger's scopes in the extension-level `scopes` instead.
|
|
41
|
-
|
|
42
38
|
Client id/secret are typically `configItems` marked `.shared()` (see [02-zod-types.md](02-zod-types.md)).
|
|
@@ -24,18 +24,22 @@ rejects the call with `FR_EXT_INVALID_METHOD_INPUT` and the offending param path
|
|
|
24
24
|
params by hand inside `execute`. Declare optionality honestly — a `z.string()` that the flow may legitimately
|
|
25
25
|
leave empty must be `.optional()`.
|
|
26
26
|
|
|
27
|
-
**
|
|
28
|
-
declare
|
|
29
|
-
|
|
30
|
-
| Slot |
|
|
31
|
-
|
|
32
|
-
| Action `params`, SYSTEM invocations |
|
|
33
|
-
| Dictionary `criteria` |
|
|
34
|
-
| Sample-result / dynamic-params loader `criteria` |
|
|
35
|
-
| Polling trigger `params` |
|
|
36
|
-
|
|
37
|
-
So a
|
|
38
|
-
|
|
27
|
+
**Every slot enforces required fields.** Slots differ only in what happens to fields the schema does not
|
|
28
|
+
declare:
|
|
29
|
+
|
|
30
|
+
| Slot | Required fields | Unknown fields |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| Action `params`, SYSTEM invocations | enforced — `FR_EXT_INVALID_METHOD_INPUT` | stripped (kept with `dynamicParams`) |
|
|
33
|
+
| Dictionary `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | dropped |
|
|
34
|
+
| Sample-result / dynamic-params loader `criteria` | enforced — `FR_EXT_INVALID_CRITERIA` | ride through — the node's other params come along |
|
|
35
|
+
| Polling trigger `params` | enforced — `FR_EXT_INVALID_METHOD_INPUT`, target `triggerData` | ride through |
|
|
36
|
+
|
|
37
|
+
So a sample-result loader resolves only once its owner's required params are filled.
|
|
38
|
+
|
|
39
|
+
**Make trigger filters optional.** A polling trigger's params are checked on every poll, against the values
|
|
40
|
+
the instance was saved with. A required field the user left empty fails every poll, and the trigger never
|
|
41
|
+
produces an event. Mark a trigger param required only when the trigger cannot work without it; declare
|
|
42
|
+
every filter `.optional()` and handle the empty value in `fetch`/`poll`.
|
|
39
43
|
|
|
40
44
|
## `result` — return the sample object
|
|
41
45
|
|
|
@@ -56,10 +56,11 @@ const ext = Flowrunner.createExtension({
|
|
|
56
56
|
logger?.debug(`[${ logTag ?? 'api' }] ${ method.toUpperCase() } ${ fullUrl }`)
|
|
57
57
|
|
|
58
58
|
try {
|
|
59
|
-
// 04: the verb is a value here
|
|
60
|
-
const response = await new Flowrunner.Request(fullUrl, method
|
|
59
|
+
// 04: the verb is a value here; the constructor form takes it as-is.
|
|
60
|
+
const response = await new Flowrunner.Request(fullUrl, method)
|
|
61
61
|
.set({ Authorization: `Bearer ${ context.token }` })
|
|
62
62
|
.query(query ?? {})
|
|
63
|
+
.send(body)
|
|
63
64
|
|
|
64
65
|
return response?.data ?? response
|
|
65
66
|
} catch (error) {
|
|
@@ -175,7 +176,7 @@ ext.addAction({
|
|
|
175
176
|
},
|
|
176
177
|
})
|
|
177
178
|
|
|
178
|
-
// 08: exactly one mechanism. `params`
|
|
179
|
+
// 08: exactly one mechanism. `params` are checked on every poll, so the filter is optional — 07.
|
|
179
180
|
ext.addPollingTrigger({
|
|
180
181
|
category : 'Notes',
|
|
181
182
|
id : 'onNoteCreated',
|
|
@@ -342,5 +343,5 @@ Things in that output worth reading twice:
|
|
|
342
343
|
| `result` is a sample object, never a zod schema plus `.example()` | [07](07-actions.md) |
|
|
343
344
|
| Every `execute` is a block body with an explicit `return` | [07](07-actions.md) |
|
|
344
345
|
| `createNote` returns the API's response whole; `listBoardNotes` extends without dropping | [07](07-actions.md) |
|
|
345
|
-
| `new Flowrunner.Request(url, method
|
|
346
|
+
| `new Flowrunner.Request(url, method)` … `.send(body)` for a verb held in a variable | [04](04-http-requests.md) |
|
|
346
347
|
| `Object.hasOwn` at the lookup, on a plain object literal | [16](16-gotchas.md) |
|
|
@@ -50,10 +50,12 @@ initContext: ({ config }) => ({
|
|
|
50
50
|
clientKey : config.clientKey,
|
|
51
51
|
}),
|
|
52
52
|
|
|
53
|
-
apiRequest: async ({ url, method = 'get', body, query, context }) =>
|
|
54
|
-
new Flowrunner.Request(`${ context.apiUrl }${ url }`, method
|
|
53
|
+
apiRequest: async ({ url, method = 'get', body, query, context }) => {
|
|
54
|
+
return new Flowrunner.Request(`${ context.apiUrl }${ url }`, method)
|
|
55
55
|
.cert({ cert: context.clientCert, key: context.clientKey })
|
|
56
|
-
.query(query)
|
|
56
|
+
.query(query)
|
|
57
|
+
.send(body)
|
|
58
|
+
}
|
|
57
59
|
```
|
|
58
60
|
|
|
59
61
|
See [01-service-structure.md](01-service-structure.md) for `configItems` and `initContext`.
|
package/dist/cli.js
CHANGED
|
@@ -4185,7 +4185,7 @@ var require_package = __commonJS({
|
|
|
4185
4185
|
"package.json"(exports2, module2) {
|
|
4186
4186
|
module2.exports = {
|
|
4187
4187
|
name: "@flowrunner/cli",
|
|
4188
|
-
version: "0.1.
|
|
4188
|
+
version: "0.1.9",
|
|
4189
4189
|
publishConfig: {
|
|
4190
4190
|
access: "public"
|
|
4191
4191
|
},
|
|
@@ -10516,6 +10516,22 @@ function writeReadme(projectRoot) {
|
|
|
10516
10516
|
import_fs14.default.writeFileSync(fullPath, README(packageNameFrom(projectRoot)), "utf-8");
|
|
10517
10517
|
return "created";
|
|
10518
10518
|
}
|
|
10519
|
+
var JSCONFIG = {
|
|
10520
|
+
compilerOptions: {
|
|
10521
|
+
module: "node16",
|
|
10522
|
+
moduleResolution: "node16",
|
|
10523
|
+
types: [`${CLI_PACKAGE}/runtime`]
|
|
10524
|
+
},
|
|
10525
|
+
include: ["services/*/src/**/*.js"]
|
|
10526
|
+
};
|
|
10527
|
+
function writeJsconfig(projectRoot) {
|
|
10528
|
+
const fullPath = import_path20.default.join(projectRoot, "jsconfig.json");
|
|
10529
|
+
if (import_fs14.default.existsSync(fullPath)) {
|
|
10530
|
+
return "skipped";
|
|
10531
|
+
}
|
|
10532
|
+
import_fs14.default.writeFileSync(fullPath, JSON.stringify(JSCONFIG, null, 2) + "\n", "utf-8");
|
|
10533
|
+
return "created";
|
|
10534
|
+
}
|
|
10519
10535
|
function git(projectRoot, args) {
|
|
10520
10536
|
(0, import_child_process.execFileSync)("git", args, { cwd: projectRoot, stdio: "pipe" });
|
|
10521
10537
|
}
|
|
@@ -10631,6 +10647,7 @@ async function init(options = {}) {
|
|
|
10631
10647
|
const server = ensureServerUrl(projectRoot, requestedServerUrl);
|
|
10632
10648
|
record2(CONFIG_FILE, server.created ? "created" : server.updated ? "updated" : "skipped");
|
|
10633
10649
|
record2("README.md", writeReadme(projectRoot));
|
|
10650
|
+
record2("jsconfig.json", writeJsconfig(projectRoot));
|
|
10634
10651
|
const testing = tests ? writeTestingFiles(projectRoot) : { created: [], skipped: [] };
|
|
10635
10652
|
testing.created.forEach((file) => record2(file, "created"));
|
|
10636
10653
|
testing.skipped.forEach((file) => record2(file, "skipped"));
|