@flowrunner/cli 0.1.12 → 0.1.13

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.
@@ -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 | Endpoint verification (see table). |
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? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
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,67 @@ 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
- | `match` (fn) | `{ params, providerEventData, webhookData }` | `boolean` — for ranges/contains/derived logic |
326
+ | `extendMatchData` | `{ providerEventData, webhookData, instances:[{ id, params }], 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?` → `verify`/`verifyRequest` → read `extractProviderEventName` → for
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, `extendResult` once → fire.
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
+ - **Read only when a flow filters.** The runtime skips the hook when nothing would read its result: no
366
+ configured instances, no `match` declared, or a declarative `match` none of whose params any instance has
367
+ filled (an empty param means "any", so every instance matches whatever the read returns). An event with no
368
+ filtering flow therefore costs no provider call.
369
+ - **Behind a predicate `match`, decide it yourself.** The runtime cannot see which params a function reads, so
370
+ the hook always runs and receives `instances` — `[{ id, params }]` for every configured instance — to skip
371
+ the read when none of them filters on what it would fetch:
372
+
373
+ ```js
374
+ extendMatchData: async ({ providerEventData, apiRequest, instances }) => {
375
+ if (!instances.some(({ params }) => params.minAmount != null)) {
376
+ return {}
377
+ }
378
+ …
379
+ },
380
+ match: ({ params, providerEventData }) => params.minAmount == null || providerEventData.amount >= params.minAmount,
381
+ ```
382
+ - **The fired event is unchanged.** What it returns is merged onto `providerEventData` for `match` and
383
+ `extendResult` only; to put fetched data on the event, return it from `extendResult`.
384
+ - **A failed read is not a failed delivery.** If it throws, the runtime logs a warning and matches on the
385
+ delivered data: instances filtering on the missing fields decline, unfiltered ones still fire. Return `{}`
386
+ (or nothing) for "not found" to get the same outcome without the warning.
288
387
 
289
388
  **A trigger declaring no `match` fires every configured instance** — "no filter" means "fires always", and
290
389
  that is a different case from a name this service does not declare, which selects nothing (see
@@ -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 — the runtime acks those automatically, with no `handshake` declared
122
- ([09-realtime-triggers.md](09-realtime-triggers.md)). A `verify` / `verifyRequest` that turns a delivery down
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.12",
4188
+ version: "0.1.13",
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, anonymous(ctx))
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
- if (this.props.handshake) {
8357
- const result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
8358
- if (result && (result.responseToExternalService !== void 0 || result.responseHeaders || result.responseToWebhook)) {
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 }));
@@ -8415,6 +8459,26 @@ var RealtimeSetup = class {
8415
8459
  }
8416
8460
  return true;
8417
8461
  }
8462
+ /**
8463
+ * The event data `match` decides on: the delivered data plus whatever `extendMatchData` fetched, read ONCE
8464
+ * for every instance — the case is an id-only webhook (Xero names an invoice, not its type or status) whose
8465
+ * instance filters need the resource itself.
8466
+ *
8467
+ * A failed read is NOT a failed delivery. Select is the data plane: nothing is waiting on it, and a throw
8468
+ * would abort the delivery's other events. So it is logged and the instances are matched against the data
8469
+ * that WAS delivered — an instance filtering on the missing fields declines, an unfiltered one still fires.
8470
+ */
8471
+ async #withMatchData(trigger, eventData, instances, webhookData, ctx) {
8472
+ try {
8473
+ const extra = await trigger.extendMatchData(eventData, instances, ctx, webhookData);
8474
+ return extra && typeof extra === "object" ? { ...eventData, ...extra } : eventData;
8475
+ } catch (error) {
8476
+ ctx.logger.warn(
8477
+ `[flow-extension:${this.extension.id}] extendMatchData of "${trigger.id}" failed \u2014 matching on the delivered data: ${error?.message ?? error}`
8478
+ );
8479
+ return eventData;
8480
+ }
8481
+ }
8418
8482
  // Fan one resolved event out over the configured instances of its trigger. An `eventName` this service
8419
8483
  // does not declare is DECLINED outright — `{ ids: [], enrichedEventData: null }`, no instance offered up
