@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.
Files changed (48) hide show
  1. package/ai-docs/instructions/service-code-format/01-service-structure.md +1 -0
  2. package/ai-docs/instructions/service-code-format/06-oauth2.md +20 -1
  3. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +89 -5
  4. package/ai-docs/instructions/service-code-format/11-output-model.md +1 -1
  5. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +6 -3
  6. package/dist/cli.js +105 -22
  7. package/dist/cli.js.map +2 -2
  8. package/dist/index.js +104 -21
  9. package/dist/index.js.map +2 -2
  10. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +1 -1
  11. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +8 -1
  12. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -2
  13. package/dist/types/flow-extension-runner/src/v2/types.d.ts +5 -0
  14. package/dist/types/shared/src/constants/shared-extensions.d.ts +12 -0
  15. package/dist/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
  16. package/dist/types/shared/src/scheme/access-keys/index.d.ts +2 -0
  17. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +8 -8
  18. package/dist/types/shared/src/scheme/index.d.ts +1 -0
  19. package/dist/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
  20. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +1 -1
  21. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +9 -9
  22. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +8 -8
  23. package/dist/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
  24. package/dist/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
  25. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +6 -6
  26. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +4 -4
  27. package/dist/types/shared/src/scheme/shared-extensions/service-info.d.ts +1 -1
  28. package/package.json +1 -1
  29. package/runtime/index.js +103 -20
  30. package/runtime/index.js.map +2 -2
  31. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +1 -1
  32. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +8 -1
  33. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -2
  34. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +5 -0
  35. package/runtime/types/shared/src/constants/shared-extensions.d.ts +12 -0
  36. package/runtime/types/shared/src/scheme/access-keys/dto.d.ts +101 -0
  37. package/runtime/types/shared/src/scheme/access-keys/index.d.ts +2 -0
  38. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +8 -8
  39. package/runtime/types/shared/src/scheme/index.d.ts +1 -0
  40. package/runtime/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -5
  41. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +1 -1
  42. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +9 -9
  43. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +8 -8
  44. package/runtime/types/shared/src/scheme/shared-extensions/index.d.ts +1 -0
  45. package/runtime/types/shared/src/scheme/shared-extensions/list.d.ts +209 -0
  46. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +6 -6
  47. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +4 -4
  48. package/runtime/types/shared/src/scheme/shared-extensions/service-info.d.ts +1 -1
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, anonymous(ctx))
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
- if (this.props.handshake) {
7835
- const result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
7836
- if (result && (result.responseToExternalService !== void 0 || result.responseHeaders || result.responseToWebhook)) {
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 }));
@@ -7903,14 +7947,38 @@ var RealtimeSetup = class {
7903
7947
  // opposite way to `#toSubTriggers`. This is the DATA PLANE: the platform has already answered the
7904
7948
  // provider and detached this work, so a throw reaches nobody — and worse, it aborts every remaining event
7905
7949
  // of the same delivery, dropping the good ones beside the stale name.
7950
+ /**
7951
+ * The event data `match` decides on: the delivered data plus whatever `extendMatchData` fetched, read ONCE
7952
+ * for every instance — the case is an id-only webhook (Xero names an invoice, not its type or status) whose
7953
+ * instance filters need the resource itself.
7954
+ *
7955
+ * A failed read is NOT a failed delivery. Select is the data plane: nothing is waiting on it, and a throw
7956
+ * would abort the delivery's other events. So it is logged and the instances are matched against the data
7957
+ * that WAS delivered — an instance filtering on the missing fields declines, an unfiltered one still fires.
7958
+ */
7959
+ async #withMatchData(trigger, eventData, webhookData, ctx) {
7960
+ try {
7961
+ const extra = await trigger.extendMatchData(eventData, ctx, webhookData);
7962
+ return extra && typeof extra === "object" ? { ...eventData, ...extra } : eventData;
7963
+ } catch (error) {
7964
+ ctx.logger.warn(
7965
+ `[flow-extension:${this.extension.id}] extendMatchData of "${trigger.id}" failed \u2014 matching on the delivered data: ${error?.message ?? error}`
7966
+ );
7967
+ return eventData;
7968
+ }
7969
+ }
7906
7970
  async #selectMatched(invocation, ctx) {
