@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
@@ -47,7 +47,7 @@ param names are live contract, not style choices.
47
47
  ## Reading order
48
48
 
49
49
  **Decide the feature set first, then load in one batch.** Every document you load stays in context for the
50
- rest of the task and is re-read on every subsequent turn, so loading all eighteen to build a three-action
50
+ rest of the task and is re-read on every subsequent turn, so loading all nineteen to build a three-action
51
51
  service is the single most expensive mistake available here. Loading one you turn out to need *late* is
52
52
  worse still — it costs a rewrite. So: settle what the service will contain, then read the core plus the
53
53
  conditional groups that apply, together.
@@ -63,7 +63,8 @@ conditional groups that apply, together.
63
63
  | 5 | [05-dictionaries.md](05-dictionaries.md) | `ext.dictionary(props)` — dynamic param options; `label` (→ `operationName`, always set it), `criteria` → auto `dependsOn`, optional `result` sample |
64
64
  | 6 | [07-actions.md](07-actions.md) | `ext.addAction(props)`, the shared `execute` context bag, and input validation |
65
65
  | 7 | [16-gotchas.md](16-gotchas.md) | Cross-cutting traps that fail *silently* — empty-string params, lookup tables keyed by user input, dictionary error handling. Deliberately short |
66
- | 8 | [14-reference-service.md](14-reference-service.md) | A complete verified service exercising the whole surface — **read this instead of the CLI templates** |
66
+ | 8 | [19-security.md](19-security.md) | Four silent security mistakes: secrets in logs, credentials in the URL, credentials or headers sent where the service didn't choose, upload MIME type. Short — check a service against it before calling it done |
67
+ | 9 | [14-reference-service.md](14-reference-service.md) | A complete verified service exercising the whole surface — **read this instead of the CLI templates** |
67
68
 
68
69
  Dictionaries are core because nearly every service has at least one id-like parameter, and a flow author
69
70
  picking a value from a list is the difference between a usable service and one that requires them to go
@@ -24,7 +24,7 @@ is the routing authority, so follow it rather than guessing from filenames.
24
24
 
25
25
  **Load once, deliberately.** Decide the feature set first — auth style, whether there are triggers and of
26
26
  which kind, whether any parameter takes a file or wants a dropdown — then read the core plus exactly the
27
- conditional documents that decision implies, in a single batch. Do not read all eighteen by default: every
27
+ conditional documents that decision implies, in a single batch. Do not read all nineteen by default: every
28
28
  document stays in context and is re-read on each subsequent turn, so an unneeded one is paid for many times
29
29
  over. Reading a needed one late is worse, which is why the feature-set decision comes first.
30
30
 
