@flowrunner/cli 0.1.14 → 0.1.15

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 (43) hide show
  1. package/ai-docs/instructions/service-code-format/04-http-requests.md +9 -0
  2. package/ai-docs/instructions/service-code-format/06-oauth2.md +59 -9
  3. package/ai-docs/instructions/service-code-format/07-actions.md +1 -1
  4. package/ai-docs/instructions/service-code-format/08-polling-triggers.md +13 -0
  5. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +110 -4
  6. package/ai-docs/instructions/service-code-format/16-gotchas.md +24 -0
  7. package/ai-docs/instructions/service-code-format/18-test-recipes.md +16 -0
  8. package/ai-docs/instructions/service-code-format/19-security.md +121 -0
  9. package/ai-docs/instructions/service-code-format/README.md +3 -2
  10. package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +1 -1
  11. package/dist/cli.js +48 -9
  12. package/dist/cli.js.map +2 -2
  13. package/dist/index.js +47 -8
  14. package/dist/index.js.map +2 -2
  15. package/dist/types/flow-extension-runner/src/v2/oauth/types.d.ts +9 -7
  16. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +2 -1
  17. package/dist/types/shared/src/constants/activity-log.d.ts +77 -0
  18. package/dist/types/shared/src/constants/app.d.ts +0 -1
  19. package/dist/types/shared/src/constants/notification-types.d.ts +117 -6
  20. package/dist/types/shared/src/scheme/account/dto.d.ts +3 -0
  21. package/dist/types/shared/src/scheme/crm/dto.d.ts +6 -0
  22. package/dist/types/shared/src/scheme/index.d.ts +1 -0
  23. package/dist/types/shared/src/scheme/integration-connection/dto.d.ts +27 -15
  24. package/dist/types/shared/src/scheme/notifications/dto.d.ts +3 -0
  25. package/dist/types/shared/src/scheme/notifications/rest.d.ts +6 -0
  26. package/dist/types/shared/src/scheme/onboarding/dto.d.ts +29 -0
  27. package/dist/types/shared/src/scheme/onboarding/index.d.ts +1 -0
  28. package/package.json +1 -1
  29. package/runtime/index.js +47 -8
  30. package/runtime/index.js.map +2 -2
  31. package/runtime/types/flow-extension-runner/src/v2/oauth/types.d.ts +9 -7
  32. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +2 -1
  33. package/runtime/types/shared/src/constants/activity-log.d.ts +77 -0
  34. package/runtime/types/shared/src/constants/app.d.ts +0 -1
  35. package/runtime/types/shared/src/constants/notification-types.d.ts +117 -6
  36. package/runtime/types/shared/src/scheme/account/dto.d.ts +3 -0
  37. package/runtime/types/shared/src/scheme/crm/dto.d.ts +6 -0
  38. package/runtime/types/shared/src/scheme/index.d.ts +1 -0
  39. package/runtime/types/shared/src/scheme/integration-connection/dto.d.ts +27 -15
  40. package/runtime/types/shared/src/scheme/notifications/dto.d.ts +3 -0
  41. package/runtime/types/shared/src/scheme/notifications/rest.d.ts +6 -0
  42. package/runtime/types/shared/src/scheme/onboarding/dto.d.ts +29 -0
  43. package/runtime/types/shared/src/scheme/onboarding/index.d.ts +1 -0
package/dist/index.js CHANGED
@@ -17702,10 +17702,11 @@ var OAuth2 = class {
17702
17702
  this.#registerSystemMethods();
17703
17703
  }
17704
17704
  // The handler bag's `oauth`: the header access token, plus its deserialized composite payload when the
17705
- // author declared a deserializer (the pattern for providers whose "token" carries a realm or instance id).
17705
+ // author declared a deserializer (the pattern for providers whose "token" carries a realm or instance id),
17706
+ // and that payload's `userData` — the standard shape's slot for per-connection data.
17706
17707
  buildBag(accessToken) {
17707
17708
  const token = this.props.deserializeToken && accessToken != null ? this.props.deserializeToken(accessToken) : void 0;
17708
- return { accessToken, token };
17709
+ return { accessToken, token, userData: userDataOf(token) };
17709
17710
  }
17710
17711
  // ── SYSTEM seam: name · input · return · handler, in one table ─────────────
17711
17712
  #registerSystemMethods() {
@@ -17793,12 +17794,23 @@ var OAuth2 = class {
17793
17794
  });
17794
17795
  const nextRefresh = tokenResponse.refresh_token ?? currentRefreshToken;
17795
17796
  return {
17796
- token: this.#serialize(tokenResponse.access_token, nextRefresh),
17797
+ token: this.#serialize(tokenResponse.access_token, nextRefresh, this.#storedUserData(ctx)),
17797
17798
  expirationInSeconds: tokenResponse.expires_in,
17798
17799
  refreshToken: nextRefresh
17799
17800
  };
17800
17801
  }
17801
17802
  // ── token exchange ─────────────────────────────────────────────────────────
17803
+ // A refresh response repeats none of the connect-time data, and the platform keeps the connection's
17804
+ // `userData` to itself, so the only copy is inside the current token: read it back, to store it again in
17805
+ // the next one. A token the deserializer cannot read — a bare one saved before the service wrapped its
17806
+ // tokens — has nothing to carry over, and must not fail the refresh for that.
17807
+ #storedUserData(ctx) {
17808
+ try {
17809
+ return ctx.oauth.userData;
17810
+ } catch {
17811
+ return void 0;
17812
+ }
17813
+ }
17802
17814
  #serialize(accessToken, refreshToken, userData) {
17803
17815
  return this.props.serializeToken ? this.props.serializeToken({ accessToken, refreshToken, userData }) : accessToken;