7907
7971
  const trigger = invocation.eventName ? this.extension.findRealtimeTrigger(invocation.eventName) : void 0;
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 ids = (invocation.triggers ?? []).filter((instance) => trigger.matches(instance.data ?? {}, eventData, webhookData)).map((instance) => instance.id);
7976
+ const instances = invocation.triggers ?? [];
7977
+ const eventData = trigger.needsMatchData(instances.length) ? await this.#withMatchData(trigger, invocation.eventData, webhookData, ctx) : invocation.eventData;
7978
+ const verdicts = await Promise.all(
7979
+ instances.map((instance) => trigger.matches(instance.data ?? {}, 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
  }
@@ -7968,6 +8036,19 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
7968
8036
  extendEventData(requestBody, providerEventData) {
7969
8037
  return this.props.extendEventData?.({ requestBody, providerEventData });
7970
8038
  }
8039
+ /**
8040
+ * Whether `extendMatchData` should run for an event about to be matched against `instanceCount` instances.
8041
+ * Only when something will READ its result: with no instances there is nothing to decide, and with no
8042
+ * `match` every instance fires regardless — either way the API call would be pure cost.
8043
+ */
8044
+ needsMatchData(instanceCount) {
8045
+ return typeof this.props.extendMatchData === "function" && !!this.props.match && instanceCount > 0;
8046
+ }
8047
+ // Runs ONCE per event, before any instance is matched, with the full handler bag (`apiRequest` on the
8048
+ // connection's token) — for an instance filter on data the delivery does not carry.
8049
+ extendMatchData(providerEventData, ctx, webhookData = null) {
8050
+ return this.props.extendMatchData?.(ctx.bagWith({ providerEventData, webhookData }));
8051
+ }
7971
8052
  /**
7972
8053
  * Whether one CONFIGURED INSTANCE of this trigger cares about an event. Declarative form: type-coerced
7973
8054
  * equality per filled param, where an empty param means "any" — that is what lets a user leave a filter
@@ -7977,13 +8058,13 @@ var RealtimeTriggerMethod = class extends ExtensionMethod {
7977
8058
  * subscription registered (a tenant id, a resource the webhook was scoped to) has nowhere else to get it.
7978
8059
  * Returning a new document is not a thing this seam can do; only subscribe/refresh/unsubscribe persist.
7979
8060
  */
7980
- matches(params, providerEventData, webhookData = null) {
8061
+ async matches(params, providerEventData, webhookData = null) {
7981
8062
  const match = this.props.match;
7982
8063
  if (!match) {
7983
8064
  return true;
7984
8065
  }
7985
8066
  if (typeof match === "function") {
7986
- return !!match({ params, providerEventData, webhookData });
8067
+ return !!await match({ params, providerEventData, webhookData });
7987
8068
  }
7988
8069
  for (const [paramKey, path19] of Object.entries(match)) {
7989
8070
  const paramValue = params[paramKey];
@@ -8208,7 +8289,9 @@ var Extension = class {
8208
8289
  }
8209
8290
  toServiceInfo() {
8210
8291
  return {
8211
- serviceClassName: this.props.id,
8292
+ // Only a shared extension migrated from v1 has one: its v1 class name, which the legacy ids of its elements,
8293
+ // configs and OAuth connections are built from. A service written as v2 is identified by its id alone
8294
+ ...this.props.serviceClassName ? { serviceClassName: this.props.serviceClassName } : {},
8212
8295
  integrationName: this.props.name,
8213
8296
  integrationIcon: this.props.logo ?? null,
8214
8297
  description: this.props.description || null,
@@ -9002,7 +9085,7 @@ function discoverServices(projectRoot = process.cwd()) {
9002
9085
  }
9003
9086
  const v2Definition = buildServiceDefinition2(serviceId, serviceFilePath);
9004
9087
  const { methodsMap, serviceInfo } = v2Definition ?? parseJsDocToServiceJson(serviceFilePath);
9005
- if (!serviceInfo || !serviceInfo.serviceClassName) {
9088
+ if (!serviceInfo || !v2Definition && !serviceInfo.serviceClassName) {
9006
9089
  skipped.push({ serviceId, reason: "its entry point does not define a service" });
9007
9090
  continue;
9008
9091
  }