@flowrunner/cli 0.1.14 → 0.1.16

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/02-zod-types.md +59 -15
  2. package/ai-docs/instructions/service-code-format/04-http-requests.md +9 -0
  3. package/ai-docs/instructions/service-code-format/06-oauth2.md +59 -9
  4. package/ai-docs/instructions/service-code-format/07-actions.md +1 -1
  5. package/ai-docs/instructions/service-code-format/08-polling-triggers.md +13 -0
  6. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +110 -4
  7. package/ai-docs/instructions/service-code-format/16-gotchas.md +28 -0
  8. package/ai-docs/instructions/service-code-format/18-test-recipes.md +16 -0
  9. package/ai-docs/instructions/service-code-format/19-security.md +121 -0
  10. package/ai-docs/instructions/service-code-format/README.md +3 -2
  11. package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +1 -1
  12. package/dist/cli.js +104 -16
  13. package/dist/cli.js.map +2 -2
  14. package/dist/index.js +103 -15
  15. package/dist/index.js.map +2 -2
  16. package/dist/types/flow-extension-runner/src/v2/oauth/types.d.ts +9 -7
  17. package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -4
  18. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +12 -0
  19. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +2 -1
  20. package/dist/types/shared/src/constants/activity-log.d.ts +77 -0
  21. package/dist/types/shared/src/constants/app.d.ts +0 -1
  22. package/dist/types/shared/src/constants/notification-types.d.ts +117 -6
  23. package/dist/types/shared/src/scheme/account/dto.d.ts +3 -0
  24. package/dist/types/shared/src/scheme/crm/dto.d.ts +6 -0
  25. package/dist/types/shared/src/scheme/index.d.ts +1 -0
  26. package/dist/types/shared/src/scheme/integration-connection/dto.d.ts +27 -15
  27. package/dist/types/shared/src/scheme/notifications/dto.d.ts +3 -0
  28. package/dist/types/shared/src/scheme/notifications/rest.d.ts +6 -0
  29. package/dist/types/shared/src/scheme/onboarding/dto.d.ts +29 -0
  30. package/dist/types/shared/src/scheme/onboarding/index.d.ts +1 -0
  31. package/package.json +1 -1
  32. package/runtime/index.js +103 -15
  33. package/runtime/index.js.map +2 -2
  34. package/runtime/types/flow-extension-runner/src/v2/oauth/types.d.ts +9 -7
  35. package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +9 -4
  36. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +12 -0
  37. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +2 -1
  38. package/runtime/types/shared/src/constants/activity-log.d.ts +77 -0
  39. package/runtime/types/shared/src/constants/app.d.ts +0 -1
  40. package/runtime/types/shared/src/constants/notification-types.d.ts +117 -6
  41. package/runtime/types/shared/src/scheme/account/dto.d.ts +3 -0
  42. package/runtime/types/shared/src/scheme/crm/dto.d.ts +6 -0
  43. package/runtime/types/shared/src/scheme/index.d.ts +1 -0
  44. package/runtime/types/shared/src/scheme/integration-connection/dto.d.ts +27 -15
  45. package/runtime/types/shared/src/scheme/notifications/dto.d.ts +3 -0
  46. package/runtime/types/shared/src/scheme/notifications/rest.d.ts +6 -0
  47. package/runtime/types/shared/src/scheme/onboarding/dto.d.ts +29 -0
  48. package/runtime/types/shared/src/scheme/onboarding/index.d.ts +1 -0
package/dist/index.js CHANGED
@@ -15772,16 +15772,39 @@ function declaredAbsence(schema) {
15772
15772
  current = def.innerType;
15773
15773
  }
15774
15774
  const absence = acceptsUndefined && acceptsNull ? "as-received" : acceptsUndefined ? "undefined" : acceptsNull ? "null" : "required";
15775
- return { absence, absorbsBlank };
15775
+ return { absence, absorbsBlank, keepsEmpty: false, blankIsValue: false };
15776
15776
  }
15777
15777
  function coerces(schema) {
15778
15778
  return inspect(schema).core?._zod?.def?.coerce === true;
15779
15779
  }
15780
15780
  var parsesJson = (schema) => !!inspect(schema).meta.frJson;
