@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flowrunner/cli",
3
- "version": "0.1.14",
3
+ "version": "0.1.16",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
package/runtime/index.js CHANGED
@@ -12469,16 +12469,39 @@ function declaredAbsence(schema) {
12469
12469
  current = def.innerType;
12470
12470
  }
12471
12471
  const absence = acceptsUndefined && acceptsNull ? "as-received" : acceptsUndefined ? "undefined" : acceptsNull ? "null" : "required";
12472
- return { absence, absorbsBlank };
12472
+ return { absence, absorbsBlank, keepsEmpty: false, blankIsValue: false };
12473
12473
  }
12474
12474
  function coerces(schema) {
12475
12475
  return inspect(schema).core?._zod?.def?.coerce === true;
12476
12476
  }
12477
12477
  var parsesJson = (schema) => !!inspect(schema).meta.frJson;
12478
+ var OPEN_TYPES = /* @__PURE__ */ new Set(["unknown", "any"]);
12479
+ var isOpenType = (schema) => OPEN_TYPES.has(inspect(schema).coreType);
12480
+ function requiredOpenType(schema) {
12481
+ if (!isOpenType(schema)) {
12482
+ return false;
12483
+ }
12484
+ let current = schema;
12485
+ while (current?._zod) {
12486
+ const def = current._zod.def ?? {};
12487
+ const type = def.type;
12488
+ if (type === "nonoptional") {
12489
+ return true;
12490
+ }
12491
+ if (!TRANSPARENT_WRAPPERS.has(type)) {
12492
+ return false;
12493
+ }
12494
+ current = innerOf(def, type);
12495
+ }
12496
+ return false;
12497
+ }
12478
12498
  function probeAbsence(schema) {
12479
12499
  if (coerces(schema) || parsesJson(schema)) {
12480
12500
  return declaredAbsence(schema);
12481
12501
  }
12502
+ if (requiredOpenType(schema)) {
12503
+ return { absence: "required", absorbsBlank: false, keepsEmpty: true, blankIsValue: true };
12504
+ }
12482
12505
  const parse = (value) => {
12483
12506
  try {
12484
12507
  return schema.safeParse(value);
@@ -12489,24 +12512,24 @@ function probeAbsence(schema) {
12489
12512
  const asUndefined = parse(void 0);
12490
12513
  const asNull = parse(null);
12491
12514
  const absence = asUndefined.success && asNull.success ? "as-received" : asUndefined.success ? "undefined" : asNull.success ? "null" : "required";
12492
- return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0 };
12515
+ return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0, keepsEmpty: false, blankIsValue: false };
12493
12516
  }
12494
12517
  var probeCache = /* @__PURE__ */ new WeakMap();
12495
12518
  function absenceOf(schema) {
12496
12519
  if (!schema || typeof schema !== "object") {
12497
- return { absence: "as-received", absorbsBlank: false };
12520
+ return { absence: "as-received", absorbsBlank: false, keepsEmpty: false, blankIsValue: false };
12498
12521
  }
12499
12522
  const cached = probeCache.get(schema);
12500
12523
  if (cached) {
12501
12524
  return cached;
12502
12525
  }
12503
- const probed = probeAbsence(schema);
12526
+ const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema) && !parsesJson(schema) };
12504
12527
  probeCache.set(schema, probed);
12505
12528
  return probed;
12506
12529
  }
