@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.
- package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +51 -8
- package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +18 -5
- package/dist/cli.js +423 -235
- package/dist/cli.js.map +4 -4
- package/dist/index.js +420 -232
- package/dist/index.js.map +4 -4
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
- package/dist/types/packages/cli/src/constants/testing.d.ts +9 -4
- package/dist/types/shared/src/constants/knowledge-base.d.ts +1 -0
- package/dist/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
- package/dist/types/shared/src/scheme/crm/dto.d.ts +2 -2
- package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
- package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
- package/dist/types/shared/src/scheme/workspace/dto.d.ts +1 -1
- package/package.json +3 -3
- package/runtime/index.js +39 -24
- package/runtime/index.js.map +2 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
- package/runtime/types/shared/src/constants/knowledge-base.d.ts +1 -0
- package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
- package/runtime/types/shared/src/scheme/crm/dto.d.ts +2 -2
- package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
- package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
- 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
|
|
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?,
|
|
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 `
|
|
104
|
-
forwarded to `verifyRequest`; `
|
|
105
|
-
|
|
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
|