@flowrunner/cli 0.1.10 → 0.1.12-dev.1
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 -0
- package/ai-docs/instructions/service-code-format/06-oauth2.md +20 -1
- package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +89 -5
- package/ai-docs/instructions/service-code-format/11-output-model.md +1 -1
- package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +6 -3
- package/dist/cli.js +105 -22
- package/dist/cli.js.map +2 -2
- package/dist/index.js +104 -21
- package/dist/index.js.map +2 -2
- package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +1 -1
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +8 -1
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -2
- package/dist/types/flow-extension-runner/src/v2/types.d.ts +5 -0
- package/dist/types/shared/src/constants/shared-extensions.d.ts +12 -0
- package/dist/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
- package/dist/types/shared/src/scheme/access-keys/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +8 -8
- package/dist/types/shared/src/scheme/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
- package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +1 -1
- package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +9 -9
- package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +8 -8
- package/dist/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
- package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +6 -6
- package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +4 -4
- package/dist/types/shared/src/scheme/shared-extensions/service-info.d.ts +1 -1
- package/package.json +1 -1
- package/runtime/index.js +103 -20
- package/runtime/index.js.map +2 -2
- package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +1 -1
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +8 -1
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -2
- package/runtime/types/flow-extension-runner/src/v2/types.d.ts +5 -0
- package/runtime/types/shared/src/constants/shared-extensions.d.ts +12 -0
- package/runtime/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
- package/runtime/types/shared/src/scheme/access-keys/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +8 -8
- package/runtime/types/shared/src/scheme/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
- package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +1 -1
- package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +9 -9
- package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +8 -8
- package/runtime/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
- package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +6 -6
- package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +4 -4
- package/runtime/types/shared/src/scheme/shared-extensions/service-info.d.ts +1 -1
|
@@ -61,6 +61,7 @@ logo for that one item. Omit it and the item inherits the service's.
|
|
|
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). |
|
|
64
|
+
| `serviceClassName` | string | – | **Deprecated — will be removed soon. Shared extensions only.** The class name of a shared extension rewritten from the legacy JSDoc class format (`'GeminiAIService'`). It is published as `serviceInfo.serviceClassName` (absent otherwise), so flows, configs and connections saved against the old service keep resolving to this one. Keep it unchanged once set. Never set it on a new service or a custom extension. |
|
|
64
65
|
| `configItems` | `z.object` | – | App + shared config (see [02-zod-types.md](02-zod-types.md)). → `appConfigDescriptions` / `sharedConfigDescriptions`. Omit when the service needs none — see [Services with no credentials](#services-with-no-credentials); a plain object of fields is **not** accepted (see [03-parameters.md](03-parameters.md)). |
|
|
65
66
|
| `initContext` | fn | – | `({ config, oauth }) => context`; runs once per invocation. Runs for OAuth flows too (`oauth` may be empty). |
|
|
66
67
|
| `apiRequest` | fn | – | Shared HTTP helper (envelope-unwrap, error-normalize, redacted logging). See [04-http-requests.md](04-http-requests.md). |
|
|
@@ -23,7 +23,26 @@ for the common case; any handler below overrides its step. Combined scopes = `sc
|
|
|
23
23
|
|---|---|---|
|
|
24
24
|
| `getConnectionURL` | `{ config, context, scopes }` | `string` (authorize URL) |
|
|
25
25
|
| `executeCallback` | `{ callbackObject, config, context }` | `{ token, expirationInSeconds?, refreshToken?, connectionIdentityName?, connectionIdentityImageURL?, overwrite?, userData? }` |
|
|
26
|
-
| `refreshToken` | `{ refreshToken, config, context }` | `{ token, expirationInSeconds?, refreshToken? }` |
|
|
26
|
+
| `refreshToken` | `{ refreshToken, config, context, oauth }` | `{ token, expirationInSeconds?, refreshToken? }` |
|
|
27
|
+
|
|
28
|
+
`getConnectionURL` and `executeCallback` run before any token exists, so their `oauth` is empty. `refreshToken`
|
|
29
|
+
is different: the platform sends the connection's **current (expired) token** in the `oauth-access-token`
|
|
30
|
+
header, so `oauth = { accessToken, token? }` and `initContext` see it exactly as in any other handler. That is
|
|
31
|
+
how a composite token survives a refresh — rebuild the next one from the data in the current one, because the
|
|
32
|
+
provider's refresh response does not repeat what it returned at connect time:
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
refreshToken: async ({ refreshToken, config, oauth }) => {
|
|
36
|
+
const res = await exchangeRefreshToken(config, refreshToken)
|
|
37
|
+
|
|
38
|
+
// `oauth.token` is `deserializeToken(<current token>)` — carry the realm id over
|
|
39
|
+
return {
|
|
40
|
+
token : `${ res.access_token }::realm::${ oauth.token.realmId }`,
|
|
41
|
+
refreshToken: res.refresh_token ?? refreshToken,
|
|
42
|
+
expirationInSeconds: res.expires_in,
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
```
|
|
27
46
|
|
|
28
47
|
## Using OAuth in handlers
|
|
29
48
|
|
|
@@ -53,7 +53,7 @@ running and the error appears in the customer's **workspace log** on each refres
|
|
|
53
53
|
| `extractProviderEventData` | path \| fn | Base `providerEventData` handed to matched triggers. Default = whole body. |
|
|
54
54
|
| `scopeAt` | path | ALL_APPS routing key path (route where `scopeAt === eventScopeId`). |
|
|
55
55
|
| `verify` | object | Declarative signature check — see the field table below. |
|
|
56
|
-
| `handshake` | fn |
|
|
56
|
+
| `handshake` | fn | Decides which deliveries are endpoint-verification handshakes — replaces the empty-body default (see [Handshakes](#handshakes)). |
|
|
57
57
|
| `subscribe` | fn | Required (see table). |
|
|
58
58
|
| `unsubscribe` | fn | Required (see table). |
|
|
59
59
|
| `refresh` | fn | Optional. |
|
|
@@ -74,7 +74,7 @@ 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, webhookData }` | `{ responseToWebhook
|
|
77
|
+
| `handshake` | `{ requestBody, headers, rawBody, webhookData }` | `true` → ack with a plain 200; `{ responseToWebhook }` → ack with that response (runtime adds `handshake:true`); nothing / `false` / `{}` → proceed. See [Handshakes](#handshakes). |
|
|
78
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
|
|
@@ -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
|
+
### Handshakes
|
|
93
|
+
|
|
94
|
+
A handshake is a delivery the provider sends to check the callback URL rather than to report an event. It is
|
|
95
|
+
acked and goes no further: no `verify`, no routing, nothing fires.
|
|
96
|
+
|
|
97
|
+
**Without a `handshake` hook, an empty body is a handshake.** A body that is `null`, `''` or `{}` is acked with
|
|
98
|
+
`{ handshake: true, events: [] }` and a plain 200 — the URL-verification ping most providers send. Most
|
|
99
|
+
services need nothing more.
|
|
100
|
+
|
|
101
|
+
**A declared `handshake` replaces that default — it does not run before it.** The hook alone decides, and an
|
|
102
|
+
empty body it does not claim proceeds to `verify` and `resolveEvents` like any other delivery. That is what a
|
|
103
|
+
provider whose real events carry **no body** needs (Google Drive puts the whole notification in `X-Goog-*`
|
|
104
|
+
headers): with the default in place, its events would be acked as pings and never fire.
|
|
105
|
+
|
|
106
|
+
| The hook | The delivery |
|
|
107
|
+
|---|---|
|
|
108
|
+
| returns `true` | handshake — acked with a plain 200 |
|
|
109
|
+
| returns `{ responseToWebhook }` (or the deprecated `responseToExternalService` / `responseHeaders`) | handshake — answered with that response |
|
|
110
|
+
| returns nothing, `false`, or an object with no response in it (`{}`) | not a handshake — proceeds |
|
|
111
|
+
| throws | answered `{ events: [], responseToWebhook: { httpStatus, body: { message } } }` — the error's own `statusCode` (or `status`) when it is a 4xx, otherwise **400** |
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
// Google Drive-style: a real change notification has no body. Only the channel-opened message is a handshake.
|
|
115
|
+
handshake: ({ headers }) => headers['x-goog-resource-state'] === 'sync',
|
|
116
|
+
|
|
117
|
+
// Slack-style: an echoed challenge — and, since the hook replaces the default, the empty-body ping too.
|
|
118
|
+
handshake: ({ requestBody }) => {
|
|
119
|
+
if (requestBody?.challenge) {
|
|
120
|
+
return { responseToWebhook: { rawBody: requestBody.challenge } }
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
return requestBody == null || Object.keys(requestBody).length === 0
|
|
124
|
+
},
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
⚠️ **`handshake` runs before signature verification**, so it sees an unverified request. Acking one is harmless
|
|
128
|
+
— a handshake never fires anything — but do not grant anything from it, and remember that a **thrown message
|
|
129
|
+
is sent to that unverified caller**: throw what the provider may read.
|
|
130
|
+
|
|
131
|
+
⚠️ **Declaring `handshake` for a challenge drops the empty-body default.** If the provider also pings with an
|
|
132
|
+
empty body, claim it in the hook (as above), or the ping proceeds to `verify` — which answers 401 when there is
|
|
133
|
+
no body to check.
|
|
134
|
+
|
|
92
135
|
### `webhookData` on the inbound path — read-only
|
|
93
136
|
|
|
94
137
|
Every inbound seam receives the **stored webhook document**: whatever `subscribe` (or `refresh`) last returned
|
|
@@ -271,6 +314,7 @@ Use `params` for **filters** — which chat, which board, which status — never
|
|
|
271
314
|
| `params` | `z.object` | – | Trigger config — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
|
|
272
315
|
| `result` | value \| schema \| loader | ✓ | Emitted event shape (post-`extendResult`). |
|
|
273
316
|
| `extendEventData` | fn | – | see table. |
|
|
317
|
+
| `extendMatchData` | fn | – | see table, and [Filtering on data the delivery does not carry](#filtering-on-data-the-delivery-does-not-carry). |
|
|
274
318
|
| `match` | object \| fn | – | Instance selection (declarative object or predicate fn). |
|
|
275
319
|
| `extendResult` | fn | – | see table. |
|
|
276
320
|
| `oauth2Scopes` | string[] | – | Extra scopes. |
|
|
@@ -279,12 +323,52 @@ Use `params` for **filters** — which chat, which board, which status — never
|
|
|
279
323
|
|---|---|---|
|
|
280
324
|
| `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
|
|
281
325
|
| `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
|
|
282
|
-
| `
|
|
326
|
+
| `extendMatchData` | `{ providerEventData, webhookData, apiRequest, … }` (full ctx bag, on the connection's token) | partial object merged onto `providerEventData` for `match` and `extendResult` (**select, once per event, pre-match, may call API**) |
|
|
327
|
+
| `match` (fn) | `{ params, providerEventData, webhookData }` | `boolean` (or a Promise of one — awaited) — for ranges/contains/derived logic |
|
|
283
328
|
| `extendResult` | `{ providerEventData, webhookData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
|
|
284
329
|
|
|
285
|
-
**Inbound runtime flow:** `handshake
|
|
330
|
+
**Inbound runtime flow:** `handshake` (or the empty-body default) → `verify`/`verifyRequest` → read `extractProviderEventName` → for
|
|
286
331
|
each trigger whose `providerEventName` matches, build `providerEventData` (`extractProviderEventData` +
|
|
287
|
-
`extendEventData`) → `match` per instance → if ≥1 matched,
|
|
332
|
+
`extendEventData`) → *(select)* `extendMatchData` once → `match` per instance → if ≥1 matched,
|
|
333
|
+
`extendResult` once → fire.
|
|
334
|
+
|
|
335
|
+
### Filtering on data the delivery does not carry
|
|
336
|
+
|
|
337
|
+
Many webhooks name a resource without describing it — Xero sends an invoice's id, not its type or status. An
|
|
338
|
+
instance filter on those fields can only be decided after **reading the resource**, and that needs the
|
|
339
|
+
connection's token, which exists only on the select seam. The hooks split along that line:
|
|
340
|
+
|
|
341
|
+
| Hook | Seam | Token / `apiRequest` | Runs | Can change who fires |
|
|
342
|
+
|---|---|---|---|---|
|
|
343
|
+
| `extendEventData` | resolve (declarative routing only — not with `resolveEvents`) | ✗ — no connection chosen yet | per trigger, per delivery | ✓ (pure) |
|
|
344
|
+
| `extendMatchData` | select | ✓ | once per event, **before** `match` | ✓ |
|
|
345
|
+
| `extendResult` | select | ✓ | once per event, **after** `match`, if ≥1 matched | ✗ |
|
|
346
|
+
|
|
347
|
+
So fetch what a filter needs in `extendMatchData`, and keep `match` declarative over the fetched fields:
|
|
348
|
+
|
|
349
|
+
```js
|
|
350
|
+
ext.addRealtimeTrigger({
|
|
351
|
+
id : 'onInvoiceUpdated',
|
|
352
|
+
params: z.object({ invoiceType: z.string().optional(), status: z.string().optional() }),
|
|
353
|
+
extendMatchData: async ({ providerEventData, apiRequest }) => {
|
|
354
|
+
const response = await apiRequest({ url: `${ API_BASE_URL }/Invoices/${ encodeURIComponent(providerEventData.resourceId) }` })
|
|
355
|
+
const invoice = response?.Invoices?.[0]
|
|
356
|
+
|
|
357
|
+
return invoice ? { invoice: { Type: invoice.Type, Status: invoice.Status } } : {}
|
|
358
|
+
},
|
|
359
|
+
match: { invoiceType: 'invoice.Type', status: 'invoice.Status' },
|
|
360
|
+
})
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
- **One read per event**, however many instances are configured — never put the read in an async `match`,
|
|
364
|
+
which runs once per instance.
|
|
365
|
+
- **Skipped when nothing would read it:** no configured instances, or no `match` declared (every instance
|
|
366
|
+
fires then anyway).
|
|
367
|
+
- **The fired event is unchanged.** What it returns is merged onto `providerEventData` for `match` and
|
|
368
|
+
`extendResult` only; to put fetched data on the event, return it from `extendResult`.
|
|
369
|
+
- **A failed read is not a failed delivery.** If it throws, the runtime logs a warning and matches on the
|
|
370
|
+
delivered data: instances filtering on the missing fields decline, unfiltered ones still fire. Return `{}`
|
|
371
|
+
(or nothing) for "not found" to get the same outcome without the warning.
|
|
288
372
|
|
|
289
373
|
**A trigger declaring no `match` fires every configured instance** — "no filter" means "fires always", and
|
|
290
374
|
that is a different case from a name this service does not declare, which selects nothing (see
|
|
@@ -23,7 +23,7 @@ The names change on the way out, which matters when you inspect a built model:
|
|
|
23
23
|
|
|
24
24
|
| Authored | Published as |
|
|
25
25
|
|---|---|
|
|
26
|
-
| `
|
|
26
|
+
| `serviceClassName` (deprecated) | `serviceInfo.serviceClassName` — absent when not declared: `id` is not published on `serviceInfo` |
|
|
27
27
|
| `name` | `serviceInfo.integrationName` |
|
|
28
28
|
| `logo` | `serviceInfo.integrationIcon` |
|
|
29
29
|
| `description` | `serviceInfo.description` — shown under the extension's name in the console and the block palette |
|
|
@@ -110,7 +110,7 @@ spec asserting on a query-string branch silently drives the wrong path.
|
|
|
110
110
|
|
|
111
111
|
**`webhookData` is the webhook document the platform stored** — what `subscribe`/`refresh` last returned —
|
|
112
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
|
|
113
|
+
`extendMatchData`/`match`/`extendResult` on `handleTriggerSelectMatched`, and is `null` when none is stored or when the request
|
|
114
114
|
carries no workspace to look one up for (the general callback of a service that is not app-hosted). Both
|
|
115
115
|
methods only **read** it: neither response carries a `webhookData` field, so a document returned from one is
|
|
116
116
|
dropped — only upsert/refresh/delete persist. The harness never supplies it on its own: pass it in
|
|
@@ -118,8 +118,11 @@ dropped — only upsert/refresh/delete persist. The harness never supplies it on
|
|
|
118
118
|
([09-realtime-triggers.md](09-realtime-triggers.md#webhookdata-on-the-inbound-path--read-only)).
|
|
119
119
|
|
|
120
120
|
It answers `{ events: [] }` for a delivery no trigger claims, and `{ handshake: true, events: [] }` for an
|
|
121
|
-
empty body
|
|
122
|
-
|
|
121
|
+
empty body (`null`, `''` or `{}`) **when the service declares no `handshake`**. A declared `handshake`
|
|
122
|
+
replaces that default: an empty body it does not claim proceeds to `verify` and `resolveEvents`, and a
|
|
123
|
+
`handshake` that throws resolves with `{ events: [], responseToWebhook: { httpStatus, body: { message } } }`
|
|
124
|
+
(the error's 4xx, otherwise 400) rather than rejecting
|
|
125
|
+
([09-realtime-triggers.md](09-realtime-triggers.md#handshakes)). A `verify` / `verifyRequest` that turns a delivery down
|
|
123
126
|
**resolves** with `{ events: [], responseToWebhook: { httpStatus: 401, rawBody: '' } }` — it does not reject,
|
|
124
127
|
so assert on the returned value, not on a thrown error.
|
|
125
128
|
|
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.12-dev.1",
|
|
4189
4189
|
publishConfig: {
|
|
4190
4190
|
access: "public"
|
|
4191
4191
|
},
|
|
@@ -7804,7 +7804,7 @@ var OAuth2 = class {
|
|
|
7804
7804
|
{
|
|
7805
7805
|
name: REFRESH_TOKEN,
|
|
7806
7806
|
scheme: z2.object({ refreshToken: RefreshTokenSchema }),
|
|
7807
|
-
run: ({ refreshToken }, ctx) => this.#refresh(refreshToken,
|
|
7807
|
+
run: ({ refreshToken }, ctx) => this.#refresh(refreshToken, ctx)
|
|
7808
7808
|
}
|
|
7809
7809
|
]);
|
|
7810
7810
|
}
|
|
@@ -8242,7 +8242,15 @@ function readExtract(extract, body) {
|
|
|
8242
8242
|
return void 0;
|
|
8243
8243
|
}
|
|
8244
8244
|
function isEmptyBody(body) {
|
|
8245
|
-
return body == null || typeof body === "object" && Object.keys(body).length === 0;
|
|
8245
|
+
return body == null || body === "" || typeof body === "object" && Object.keys(body).length === 0;
|
|
8246
|
+
}
|
|
8247
|
+
function hasHandshakeResponse(result) {
|
|
8248
|
+
return result.responseToExternalService !== void 0 || !!result.responseHeaders || !!result.responseToWebhook;
|
|
8249
|
+
}
|
|
8250
|
+
function handshakeErrorStatus(error) {
|
|
8251
|
+
const { statusCode, status } = error ?? {};
|
|
8252
|
+
const candidate = typeof statusCode === "number" ? statusCode : status;
|
|
8253
|
+
return typeof candidate === "number" && candidate >= 400 && candidate < 500 ? candidate : 400;
|
|
8246
8254
|
}
|
|
8247
8255
|
var RealtimeSetup = class {
|
|
8248
8256
|
constructor(extension, props) {
|
|
@@ -8353,19 +8361,9 @@ var RealtimeSetup = class {
|
|
|
8353
8361
|
const body = invocation.body;
|
|
8354
8362
|
const rawBody = invocation.rawBody;
|
|
8355
8363
|
const webhookData = invocation.webhookData ?? null;
|
|
8356
|
-
|
|
8357
|
-
|
|
8358
|
-
|
|
8359
|
-
return {
|
|
8360
|
-
handshake: true,
|
|
8361
|
-
responseToExternalService: result.responseToExternalService,
|
|
8362
|
-
responseHeaders: result.responseHeaders,
|
|
8363
|
-
responseToWebhook: result.responseToWebhook
|
|
8364
|
-
};
|
|
8365
|
-
}
|
|
8366
|
-
}
|
|
8367
|
-
if (isEmptyBody(body)) {
|
|
8368
|
-
return { handshake: true, events: [] };
|
|
8364
|
+
const handshake = await this.#handshake(body, headers, rawBody, webhookData, ctx);
|
|
8365
|
+
if (handshake) {
|
|
8366
|
+
return handshake;
|
|
8369
8367
|
}
|
|
8370
8368
|
if (!await this.#verify(rawBody, headers, webhookData, ctx)) {
|
|
8371
8369
|
ctx.logger.warn(`[flow-extension:${this.extension.id}] webhook signature verification failed \u2014 answering 401`);
|
|
@@ -8406,6 +8404,52 @@ var RealtimeSetup = class {
|
|
|
8406
8404
|
return { events, eventScopeId, connectionId: invocation.connectionId };
|
|
8407
8405
|
}
|
|
8408
8406
|
// The author's own check wins; otherwise the declarative one; otherwise nothing was asked for.
|
|
8407
|
+
/**
|
|
8408
|
+
* Whether this delivery is an endpoint-verification handshake, and if so the answer to it; `null` → proceed.
|
|
8409
|
+
*
|
|
8410
|
+
* Without a `handshake` hook the default applies: an EMPTY body is a handshake, acked with a plain 200 —
|
|
8411
|
+
* the URL-verification ping most providers send. A declared hook REPLACES that default rather than running
|
|
8412
|
+
* before it, so it alone decides: some providers deliver real events with no body at all (Google Drive
|
|
8413
|
+
* puts everything in `X-Goog-*` headers), and a hook that can't overrule the empty-body rule leaves them
|
|
8414
|
+
* no way to reach `resolveEvents`.
|
|
8415
|
+
*
|
|
8416
|
+
* `true` → handshake, plain 200
|
|
8417
|
+
* `{ responseToWebhook, … }` → handshake, answered with that response
|
|
8418
|
+
* nothing / `false` / `{}` → not a handshake, the delivery proceeds
|
|
8419
|
+
* throws → answered with the error, as a 4xx carrying its message
|
|
8420
|
+
*
|
|
8421
|
+
* The throw is turned into a RESPONSE for the same reason a failed signature check is: a throw leaves the
|
|
8422
|
+
* pod as a failed invocation and the provider receives a 500 telling it nothing. The hook runs BEFORE
|
|
8423
|
+
* verification, so the message reaches an unverified caller — throw what the provider may read.
|
|
8424
|
+
*/
|
|
8425
|
+
async #handshake(body, headers, rawBody, webhookData, ctx) {
|
|
8426
|
+
if (!this.props.handshake) {
|
|
8427
|
+
return isEmptyBody(body) ? { handshake: true, events: [] } : null;
|
|
8428
|
+
}
|
|
8429
|
+
let result;
|
|
8430
|
+
try {
|
|
8431
|
+
result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
|
|
8432
|
+
} catch (error) {
|
|
8433
|
+
const message = error?.message ?? String(error);
|
|
8434
|
+
ctx.logger.error(`[flow-extension:${this.extension.id}] handshake failed \u2014 ${message}`);
|
|
8435
|
+
return {
|
|
8436
|
+
events: [],
|
|
8437
|
+
responseToWebhook: { httpStatus: handshakeErrorStatus(error), body: { message } }
|
|
8438
|
+
};
|
|
8439
|
+
}
|
|
8440
|
+
if (result === true) {
|
|
8441
|
+
return { handshake: true, events: [] };
|
|
8442
|
+
}
|
|
8443
|
+
if (result && typeof result === "object" && hasHandshakeResponse(result)) {
|
|
8444
|
+
return {
|
|
8445
|
+
handshake: true,
|
|
8446
|
+
responseToExternalService: result.responseToExternalService,
|
|
8447
|
+
responseHeaders: result.responseHeaders,
|
|
8448
|
+
responseToWebhook: result.responseToWebhook
|
|
8449
|
+
};
|
|
8450
|
+
}
|
|
8451
|
+
return null;
|
|
8452
|
+
}
|
|
8409
8453
|
async #verify(rawBody, headers, webhookData, ctx) {
|
|
8410
8454
|
if (this.props.verifyRequest) {
|
|
8411
8455
|
return !!await this.props.verifyRequest(ctx.bagWith({ rawBody, headers, webhookData, config: ctx.config }));
|
|
@@ -8425,14 +8469,38 @@ var RealtimeSetup = class {
|
|
|
8425
8469
|
// opposite way to `#toSubTriggers`. This is the DATA PLANE: the platform has already answered the
|
|
8426
8470
|
// provider and detached this work, so a throw reaches nobody — and worse, it aborts every remaining event
|
|
8427
8471
|
// of the same delivery, dropping the good ones beside the stale name.
|
|
8472
|
+
/**
|
|
8473
|
+
* The event data `match` decides on: the delivered data plus whatever `extendMatchData` fetched, read ONCE
|
|
8474
|
+
* for every instance — the case is an id-only webhook (Xero names an invoice, not its type or status) whose
|
|
8475
|
+
* instance filters need the resource itself.
|
|
8476
|
+
*
|
|
8477
|
+
* A failed read is NOT a failed delivery. Select is the data plane: nothing is waiting on it, and a throw
|
|
8478
|
+
* would abort the delivery's other events. So it is logged and the instances are matched against the data
|
|
8479
|
+
* that WAS delivered — an instance filtering on the missing fields declines, an unfiltered one still fires.
|
|
8480
|
+
*/
|
|
8481
|
+
async #withMatchData(trigger, eventData, webhookData, ctx) {
|
|
8482
|
+
try {
|
|
8483
|
+
const extra = await trigger.extendMatchData(eventData, ctx, webhookData);
|
|
8484
|
+
return extra && typeof extra === "object" ? { ...eventData, ...extra } : eventData;
|
|
8485
|
+
} catch (error) {
|
|
8486
|
+
ctx.logger.warn(
|
|
8487
|
+
`[flow-extension:${this.extension.id}] extendMatchData of "${trigger.id}" failed \u2014 matching on the delivered data: ${error?.message ?? error}`
|
|
8488
|
+
);
|
|
8489
|
+
return eventData;
|
|
8490
|
+
}
|
|
8491
|
+
}
|
|
8428
8492
|
async #selectMatched(invocation, ctx) {
|
|
8429
8493
|
const trigger = invocation.eventName ? this.extension.findRealtimeTrigger(invocation.eventName) : void 0;
|
|
8430
8494
|
if (!trigger) {
|
|
8431
8495
|
return { ids: [], enrichedEventData: null };
|
|
8432
8496
|
}
|
|
8433
|
-
const eventData = invocation.eventData;
|
|
8434
8497
|
const webhookData = invocation.webhookData ?? null;
|
|
8435
|
-
const
|
|
8498
|
+
const instances = invocation.triggers ?? [];
|
|
8499
|
+
const eventData = trigger.needsMatchData(instances.length) ? await this.#withMatchData(trigger, invocation.eventData, webhookData, ctx) : invocation.eventData;
|
|
8500
|
+
const verdicts = await Promise.all(
|
|
8501
|
+
instances.map((instance) => trigger.matches(instance.data ?? {}, eventData, webhookData))
|
|
8502
|
+
);
|
|
8503
|
+
const ids = instances.filter((_instance, index) => verdicts[index]).map((instance) => instance.id);
|
|
8436
8504
|
const enrichedEventData = ids.length && trigger.hasExtendResult() ? await trigger.extendResult(eventData, ctx, webhookData) : null;
|
|
8437
8505
|
return { ids, enrichedEventData };
|
|
8438
8506
|
}
|
|
@@ -8490,6 +8558,19 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
|
8490
8558
|
extendEventData(requestBody, providerEventData) {
|
|
8491
8559
|
return this.props.extendEventData?.({ requestBody, providerEventData });
|
|
8492
8560
|
}
|
|
8561
|
+
/**
|
|
8562
|
+
* Whether `extendMatchData` should run for an event about to be matched against `instanceCount` instances.
|
|
8563
|
+
* Only when something will READ its result: with no instances there is nothing to decide, and with no
|
|
8564
|
+
* `match` every instance fires regardless — either way the API call would be pure cost.
|
|
8565
|
+
*/
|
|
8566
|
+
needsMatchData(instanceCount) {
|
|
8567
|
+
return typeof this.props.extendMatchData === "function" && !!this.props.match && instanceCount > 0;
|
|
8568
|
+
}
|
|
8569
|
+
// Runs ONCE per event, before any instance is matched, with the full handler bag (`apiRequest` on the
|
|
8570
|
+
// connection's token) — for an instance filter on data the delivery does not carry.
|
|
8571
|
+
extendMatchData(providerEventData, ctx, webhookData = null) {
|
|
8572
|
+
return this.props.extendMatchData?.(ctx.bagWith({ providerEventData, webhookData }));
|
|
8573
|
+
}
|
|
8493
8574
|
/**
|
|
8494
8575
|
* Whether one CONFIGURED INSTANCE of this trigger cares about an event. Declarative form: type-coerced
|
|
8495
8576
|
* equality per filled param, where an empty param means "any" — that is what lets a user leave a filter
|
|
@@ -8499,13 +8580,13 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
|
8499
8580
|
* subscription registered (a tenant id, a resource the webhook was scoped to) has nowhere else to get it.
|
|
8500
8581
|
* Returning a new document is not a thing this seam can do; only subscribe/refresh/unsubscribe persist.
|
|
8501
8582
|
*/
|
|
8502
|
-
matches(params, providerEventData, webhookData = null) {
|
|
8583
|
+
async matches(params, providerEventData, webhookData = null) {
|
|
8503
8584
|
const match = this.props.match;
|
|
8504
8585
|
if (!match) {
|
|
8505
8586
|
return true;
|
|
8506
8587
|
}
|
|
8507
8588
|
if (typeof match === "function") {
|
|
8508
|
-
return !!match({ params, providerEventData, webhookData });
|
|
8589
|
+
return !!await match({ params, providerEventData, webhookData });
|
|
8509
8590
|
}
|
|
8510
8591
|
for (const [paramKey, path23] of Object.entries(match)) {
|
|
8511
8592
|
const paramValue = params[paramKey];
|
|
@@ -8730,7 +8811,9 @@ var Extension = class {
|
|
|
8730
8811
|
}
|
|
8731
8812
|
toServiceInfo() {
|
|
8732
8813
|
return {
|
|
8733
|
-
|
|
8814
|
+
// Only a shared extension migrated from v1 has one: its v1 class name, which the legacy ids of its elements,
|
|
8815
|
+
// configs and OAuth connections are built from. A service written as v2 is identified by its id alone
|
|
8816
|
+
...this.props.serviceClassName ? { serviceClassName: this.props.serviceClassName } : {},
|
|
8734
8817
|
integrationName: this.props.name,
|
|
8735
8818
|
integrationIcon: this.props.logo ?? null,
|
|
8736
8819
|
description: this.props.description || null,
|
|
@@ -9524,7 +9607,7 @@ function discoverServices(projectRoot = process.cwd()) {
|
|
|
9524
9607
|
}
|
|
9525
9608
|
const v2Definition = buildServiceDefinition2(serviceId, serviceFilePath);
|
|
9526
9609
|
const { methodsMap, serviceInfo } = v2Definition ?? parseJsDocToServiceJson(serviceFilePath);
|
|
9527
|
-
if (!serviceInfo || !serviceInfo.serviceClassName) {
|
|
9610
|
+
if (!serviceInfo || !v2Definition && !serviceInfo.serviceClassName) {
|
|
9528
9611
|
skipped.push({ serviceId, reason: "its entry point does not define a service" });
|
|
9529
9612
|
continue;
|
|
9530
9613
|
}
|