@flowrunner/cli 0.1.7 → 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.
Files changed (37) hide show
  1. package/ai-docs/instructions/service-code-format/01-service-structure.md +2 -2
  2. package/ai-docs/instructions/service-code-format/04-http-requests.md +17 -13
  3. package/ai-docs/instructions/service-code-format/06-oauth2.md +1 -5
  4. package/ai-docs/instructions/service-code-format/07-actions.md +16 -12
  5. package/ai-docs/instructions/service-code-format/11-output-model.md +2 -1
  6. package/ai-docs/instructions/service-code-format/14-reference-service.md +5 -4
  7. package/ai-docs/instructions/service-code-format/17-client-certificates.md +5 -3
  8. package/dist/cli.js +19 -1
  9. package/dist/cli.js.map +2 -2
  10. package/dist/index.js +18 -0
  11. package/dist/index.js.map +2 -2
  12. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +1 -0
  13. package/dist/types/flow-extension-runner/src/v2/types.d.ts +2 -2
  14. package/dist/types/shared/src/constants/notification-types.d.ts +2 -2
  15. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +4 -0
  16. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +1 -0
  17. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +5 -0
  18. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +4 -0
  19. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +3 -0
  20. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +2 -0
  21. package/dist/types/shared/src/scheme/shared-extensions/service-info.d.ts +1 -0
  22. package/package.json +1 -1
  23. package/runtime/index.js +1 -0
  24. package/runtime/index.js.map +2 -2
  25. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +1 -0
  26. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +2 -2
  27. package/runtime/types/shared/src/constants/notification-types.d.ts +2 -2
  28. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +4 -0
  29. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +1 -0
  30. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +5 -0
  31. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +4 -0
  32. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +3 -0
  33. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +2 -0
  34. package/runtime/types/shared/src/scheme/shared-extensions/service-info.d.ts +1 -0
  35. package/templates/blank/files/src/index.js +1 -1
  36. package/templates/demo-todo-list/files/src/index.js +1 -1
  37. package/templates/qa-test/files/src/index.js +1 -1
@@ -57,7 +57,7 @@ logo for that one item. Omit it and the item inherits the service's.
57
57
  |---|---|---|---|
58
58
  | `id` | string | ✓ | Stable service id (→ `SharedExtensionServiceInfo.id`). |
59
59
  | `name` | string | ✓ | Human display name. |
60
- | `description` | string | ✓ | Service description. |
60
+ | `description` | string | – | One-line summary of the service, shown under its name in the console and the block palette. |
61
61
  | `logo` | string | ✓ | Icon path, resolved **inside the service's `public/` folder** — see [Folder layout](#folder-layout). |
62
62
  | `appearanceColors` | `[string, string]` | – | `[primary, secondary]`. |
63
63
  | `usesFileStorage` | boolean | – | `true` provisions `ctx.files`; when false, `ctx.files` is a proxy that throws. Default false. See [10-files-api.md](10-files-api.md). |
@@ -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
 
@@ -25,12 +25,13 @@ The names change on the way out, which matters when you inspect a built model:
25
25
  | `id` | `serviceInfo.serviceClassName` |
26
26
  | `name` | `serviceInfo.integrationName` |
27
27
  | `logo` | `serviceInfo.integrationIcon` |
28
+ | `description` | `serviceInfo.description` — shown under the extension's name in the console and the block palette |
28
29
  | `scope` (realtime) | `serviceInfo.integrationTriggersScope` |
29
30
  | `appearanceColors` | per-method `colorStart` / `colorEnd` (every method inherits them) |
30
31
  | `label` | per-method `operationName` |
31
32
 
32
33
  `serviceInfo` also carries `requireOAuth`, and the definition root carries `runnerVersion` (`'v2'`). A
33
- service's `description` and `appearanceColors` are not published on `serviceInfo` itself.
34
+ service's `appearanceColors` are not published on `serviceInfo` itself.
34
35
 
35
36
  ## The schema travels too
36
37
 
@@ -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.7",
4188
+ version: "0.1.9",
4189
4189
  publishConfig: {
4190
4190
  access: "public"
4191
4191
  },
@@ -8499,6 +8499,7 @@ var Extension = class {
8499
8499
  serviceClassName: this.props.id,
8500
8500
  integrationName: this.props.name,
8501
8501
  integrationIcon: this.props.logo ?? null,
8502
+ description: this.props.description || null,
8502
8503
  integrationTriggersScope: this.#realtime?.scope ?? null,
8503
8504
  requireOAuth: this.#oauth ? true : void 0
8504
8505
  };
@@ -10515,6 +10516,22 @@ function writeReadme(projectRoot) {
10515
10516
  import_fs14.default.writeFileSync(fullPath, README(packageNameFrom(projectRoot)), "utf-8");
10516
10517
  return "created";
10517
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
+ }
10518
10535
  function git(projectRoot, args) {
10519
10536
  (0, import_child_process.execFileSync)("git", args, { cwd: projectRoot, stdio: "pipe" });
10520
10537
  }
@@ -10630,6 +10647,7 @@ async function init(options = {}) {
10630
10647
  const server = ensureServerUrl(projectRoot, requestedServerUrl);
10631
10648
  record2(CONFIG_FILE, server.created ? "created" : server.updated ? "updated" : "skipped");
10632
10649
  record2("README.md", writeReadme(projectRoot));
10650
+ record2("jsconfig.json", writeJsconfig(projectRoot));
10633
10651
  const testing = tests ? writeTestingFiles(projectRoot) : { created: [], skipped: [] };
10634
10652
  testing.created.forEach((file) => record2(file, "created"));
10635
10653
  testing.skipped.forEach((file) => record2(file, "skipped"));