@flowrunner/cli 0.1.1 → 0.1.2

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 (30) hide show
  1. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +51 -8
  2. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +18 -5
  3. package/dist/cli.js +423 -235
  4. package/dist/cli.js.map +4 -4
  5. package/dist/index.js +420 -232
  6. package/dist/index.js.map +4 -4
  7. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
  8. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
  9. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
  10. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
  11. package/dist/types/packages/cli/src/constants/testing.d.ts +9 -4
  12. package/dist/types/shared/src/constants/knowledge-base.d.ts +1 -0
  13. package/dist/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
  14. package/dist/types/shared/src/scheme/crm/dto.d.ts +2 -2
  15. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
  16. package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
  17. package/dist/types/shared/src/scheme/workspace/dto.d.ts +1 -1
  18. package/package.json +3 -3
  19. package/runtime/index.js +39 -24
  20. package/runtime/index.js.map +2 -2
  21. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
  22. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
  23. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
  24. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
  25. package/runtime/types/shared/src/constants/knowledge-base.d.ts +1 -0
  26. package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
  27. package/runtime/types/shared/src/scheme/crm/dto.d.ts +2 -2
  28. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
  29. package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
  30. package/runtime/types/shared/src/scheme/workspace/dto.d.ts +1 -1
@@ -74,12 +74,12 @@ does its own lowercased retry; that behaviour does not extend to `verifyRequest`
74
74
  | `subscribe` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` (null first), `connectionId` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
75
75
  | `unsubscribe` | `callbackUrl`, `webhookData`, `connectionId` | `{ webhookData? }` |
76
76
  | `refresh` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` | `{ webhookData?, refreshIntervalInSeconds }` |
77
- | `handshake` | `{ requestBody, headers, rawBody }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
78
- | `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
77
+ | `handshake` | `{ requestBody, headers, rawBody, webhookData }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
78
+ | `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `webhookData`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
79
79
 
80
80
  Both also still accept the **deprecated** `responseToExternalService` / `responseHeaders` — see