15781
+ var OPEN_TYPES = /* @__PURE__ */ new Set(["unknown", "any"]);
15782
+ var isOpenType = (schema) => OPEN_TYPES.has(inspect(schema).coreType);
15783
+ function requiredOpenType(schema) {
15784
+ if (!isOpenType(schema)) {
15785
+ return false;
15786
+ }
15787
+ let current = schema;
15788
+ while (current?._zod) {
15789
+ const def = current._zod.def ?? {};
15790
+ const type = def.type;
15791
+ if (type === "nonoptional") {
15792
+ return true;
15793
+ }
15794
+ if (!TRANSPARENT_WRAPPERS.has(type)) {
15795
+ return false;
15796
+ }
15797
+ current = innerOf(def, type);
15798
+ }
15799
+ return false;
15800
+ }
15781
15801
  function probeAbsence(schema) {
15782
15802
  if (coerces(schema) || parsesJson(schema)) {
15783
15803
  return declaredAbsence(schema);
15784
15804
  }
15805
+ if (requiredOpenType(schema)) {
15806
+ return { absence: "required", absorbsBlank: false, keepsEmpty: true, blankIsValue: true };
15807
+ }
15785
15808
  const parse = (value) => {
15786
15809
  try {
15787
15810
  return schema.safeParse(value);
@@ -15792,24 +15815,24 @@ function probeAbsence(schema) {
15792
15815
  const asUndefined = parse(void 0);
15793
15816
  const asNull = parse(null);
15794
15817
  const absence = asUndefined.success && asNull.success ? "as-received" : asUndefined.success ? "undefined" : asNull.success ? "null" : "required";
15795
- return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0 };
15818
+ return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0, keepsEmpty: false, blankIsValue: false };
15796
15819
  }
15797
15820
  var probeCache = /* @__PURE__ */ new WeakMap();
15798
15821
  function absenceOf(schema) {
15799
15822
  if (!schema || typeof schema !== "object") {
15800
- return { absence: "as-received", absorbsBlank: false };
15823
+ return { absence: "as-received", absorbsBlank: false, keepsEmpty: false, blankIsValue: false };
15801
15824
  }
15802
15825
  const cached2 = probeCache.get(schema);
15803
15826
  if (cached2) {
15804
15827
  return cached2;
15805
15828
  }
15806
- const probed = probeAbsence(schema);
15829
+ const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema) && !parsesJson(schema) };
15807
15830
  probeCache.set(schema, probed);
15808
15831
  return probed;
15809
15832
  }