8420
8484
  // and no per-event seam run. That is deliberately not the same case as a trigger which declares no
@@ -8430,15 +8494,22 @@ var RealtimeSetup = class {
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 ids = (invocation.triggers ?? []).filter((instance) => trigger.matches(instance.data ?? {}, eventData, webhookData)).map((instance) => instance.id);
8498
+ const instances = (invocation.triggers ?? []).map((instance) => ({ id: instance.id, params: instance.data ?? {} }));
8499
+ const eventData = trigger.needsMatchData(instances) ? await this.#withMatchData(trigger, invocation.eventData, instances, webhookData, ctx) : invocation.eventData;
8500
+ const verdicts = await Promise.all(
8501
+ instances.map((instance) => trigger.matches(instance.params, 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
  }
8439
8507
  };
8440
8508
 
8441
8509
  // ../../flow-extension-runner/src/v2/realtime-triggers/trigger-method.ts
8510
+ function isFilled(value) {
8511
+ return value != null && value !== "";
8512
+ }
8442
8513
  var RealtimeTriggerMethod = class extends ExtensionMethod {
8443
8514
  constructor(extension, props) {
8444
8515
  super(extension);
@@ -8490,6 +8561,30 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
8490
8561
  extendEventData(requestBody, providerEventData) {
8491
8562
  return this.props.extendEventData?.({ requestBody, providerEventData });
8492
8563
  }
8564
+ /**
8565
+ * Whether `extendMatchData` should run before these instances are matched. Only when something will READ its
8566
+ * result — otherwise the API call is pure cost, paid on every event:
8567
+ * - no instances, or no `match` → nothing to decide (with no `match` every instance fires);
8568
+ * - declarative `match`, and no instance fills any of its params → every instance matches regardless,
8569
+ * since an empty param means "any". This is the v1 rule: read the resource only when a flow filters.
8570
+ * A predicate `match` is opaque, so the hook runs and receives the instances to make that call itself.
8571
+ */
8572
+ needsMatchData(instances) {
8573
+ const match = this.props.match;
8574
+ if (typeof this.props.extendMatchData !== "function" || !match || !instances.length) {
8575
+ return false;
8576
+ }
8577
+ if (typeof match === "function") {
8578
+ return true;
8579
+ }
8580
+ const filterKeys = Object.keys(match);
8581
+ return instances.some((instance) => filterKeys.some((key) => isFilled(instance.params[key])));
8582
+ }
8583
+ // Runs ONCE per event, before any instance is matched, with the full handler bag (`apiRequest` on the
8584
+ // connection's token) — for an instance filter on data the delivery does not carry.
8585
+ extendMatchData(providerEventData, instances, ctx, webhookData = null) {
8586
+ return this.props.extendMatchData?.(ctx.bagWith({ providerEventData, webhookData, instances }));
8587
+ }
8493
8588
  /**
8494
8589
  * Whether one CONFIGURED INSTANCE of this trigger cares about an event. Declarative form: type-coerced
8495
8590
  * equality per filled param, where an empty param means "any" — that is what lets a user leave a filter
@@ -8499,17 +8594,17 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
8499
8594
  * subscription registered (a tenant id, a resource the webhook was scoped to) has nowhere else to get it.
8500
8595
  * Returning a new document is not a thing this seam can do; only subscribe/refresh/unsubscribe persist.
8501
8596
  */
8502
- matches(params, providerEventData, webhookData = null) {
8597
+ async matches(params, providerEventData, webhookData = null) {
8503
8598
  const match = this.props.match;
8504
8599
  if (!match) {
8505
8600
  return true;
8506
8601
  }
8507
8602
  if (typeof match === "function") {
8508
- return !!match({ params, providerEventData, webhookData });
8603
+ return !!await match({ params, providerEventData, webhookData });
8509
8604
  }
8510
8605
  for (const [paramKey, path23] of Object.entries(match)) {
8511
8606
  const paramValue = params[paramKey];
8512
- if (paramValue == null || paramValue === "") {
8607
+ if (!isFilled(paramValue)) {
8513
8608
  continue;
8514
8609
  }
8515
8610
  if (`${paramValue}` !== `${getPath(providerEventData, path23)}`) {