@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.
@@ -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, body).set({ Authorization: `Bearer ${ context.apiKey }` }).query(query),
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, body)
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 form takes the verb as a value, which is what you want when `method` arrives as an argument.
16
- Avoid `Flowrunner.Request[method.toLowerCase()](url)`: an object lookup keyed by a variable resolves
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, body)
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, body)
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, **polling** trigger, or dictionary.
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
- **Not every slot is equally strict**, because not every slot has the same producer. Worth knowing so you
28
- declare schemas that hold up in each:
29
-
30
- | Slot | Strictness |
31
- |---|---|
32
- | Action `params`, SYSTEM invocations | **strict** — required fields enforced, unknown stripped. The flow engine produces these against the published model, so a violation is a real contract break |
33
- | Dictionary `criteria` | **strict** — the console only calls a dictionary once its `dependsOn` fields are filled |
34
- | Sample-result / dynamic-params loader `criteria` | **lenient** — the schema is relaxed so nothing is required, and unknown fields ride through. These fire on every keystroke while the form is half-filled |
35
- | Polling trigger `params` | **lenient** — the runtime polls with whatever the instance was saved with; rejecting a poll would silently stop a live automation |
36
-
37
- So a loader's `result` fn must tolerate partial criteria, and a trigger's `fetch`/`poll` must tolerate a
38
- partially configured instance. Handlers reached through a strict slot need no such defence.
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, so the constructor form — never Request[method](url).
60
- const response = await new Flowrunner.Request(fullUrl, method, body)
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` here are lenient — tolerate a half-configured instance.
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, body)` — never `Request[method](url)` | [04](04-http-requests.md) |
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, body)
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.8",
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"));