15810
15833
  function planField(name, schema) {
15811
15834
  const ins = inspect(schema);
15812
- const { absence, absorbsBlank } = probeAbsence(schema);
15835
+ const { absence, absorbsBlank, keepsEmpty, blankIsValue } = absenceOf(schema);
15813
15836
  return {
15814
15837
  name,
15815
15838
  schema,
@@ -15818,6 +15841,8 @@ function planField(name, schema) {
15818
15841
  isUnion: !!ins.branches,
15819
15842
  absence,
15820
15843
  absorbsBlank,
15844
+ keepsEmpty,
15845
+ blankIsValue,
15821
15846
  passThroughDate: passesDateThrough(ins),
15822
15847
  restoresDates: hasPassThroughDate(schema, inspect, shapeEntries)
15823
15848
  };
@@ -15916,6 +15941,9 @@ function accepts(schema, value) {
15916
15941
  }
15917
15942
  }
15918
15943
  function coerceUnion(value, branches) {
15944
+ if (branches.some((branch) => accepts(branch, value))) {
15945
+ return value;
15946
+ }
15919
15947
  for (const branch of branches) {
15920
15948
  const coerced = coerceDeep(value, branch);
15921
15949
  if (accepts(branch, coerced)) {
@@ -15991,7 +16019,13 @@ function coerceLeaf(value, ins) {
15991
16019
  return coerceValue(value, ins.coreType);
15992
16020
  }
15993
16021
  function isBlank(value, ins, schema) {
15994
- if (value === void 0 || value === null) {
16022
+ if (value === void 0) {
16023
+ return true;
16024
+ }
16025
+ if (absenceOf(schema).keepsEmpty) {
16026
+ return false;
16027
+ }
16028
+ if (value === null) {
15995
16029
  return true;
15996
16030
  }
15997
16031
  if (value !== "") {
@@ -16000,6 +16034,9 @@ function isBlank(value, ins, schema) {
16000
16034
  if (ins.branches) {
16001
16035
  return true;
16002
16036
  }
16037
+ if (absenceOf(schema).blankIsValue) {
16038
+ return absenceOf(schema).absorbsBlank;
16039
+ }
16003
16040
  return ins.coreType !== "string" || absenceOf(schema).absorbsBlank;
16004
16041
  }
16005
16042
  function absentAs(schema, value) {
@@ -16136,7 +16173,13 @@ function toFieldIssue(plan2, issue, fieldValue) {
16136
16173
  var resolved = (value) => ({ value, present: true, issues: [] });
16137
16174
  var rejected = (issues) => ({ present: false, issues });
16138
16175
  function isAbsent(value, plan2) {
16139
- if (value === void 0 || value === null) {
16176
+ if (value === void 0) {
16177
+ return true;
16178
+ }
16179
+ if (plan2.keepsEmpty) {
16180
+ return false;
16181
+ }
16182
+ if (value === null) {
16140
16183
  return true;
16141
16184
  }
16142
16185
  if (value !== "") {
@@ -16145,6 +16188,9 @@ function isAbsent(value, plan2) {
16145
16188
  if (plan2.isUnion) {
16146
16189
  return true;
16147
16190
  }
16191
+ if (plan2.blankIsValue) {
16192
+ return plan2.absorbsBlank;
16193
+ }
16148
16194
  return plan2.coreType !== "string" || plan2.absorbsBlank;
16149
16195
  }
16150
16196
  function normalizeAbsence(value, plan2) {
@@ -16432,6 +16478,9 @@ function extendPrototype() {
16432
16478
  const existing = this.meta()?.examples ?? [];
16433
16479
  return this.meta({ examples: [...existing, value] });
16434
16480
  };
16481
+ proto.required = function required() {
16482
+ return this.nonoptional();
16483
+ };
16435
16484
  proto.shared = function shared() {
16436
16485
  return this.meta({ frShared: true });
16437
16486
  };
@@ -17702,10 +17751,11 @@ var OAuth2 = class {
17702
17751
  this.#registerSystemMethods();
17703
17752
  }
17704
17753
  // 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).
17754
+ // author declared a deserializer (the pattern for providers whose "token" carries a realm or instance id),
17755
+ // and that payload's `userData` — the standard shape's slot for per-connection data.
17706
17756
  buildBag(accessToken) {
17707
17757
  const token = this.props.deserializeToken && accessToken != null ? this.props.deserializeToken(accessToken) : void 0;
17708
- return { accessToken, token };
17758
+ return { accessToken, token, userData: userDataOf(token) };
17709
17759
  }
17710
17760
  // ── SYSTEM seam: name · input · return · handler, in one table ─────────────
17711
17761
  #registerSystemMethods() {
@@ -17793,12 +17843,23 @@ var OAuth2 = class {
17793
17843
  });
17794
17844
  const nextRefresh = tokenResponse.refresh_token ?? currentRefreshToken;
17795
17845
  return {
17796
- token: this.#serialize(tokenResponse.access_token, nextRefresh),
17846
+ token: this.#serialize(tokenResponse.access_token, nextRefresh, this.#storedUserData(ctx)),
17797
17847
  expirationInSeconds: tokenResponse.expires_in,
17798
17848
  refreshToken: nextRefresh
17799
17849
  };
17800
17850
  }
17801
17851
  // ── token exchange ─────────────────────────────────────────────────────────
17852
+ // A refresh response repeats none of the connect-time data, and the platform keeps the connection's
17853
+ // `userData` to itself, so the only copy is inside the current token: read it back, to store it again in
17854
+ // the next one. A token the deserializer cannot read — a bare one saved before the service wrapped its
17855
+ // tokens — has nothing to carry over, and must not fail the refresh for that.
17856
+ #storedUserData(ctx) {
17857
+ try {
17858
+ return ctx.oauth.userData;
17859
+ } catch {
17860
+ return void 0;
17861
+ }
17862
+ }
17802
17863
  #serialize(accessToken, refreshToken, userData) {
17803
17864
  return this.props.serializeToken ? this.props.serializeToken({ accessToken, refreshToken, userData }) : accessToken;
17804
17865
  }
@@ -17823,6 +17884,9 @@ var OAuth2 = class {
17823
17884
  return Flowrunner.Request.post(this.props.tokenUrl).set(headers).send(params.toString());
17824
17885
  }
17825
17886
  };
17887
+ function userDataOf(token) {
17888
+ return token && typeof token === "object" ? token.userData : void 0;
17889
+ }
17826
17890
 
17827
17891
  // ../../flow-extension-runner/src/v2/polling-triggers/method-names.ts
17828
17892
  var POLLING_SYSTEM_METHOD = "handleTriggerPollingForEvent";
@@ -18135,11 +18199,14 @@ var RealtimeSelectInvocationSchema = z.looseObject({
18135
18199
 
18136
18200
  // ../../flow-extension-runner/src/v2/realtime-triggers/verify.ts
18137
18201
  function verifyDeclarative(verify, rawBody, headers, config, webhookData) {
18202
+ const secret = verify.secret(config, { webhookData });
18203
+ if (!secret) {
18204
+ return true;
18205
+ }
18138
18206
  const provided = headers[verify.header] ?? headers[verify.header.toLowerCase()];
18139
18207
  if (!provided) {
18140
18208
  return false;
18141
18209
  }
18142
- const secret = verify.secret(config, { webhookData });
18143
18210
  const computed = Flowrunner.crypto.hmac(verify.algo, secret, rawBody ?? "", verify.encoding);
18144
18211
  if (!Flowrunner.crypto.timingSafeEqual(provided, computed)) {
18145
18212
  return false;
@@ -18216,12 +18283,32 @@ var RealtimeSetup = class {
18216
18283
  webhookData: invocation.webhookData ?? null,
18217
18284
  connectionId: invocation.connectionId
18218
18285
  }));
18286
+ this.#warnOnSuspectScope(result?.eventScopeId, ctx);
18219
18287
  return {
18220
18288
  webhookData: result?.webhookData,
18221
18289
  eventScopeId: result?.eventScopeId,
18222
18290
  refreshIntervalInSeconds: result?.refreshIntervalInSeconds
18223
18291
  };
18224
18292
  }
18293
+ // On ALL_APPS the platform routes every delivery of the shared callback by `eventScopeId`, so it has to name
18294
+ // the customer's tenant. A missing one leaves the app unroutable; the extension's own id or name is the
18295
+ // constant an author most often reaches for, and it puts every customer on one routing key. Neither is
18296
+ // refused — a warning, because a value equal to the name could in principle be a real tenant id.
18297
+ #warnOnSuspectScope(eventScopeId, ctx) {
18298
+ if (this.props.scope !== "ALL_APPS") {
18299
+ return;
18300
+ }
18301
+ const { id, name } = this.extension.props;
18302
+ if (eventScopeId == null || eventScopeId === "") {
18303
+ ctx.logger.warn(
18304
+ `[flow-extension:${id}] ALL_APPS subscribe returned no eventScopeId \u2014 deliveries on the shared callback cannot be routed to this app`
18305
+ );
18306
+ } else if (eventScopeId === id || eventScopeId === name) {
18307
+ ctx.logger.warn(
18308
+ `[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`
18309
+ );
18310
+ }
18311
+ }
18225
18312
  async #unsubscribe(invocation, ctx) {
18226
18313
  const result = await this.props.unsubscribe(ctx.bagWith({
18227
18314
  callbackUrl: invocation.callbackUrl,
@@ -18282,8 +18369,9 @@ var RealtimeSetup = class {
18282
18369
  const headers = invocation.headers ?? {};
18283
18370
  const body = invocation.body;
18284
18371
  const rawBody = invocation.rawBody;
18372
+ const query = invocation.queryParams ?? {};
18285
18373
  const webhookData = invocation.webhookData ?? null;
18286
- const handshake = await this.#handshake(body, headers, rawBody, webhookData, ctx);
18374
+ const handshake = await this.#handshake(body, headers, query, rawBody, webhookData, ctx);
18287
18375
  if (handshake) {
18288
18376
  return handshake;
18289
18377
  }
@@ -18295,7 +18383,7 @@ var RealtimeSetup = class {
18295
18383
  const result = await this.props.resolveEvents(ctx.bagWith({
18296
18384
  rawBody,
18297
18385
  headers,
18298
- query: invocation.queryParams ?? {},
18386
+ query,
18299
18387
  body,
18300
18388
  webhookData,
18301
18389
  connectionId: invocation.connectionId
@@ -18344,13 +18432,13 @@ var RealtimeSetup = class {
18344
18432
  * pod as a failed invocation and the provider receives a 500 telling it nothing. The hook runs BEFORE
18345
18433
  * verification, so the message reaches an unverified caller — throw what the provider may read.
18346
18434
  */
18347
- async #handshake(body, headers, rawBody, webhookData, ctx) {
18435
+ async #handshake(body, headers, query, rawBody, webhookData, ctx) {
18348
18436
  if (!this.props.handshake) {
18349
18437
  return isEmptyBody(body) ? { handshake: true, events: [] } : null;
18350
18438
  }
18351
18439
  let result;
18352
18440
  try {
18353
- result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
18441
+ result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, query, rawBody, webhookData }));
18354
18442
  } catch (error) {
18355
18443
  const message = error?.message ?? String(error);
18356
18444
  ctx.logger.error(`[flow-extension:${this.extension.id}] handshake failed \u2014 ${message}`);