@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.
- package/ai-docs/instructions/service-code-format/06-oauth2.md +20 -1
- package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +104 -5
- package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +6 -3
- package/dist/cli.js +116 -21
- package/dist/cli.js.map +2 -2
- package/dist/index.js +115 -20
- package/dist/index.js.map +2 -2
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +12 -2
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +11 -2
- package/package.json +1 -1
- package/runtime/index.js +115 -20
- package/runtime/index.js.map +2 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +12 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +11 -2
package/dist/index.js
CHANGED
|
@@ -7282,7 +7282,7 @@ var OAuth2 = class {
|
|
|
7282
7282
|
{
|
|
7283
7283
|
name: REFRESH_TOKEN,
|
|
7284
7284
|
scheme: z.object({ refreshToken: RefreshTokenSchema }),
|
|
7285
|
-
run: ({ refreshToken }, ctx) => this.#refresh(refreshToken,
|
|
7285
|
+
run: ({ refreshToken }, ctx) => this.#refresh(refreshToken, ctx)
|
|
7286
7286
|
}
|
|
7287
7287
|
]);
|
|
7288
7288
|
}
|
|
@@ -7720,7 +7720,15 @@ function readExtract(extract, body) {
|
|
|
7720
7720
|
return void 0;
|
|
7721
7721
|
}
|
|
7722
7722
|
function isEmptyBody(body) {
|
|
7723
|
-
return body == null || typeof body === "object" && Object.keys(body).length === 0;
|
|
7723
|
+
return body == null || body === "" || typeof body === "object" && Object.keys(body).length === 0;
|
|
7724
|
+
}
|
|
7725
|
+
function hasHandshakeResponse(result) {
|
|
7726
|
+
return result.responseToExternalService !== void 0 || !!result.responseHeaders || !!result.responseToWebhook;
|
|
7727
|
+
}
|
|
7728
|
+
function handshakeErrorStatus(error) {
|
|
7729
|
+
const { statusCode, status } = error ?? {};
|
|
7730
|
+
const candidate = typeof statusCode === "number" ? statusCode : status;
|
|
7731
|
+
return typeof candidate === "number" && candidate >= 400 && candidate < 500 ? candidate : 400;
|
|
7724
7732
|
}
|
|
7725
7733
|
var RealtimeSetup = class {
|
|
7726
7734
|
constructor(extension, props) {
|
|
@@ -7831,19 +7839,9 @@ var RealtimeSetup = class {
|
|
|
7831
7839
|
const body = invocation.body;
|
|
7832
7840
|
const rawBody = invocation.rawBody;
|
|
7833
7841
|
const webhookData = invocation.webhookData ?? null;
|
|
7834
|
-
|
|
7835
|
-
|
|
7836
|
-
|
|
7837
|
-
return {
|
|
7838
|
-
handshake: true,
|
|
7839
|
-
responseToExternalService: result.responseToExternalService,
|
|
7840
|
-
responseHeaders: result.responseHeaders,
|
|
7841
|
-
responseToWebhook: result.responseToWebhook
|
|
7842
|
-
};
|
|
7843
|
-
}
|
|
7844
|
-
}
|
|
7845
|
-
if (isEmptyBody(body)) {
|
|
7846
|
-
return { handshake: true, events: [] };
|
|
7842
|
+
const handshake = await this.#handshake(body, headers, rawBody, webhookData, ctx);
|
|
7843
|
+
if (handshake) {
|
|
7844
|
+
return handshake;
|
|
7847
7845
|
}
|
|
7848
7846
|
if (!await this.#verify(rawBody, headers, webhookData, ctx)) {
|
|
7849
7847
|
ctx.logger.warn(`[flow-extension:${this.extension.id}] webhook signature verification failed \u2014 answering 401`);
|
|
@@ -7884,6 +7882,52 @@ var RealtimeSetup = class {
|
|
|
7884
7882
|
return { events, eventScopeId, connectionId: invocation.connectionId };
|
|
7885
7883
|
}
|
|
7886
7884
|
// The author's own check wins; otherwise the declarative one; otherwise nothing was asked for.
|
|
7885
|
+
/**
|
|
7886
|
+
* Whether this delivery is an endpoint-verification handshake, and if so the answer to it; `null` → proceed.
|
|
7887
|
+
*
|
|
7888
|
+
* Without a `handshake` hook the default applies: an EMPTY body is a handshake, acked with a plain 200 —
|
|
7889
|
+
* the URL-verification ping most providers send. A declared hook REPLACES that default rather than running
|
|
7890
|
+
* before it, so it alone decides: some providers deliver real events with no body at all (Google Drive
|
|
7891
|
+
* puts everything in `X-Goog-*` headers), and a hook that can't overrule the empty-body rule leaves them
|
|
7892
|
+
* no way to reach `resolveEvents`.
|
|
7893
|
+
*
|
|
7894
|
+
* `true` → handshake, plain 200
|
|
7895
|
+
* `{ responseToWebhook, … }` → handshake, answered with that response
|
|
7896
|
+
* nothing / `false` / `{}` → not a handshake, the delivery proceeds
|
|
7897
|
+
* throws → answered with the error, as a 4xx carrying its message
|
|
7898
|
+
*
|
|
7899
|
+
* The throw is turned into a RESPONSE for the same reason a failed signature check is: a throw leaves the
|
|
7900
|
+
* pod as a failed invocation and the provider receives a 500 telling it nothing. The hook runs BEFORE
|
|
7901
|
+
* verification, so the message reaches an unverified caller — throw what the provider may read.
|
|
7902
|
+
*/
|
|
7903
|
+
async #handshake(body, headers, rawBody, webhookData, ctx) {
|
|
7904
|
+
if (!this.props.handshake) {
|
|
7905
|
+
return isEmptyBody(body) ? { handshake: true, events: [] } : null;
|
|
7906
|
+
}
|
|
7907
|
+
let result;
|
|
7908
|
+
try {
|
|
7909
|
+
result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
|
|
7910
|
+
} catch (error) {
|
|
7911
|
+
const message = error?.message ?? String(error);
|
|
7912
|
+
ctx.logger.error(`[flow-extension:${this.extension.id}] handshake failed \u2014 ${message}`);
|
|
7913
|
+
return {
|
|
7914
|
+
events: [],
|
|
7915
|
+
responseToWebhook: { httpStatus: handshakeErrorStatus(error), body: { message } }
|
|
7916
|
+
};
|
|
7917
|
+
}
|
|
7918
|
+
if (result === true) {
|
|
7919
|
+
return { handshake: true, events: [] };
|
|
7920
|
+
}
|
|
7921
|
+
if (result && typeof result === "object" && hasHandshakeResponse(result)) {
|
|
7922
|
+
return {
|
|
7923
|
+
handshake: true,
|
|
7924
|
+
responseToExternalService: result.responseToExternalService,
|
|
7925
|
+
responseHeaders: result.responseHeaders,
|
|
7926
|
+
responseToWebhook: result.responseToWebhook
|
|
7927
|
+
};
|
|
7928
|
+
}
|
|
7929
|
+
return null;
|
|
7930
|
+
}
|
|
7887
7931
|
async #verify(rawBody, headers, webhookData, ctx) {
|
|
7888
7932
|
if (this.props.verifyRequest) {
|
|
7889
7933
|
return !!await this.props.verifyRequest(ctx.bagWith({ rawBody, headers, webhookData, config: ctx.config }));
|
|
@@ -7893,6 +7937,26 @@ var RealtimeSetup = class {
|
|
|
7893
7937
|
}
|
|
7894
7938
|
return true;
|
|
7895
7939
|
}
|
|
7940
|
+
/**
|
|
7941
|
+
* The event data `match` decides on: the delivered data plus whatever `extendMatchData` fetched, read ONCE
|
|
7942
|
+
* for every instance — the case is an id-only webhook (Xero names an invoice, not its type or status) whose
|
|
7943
|
+
* instance filters need the resource itself.
|
|
7944
|
+
*
|
|
7945
|
+
* A failed read is NOT a failed delivery. Select is the data plane: nothing is waiting on it, and a throw
|
|
7946
|
+
* would abort the delivery's other events. So it is logged and the instances are matched against the data
|
|
7947
|
+
* that WAS delivered — an instance filtering on the missing fields declines, an unfiltered one still fires.
|
|
7948
|
+
*/
|
|
7949
|
+
async #withMatchData(trigger, eventData, instances, webhookData, ctx) {
|
|
7950
|
+
try {
|
|
7951
|
+
const extra = await trigger.extendMatchData(eventData, instances, ctx, webhookData);
|
|
7952
|
+
return extra && typeof extra === "object" ? { ...eventData, ...extra } : eventData;
|
|
7953
|
+
} catch (error) {
|
|
7954
|
+
ctx.logger.warn(
|
|
7955
|
+
`[flow-extension:${this.extension.id}] extendMatchData of "${trigger.id}" failed \u2014 matching on the delivered data: ${error?.message ?? error}`
|
|
7956
|
+
);
|
|
7957
|
+
return eventData;
|
|
7958
|
+
}
|
|
7959
|
+
}
|
|
7896
7960
|
// Fan one resolved event out over the configured instances of its trigger. An `eventName` this service
|
|
7897
7961
|
// does not declare is DECLINED outright — `{ ids: [], enrichedEventData: null }`, no instance offered up
|
|
7898
7962
|
// and no per-event seam run. That is deliberately not the same case as a trigger which declares no
|
|
@@ -7908,15 +7972,22 @@ var RealtimeSetup = class {
|
|
|
7908
7972
|
if (!trigger) {
|
|
7909
7973
|
return { ids: [], enrichedEventData: null };
|
|
7910
7974
|
}
|
|
7911
|
-
const eventData = invocation.eventData;
|
|
7912
7975
|
const webhookData = invocation.webhookData ?? null;
|
|
7913
|
-
const
|
|
7976
|
+
const instances = (invocation.triggers ?? []).map((instance) => ({ id: instance.id, params: instance.data ?? {} }));
|
|
7977
|
+
const eventData = trigger.needsMatchData(instances) ? await this.#withMatchData(trigger, invocation.eventData, instances, webhookData, ctx) : invocation.eventData;
|
|
7978
|
+
const verdicts = await Promise.all(
|
|
7979
|
+
instances.map((instance) => trigger.matches(instance.params, eventData, webhookData))
|
|
7980
|
+
);
|
|
7981
|
+
const ids = instances.filter((_instance, index) => verdicts[index]).map((instance) => instance.id);
|
|
7914
7982
|
const enrichedEventData = ids.length && trigger.hasExtendResult() ? await trigger.extendResult(eventData, ctx, webhookData) : null;
|
|
7915
7983
|
return { ids, enrichedEventData };
|
|
7916
7984
|
}
|
|
7917
7985
|
};
|
|
7918
7986
|
|
|
7919
7987
|
// ../../flow-extension-runner/src/v2/realtime-triggers/trigger-method.ts
|
|
7988
|
+
function isFilled(value) {
|
|
7989
|
+
return value != null && value !== "";
|
|
7990
|
+
}
|
|
7920
7991
|
var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
7921
7992
|
constructor(extension, props) {
|
|
7922
7993
|
super(extension);
|
|
@@ -7968,6 +8039,30 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
|
7968
8039
|
extendEventData(requestBody, providerEventData) {
|
|
7969
8040
|
return this.props.extendEventData?.({ requestBody, providerEventData });
|
|
7970
8041
|
}
|
|
8042
|
+
/**
|
|
8043
|
+
* Whether `extendMatchData` should run before these instances are matched. Only when something will READ its
|
|
8044
|
+
* result — otherwise the API call is pure cost, paid on every event:
|
|
8045
|
+
* - no instances, or no `match` → nothing to decide (with no `match` every instance fires);
|
|
8046
|
+
* - declarative `match`, and no instance fills any of its params → every instance matches regardless,
|
|
8047
|
+
* since an empty param means "any". This is the v1 rule: read the resource only when a flow filters.
|
|
8048
|
+
* A predicate `match` is opaque, so the hook runs and receives the instances to make that call itself.
|
|
8049
|
+
*/
|
|
8050
|
+
needsMatchData(instances) {
|
|
8051
|
+
const match = this.props.match;
|
|
8052
|
+
if (typeof this.props.extendMatchData !== "function" || !match || !instances.length) {
|
|
8053
|
+
return false;
|
|
8054
|
+
}
|
|
8055
|
+
if (typeof match === "function") {
|
|
8056
|
+
return true;
|
|
8057
|
+
}
|
|
8058
|
+
const filterKeys = Object.keys(match);
|
|
8059
|
+
return instances.some((instance) => filterKeys.some((key) => isFilled(instance.params[key])));
|
|
8060
|
+
}
|
|
8061
|
+
// Runs ONCE per event, before any instance is matched, with the full handler bag (`apiRequest` on the
|
|
8062
|
+
// connection's token) — for an instance filter on data the delivery does not carry.
|
|
8063
|
+
extendMatchData(providerEventData, instances, ctx, webhookData = null) {
|
|
8064
|
+
return this.props.extendMatchData?.(ctx.bagWith({ providerEventData, webhookData, instances }));
|
|
8065
|
+
}
|
|
7971
8066
|
/**
|
|
7972
8067
|
* Whether one CONFIGURED INSTANCE of this trigger cares about an event. Declarative form: type-coerced
|
|
7973
8068
|
* equality per filled param, where an empty param means "any" — that is what lets a user leave a filter
|
|
@@ -7977,17 +8072,17 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
|
|
|
7977
8072
|
* subscription registered (a tenant id, a resource the webhook was scoped to) has nowhere else to get it.
|
|
7978
8073
|
* Returning a new document is not a thing this seam can do; only subscribe/refresh/unsubscribe persist.
|
|
7979
8074
|
*/
|
|
7980
|
-
matches(params, providerEventData, webhookData = null) {
|
|
8075
|
+
async matches(params, providerEventData, webhookData = null) {
|
|
7981
8076
|
const match = this.props.match;
|
|
7982
8077
|
if (!match) {
|
|
7983
8078
|
return true;
|
|
7984
8079
|
}
|
|
7985
8080
|
if (typeof match === "function") {
|
|
7986
|
-
return !!match({ params, providerEventData, webhookData });
|
|
8081
|
+
return !!await match({ params, providerEventData, webhookData });
|
|
7987
8082
|
}
|
|
7988
8083
|
for (const [paramKey, path19] of Object.entries(match)) {
|
|
7989
8084
|
const paramValue = params[paramKey];
|
|
7990
|
-
if (paramValue
|
|
8085
|
+
if (!isFilled(paramValue)) {
|
|
7991
8086
|
continue;
|
|
7992
8087
|
}
|
|
7993
8088
|
if (`${paramValue}` !== `${getPath(providerEventData, path19)}`) {
|