@flowrunner/cli 0.1.12-dev.1 → 0.1.12-dev.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 +18 -3
- package/dist/cli.js +38 -24
- package/dist/cli.js.map +2 -2
- package/dist/index.js +37 -23
- package/dist/index.js.map +2 -2
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +9 -6
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +5 -0
- package/package.json +1 -1
- package/runtime/index.js +37 -23
- package/runtime/index.js.map +2 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +9 -6
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +5 -0
|
@@ -323,7 +323,7 @@ Use `params` for **filters** — which chat, which board, which status — never
|
|
|
323
323
|
|---|---|---|
|
|
324
324
|
| `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
|
|
325
325
|
| `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
|
|
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**) |
|
|
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
327
|
| `match` (fn) | `{ params, providerEventData, webhookData }` | `boolean` (or a Promise of one — awaited) — for ranges/contains/derived logic |
|
|
328
328
|
| `extendResult` | `{ providerEventData, webhookData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
|
|
329
329
|
|
|
@@ -362,8 +362,23 @@ ext.addRealtimeTrigger({
|
|
|
362
362
|
|
|
363
363
|
- **One read per event**, however many instances are configured — never put the read in an async `match`,
|
|
364
364
|
which runs once per instance.
|
|
365
|
-
- **
|
|
366
|
-
|
|
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
|
+
```
|
|
367
382
|
- **The fired event is unchanged.** What it returns is merged onto `providerEventData` for `match` and
|
|
368
383
|
`extendResult` only; to put fetched data on the event, return it from `extendResult`.
|
|
369
384
|
- **A failed read is not a failed delivery.** If it throws, the runtime logs a warning and matches on the
|
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-dev.
|
|
4188
|
+
version: "0.1.12-dev.2",
|
|
4189
4189
|
publishConfig: {
|
|
4190
4190
|
access: "public"
|
|
4191
4191
|
},
|
|
@@ -8459,16 +8459,6 @@ var RealtimeSetup = class {
|
|
|
8459
8459
|
}
|
|
8460
8460
|
return true;
|
|
8461
8461
|
}
|
|
8462
|
-
// Fan one resolved event out over the configured instances of its trigger. An `eventName` this service
|
|
8463
|
-
// does not declare is DECLINED outright — `{ ids: [], enrichedEventData: null }`, no instance offered up
|
|
8464
|
-
// and no per-event seam run. That is deliberately not the same case as a trigger which declares no
|
|
8465
|
-
// `match`: `matches()` already answers "fires always" for that one, so resolve the name FIRST and never
|
|
8466
|
-
// let the two share a branch.
|
|
8467
|
-
//
|
|
8468
|
-
// Declining is the GUARANTEE here, not an accident of a past fix, and it is why this seam is ruled the
|
|
8469
|
-
// opposite way to `#toSubTriggers`. This is the DATA PLANE: the platform has already answered the
|
|
8470
|
-
// provider and detached this work, so a throw reaches nobody — and worse, it aborts every remaining event
|
|
8471
|
-
// of the same delivery, dropping the good ones beside the stale name.
|
|
8472
8462
|
/**
|
|
8473
8463
|
* The event data `match` decides on: the delivered data plus whatever `extendMatchData` fetched, read ONCE
|
|
8474
8464
|
* for every instance — the case is an id-only webhook (Xero names an invoice, not its type or status) whose
|
|
@@ -8478,9 +8468,9 @@ var RealtimeSetup = class {
|
|
|
8478
8468
|
* would abort the delivery's other events. So it is logged and the instances are matched against the data
|
|
8479
8469
|
* that WAS delivered — an instance filtering on the missing fields declines, an unfiltered one still fires.
|
|
8480
8470
|
*/
|
|
8481
|
-
async #withMatchData(trigger, eventData, webhookData, ctx) {
|
|
8471
|
+
async #withMatchData(trigger, eventData, instances, webhookData, ctx) {
|
|
8482
8472
|
try {
|
|
8483
|
-
const extra = await trigger.extendMatchData(eventData, ctx, webhookData);
|
|
8473
|
+
const extra = await trigger.extendMatchData(eventData, instances, ctx, webhookData);
|
|
8484
8474
|
return extra && typeof extra === "object" ? { ...eventData, ...extra } : eventData;
|
|
8485
8475
|
} catch (error) {
|
|
8486
8476
|
ctx.logger.warn(
|
|
@@ -8489,16 +8479,26 @@ var RealtimeSetup = class {
|
|
|
8489
8479
|
return eventData;
|
|
8490
8480
|
}
|
|
8491
8481
|
}
|
|
8482
|
+
// Fan one resolved event out over the configured instances of its trigger. An `eventName` this service
|
|
8483
|
+
// does not declare is DECLINED outright — `{ ids: [], enrichedEventData: null }`, no instance offered up
|
|
8484
|
+
// and no per-event seam run. That is deliberately not the same case as a trigger which declares no
|
|
8485
|
+
// `match`: `matches()` already answers "fires always" for that one, so resolve the name FIRST and never
|
|
8486
|
+
// let the two share a branch.
|
|
8487
|
+
//
|
|
8488
|
+
// Declining is the GUARANTEE here, not an accident of a past fix, and it is why this seam is ruled the
|
|
8489
|
+
// opposite way to `#toSubTriggers`. This is the DATA PLANE: the platform has already answered the
|
|
8490
|
+
// provider and detached this work, so a throw reaches nobody — and worse, it aborts every remaining event
|
|
8491
|
+
// of the same delivery, dropping the good ones beside the stale name.
|
|
8492
8492
|
async #selectMatched(invocation, ctx) {
|
|
8493
8493
|
const trigger = invocation.eventName ? this.extension.findRealtimeTrigger(invocation.eventName) : void 0;
|
|
8494
8494
|
if (!trigger) {
|
|
8495
8495
|
return { ids: [], enrichedEventData: null };
|
|
8496
8496
|
}
|
|
8497
8497
|
const webhookData = invocation.webhookData ?? null;
|
|
8498
|
-
const instances = invocation.triggers ?? [];
|
|
8499
|
-
const eventData = trigger.needsMatchData(instances
|
|
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
8500
|
const verdicts = await Promise.all(
|
|
8501
|
-
instances.map((instance) => trigger.matches(instance.
|
|
8501
|
+
instances.map((instance) => trigger.matches(instance.params, eventData, webhookData))
|
|
8502
8502
|
);
|
|
8503
8503
|
const ids = instances.filter((_instance, index) => verdicts[index]).map((instance) => instance.id);
|
|
8504
8504
|
const enrichedEventData = ids.length && trigger.hasExtendResult() ? await trigger.extendResult(eventData, ctx, webhookData) : null;
|
|
@@ -8507,6 +8507,9 @@ var RealtimeSetup = class {
|
|
|
8507
8507
|
};
|
|
8508
8508
|
|
|
8509
8509
|
// ../../flow-extension-runner/src/v2/realtime-triggers/trigger-method.ts
|
|
8510
|
+
function isFilled(value) {
|
|
8511
|
+
return value != null && value !== "";
|
|
8512
|
+
}
|
|
8510
8513
|
var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
8511
8514
|
constructor(extension, props) {
|
|
8512
8515
|
super(extension);
|
|
@@ -8559,17 +8562,28 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
|
8559
8562
|
return this.props.extendEventData?.({ requestBody, providerEventData });
|
|
8560
8563
|
}
|
|
8561
8564
|
/**
|
|
8562
|
-
* Whether `extendMatchData` should run
|
|
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.
|
|
8565
8571
|
*/
|
|
8566
|
-
needsMatchData(
|
|
8567
|
-
|
|
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])));
|
|
8568
8582
|
}
|
|
8569
8583
|
// Runs ONCE per event, before any instance is matched, with the full handler bag (`apiRequest` on the
|
|
8570
8584
|
// 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 }));
|
|
8585
|
+
extendMatchData(providerEventData, instances, ctx, webhookData = null) {
|
|
8586
|
+
return this.props.extendMatchData?.(ctx.bagWith({ providerEventData, webhookData, instances }));
|
|
8573
8587
|
}
|
|
8574
8588
|
/**
|
|
8575
8589
|
* Whether one CONFIGURED INSTANCE of this trigger cares about an event. Declarative form: type-coerced
|
|
@@ -8590,7 +8604,7 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
|
8590
8604
|
}
|
|
8591
8605
|
for (const [paramKey, path23] of Object.entries(match)) {
|
|
8592
8606
|
const paramValue = params[paramKey];
|
|
8593
|
-
if (paramValue
|
|
8607
|
+
if (!isFilled(paramValue)) {
|
|
8594
8608
|
continue;
|
|
8595
8609
|
}
|
|
8596
8610
|
if (`${paramValue}` !== `${getPath(providerEventData, path23)}`) {
|