81
81
  [below](#responsetoexternalservice--deprecated).
82
- | `verifyRequest` | `{ rawBody, headers }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
82
+ | `verifyRequest` | `{ rawBody, headers, webhookData }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
83
83
 
84
84
  **The `triggers` bag holds one entry per (trigger × `providerEventName`)**, so a trigger declaring several
85
85
  names appears several times. A trigger that declares **no** `providerEventName` — what you write when
@@ -89,6 +89,49 @@ reconcile it. Guard the field rather than assuming it (`if (t.providerEventName)
89
89
  on it unconditionally. Nothing is left out of the bag: a name resolving to no trigger **rejects the whole
90
90
  call** — see [Unknown trigger names](#unknown-trigger-names) below.
91
91
 
92
+ ### `webhookData` on the inbound path — read-only
93
+
94
+ Every inbound seam receives the **stored webhook document**: whatever `subscribe` (or `refresh`) last returned
95
+ as `webhookData`, persisted by the platform and looked up for this delivery.
96
+
97
+ | Seam | Runs | Reads `webhookData` |
98
+ |---|---|---|
99
+ | `handshake`, `verify`/`verifyRequest`, `resolveEvents` | once per delivery | ✓ |
100
+ | `match` (predicate form), `extendResult` | per instance / once per event | ✓ |
101
+ | `extendEventData` | per trigger, pure | — |
102
+
103
+ It is the only channel from registration to delivery, and the case it exists for is the **signing secret a
104
+ provider mints when the webhook is created**: it comes back from the registration call, `subscribe` stores it,
105
+ and the delivery it signs can then be verified against it. The same applies to an external webhook id or
106
+ tenant id a delivery has to be recognised or filtered by.
107
+
108
+ ⚠️ **Reading is all these seams do.** None of them can update the document — their result types have no
109
+ `webhookData` field, and one returned anyway is dropped. Only `subscribe`, `refresh` and `unsubscribe`
110
+ persist it, so anything an inbound delivery would like to record has to wait for the next one of those.
111
+ Do not design around writing it back from a delivery.
112
+
113
+ ```js
114
+ verify: {
115
+ header : 'x-provider-signature',
116
+ algo : 'sha256',
117
+ encoding: 'hex',
118
+ // The per-webhook secret the provider issued at registration; the app-level config key is the fallback
119
+ // for a webhook registered before the service started storing it.
120
+ secret : (config, { webhookData }) => webhookData?.signingSecret ?? config.signingSecret,
121
+ },
122
+ ```
123
+
124
+ ⚠️ **`webhookData` is `null` whenever there is no document to read**, and that is a normal delivery, not a
125
+ broken one:
126
+
127
+ - nothing has been stored for this webhook yet, or
128
+ - the delivery arrived on the **general callback of a service that is not app-hosted** — the document is
129
+ stored per workspace, so there is no workspace to look one up for.
130
+
131
+ So read it defensively (`webhookData?.field`), and never let an absent document *reject* a delivery on its
132
+ own: "no id to compare against" is not "the ids differ". Anything mandatory for verification still belongs in
133
+ `config`, with the stored value as the refinement over it.
134
+
92
135
  ### `responseToWebhook` — answering the provider
93
136
 
94
137
  Some providers do not accept a generic `200`. Xero's *Intent to Receive* validation sends two deliveries and
@@ -163,14 +206,14 @@ than the missing input it is — and sends you hunting for a wrong secret.
163
206
 
164
207
  ### `verify` fields
165
208
 
166
- HMACs the **raw body alone** with `secret(config)` and compares it to the header in constant time.
209
+ HMACs the **raw body alone** with the key `secret` returns and compares it to the header in constant time.
167
210
 
168
211
  | Field | Req | Description |
169
212
  |---|---|---|
170
213
  | `header` | ✓ | Signature header. Read as declared, then retried lowercased. Absent header → fail. |
171
214
  | `algo` | ✓ | Hash algorithm, e.g. `'sha256'`. |
172
215
  | `encoding` | ✓ | `'hex' \| 'base64'` — the digest encoding the provider sends. |
173
- | `secret` | ✓ | `(config) => key`. |
216
+ | `secret` | ✓ | `(config, { webhookData }) => key`. The second argument is the stored webhook document — `null` when there is none — for a provider that mints the secret at registration time. |
174
217
  | `timestampHeader` | – | Header carrying the request timestamp. **Required for `freshness` to run.** |
175
218
  | `freshness` | – | Max age in seconds. **Only checked when `timestampHeader` is also declared** — on its own it is silently inert. A declared-but-absent timestamp header passes. |
176
219
 
@@ -236,8 +279,8 @@ Use `params` for **filters** — which chat, which board, which status — never
236
279
  |---|---|---|
237
280
  | `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
238
281
  | `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
239
- | `match` (fn) | `{ params, providerEventData }` | `boolean` — for ranges/contains/derived logic |
240
- | `extendResult` | `{ providerEventData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
282
+ | `match` (fn) | `{ params, providerEventData, webhookData }` | `boolean` — for ranges/contains/derived logic |
283
+ | `extendResult` | `{ providerEventData, webhookData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
241
284
 
242
285
  **Inbound runtime flow:** `handshake?` → `verify`/`verifyRequest` → read `extractProviderEventName` → for
243
286
  each trigger whose `providerEventName` matches, build `providerEventData` (`extractProviderEventData` +
@@ -254,7 +297,7 @@ costs no provider call.
254
297
  |---|---|
255
298
  | subscribe (flow start) | `null → webhookData` (create webhook / resolve `eventScopeId`) |
256
299
  | subscribe (set changed) | `webhookData → webhookData'` (recreate: delete prior + create; or diff) |
257
- | inbound event | unchanged \| emits matched instances |
300
+ | inbound event | unchanged — **read-only** for every inbound seam (`handshake`, `verify`/`verifyRequest`, `resolveEvents`, `match`, `extendResult`) \| emits matched instances |
258
301
  | refresh (opt) | `webhookData → webhookData'` (renew) |
259
302
  | unsubscribe (flow stop) | `webhookData → {}` (tear down) |
260
303
 
@@ -96,13 +96,26 @@ buildServiceDefinition('telegram', ENTRY)
96
96
  |---|---|---|
97
97
  | `handleTriggerUpsertWebhook` | `{ invocation: { callbackUrl, triggers, webhookData?, connectionId? } }` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
98
98
  | `handleTriggerDeleteWebhook` | `{ invocation: { callbackUrl, webhookData, connectionId? } }` | `{ webhookData? }` |
99
- | `handleTriggerSelectMatched` | `{ invocation: { eventName, eventData, triggers } }` | `{ ids, enrichedEventData }` |
100
- | `handleTriggerResolveEvents` | `{ invocation: { body, rawBody?, headers?, query?, connectionId? } }` | `{ events: [{ name, data }], responseToWebhook? }` (plus the deprecated `responseToExternalService`, still forwarded) |
99
+ | `handleTriggerSelectMatched` | `{ invocation: { eventName, eventData, triggers, webhookData? } }` | `{ ids, enrichedEventData }` |
100
+ | `handleTriggerResolveEvents` | `{ invocation: { body, rawBody?, headers?, queryParams?, webhookData?, connectionId? } }` | `{ events: [{ name, data }], responseToWebhook? }` (plus the deprecated `responseToExternalService`, still forwarded) |
101
101
 
102
102
  `handleTriggerResolveEvents` is the inbound-delivery seam. **`body` is required** — omitting it fails with
103
- `body: Invalid input: expected nonoptional, received undefined`. `rawBody` and `headers` are the only fields
104
- forwarded to `verifyRequest`; `query` is accepted but not forwarded, and `connectionId` is echoed back on the
105
- response. Unknown fields in `invocation` are ignored rather than rejected.
103
+ `body: Invalid input: expected nonoptional, received undefined`. `rawBody`, `headers` and `webhookData` are
104
+ the fields forwarded to `verifyRequest`; `connectionId` is echoed back on the response. Unknown fields in
105
+ `invocation` are ignored rather than rejected.
106
+
107
+ ⚠️ **The query string is `queryParams` in the invocation and `query` in the handler bag.** Spelling it
108
+ `query` in `methodData` is one of those ignored unknown fields, so `resolveEvents` sees `query: {}` and a
109
+ spec asserting on a query-string branch silently drives the wrong path.
110
+
111
+ **`webhookData` is the webhook document the platform stored** — what `subscribe`/`refresh` last returned —
112
+ looked up for this delivery. It reaches `handshake`, `verify`/`verifyRequest` and `resolveEvents` here, and
113
+ `match`/`extendResult` on `handleTriggerSelectMatched`, and is `null` when none is stored or when the request
114
+ carries no workspace to look one up for (the general callback of a service that is not app-hosted). Both
115
+ methods only **read** it: neither response carries a `webhookData` field, so a document returned from one is
116
+ dropped — only upsert/refresh/delete persist. The harness never supplies it on its own: pass it in
117
+ `invocation` to drive a path that depends on it
118
+ ([09-realtime-triggers.md](09-realtime-triggers.md#webhookdata-on-the-inbound-path--read-only)).
106
119
 
107
120
  It answers `{ events: [] }` for a delivery no trigger claims, and `{ handshake: true, events: [] }` for an
108
121
  empty body — the runtime acks those automatically, with no `handshake` declared