package/dist/cli.js CHANGED
@@ -14508,7 +14508,7 @@ var require_package = __commonJS({
14508
14508
  "package.json"(exports2, module2) {
14509
14509
  module2.exports = {
14510
14510
  name: "@flowrunner/cli",
14511
- version: "0.1.14",
14511
+ version: "0.1.16",
14512
14512
  publishConfig: {
14513
14513
  access: "public"
14514
14514
  },
@@ -16291,16 +16291,39 @@ function declaredAbsence(schema) {
16291
16291
  current = def.innerType;
16292
16292
  }
16293
16293
  const absence = acceptsUndefined && acceptsNull ? "as-received" : acceptsUndefined ? "undefined" : acceptsNull ? "null" : "required";
16294
- return { absence, absorbsBlank };
16294
+ return { absence, absorbsBlank, keepsEmpty: false, blankIsValue: false };
16295
16295
  }
16296
16296
  function coerces(schema) {
16297
16297
  return inspect(schema).core?._zod?.def?.coerce === true;
16298
16298
  }
16299
16299
  var parsesJson = (schema) => !!inspect(schema).meta.frJson;
16300
+ var OPEN_TYPES = /* @__PURE__ */ new Set(["unknown", "any"]);
16301
+ var isOpenType = (schema) => OPEN_TYPES.has(inspect(schema).coreType);
16302
+ function requiredOpenType(schema) {
16303
+ if (!isOpenType(schema)) {
16304
+ return false;
16305
+ }
16306
+ let current = schema;
16307
+ while (current?._zod) {
16308
+ const def = current._zod.def ?? {};
16309
+ const type = def.type;
16310
+ if (type === "nonoptional") {
16311
+ return true;
16312
+ }
16313
+ if (!TRANSPARENT_WRAPPERS.has(type)) {
16314
+ return false;
16315
+ }
16316
+ current = innerOf(def, type);
16317
+ }
16318
+ return false;
16319
+ }
16300
16320
  function probeAbsence(schema) {
16301
16321
  if (coerces(schema) || parsesJson(schema)) {
16302
16322
  return declaredAbsence(schema);
16303
16323
  }
16324
+ if (requiredOpenType(schema)) {
16325
+ return { absence: "required", absorbsBlank: false, keepsEmpty: true, blankIsValue: true };
16326
+ }
16304
16327
  const parse = (value) => {
16305
16328
  try {
16306
16329
  return schema.safeParse(value);
@@ -16311,24 +16334,24 @@ function probeAbsence(schema) {
16311
16334
  const asUndefined = parse(void 0);
16312
16335
  const asNull = parse(null);
16313
16336
  const absence = asUndefined.success && asNull.success ? "as-received" : asUndefined.success ? "undefined" : asNull.success ? "null" : "required";
16314
- return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0 };
16337
+ return { absence, absorbsBlank: asUndefined.success && asUndefined.data !== void 0, keepsEmpty: false, blankIsValue: false };
16315
16338
  }
16316
16339
  var probeCache = /* @__PURE__ */ new WeakMap();
16317
16340
  function absenceOf(schema) {
16318
16341
  if (!schema || typeof schema !== "object") {
16319
- return { absence: "as-received", absorbsBlank: false };
16342
+ return { absence: "as-received", absorbsBlank: false, keepsEmpty: false, blankIsValue: false };
16320
16343
  }
16321
16344
  const cached2 = probeCache.get(schema);
16322
16345
  if (cached2) {
16323
16346
  return cached2;
16324
16347
  }
16325
- const probed = probeAbsence(schema);
16348
+ const probed = { ...probeAbsence(schema), blankIsValue: isOpenType(schema) && !parsesJson(schema) };
16326
16349
  probeCache.set(schema, probed);
16327
16350
  return probed;
16328
16351
  }
16329
16352
  function planField(name, schema) {
16330
16353
  const ins = inspect(schema);
16331
- const { absence, absorbsBlank } = probeAbsence(schema);
16354
+ const { absence, absorbsBlank, keepsEmpty, blankIsValue } = absenceOf(schema);
16332
16355
  return {
16333
16356
  name,
16334
16357
  schema,
@@ -16337,6 +16360,8 @@ function planField(name, schema) {
16337
16360
  isUnion: !!ins.branches,
16338
16361
  absence,
16339
16362
  absorbsBlank,
16363
+ keepsEmpty,
16364
+ blankIsValue,
16340
16365
  passThroughDate: passesDateThrough(ins),
16341
16366
  restoresDates: hasPassThroughDate(schema, inspect, shapeEntries)
16342
16367
  };
@@ -16435,6 +16460,9 @@ function accepts(schema, value) {
16435
16460
  }
16436
16461
  }
16437
16462
  function coerceUnion(value, branches) {
16463
+ if (branches.some((branch) => accepts(branch, value))) {
16464
+ return value;
16465
+ }
16438
16466
  for (const branch of branches) {
16439
16467
  const coerced = coerceDeep(value, branch);
16440
16468
  if (accepts(branch, coerced)) {
@@ -16510,7 +16538,13 @@ function coerceLeaf(value, ins) {
16510
16538
  return coerceValue(value, ins.coreType);
16511
16539
  }
16512
16540
  function isBlank(value, ins, schema) {
16513
- if (value === void 0 || value === null) {
16541
+ if (value === void 0) {
16542
+ return true;
16543
+ }
16544
+ if (absenceOf(schema).keepsEmpty) {
16545
+ return false;
16546
+ }
16547
+ if (value === null) {
16514
16548
  return true;
16515
16549
  }
16516
16550
  if (value !== "") {
@@ -16519,6 +16553,9 @@ function isBlank(value, ins, schema) {
16519
16553
  if (ins.branches) {
16520
16554
  return true;
16521
16555
  }
16556
+ if (absenceOf(schema).blankIsValue) {
16557
+ return absenceOf(schema).absorbsBlank;
16558
+ }
16522
16559
  return ins.coreType !== "string" || absenceOf(schema).absorbsBlank;
16523
16560
  }
16524
16561
  function absentAs(schema, value) {
@@ -16655,7 +16692,13 @@ function toFieldIssue(plan2, issue, fieldValue) {
16655
16692
  var resolved2 = (value) => ({ value, present: true, issues: [] });
16656
16693
  var rejected = (issues) => ({ present: false, issues });
16657
16694
  function isAbsent(value, plan2) {
16658
- if (value === void 0 || value === null) {
16695
+ if (value === void 0) {
16696
+ return true;
16697
+ }
16698
+ if (plan2.keepsEmpty) {
16699
+ return false;
16700
+ }
16701
+ if (value === null) {
16659
16702
  return true;
16660
16703
  }
16661
16704
  if (value !== "") {
@@ -16664,6 +16707,9 @@ function isAbsent(value, plan2) {
16664
16707
  if (plan2.isUnion) {
16665
16708
  return true;
16666
16709
  }
16710
+ if (plan2.blankIsValue) {
16711
+ return plan2.absorbsBlank;
16712
+ }
16667
16713
  return plan2.coreType !== "string" || plan2.absorbsBlank;
16668
16714
  }
16669
16715
  function normalizeAbsence(value, plan2) {
@@ -16951,6 +16997,9 @@ function extendPrototype() {
16951
16997
  const existing = this.meta()?.examples ?? [];
16952
16998
  return this.meta({ examples: [...existing, value] });
16953
16999
  };
17000
+ proto.required = function required() {
17001
+ return this.nonoptional();
17002
+ };
16954
17003
  proto.shared = function shared() {
16955
17004
  return this.meta({ frShared: true });
16956
17005
  };
@@ -18221,10 +18270,11 @@ var OAuth2 = class {
18221
18270
  this.#registerSystemMethods();
18222
18271
  }
18223
18272
  // The handler bag's `oauth`: the header access token, plus its deserialized composite payload when the
18224
- // author declared a deserializer (the pattern for providers whose "token" carries a realm or instance id).
18273
+ // author declared a deserializer (the pattern for providers whose "token" carries a realm or instance id),
18274
+ // and that payload's `userData` — the standard shape's slot for per-connection data.
18225
18275
  buildBag(accessToken) {
18226
18276
  const token = this.props.deserializeToken && accessToken != null ? this.props.deserializeToken(accessToken) : void 0;
18227
- return { accessToken, token };
18277
+ return { accessToken, token, userData: userDataOf(token) };
18228
18278
  }
18229
18279
  // ── SYSTEM seam: name · input · return · handler, in one table ─────────────
18230
18280
  #registerSystemMethods() {
@@ -18312,12 +18362,23 @@ var OAuth2 = class {
18312
18362
  });
18313
18363
  const nextRefresh = tokenResponse.refresh_token ?? currentRefreshToken;
18314
18364
  return {
18315
- token: this.#serialize(tokenResponse.access_token, nextRefresh),
18365
+ token: this.#serialize(tokenResponse.access_token, nextRefresh, this.#storedUserData(ctx)),
18316
18366
  expirationInSeconds: tokenResponse.expires_in,
18317
18367
  refreshToken: nextRefresh
18318
18368
  };
18319
18369
  }
18320
18370
  // ── token exchange ─────────────────────────────────────────────────────────
18371
+ // A refresh response repeats none of the connect-time data, and the platform keeps the connection's
18372
+ // `userData` to itself, so the only copy is inside the current token: read it back, to store it again in
18373
+ // the next one. A token the deserializer cannot read — a bare one saved before the service wrapped its
18374
+ // tokens — has nothing to carry over, and must not fail the refresh for that.
18375
+ #storedUserData(ctx) {
18376
+ try {
18377
+ return ctx.oauth.userData;
18378
+ } catch {
18379
+ return void 0;
18380
+ }
18381
+ }
18321
18382
  #serialize(accessToken, refreshToken, userData) {
18322
18383
  return this.props.serializeToken ? this.props.serializeToken({ accessToken, refreshToken, userData }) : accessToken;
18323
18384
  }
@@ -18342,6 +18403,9 @@ var OAuth2 = class {
18342
18403
  return Flowrunner.Request.post(this.props.tokenUrl).set(headers).send(params.toString());
18343
18404
  }
18344
18405
  };
18406
+ function userDataOf(token) {
18407
+ return token && typeof token === "object" ? token.userData : void 0;
18408
+ }
18345
18409
 
18346
18410
  // ../../flow-extension-runner/src/v2/polling-triggers/method-names.ts
18347
18411
  var POLLING_SYSTEM_METHOD = "handleTriggerPollingForEvent";
@@ -18654,11 +18718,14 @@ var RealtimeSelectInvocationSchema = z2.looseObject({
18654
18718
 
18655
18719
  // ../../flow-extension-runner/src/v2/realtime-triggers/verify.ts
18656
18720
  function verifyDeclarative(verify, rawBody, headers, config, webhookData) {
18721
+ const secret = verify.secret(config, { webhookData });
18722
+ if (!secret) {
18723
+ return true;
18724
+ }
18657
18725
  const provided = headers[verify.header] ?? headers[verify.header.toLowerCase()];
18658
18726
  if (!provided) {
18659
18727
  return false;
18660
18728
  }
18661
- const secret = verify.secret(config, { webhookData });
18662
18729
  const computed = Flowrunner.crypto.hmac(verify.algo, secret, rawBody ?? "", verify.encoding);
18663
18730
  if (!Flowrunner.crypto.timingSafeEqual(provided, computed)) {
18664
18731
  return false;
@@ -18735,12 +18802,32 @@ var RealtimeSetup = class {
18735
18802
  webhookData: invocation.webhookData ?? null,
18736
18803
  connectionId: invocation.connectionId
18737
18804
  }));
18805
+ this.#warnOnSuspectScope(result?.eventScopeId, ctx);
18738
18806
  return {
18739
18807
  webhookData: result?.webhookData,
18740
18808
  eventScopeId: result?.eventScopeId,
18741
18809
  refreshIntervalInSeconds: result?.refreshIntervalInSeconds
18742
18810
  };
18743
18811
  }
18812
+ // On ALL_APPS the platform routes every delivery of the shared callback by `eventScopeId`, so it has to name
18813
+ // the customer's tenant. A missing one leaves the app unroutable; the extension's own id or name is the
18814
+ // constant an author most often reaches for, and it puts every customer on one routing key. Neither is
18815
+ // refused — a warning, because a value equal to the name could in principle be a real tenant id.
18816
+ #warnOnSuspectScope(eventScopeId, ctx) {
18817
+ if (this.props.scope !== "ALL_APPS") {
18818
+ return;
18819
+ }
18820
+ const { id, name } = this.extension.props;
18821
+ if (eventScopeId == null || eventScopeId === "") {
18822
+ ctx.logger.warn(
18823
+ `[flow-extension:${id}] ALL_APPS subscribe returned no eventScopeId \u2014 deliveries on the shared callback cannot be routed to this app`
18824
+ );
18825
+ } else if (eventScopeId === id || eventScopeId === name) {
18826
+ ctx.logger.warn(
18827
+ `[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`
18828
+ );
18829
+ }
18830
+ }
18744
18831
  async #unsubscribe(invocation, ctx) {
18745
18832
  const result = await this.props.unsubscribe(ctx.bagWith({
18746
18833
  callbackUrl: invocation.callbackUrl,
@@ -18801,8 +18888,9 @@ var RealtimeSetup = class {
18801
18888
  const headers = invocation.headers ?? {};
18802
18889
  const body = invocation.body;
18803
18890
  const rawBody = invocation.rawBody;
18891
+ const query = invocation.queryParams ?? {};
18804
18892
  const webhookData = invocation.webhookData ?? null;
18805
- const handshake = await this.#handshake(body, headers, rawBody, webhookData, ctx);
18893
+ const handshake = await this.#handshake(body, headers, query, rawBody, webhookData, ctx);
18806
18894
  if (handshake) {
18807
18895
  return handshake;
18808
18896
  }
@@ -18814,7 +18902,7 @@ var RealtimeSetup = class {
18814
18902
  const result = await this.props.resolveEvents(ctx.bagWith({
18815
18903
  rawBody,
18816
18904
  headers,
18817
- query: invocation.queryParams ?? {},
18905
+ query,
18818
18906
  body,
18819
18907
  webhookData,
18820
18908
  connectionId: invocation.connectionId
@@ -18863,13 +18951,13 @@ var RealtimeSetup = class {
18863
18951
  * pod as a failed invocation and the provider receives a 500 telling it nothing. The hook runs BEFORE
18864
18952
  * verification, so the message reaches an unverified caller — throw what the provider may read.
18865
18953
  */
18866
- async #handshake(body, headers, rawBody, webhookData, ctx) {
18954
+ async #handshake(body, headers, query, rawBody, webhookData, ctx) {
18867
18955
  if (!this.props.handshake) {
18868
18956
  return isEmptyBody(body) ? { handshake: true, events: [] } : null;
18869
18957
  }
18870
18958
  let result;
18871
18959
  try {
18872
- result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, rawBody, webhookData }));
18960
+ result = await this.props.handshake(ctx.bagWith({ requestBody: body, headers, query, rawBody, webhookData }));
18873
18961
  } catch (error) {
18874
18962
  const message = error?.message ?? String(error);
18875
18963
  ctx.logger.error(`[flow-extension:${this.extension.id}] handshake failed \u2014 ${message}`);