12507
12530
  function planField(name, schema) {
12508
12531
  const ins = inspect(schema);
12509
- const { absence, absorbsBlank } = probeAbsence(schema);
12532
+ const { absence, absorbsBlank, keepsEmpty, blankIsValue } = absenceOf(schema);
12510
12533
  return {
12511
12534
  name,
12512
12535
  schema,
@@ -12515,6 +12538,8 @@ function planField(name, schema) {
12515
12538
  isUnion: !!ins.branches,
12516
12539
  absence,
12517
12540
  absorbsBlank,
12541
+ keepsEmpty,
12542
+ blankIsValue,
12518
12543
  passThroughDate: passesDateThrough(ins),
12519
12544
  restoresDates: hasPassThroughDate(schema, inspect, shapeEntries)
12520
12545
  };
@@ -12613,6 +12638,9 @@ function accepts(schema, value) {
12613
12638
  }
12614
12639
  }
12615
12640
  function coerceUnion(value, branches) {
12641
+ if (branches.some((branch) => accepts(branch, value))) {
12642
+ return value;
12643
+ }
12616
12644
  for (const branch of branches) {
12617
12645
  const coerced = coerceDeep(value, branch);
12618
12646
  if (accepts(branch, coerced)) {
@@ -12688,7 +12716,13 @@ function coerceLeaf(value, ins) {
12688
12716
  return coerceValue(value, ins.coreType);
12689
12717
  }
12690
12718
  function isBlank(value, ins, schema) {
12691
- if (value === void 0 || value === null) {
12719
+ if (value === void 0) {
12720
+ return true;
12721
+ }
12722
+ if (absenceOf(schema).keepsEmpty) {
12723
+ return false;
12724
+ }
12725
+ if (value === null) {
12692
12726
  return true;
12693
12727
  }
12694
12728
  if (value !== "") {
@@ -12697,6 +12731,9 @@ function isBlank(value, ins, schema) {
12697
12731
  if (ins.branches) {
12698
12732
  return true;
12699
12733
  }
12734
+ if (absenceOf(schema).blankIsValue) {
12735
+ return absenceOf(schema).absorbsBlank;
12736
+ }
12700
12737
  return ins.coreType !== "string" || absenceOf(schema).absorbsBlank;
12701
12738
  }
12702
12739
  function absentAs(schema, value) {
@@ -12833,7 +12870,13 @@ function toFieldIssue(plan, issue, fieldValue) {
12833
12870
  var resolved = (value) => ({ value, present: true, issues: [] });
12834
12871
  var rejected = (issues) => ({ present: false, issues });
12835
12872
  function isAbsent(value, plan) {
12836
- if (value === void 0 || value === null) {
12873
+ if (value === void 0) {
12874
+ return true;
12875
+ }
12876
+ if (plan.keepsEmpty) {
12877
+ return false;
12878
+ }
12879
+ if (value === null) {
12837
12880
  return true;
12838
12881
  }
12839
12882
  if (value !== "") {
@@ -12842,6 +12885,9 @@ function isAbsent(value, plan) {
12842
12885
  if (plan.isUnion) {
12843
12886
  return true;
12844
12887
  }
12888
+ if (plan.blankIsValue) {
12889
+ return plan.absorbsBlank;
12890
+ }
12845
12891
  return plan.coreType !== "string" || plan.absorbsBlank;
12846
12892
  }
12847
12893
  function normalizeAbsence(value, plan) {
@@ -13129,6 +13175,9 @@ function extendPrototype() {
13129
13175
  const existing = this.meta()?.examples ?? [];
13130
13176
  return this.meta({ examples: [...existing, value] });
13131
13177
  };
13178
+ proto.required = function required() {
13179
+ return this.nonoptional();
13180
+ };
13132
13181
  proto.shared = function shared() {
13133
13182
  return this.meta({ frShared: true });
13134
13183
  };
@@ -14524,10 +14573,11 @@ var OAuth2 = class {
14524
14573
  this.#registerSystemMethods();
14525
14574
  }
14526
14575
  // The handler bag's `oauth`: the header access token, plus its deserialized composite payload when the
14527
- // author declared a deserializer (the pattern for providers whose "token" carries a realm or instance id).
14576
+ // author declared a deserializer (the pattern for providers whose "token" carries a realm or instance id),
14577
+ // and that payload's `userData` — the standard shape's slot for per-connection data.
14528
14578
  buildBag(accessToken) {
14529
14579
  const token = this.props.deserializeToken && accessToken != null ? this.props.deserializeToken(accessToken) : void 0;
14530
- return { accessToken, token };
14580
+ return { accessToken, token, userData: userDataOf(token) };
14531
14581
  }
14532
14582
  // ── SYSTEM seam: name · input · return · handler, in one table ─────────────
14533
14583
  #registerSystemMethods() {
@@ -14615,12 +14665,23 @@ var OAuth2 = class {
14615
14665
  });
14616
14666
  const nextRefresh = tokenResponse.refresh_token ?? currentRefreshToken;
14617
14667
  return {
14618
- token: this.#serialize(tokenResponse.access_token, nextRefresh),
14668
+ token: this.#serialize(tokenResponse.access_token, nextRefresh, this.#storedUserData(ctx)),
14619
14669
  expirationInSeconds: tokenResponse.expires_in,
14620
14670
  refreshToken: nextRefresh
14621
14671
  };
14622
14672
  }
14623
14673
  // ── token exchange ─────────────────────────────────────────────────────────
14674
+ // A refresh response repeats none of the connect-time data, and the platform keeps the connection's
14675
+ // `userData` to itself, so the only copy is inside the current token: read it back, to store it again in
14676
+ // the next one. A token the deserializer cannot read — a bare one saved before the service wrapped its
14677
+ // tokens — has nothing to carry over, and must not fail the refresh for that.
14678
+ #storedUserData(ctx) {
14679
+ try {
14680
+ return ctx.oauth.userData;
14681
+ } catch {
14682
+ return void 0;
14683
+ }
14684
+ }
14624
14685
  #serialize(accessToken, refreshToken, userData) {
14625
14686
  return this.props.serializeToken ? this.props.serializeToken({ accessToken, refreshToken, userData }) : accessToken;
14626
14687
  }
@@ -14645,6 +14706,9 @@ var OAuth2 = class {
14645
14706
  return Flowrunner.Request.post(this.props.tokenUrl).set(headers).send(params.toString());
14646
14707
  }
14647
14708
  };
14709
+ function userDataOf(token) {
14710
+ return token && typeof token === "object" ? token.userData : void 0;
14711
+ }
14648
14712
 
14649
14713
  // ../../flow-extension-runner/src/v2/polling-triggers/method-names.ts
14650
14714
  var POLLING_SYSTEM_METHOD = "handleTriggerPollingForEvent";
@@ -14957,11 +15021,14 @@ var RealtimeSelectInvocationSchema = z.looseObject({
14957
15021
 
14958
15022
  // ../../flow-extension-runner/src/v2/realtime-triggers/verify.ts
14959
15023
  function verifyDeclarative(verify, rawBody, headers, config, webhookData) {
15024
+ const secret = verify.secret(config, { webhookData });
15025
+ if (!secret) {
15026
+ return true;
15027
+ }
14960
15028
  const provided = headers[verify.header] ?? headers[verify.header.toLowerCase()];
14961
15029
  if (!provided) {
14962
15030
  return false;
14963
15031
  }
14964
- const secret = verify.secret(config, { webhookData });
14965
15032
  const computed = Flowrunner.crypto.hmac(verify.algo, secret, rawBody ?? "", verify.encoding);
14966
15033
  if (!Flowrunner.crypto.timingSafeEqual(provided, computed)) {
14967
15034
  return false;
@@ -15038,12 +15105,32 @@ var RealtimeSetup = class {
15038
15105
  webhookData: invocation.webhookData ?? null,
15039
15106
  connectionId: invocation.connectionId
15040
15107
  }));
15108
+ this.#warnOnSuspectScope(result?.eventScopeId, ctx);
15041
15109
  return {
15042
15110
  webhookData: result?.webhookData,
15043
15111
  eventScopeId: result?.eventScopeId,
15044
15112
  refreshIntervalInSeconds: result?.refreshIntervalInSeconds
15045
15113
  };
15046
15114
  }
15115
+ // On ALL_APPS the platform routes every delivery of the shared callback by `eventScopeId`, so it has to name
15116
+ // the customer's tenant. A missing one leaves the app unroutable; the extension's own id or name is the
15117
+ // constant an author most often reaches for, and it puts every customer on one routing key. Neither is
15118
+ // refused — a warning, because a value equal to the name could in principle be a real tenant id.
15119
+ #warnOnSuspectScope(eventScopeId, ctx) {
15120
+ if (this.props.scope !== "ALL_APPS") {
15121
+ return;
15122
+ }
15123
+ const { id, name } = this.extension.props;
15124
+ if (eventScopeId == null || eventScopeId === "") {
15125
+ ctx.logger.warn(
15126
+ `[flow-extension:${id}] ALL_APPS subscribe returned no eventScopeId \u2014 deliveries on the shared callback cannot be routed to this app`
15127
+ );
15128
+ } else if (eventScopeId === id || eventScopeId === name) {
15129
+ ctx.logger.warn(
15130
+ `[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`
15131
+ );
15132
+ }
15133
+ }
15047
15134
  async #unsubscribe(invocation, ctx) {
15048
15135
  const result = await this.props.unsubscribe(ctx.bagWith({
15049
15136
  callbackUrl: invocation.callbackUrl,
@@ -15104,8 +15191,9 @@ var RealtimeSetup = class {
15104
15191
  const headers = invocation.headers ?? {};
15105
15192
  const body = invocation.body;
15106
15193
  const rawBody = invocation.rawBody;
15194
+ const query = invocation.queryParams ?? {};
15107
15195
  const webhookData = invocation.webhookData ?? null;
15108
- const handshake = await this.#handshake(body, headers, rawBody, webhookData, ctx);
15196
+ const handshake = await this.#handshake(body, headers, query, rawBody, webhookData, ctx);
15109
15197
  if (handshake) {
15110
15198
  return handshake;
15111
15199
  }
@@ -15117,7 +15205,7 @@ var RealtimeSetup = class {
15117
15205
  const result = await this.props.resolveEvents(ctx.bagWith({
15118
15206
  rawBody,
15119
15207
  headers,
15120
- query: invocation.queryParams ?? {},
15208
+ query,
15121
15209
  body,
15122
15210
  webhookData,
15123
15211
  connectionId: invocation.connectionId
@@ -15166,13 +15254,13 @@ var RealtimeSetup = class {
15166
15254
  * pod as a failed invocation and the provider receives a 500 telling it nothing. The hook runs BEFORE
15167
15255
  * verification, so the message reaches an unverified caller — throw what the provider may read.
15168
15256
  */
15169
- async #handshake(body, headers, rawBody, webhookData, ctx) {
15257
+ async #handshake(body, headers, query, rawBody, webhookData, ctx) {
15170
15258
  if (!this.props.handshake) {
15171
15259
  return isEmptyBody(body) ? { handshake: true, events: [] } : null;
15172
15260
  }
15173
15261
  let result;
15174
15262
  try {
15175
- result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
15263
+ result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, query, rawBody, webhookData }));
15176
15264
  } catch (error) {
15177
15265
  const message = error?.message ?? String(error);
15178
15266
  ctx.logger.error(`[flow-extension:${this.extension.id}] handshake failed \u2014 ${message}`);