17804
17816
  }
@@ -17823,6 +17835,9 @@ var OAuth2 = class {
17823
17835
  return Flowrunner.Request.post(this.props.tokenUrl).set(headers).send(params.toString());
17824
17836
  }
17825
17837
  };
17838
+ function userDataOf(token) {
17839
+ return token && typeof token === "object" ? token.userData : void 0;
17840
+ }
17826
17841
 
17827
17842
  // ../../flow-extension-runner/src/v2/polling-triggers/method-names.ts
17828
17843
  var POLLING_SYSTEM_METHOD = "handleTriggerPollingForEvent";
@@ -18135,11 +18150,14 @@ var RealtimeSelectInvocationSchema = z.looseObject({
18135
18150
 
18136
18151
  // ../../flow-extension-runner/src/v2/realtime-triggers/verify.ts
18137
18152
  function verifyDeclarative(verify, rawBody, headers, config, webhookData) {
18153
+ const secret = verify.secret(config, { webhookData });
18154
+ if (!secret) {
18155
+ return true;
18156
+ }
18138
18157
  const provided = headers[verify.header] ?? headers[verify.header.toLowerCase()];
18139
18158
  if (!provided) {
18140
18159
  return false;
18141
18160
  }
18142
- const secret = verify.secret(config, { webhookData });
18143
18161
  const computed = Flowrunner.crypto.hmac(verify.algo, secret, rawBody ?? "", verify.encoding);
18144
18162
  if (!Flowrunner.crypto.timingSafeEqual(provided, computed)) {
18145
18163
  return false;
@@ -18216,12 +18234,32 @@ var RealtimeSetup = class {
18216
18234
  webhookData: invocation.webhookData ?? null,
18217
18235
  connectionId: invocation.connectionId
18218
18236
  }));
18237
+ this.#warnOnSuspectScope(result?.eventScopeId, ctx);
18219
18238
  return {
18220
18239
  webhookData: result?.webhookData,
18221
18240
  eventScopeId: result?.eventScopeId,
18222
18241
  refreshIntervalInSeconds: result?.refreshIntervalInSeconds
18223
18242
  };
18224
18243
  }
18244
+ // On ALL_APPS the platform routes every delivery of the shared callback by `eventScopeId`, so it has to name
18245
+ // the customer's tenant. A missing one leaves the app unroutable; the extension's own id or name is the
18246
+ // constant an author most often reaches for, and it puts every customer on one routing key. Neither is
18247
+ // refused — a warning, because a value equal to the name could in principle be a real tenant id.
18248
+ #warnOnSuspectScope(eventScopeId, ctx) {
18249
+ if (this.props.scope !== "ALL_APPS") {
18250
+ return;
18251
+ }
18252
+ const { id, name } = this.extension.props;
18253
+ if (eventScopeId == null || eventScopeId === "") {
18254
+ ctx.logger.warn(
18255
+ `[flow-extension:${id}] ALL_APPS subscribe returned no eventScopeId \u2014 deliveries on the shared callback cannot be routed to this app`
18256
+ );
18257
+ } else if (eventScopeId === id || eventScopeId === name) {
18258
+ ctx.logger.warn(
18259
+ `[flow-extension:${id}] ALL_APPS subscribe returned the extension's own ${eventScopeId === id ? "id" : "name"} ("${eventScopeId}") as eventScopeId \u2014 a constant puts every customer on one routing key; return the tenant id the provider's deliveries carry`
18260
+ );
18261
+ }
18262
+ }
18225
18263
  async #unsubscribe(invocation, ctx) {
18226
18264
  const result = await this.props.unsubscribe(ctx.bagWith({
18227
18265
  callbackUrl: invocation.callbackUrl,
@@ -18282,8 +18320,9 @@ var RealtimeSetup = class {
18282
18320
  const headers = invocation.headers ?? {};
18283
18321
  const body = invocation.body;
18284
18322
  const rawBody = invocation.rawBody;
18323
+ const query = invocation.queryParams ?? {};
18285
18324
  const webhookData = invocation.webhookData ?? null;
18286
- const handshake = await this.#handshake(body, headers, rawBody, webhookData, ctx);
18325
+ const handshake = await this.#handshake(body, headers, query, rawBody, webhookData, ctx);
18287
18326
  if (handshake) {
18288
18327
  return handshake;
18289
18328
  }
@@ -18295,7 +18334,7 @@ var RealtimeSetup = class {
18295
18334
  const result = await this.props.resolveEvents(ctx.bagWith({
18296
18335
  rawBody,
18297
18336
  headers,
18298
- query: invocation.queryParams ?? {},
18337
+ query,
18299
18338
  body,
18300
18339
  webhookData,
18301
18340
  connectionId: invocation.connectionId
@@ -18344,13 +18383,13 @@ var RealtimeSetup = class {
18344
18383
  * pod as a failed invocation and the provider receives a 500 telling it nothing. The hook runs BEFORE
18345
18384
  * verification, so the message reaches an unverified caller — throw what the provider may read.
18346
18385
  */
18347
- async #handshake(body, headers, rawBody, webhookData, ctx) {
18386
+ async #handshake(body, headers, query, rawBody, webhookData, ctx) {
18348
18387
  if (!this.props.handshake) {
18349
18388
  return isEmptyBody(body) ? { handshake: true, events: [] } : null;
18350
18389
  }
18351
18390
  let result;
18352
18391
  try {
18353
- result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
18392
+ result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, query, rawBody, webhookData }));
18354
18393
  } catch (error) {
18355
18394
  const message = error?.message ?? String(error);
18356
18395
  ctx.logger.error(`[flow-extension:${this.extension.id}] handshake failed \u2014 ${message}`);