@flowrunner/cli 0.1.0

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 (460) hide show
  1. package/README.md +148 -0
  2. package/ai-docs/instructions/service-code-format/01-service-structure.md +180 -0
  3. package/ai-docs/instructions/service-code-format/02-zod-types.md +260 -0
  4. package/ai-docs/instructions/service-code-format/03-parameters.md +193 -0
  5. package/ai-docs/instructions/service-code-format/04-http-requests.md +257 -0
  6. package/ai-docs/instructions/service-code-format/05-dictionaries.md +103 -0
  7. package/ai-docs/instructions/service-code-format/06-oauth2.md +42 -0
  8. package/ai-docs/instructions/service-code-format/07-actions.md +171 -0
  9. package/ai-docs/instructions/service-code-format/08-polling-triggers.md +54 -0
  10. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +269 -0
  11. package/ai-docs/instructions/service-code-format/10-files-api.md +148 -0
  12. package/ai-docs/instructions/service-code-format/11-output-model.md +142 -0
  13. package/ai-docs/instructions/service-code-format/12-service-readme.md +69 -0
  14. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +193 -0
  15. package/ai-docs/instructions/service-code-format/14-reference-service.md +341 -0
  16. package/ai-docs/instructions/service-code-format/15-unit-tests.md +361 -0
  17. package/ai-docs/instructions/service-code-format/16-gotchas.md +201 -0
  18. package/ai-docs/instructions/service-code-format/17-client-certificates.md +162 -0
  19. package/ai-docs/instructions/service-code-format/18-test-recipes.md +160 -0
  20. package/ai-docs/instructions/service-code-format/README.md +120 -0
  21. package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +139 -0
  22. package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +497 -0
  23. package/ai-docs/providers/claude/main-orchestrator-segment.md +51 -0
  24. package/bin/flowrunner.js +66 -0
  25. package/bin/resolve-local.js +98 -0
  26. package/dist/cli.js +10972 -0
  27. package/dist/cli.js.map +7 -0
  28. package/dist/index.d.ts +2 -0
  29. package/dist/index.js +10131 -0
  30. package/dist/index.js.map +7 -0
  31. package/dist/types/flow-extension-runner/src/common/config.d.ts +12 -0
  32. package/dist/types/flow-extension-runner/src/common/constants.d.ts +9 -0
  33. package/dist/types/flow-extension-runner/src/common/context-files.d.ts +107 -0
  34. package/dist/types/flow-extension-runner/src/common/context.d.ts +6 -0
  35. package/dist/types/flow-extension-runner/src/common/types.d.ts +11 -0
  36. package/dist/types/flow-extension-runner/src/errors/base.d.ts +17 -0
  37. package/dist/types/flow-extension-runner/src/errors/codes.d.ts +17 -0
  38. package/dist/types/flow-extension-runner/src/errors/errors.d.ts +48 -0
  39. package/dist/types/flow-extension-runner/src/errors/index.d.ts +3 -0
  40. package/dist/types/flow-extension-runner/src/global.d.ts +34 -0
  41. package/dist/types/flow-extension-runner/src/index.d.ts +15 -0
  42. package/dist/types/flow-extension-runner/src/namespace.d.ts +3 -0
  43. package/dist/types/flow-extension-runner/src/v1/config.d.ts +3 -0
  44. package/dist/types/flow-extension-runner/src/v1/constants.d.ts +4 -0
  45. package/dist/types/flow-extension-runner/src/v1/index.d.ts +11 -0
  46. package/dist/types/flow-extension-runner/src/v1/namespace.d.ts +9 -0
  47. package/dist/types/flow-extension-runner/src/v1/service.d.ts +29 -0
  48. package/dist/types/flow-extension-runner/src/v1/types.d.ts +13 -0
  49. package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +34 -0
  50. package/dist/types/flow-extension-runner/src/v2/context/execution-context.d.ts +25 -0
  51. package/dist/types/flow-extension-runner/src/v2/context/logger.d.ts +2 -0
  52. package/dist/types/flow-extension-runner/src/v2/context/method-input.d.ts +27 -0
  53. package/dist/types/flow-extension-runner/src/v2/context/proxies.d.ts +1 -0
  54. package/dist/types/flow-extension-runner/src/v2/create-extension.d.ts +2 -0
  55. package/dist/types/flow-extension-runner/src/v2/crypto.d.ts +6 -0
  56. package/dist/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +24 -0
  57. package/dist/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +10 -0
  58. package/dist/types/flow-extension-runner/src/v2/extension.d.ts +51 -0
  59. package/dist/types/flow-extension-runner/src/v2/index.d.ts +39 -0
  60. package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +31 -0
  61. package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +17 -0
  62. package/dist/types/flow-extension-runner/src/v2/loaders/payload-schema.d.ts +3 -0
  63. package/dist/types/flow-extension-runner/src/v2/method.d.ts +22 -0
  64. package/dist/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +10 -0
  65. package/dist/types/flow-extension-runner/src/v2/model/method-model.d.ts +3 -0
  66. package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +70 -0
  67. package/dist/types/flow-extension-runner/src/v2/model/params-model.d.ts +16 -0
  68. package/dist/types/flow-extension-runner/src/v2/oauth/method-names.d.ts +5 -0
  69. package/dist/types/flow-extension-runner/src/v2/oauth/oauth2.d.ts +9 -0
  70. package/dist/types/flow-extension-runner/src/v2/oauth/system-params.d.ts +6 -0
  71. package/dist/types/flow-extension-runner/src/v2/oauth/types.d.ts +54 -0
  72. package/dist/types/flow-extension-runner/src/v2/params/config-params.d.ts +14 -0
  73. package/dist/types/flow-extension-runner/src/v2/params/files-options.d.ts +58 -0
  74. package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +19 -0
  75. package/dist/types/flow-extension-runner/src/v2/params/json/checks.d.ts +26 -0
  76. package/dist/types/flow-extension-runner/src/v2/params/json/decode.d.ts +24 -0
  77. package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +20 -0
  78. package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +86 -0
  79. package/dist/types/flow-extension-runner/src/v2/params/json/values.d.ts +5 -0
  80. package/dist/types/flow-extension-runner/src/v2/params/method-params.d.ts +17 -0
  81. package/dist/types/flow-extension-runner/src/v2/params/params.d.ts +26 -0
  82. package/dist/types/flow-extension-runner/src/v2/params/schema/assert-object-schema.d.ts +6 -0
  83. package/dist/types/flow-extension-runner/src/v2/params/schema/assert-supported-schema.d.ts +8 -0
  84. package/dist/types/flow-extension-runner/src/v2/params/schema/coerce.d.ts +54 -0
  85. package/dist/types/flow-extension-runner/src/v2/params/schema/dates.d.ts +40 -0
  86. package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +36 -0
  87. package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +33 -0
  88. package/dist/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +58 -0
  89. package/dist/types/flow-extension-runner/src/v2/params/schema/labels.d.ts +3 -0
  90. package/dist/types/flow-extension-runner/src/v2/params/schema/messages.d.ts +16 -0
  91. package/dist/types/flow-extension-runner/src/v2/params/schema/normalize.d.ts +8 -0
  92. package/dist/types/flow-extension-runner/src/v2/params/schema/parse.d.ts +7 -0
  93. package/dist/types/flow-extension-runner/src/v2/params/types.d.ts +29 -0
  94. package/dist/types/flow-extension-runner/src/v2/params/widget-types.d.ts +40 -0
  95. package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +86 -0
  96. package/dist/types/flow-extension-runner/src/v2/path.d.ts +1 -0
  97. package/dist/types/flow-extension-runner/src/v2/polling-triggers/mechanisms.d.ts +19 -0
  98. package/dist/types/flow-extension-runner/src/v2/polling-triggers/method-names.d.ts +1 -0
  99. package/dist/types/flow-extension-runner/src/v2/polling-triggers/polling-triggers.d.ts +11 -0
  100. package/dist/types/flow-extension-runner/src/v2/polling-triggers/system-params.d.ts +7 -0
  101. package/dist/types/flow-extension-runner/src/v2/polling-triggers/trigger-method.d.ts +25 -0
  102. package/dist/types/flow-extension-runner/src/v2/polling-triggers/types.d.ts +46 -0
  103. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/method-names.d.ts +7 -0
  104. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/realtime-setup.d.ts +10 -0
  105. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +29 -0
  106. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +33 -0
  107. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +147 -0
  108. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +2 -0
  109. package/dist/types/flow-extension-runner/src/v2/registry.d.ts +20 -0
  110. package/dist/types/flow-extension-runner/src/v2/result.d.ts +13 -0
  111. package/dist/types/flow-extension-runner/src/v2/system-method.d.ts +41 -0
  112. package/dist/types/flow-extension-runner/src/v2/types.d.ts +126 -0
  113. package/dist/types/jsdoc-parser/src/custom-type-defs/files.d.ts +2 -0
  114. package/dist/types/jsdoc-parser/src/index.d.ts +2 -0
  115. package/dist/types/jsdoc-parser/src/lib.d.ts +42 -0
  116. package/dist/types/jsdoc-parser/src/types.d.ts +2 -0
  117. package/dist/types/packages/cli/src/api/console-client.d.ts +69 -0
  118. package/dist/types/packages/cli/src/constants/index.d.ts +5 -0
  119. package/dist/types/packages/cli/src/constants/packaging.d.ts +7 -0
  120. package/dist/types/packages/cli/src/constants/project.d.ts +9 -0
  121. package/dist/types/packages/cli/src/constants/providers.d.ts +30 -0
  122. package/dist/types/packages/cli/src/constants/server.d.ts +29 -0
  123. package/dist/types/packages/cli/src/constants/testing.d.ts +32 -0
  124. package/dist/types/packages/cli/src/errors.d.ts +131 -0
  125. package/dist/types/packages/cli/src/index.d.ts +29 -0
  126. package/dist/types/packages/cli/src/operations/deploy/discover-services.d.ts +26 -0
  127. package/dist/types/packages/cli/src/operations/deploy/hash.d.ts +1 -0
  128. package/dist/types/packages/cli/src/operations/deploy/index.d.ts +94 -0
  129. package/dist/types/packages/cli/src/operations/deploy/public-files.d.ts +20 -0
  130. package/dist/types/packages/cli/src/operations/deploy/select.d.ts +9 -0
  131. package/dist/types/packages/cli/src/operations/deploy/zip.d.ts +1 -0
  132. package/dist/types/packages/cli/src/operations/init/answers.d.ts +35 -0
  133. package/dist/types/packages/cli/src/operations/init/create-service.d.ts +39 -0
  134. package/dist/types/packages/cli/src/operations/init/index.d.ts +79 -0
  135. package/dist/types/packages/cli/src/operations/init/testing.d.ts +13 -0
  136. package/dist/types/packages/cli/src/operations/init-claude/index.d.ts +40 -0
  137. package/dist/types/packages/cli/src/operations/init-claude/segment.d.ts +25 -0
  138. package/dist/types/packages/cli/src/operations/login.d.ts +38 -0
  139. package/dist/types/packages/cli/src/operations/logout.d.ts +19 -0
  140. package/dist/types/packages/cli/src/operations/pull/extract.d.ts +23 -0
  141. package/dist/types/packages/cli/src/operations/pull/index.d.ts +87 -0
  142. package/dist/types/packages/cli/src/operations/server-target.d.ts +14 -0
  143. package/dist/types/packages/cli/src/operations/types.d.ts +20 -0
  144. package/dist/types/packages/cli/src/operations/use-server.d.ts +17 -0
  145. package/dist/types/packages/cli/src/project/auth.d.ts +41 -0
  146. package/dist/types/packages/cli/src/project/config.d.ts +31 -0
  147. package/dist/types/packages/cli/src/project/token.d.ts +5 -0
  148. package/dist/types/packages/cli/src/server/index.d.ts +14 -0
  149. package/dist/types/packages/cli/src/server/pages.d.ts +2 -0
  150. package/dist/types/packages/cli/src/server/routes/callback.d.ts +6 -0
  151. package/dist/types/packages/cli/src/server/types.d.ts +12 -0
  152. package/dist/types/packages/cli/src/templates/index.d.ts +8 -0
  153. package/dist/types/packages/cli/src/templates/manifest.d.ts +97 -0
  154. package/dist/types/packages/cli/src/templates/package-root.d.ts +3 -0
  155. package/dist/types/packages/cli/src/templates/paths.d.ts +3 -0
  156. package/dist/types/packages/cli/src/templates/registry.d.ts +13 -0
  157. package/dist/types/packages/cli/src/templates/render.d.ts +13 -0
  158. package/dist/types/packages/cli/src/templates/scaffold.d.ts +25 -0
  159. package/dist/types/packages/cli/src/utils/invocation.d.ts +28 -0
  160. package/dist/types/packages/cli/src/utils/open-browser.d.ts +2 -0
  161. package/dist/types/shared/src/constants/ai-agent-tools.d.ts +20 -0
  162. package/dist/types/shared/src/constants/ai.d.ts +11 -0
  163. package/dist/types/shared/src/constants/api-keys.d.ts +1 -0
  164. package/dist/types/shared/src/constants/app.d.ts +58 -0
  165. package/dist/types/shared/src/constants/billing.d.ts +16 -0
  166. package/dist/types/shared/src/constants/compliances.d.ts +3 -0
  167. package/dist/types/shared/src/constants/data-types.d.ts +26 -0
  168. package/dist/types/shared/src/constants/error-codes.d.ts +16 -0
  169. package/dist/types/shared/src/constants/flow.d.ts +12 -0
  170. package/dist/types/shared/src/constants/index.d.ts +16 -0
  171. package/dist/types/shared/src/constants/knowledge-base.d.ts +13 -0
  172. package/dist/types/shared/src/constants/notification-types.d.ts +985 -0
  173. package/dist/types/shared/src/constants/notifications.d.ts +10 -0
  174. package/dist/types/shared/src/constants/patterns.d.ts +28 -0
  175. package/dist/types/shared/src/constants/retry-policy.d.ts +30 -0
  176. package/dist/types/shared/src/constants/severity.d.ts +9 -0
  177. package/dist/types/shared/src/constants/shared-extensions-search.d.ts +6 -0
  178. package/dist/types/shared/src/constants/shared-extensions.d.ts +35 -0
  179. package/dist/types/shared/src/constants/zod.d.ts +2 -0
  180. package/dist/types/shared/src/errors/api.d.ts +4 -0
  181. package/dist/types/shared/src/errors/base.d.ts +38 -0
  182. package/dist/types/shared/src/errors/common.d.ts +39 -0
  183. package/dist/types/shared/src/errors/index.d.ts +13 -0
  184. package/dist/types/shared/src/errors/k8s.d.ts +4 -0
  185. package/dist/types/shared/src/errors/message.d.ts +48 -0
  186. package/dist/types/shared/src/errors/open-search.d.ts +4 -0
  187. package/dist/types/shared/src/errors/s3.d.ts +11 -0
  188. package/dist/types/shared/src/extensions/zod.d.ts +25 -0
  189. package/dist/types/shared/src/scheme/account/dto.d.ts +60 -0
  190. package/dist/types/shared/src/scheme/account/index.d.ts +1 -0
  191. package/dist/types/shared/src/scheme/ai-agent-tools/dto.d.ts +69 -0
  192. package/dist/types/shared/src/scheme/ai-agent-tools/index.d.ts +2 -0
  193. package/dist/types/shared/src/scheme/ai-agent-tools/parameters.d.ts +7 -0
  194. package/dist/types/shared/src/scheme/ai-router/dto.d.ts +23 -0
  195. package/dist/types/shared/src/scheme/ai-router/index.d.ts +2 -0
  196. package/dist/types/shared/src/scheme/api-keys/dto.d.ts +28 -0
  197. package/dist/types/shared/src/scheme/api-keys/index.d.ts +2 -0
  198. package/dist/types/shared/src/scheme/app/index.d.ts +1 -0
  199. package/dist/types/shared/src/scheme/app/java.dto.d.ts +6 -0
  200. package/dist/types/shared/src/scheme/billing/index.d.ts +1 -0
  201. package/dist/types/shared/src/scheme/billing/java.dto.d.ts +163 -0
  202. package/dist/types/shared/src/scheme/crm/billing.d.ts +149 -0
  203. package/dist/types/shared/src/scheme/crm/dto.d.ts +212 -0
  204. package/dist/types/shared/src/scheme/crm/index.d.ts +3 -0
  205. package/dist/types/shared/src/scheme/data-types/index.d.ts +1 -0
  206. package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +23 -0
  207. package/dist/types/shared/src/scheme/dynamic-forms/dto.d.ts +30 -0
  208. package/dist/types/shared/src/scheme/dynamic-forms/index.d.ts +2 -0
  209. package/dist/types/shared/src/scheme/extensions/index.d.ts +1 -0
  210. package/dist/types/shared/src/scheme/extensions/params-to-zod.d.ts +14 -0
  211. package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +368 -0
  212. package/dist/types/shared/src/scheme/flowrunner/index.d.ts +3 -0
  213. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +628 -0
  214. package/dist/types/shared/src/scheme/index.d.ts +19 -0
  215. package/dist/types/shared/src/scheme/integration-connection/dto.d.ts +81 -0
  216. package/dist/types/shared/src/scheme/integration-connection/index.d.ts +2 -0
  217. package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +540 -0
  218. package/dist/types/shared/src/scheme/knowledge-base/index.d.ts +2 -0
  219. package/dist/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -0
  220. package/dist/types/shared/src/scheme/mcp-oauth/index.d.ts +2 -0
  221. package/dist/types/shared/src/scheme/notifications/dto.d.ts +111 -0
  222. package/dist/types/shared/src/scheme/notifications/index.d.ts +3 -0
  223. package/dist/types/shared/src/scheme/notifications/rest.d.ts +148 -0
  224. package/dist/types/shared/src/scheme/properties/account.d.ts +3 -0
  225. package/dist/types/shared/src/scheme/properties/app.d.ts +5 -0
  226. package/dist/types/shared/src/scheme/properties/billing.d.ts +12 -0
  227. package/dist/types/shared/src/scheme/properties/common.d.ts +2 -0
  228. package/dist/types/shared/src/scheme/properties/db.d.ts +8 -0
  229. package/dist/types/shared/src/scheme/properties/flow-extensions.d.ts +7 -0
  230. package/dist/types/shared/src/scheme/properties/index.d.ts +7 -0
  231. package/dist/types/shared/src/scheme/remote-mcp-server/dto.d.ts +278 -0
  232. package/dist/types/shared/src/scheme/remote-mcp-server/index.d.ts +2 -0
  233. package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +56 -0
  234. package/dist/types/shared/src/scheme/shared-extensions/config.d.ts +96 -0
  235. package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +485 -0
  236. package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +387 -0
  237. package/dist/types/shared/src/scheme/shared-extensions/flow-extensions.d.ts +64 -0
  238. package/dist/types/shared/src/scheme/shared-extensions/index.d.ts +15 -0
  239. package/dist/types/shared/src/scheme/shared-extensions/light.d.ts +38 -0
  240. package/dist/types/shared/src/scheme/shared-extensions/logs.d.ts +21 -0
  241. package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +80 -0
  242. package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +47 -0
  243. package/dist/types/shared/src/scheme/shared-extensions/popular-pool.d.ts +11 -0
  244. package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +364 -0
  245. package/dist/types/shared/src/scheme/shared-extensions/rest.d.ts +9 -0
  246. package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +177 -0
  247. package/dist/types/shared/src/scheme/shared-extensions/service-identity.d.ts +10 -0
  248. package/dist/types/shared/src/scheme/shared-extensions/service-info.d.ts +15 -0
  249. package/dist/types/shared/src/scheme/workspace/dto.d.ts +40 -0
  250. package/dist/types/shared/src/scheme/workspace/index.d.ts +1 -0
  251. package/dist/types/shared/src/utils/object.d.ts +8 -0
  252. package/dist/types/shared/src/utils/uuid.d.ts +5 -0
  253. package/dist/types/shared/src/utils/versions.d.ts +4 -0
  254. package/dist/types/types/backendless-request.d.ts +40 -0
  255. package/package.json +66 -0
  256. package/project-files/jest.config.js +38 -0
  257. package/project-files/jest.setup.js +24 -0
  258. package/project-files/sandbox/files-mock.js +654 -0
  259. package/project-files/sandbox/index.js +32 -0
  260. package/project-files/sandbox/nock-mock.js +600 -0
  261. package/project-files/sandbox/service.js +145 -0
  262. package/runtime/index.d.ts +2 -0
  263. package/runtime/index.js +5665 -0
  264. package/runtime/index.js.map +7 -0
  265. package/runtime/types/flow-extension-runner/src/common/config.d.ts +12 -0
  266. package/runtime/types/flow-extension-runner/src/common/constants.d.ts +9 -0
  267. package/runtime/types/flow-extension-runner/src/common/context-files.d.ts +107 -0
  268. package/runtime/types/flow-extension-runner/src/common/context.d.ts +6 -0
  269. package/runtime/types/flow-extension-runner/src/common/types.d.ts +11 -0
  270. package/runtime/types/flow-extension-runner/src/errors/base.d.ts +17 -0
  271. package/runtime/types/flow-extension-runner/src/errors/codes.d.ts +17 -0
  272. package/runtime/types/flow-extension-runner/src/errors/errors.d.ts +48 -0
  273. package/runtime/types/flow-extension-runner/src/errors/index.d.ts +3 -0
  274. package/runtime/types/flow-extension-runner/src/global.d.ts +34 -0
  275. package/runtime/types/flow-extension-runner/src/index.d.ts +15 -0
  276. package/runtime/types/flow-extension-runner/src/namespace.d.ts +3 -0
  277. package/runtime/types/flow-extension-runner/src/v1/config.d.ts +3 -0
  278. package/runtime/types/flow-extension-runner/src/v1/constants.d.ts +4 -0
  279. package/runtime/types/flow-extension-runner/src/v1/index.d.ts +11 -0
  280. package/runtime/types/flow-extension-runner/src/v1/namespace.d.ts +9 -0
  281. package/runtime/types/flow-extension-runner/src/v1/service.d.ts +29 -0
  282. package/runtime/types/flow-extension-runner/src/v1/types.d.ts +13 -0
  283. package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +34 -0
  284. package/runtime/types/flow-extension-runner/src/v2/context/execution-context.d.ts +25 -0
  285. package/runtime/types/flow-extension-runner/src/v2/context/logger.d.ts +2 -0
  286. package/runtime/types/flow-extension-runner/src/v2/context/method-input.d.ts +27 -0
  287. package/runtime/types/flow-extension-runner/src/v2/context/proxies.d.ts +1 -0
  288. package/runtime/types/flow-extension-runner/src/v2/create-extension.d.ts +2 -0
  289. package/runtime/types/flow-extension-runner/src/v2/crypto.d.ts +6 -0
  290. package/runtime/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +24 -0
  291. package/runtime/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +10 -0
  292. package/runtime/types/flow-extension-runner/src/v2/extension.d.ts +51 -0
  293. package/runtime/types/flow-extension-runner/src/v2/index.d.ts +39 -0
  294. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +31 -0
  295. package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +17 -0
  296. package/runtime/types/flow-extension-runner/src/v2/loaders/payload-schema.d.ts +3 -0
  297. package/runtime/types/flow-extension-runner/src/v2/method.d.ts +22 -0
  298. package/runtime/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +10 -0
  299. package/runtime/types/flow-extension-runner/src/v2/model/method-model.d.ts +3 -0
  300. package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +70 -0
  301. package/runtime/types/flow-extension-runner/src/v2/model/params-model.d.ts +16 -0
  302. package/runtime/types/flow-extension-runner/src/v2/oauth/method-names.d.ts +5 -0
  303. package/runtime/types/flow-extension-runner/src/v2/oauth/oauth2.d.ts +9 -0
  304. package/runtime/types/flow-extension-runner/src/v2/oauth/system-params.d.ts +6 -0
  305. package/runtime/types/flow-extension-runner/src/v2/oauth/types.d.ts +54 -0
  306. package/runtime/types/flow-extension-runner/src/v2/params/config-params.d.ts +14 -0
  307. package/runtime/types/flow-extension-runner/src/v2/params/files-options.d.ts +58 -0
  308. package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +19 -0
  309. package/runtime/types/flow-extension-runner/src/v2/params/json/checks.d.ts +26 -0
  310. package/runtime/types/flow-extension-runner/src/v2/params/json/decode.d.ts +24 -0
  311. package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +20 -0
  312. package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +86 -0
  313. package/runtime/types/flow-extension-runner/src/v2/params/json/values.d.ts +5 -0
  314. package/runtime/types/flow-extension-runner/src/v2/params/method-params.d.ts +17 -0
  315. package/runtime/types/flow-extension-runner/src/v2/params/params.d.ts +26 -0
  316. package/runtime/types/flow-extension-runner/src/v2/params/schema/assert-object-schema.d.ts +6 -0
  317. package/runtime/types/flow-extension-runner/src/v2/params/schema/assert-supported-schema.d.ts +8 -0
  318. package/runtime/types/flow-extension-runner/src/v2/params/schema/coerce.d.ts +54 -0
  319. package/runtime/types/flow-extension-runner/src/v2/params/schema/dates.d.ts +40 -0
  320. package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +36 -0
  321. package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +33 -0
  322. package/runtime/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +58 -0
  323. package/runtime/types/flow-extension-runner/src/v2/params/schema/labels.d.ts +3 -0
  324. package/runtime/types/flow-extension-runner/src/v2/params/schema/messages.d.ts +16 -0
  325. package/runtime/types/flow-extension-runner/src/v2/params/schema/normalize.d.ts +8 -0
  326. package/runtime/types/flow-extension-runner/src/v2/params/schema/parse.d.ts +7 -0
  327. package/runtime/types/flow-extension-runner/src/v2/params/types.d.ts +29 -0
  328. package/runtime/types/flow-extension-runner/src/v2/params/widget-types.d.ts +40 -0
  329. package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +86 -0
  330. package/runtime/types/flow-extension-runner/src/v2/path.d.ts +1 -0
  331. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/mechanisms.d.ts +19 -0
  332. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/method-names.d.ts +1 -0
  333. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/polling-triggers.d.ts +11 -0
  334. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/system-params.d.ts +7 -0
  335. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/trigger-method.d.ts +25 -0
  336. package/runtime/types/flow-extension-runner/src/v2/polling-triggers/types.d.ts +46 -0
  337. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/method-names.d.ts +7 -0
  338. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/realtime-setup.d.ts +10 -0
  339. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +29 -0
  340. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +33 -0
  341. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +147 -0
  342. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +2 -0
  343. package/runtime/types/flow-extension-runner/src/v2/registry.d.ts +20 -0
  344. package/runtime/types/flow-extension-runner/src/v2/result.d.ts +13 -0
  345. package/runtime/types/flow-extension-runner/src/v2/system-method.d.ts +41 -0
  346. package/runtime/types/flow-extension-runner/src/v2/types.d.ts +126 -0
  347. package/runtime/types/jsdoc-parser/src/custom-type-defs/files.d.ts +2 -0
  348. package/runtime/types/jsdoc-parser/src/index.d.ts +2 -0
  349. package/runtime/types/jsdoc-parser/src/lib.d.ts +42 -0
  350. package/runtime/types/jsdoc-parser/src/types.d.ts +2 -0
  351. package/runtime/types/packages/cli/src/runtime/index.d.ts +5 -0
  352. package/runtime/types/shared/src/constants/ai-agent-tools.d.ts +20 -0
  353. package/runtime/types/shared/src/constants/ai.d.ts +11 -0
  354. package/runtime/types/shared/src/constants/api-keys.d.ts +1 -0
  355. package/runtime/types/shared/src/constants/app.d.ts +58 -0
  356. package/runtime/types/shared/src/constants/billing.d.ts +16 -0
  357. package/runtime/types/shared/src/constants/compliances.d.ts +3 -0
  358. package/runtime/types/shared/src/constants/data-types.d.ts +26 -0
  359. package/runtime/types/shared/src/constants/error-codes.d.ts +16 -0
  360. package/runtime/types/shared/src/constants/flow.d.ts +12 -0
  361. package/runtime/types/shared/src/constants/index.d.ts +16 -0
  362. package/runtime/types/shared/src/constants/knowledge-base.d.ts +13 -0
  363. package/runtime/types/shared/src/constants/notification-types.d.ts +985 -0
  364. package/runtime/types/shared/src/constants/notifications.d.ts +10 -0
  365. package/runtime/types/shared/src/constants/patterns.d.ts +28 -0
  366. package/runtime/types/shared/src/constants/retry-policy.d.ts +30 -0
  367. package/runtime/types/shared/src/constants/severity.d.ts +9 -0
  368. package/runtime/types/shared/src/constants/shared-extensions-search.d.ts +6 -0
  369. package/runtime/types/shared/src/constants/shared-extensions.d.ts +35 -0
  370. package/runtime/types/shared/src/constants/zod.d.ts +2 -0
  371. package/runtime/types/shared/src/errors/api.d.ts +4 -0
  372. package/runtime/types/shared/src/errors/base.d.ts +38 -0
  373. package/runtime/types/shared/src/errors/common.d.ts +39 -0
  374. package/runtime/types/shared/src/errors/index.d.ts +13 -0
  375. package/runtime/types/shared/src/errors/k8s.d.ts +4 -0
  376. package/runtime/types/shared/src/errors/message.d.ts +48 -0
  377. package/runtime/types/shared/src/errors/open-search.d.ts +4 -0
  378. package/runtime/types/shared/src/errors/s3.d.ts +11 -0
  379. package/runtime/types/shared/src/extensions/zod.d.ts +25 -0
  380. package/runtime/types/shared/src/scheme/account/dto.d.ts +60 -0
  381. package/runtime/types/shared/src/scheme/account/index.d.ts +1 -0
  382. package/runtime/types/shared/src/scheme/ai-agent-tools/dto.d.ts +69 -0
  383. package/runtime/types/shared/src/scheme/ai-agent-tools/index.d.ts +2 -0
  384. package/runtime/types/shared/src/scheme/ai-agent-tools/parameters.d.ts +7 -0
  385. package/runtime/types/shared/src/scheme/ai-router/dto.d.ts +23 -0
  386. package/runtime/types/shared/src/scheme/ai-router/index.d.ts +2 -0
  387. package/runtime/types/shared/src/scheme/api-keys/dto.d.ts +28 -0
  388. package/runtime/types/shared/src/scheme/api-keys/index.d.ts +2 -0
  389. package/runtime/types/shared/src/scheme/app/index.d.ts +1 -0
  390. package/runtime/types/shared/src/scheme/app/java.dto.d.ts +6 -0
  391. package/runtime/types/shared/src/scheme/billing/index.d.ts +1 -0
  392. package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +163 -0
  393. package/runtime/types/shared/src/scheme/crm/billing.d.ts +149 -0
  394. package/runtime/types/shared/src/scheme/crm/dto.d.ts +212 -0
  395. package/runtime/types/shared/src/scheme/crm/index.d.ts +3 -0
  396. package/runtime/types/shared/src/scheme/data-types/index.d.ts +1 -0
  397. package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +23 -0
  398. package/runtime/types/shared/src/scheme/dynamic-forms/dto.d.ts +30 -0
  399. package/runtime/types/shared/src/scheme/dynamic-forms/index.d.ts +2 -0
  400. package/runtime/types/shared/src/scheme/extensions/index.d.ts +1 -0
  401. package/runtime/types/shared/src/scheme/extensions/params-to-zod.d.ts +14 -0
  402. package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +368 -0
  403. package/runtime/types/shared/src/scheme/flowrunner/index.d.ts +3 -0
  404. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +628 -0
  405. package/runtime/types/shared/src/scheme/index.d.ts +19 -0
  406. package/runtime/types/shared/src/scheme/integration-connection/dto.d.ts +81 -0
  407. package/runtime/types/shared/src/scheme/integration-connection/index.d.ts +2 -0
  408. package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +540 -0
  409. package/runtime/types/shared/src/scheme/knowledge-base/index.d.ts +2 -0
  410. package/runtime/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -0
  411. package/runtime/types/shared/src/scheme/mcp-oauth/index.d.ts +2 -0
  412. package/runtime/types/shared/src/scheme/notifications/dto.d.ts +111 -0
  413. package/runtime/types/shared/src/scheme/notifications/index.d.ts +3 -0
  414. package/runtime/types/shared/src/scheme/notifications/rest.d.ts +148 -0
  415. package/runtime/types/shared/src/scheme/properties/account.d.ts +3 -0
  416. package/runtime/types/shared/src/scheme/properties/app.d.ts +5 -0
  417. package/runtime/types/shared/src/scheme/properties/billing.d.ts +12 -0
  418. package/runtime/types/shared/src/scheme/properties/common.d.ts +2 -0
  419. package/runtime/types/shared/src/scheme/properties/db.d.ts +8 -0
  420. package/runtime/types/shared/src/scheme/properties/flow-extensions.d.ts +7 -0
  421. package/runtime/types/shared/src/scheme/properties/index.d.ts +7 -0
  422. package/runtime/types/shared/src/scheme/remote-mcp-server/dto.d.ts +278 -0
  423. package/runtime/types/shared/src/scheme/remote-mcp-server/index.d.ts +2 -0
  424. package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +56 -0
  425. package/runtime/types/shared/src/scheme/shared-extensions/config.d.ts +96 -0
  426. package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +485 -0
  427. package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +387 -0
  428. package/runtime/types/shared/src/scheme/shared-extensions/flow-extensions.d.ts +64 -0
  429. package/runtime/types/shared/src/scheme/shared-extensions/index.d.ts +15 -0
  430. package/runtime/types/shared/src/scheme/shared-extensions/light.d.ts +38 -0
  431. package/runtime/types/shared/src/scheme/shared-extensions/logs.d.ts +21 -0
  432. package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +80 -0
  433. package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +47 -0
  434. package/runtime/types/shared/src/scheme/shared-extensions/popular-pool.d.ts +11 -0
  435. package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +364 -0
  436. package/runtime/types/shared/src/scheme/shared-extensions/rest.d.ts +9 -0
  437. package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +177 -0
  438. package/runtime/types/shared/src/scheme/shared-extensions/service-identity.d.ts +10 -0
  439. package/runtime/types/shared/src/scheme/shared-extensions/service-info.d.ts +15 -0
  440. package/runtime/types/shared/src/scheme/workspace/dto.d.ts +40 -0
  441. package/runtime/types/shared/src/scheme/workspace/index.d.ts +1 -0
  442. package/runtime/types/shared/src/utils/object.d.ts +8 -0
  443. package/runtime/types/shared/src/utils/uuid.d.ts +5 -0
  444. package/runtime/types/shared/src/utils/versions.d.ts +4 -0
  445. package/runtime/types/types/backendless-request.d.ts +40 -0
  446. package/templates/blank/files/README.md +28 -0
  447. package/templates/blank/files/package.json +8 -0
  448. package/templates/blank/files/public/icon.svg +5 -0
  449. package/templates/blank/files/src/index.js +130 -0
  450. package/templates/blank/template.json +61 -0
  451. package/templates/demo-todo-list/files/README.md +54 -0
  452. package/templates/demo-todo-list/files/package.json +8 -0
  453. package/templates/demo-todo-list/files/public/icon.svg +8 -0
  454. package/templates/demo-todo-list/files/src/index.js +590 -0
  455. package/templates/demo-todo-list/template.json +44 -0
  456. package/templates/qa-test/files/README.md +88 -0
  457. package/templates/qa-test/files/package.json +8 -0
  458. package/templates/qa-test/files/public/icon.svg +8 -0
  459. package/templates/qa-test/files/src/index.js +755 -0
  460. package/templates/qa-test/template.json +62 -0
@@ -0,0 +1,171 @@
1
+ # 07 — Actions & the Context Bag
2
+
3
+ Actions are the primary operations a service exposes. Register one with `ext.addAction(props)`.
4
+
5
+ | Property | Type | Req | Description |
6
+ |---|---|---|---|
7
+ | `category` | string | ✓ | Grouping label. |
8
+ | `id` | string | ✓ | Stable action id — persisted, never changes. |
9
+ | `label` | string | ✓ | Display name. |
10
+ | `description` | string | ✓ | Description. |
11
+ | `params` | `z.object` | – | Input params — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
12
+ | `dynamicParams` | object | – | Runtime-generated params (see [03-parameters.md](03-parameters.md)). |
13
+ | `result` | sample object | ✓ | A literal sample of what `execute` returns — see below. |
14
+ | `logo` / `appearanceColors` | – | – | Default to the extension's. |
15
+ | `oauth2Scopes` | string[] | – | Extra OAuth scopes (unioned). |
16
+ | `execute` | fn | ✓ | Handler; receives the ctx bag. |
17
+
18
+ ## Input validation
19
+
20
+ The runtime parses the incoming input against `params` **before** `execute` runs, so a handler can trust
21
+ what it receives: defaults are applied, values are coerced by the schema, and unknown fields are stripped
22
+ (an action with `dynamicParams` keeps them — its generated fields aren't in the static schema). A violation
23
+ rejects the call with `FR_EXT_INVALID_METHOD_INPUT` and the offending param paths; don't re-check required
24
+ params by hand inside `execute`. Declare optionality honestly — a `z.string()` that the flow may legitimately
25
+ leave empty must be `.optional()`.
26
+
27
+ **Not every slot is equally strict**, because not every slot has the same producer. Worth knowing so you
28
+ declare schemas that hold up in each:
29
+
30
+ | Slot | Strictness |
31
+ |---|---|
32
+ | Action `params`, SYSTEM invocations | **strict** — required fields enforced, unknown stripped. The flow engine produces these against the published model, so a violation is a real contract break |
33
+ | Dictionary `criteria` | **strict** — the console only calls a dictionary once its `dependsOn` fields are filled |
34
+ | Sample-result / dynamic-params loader `criteria` | **lenient** — the schema is relaxed so nothing is required, and unknown fields ride through. These fire on every keystroke while the form is half-filled |
35
+ | Polling trigger `params` | **lenient** — the runtime polls with whatever the instance was saved with; rejecting a poll would silently stop a live automation |
36
+
37
+ So a loader's `result` fn must tolerate partial criteria, and a trigger's `fetch`/`poll` must tolerate a
38
+ partially configured instance. Handlers reached through a strict slot need no such defence.
39
+
40
+ ## `result` — return the sample object
41
+
42
+ **`result` is a literal sample of what `execute` returns. Write the object, nothing else.**
43
+
44
+ ```js
45
+ result: {
46
+ message_id: 42,
47
+ date : 1714000000,
48
+ chat : { id: -1001234567890, type: 'supergroup', title: 'Team Standup' },
49
+ text : 'Hello',
50
+ },
51
+ ```
52
+
53
+ Do **not** declare a zod schema and then attach a sample to it. A schema here is a second description of the
54
+ same thing: it has to be kept in step with the handler by hand, it is not validated against what `execute`
55
+ actually returns, and the platform publishes only the sample from it anyway
56
+ ([11-output-model.md](11-output-model.md)). The object is the shorter, truer statement.
57
+
58
+ Two cases still justify something else:
59
+
60
+ - **A schema you genuinely reuse** — the same shape returned by several actions, declared once and
61
+ referenced. Use `z.object(...).example({...})` then, and only then; the value is the reuse, not the typing.
62
+ - **A loader** — `({ params, context, apiRequest }) => sample` — when the shape is not known until the flow
63
+ author has configured the action, because it comes from the user's own data.
64
+
65
+ Take the sample from a real response. An invented one drifts from the API and misleads every flow author who
66
+ builds against it.
67
+
68
+ ## `execute`
69
+
70
+ **Always use a block body with an explicit `return`.** A concise arrow returning an object literal reads as
71
+ a shape declaration rather than a call, and it is where responses get quietly reshaped:
72
+
73
+ ```js
74
+ execute: async ({ params, apiRequest }) => {
75
+ return apiRequest({ url: `/messages/${ params.messageId }`, method: 'delete' })
76
+ },
77
+ ```
78
+
79
+ ### Return the provider's response, do not narrow it
80
+
81
+ **An action returns what the API returned.** Extend it or rename fields when the vendor's shape is genuinely
82
+ unusable, but do not reduce a response to the part you happen to care about — every field you drop is one a
83
+ flow author cannot reach, and no amount of extra actions gives it back.
84
+
85
+ ```js
86
+ // ✗ throws the entire response away and answers with a boolean the API never sent
87
+ execute: async ({ params, apiRequest }) => {
88
+ return {
89
+ success: Boolean(await apiRequest({ url: '/deleteMessage', method: 'post', body: { … } })),
90
+ }
91
+ },
92
+
93
+ // ✓ hands back what the API said
94
+ execute: async ({ params, apiRequest }) => {
95
+ return apiRequest({ url: '/deleteMessage', method: 'post', body: { … } })
96
+ },
97
+ ```
98
+
99
+ The same applies to a list endpoint: return the items **and** the paging fields around them, not a bare
100
+ array. Adding a derived field is fine — spread the response and add to it — but the original fields stay.
101
+
102
+ ## `execute` context bag
103
+
104
+ The same bag is passed to actions, dictionaries, triggers, and result-loaders (accessed via arguments,
105
+ never `this`). Every key is typed — nothing in the bag is `unknown`, and the **Inferred as** column says
106
+ where each type comes from:
107
+
108
+ | Key | Inferred as | Description |
109
+ |---|---|---|
110
+ | `params` | `z.infer` of **this handler's own** `params` | Parsed input — defaults applied, values coerced, unknown fields stripped. `{}` when the method declares none. |
111
+ | `context` | return type of `initContext` | Whatever the factory built (see [01-service-structure.md](01-service-structure.md)). |
112
+ | `config` | `z.infer` of `configItems` | Resolved config values. |
113
+ | `oauth` | `{ accessToken?: string, token?: unknown }` | From the `oauth-access-token` header only; see [06-oauth2.md](06-oauth2.md). |
114
+ | `apiRequest` | your own `apiRequest`, minus `context` / `logger` | Shared HTTP helper — the runtime injects those two, so you never pass them (see [04-http-requests.md](04-http-requests.md)). |
115
+ | `files` | the file-service client | Present only when `usesFileStorage:true` (else a proxy that throws; see [10-files-api.md](10-files-api.md)). |
116
+ | `filesScope` | `{ WORKSPACE, FLOW, EXECUTION }` | The storage layers, so you name one instead of spelling the string. Always present, opt-in or not. |
117
+ | `logger` | `{ debug, info, warn, error }` | Runtime logger (no bare `console.log`). |
118
+ | `helpers` | return type of `helpers(ctx)` | Bound helpers (present when `createExtension({ helpers })`). |
119
+
120
+ ## Inferred types
121
+
122
+ You declare the schemas; the types follow. `createExtension` resolves `config` / `context` / `helpers` /
123
+ `apiRequest` **once** for the whole service, and each registrar infers its own `params` from the schema
124
+ sitting next to the handler — so two actions see two different `params` types, over the same `context`:
125
+
126
+ ```js
127
+ const ext = Flowrunner.createExtension({
128
+ configItems: z.object({ apiKey: z.string(), retries: z.number().optional() }),
129
+ initContext: ({ config }) => ({ base: `key:${config.apiKey}` }),
130
+ apiRequest : async ({ url, context }) => Flowrunner.Request.get(`${context.base}${url}`),
131
+ helpers : ({ apiRequest }) => ({ listAll: (url) => listAll(apiRequest, url) }),
132
+ })
133
+
134
+ ext.addAction({
135
+ // …
136
+ params : z.object({
137
+ name : z.string(),
138
+ count : z.number().optional().default(1),
139
+ mode : z.enum(['fast', 'slow']).optional(),
140
+ }),
141
+ execute: ({ params, context, config, helpers }) => {
142
+ params.name // string
143
+ params.count // number — a .default() means it is always there
144
+ params.mode // 'fast' | 'slow' | undefined
145
+ context.base // string — from initContext
146
+ config.apiKey // string
147
+ config.retries // number | undefined — .optional() with no default
148
+ params.nope // ✗ not a declared param
149
+
150
+ return helpers.listAll('/things')
151
+ },
152
+ })
153
+ ```
154
+
155
+ Optionality carries through exactly as declared: `.optional()` yields `T | undefined`, and adding
156
+ `.default(v)` removes the `undefined` because the runtime fills it in before `execute` runs.
157
+
158
+ The same inference reaches every other handler that owns a schema — a dictionary's `criteria`, a polling
159
+ trigger's `params` in `fetch` / `poll` / `watermark.by`, a realtime trigger's `params` in `providerEventName`
160
+ and `match`, and a loader `result` fn, which is typed by its owner's params.
161
+
162
+ **Payloads shaped by a third party stay open on purpose** — a webhook `requestBody`, a `providerEventData`,
163
+ a stored `webhookData`. The runtime cannot know their shape, and requiring a cast before every field read
164
+ would be noise, so they are left free to read into. Validate what matters before you trust it.
165
+
166
+ `oauth.token` is also open: `setupOauth2` runs after the service shape is resolved, so a
167
+ `deserializeToken` return can't flow back into the bag — annotate it at the point of use if it matters.
168
+
169
+ > **Editor support.** Services are plain `.js`, so these types show up as hover text and autocompletion via
170
+ > the global `Flowrunner` declaration; they are not reported as inline errors unless the project opts into
171
+ > checking JS. A service authored in TypeScript gets the same types as real compile errors.
@@ -0,0 +1,54 @@
1
+ # 08 — Polling Triggers
2
+
3
+ Register with `ext.addPollingTrigger(props)`. The runtime drives the loop (interval ≥ 30s, auto-noted in
4
+ the description), persists `state`, seeds on the first poll, and owns `handleTriggerPollingForEvent`.
5
+ Declare **exactly one** mechanism.
6
+
7
+ | Property | Type | Req | Description |
8
+ |---|---|---|---|
9
+ | `category`/`id`/`label`/`description` | string | ✓ | `id` is persisted and never changes. |
10
+ | `params` | `z.object` | – | Trigger config — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
11
+ | `result` | value \| schema \| loader | ✓ | Emitted item shape. |
12
+ | `fetch` | fn | – | Feeds `dedupe`/`watermark` (not used with `poll`). |
13
+ | `dedupe` \| `watermark` \| `poll` | see below | ✓ | Exactly one. |
14
+
15
+ | Function | Arguments | Returns |
16
+ |---|---|---|
17
+ | `fetch` | `{ params, isLearningMode, context, apiRequest, … }` | `items[]` |
18
+ | `poll` | `{ params, state, isLearningMode, context, apiRequest, … }` | `{ events, state }` |
19
+
20
+ ## Mechanisms
21
+
22
+ | Mechanism | Config | Runtime behavior |
23
+ |---|---|---|
24
+ | `dedupe` (seen-set) | `item => id` (or field path); or `{ by, stateKey='seen', max=500 }` | Keeps a bounded id set under `stateKey`; emits items whose id is new. Covers new-by-id + stateless-newest (head-only `fetch`). |
25
+ | `watermark` (marker) | `{ by, stateKey='watermark', sortedDesc? }` — `by` = field path or `(item,{params})=>value` | Stores newest marker, emits items past it, advances. `sortedDesc:true` early-breaks. Covers new-by-date + new-or-updated. |
26
+ | `poll` (escape hatch) | fn (above) | Full control; author owns `state` shape. Covers overlap-window+dedup, lag-held cursor, consuming/offset feeds. |
27
+
28
+ ## Lifecycle — `state` before → after \| emits
29
+
30
+ | Phase | `dedupe` | `watermark` | `poll` |
31
+ |---|---|---|---|
32
+ | start (no state) | `null → { seen:{…} }` \| `[]` (seed) | `null → { <marker> }` \| `[]` (seed) | `null → seeded` \| `[]` (seed yourself) |
33
+ | learningMode | `null → null` \| `[newest]` (reset) | `null → null` \| `[newest]` (reset) | `null → null` \| `[newest]` (reset) |
34
+ | timer | `{seen} → {seen+new}` \| `[new]` | `{marker} → {advanced}` \| `[past marker]` | yours → yours \| your delta |
35
+
36
+ `isLearningMode`: during setup the runtime calls `fetch`/`poll` with `isLearningMode:true`; return a real
37
+ (limited) sample; the runtime emits it and does **not** persist state. This is distinct from `result`
38
+ (which describes shape only).
39
+
40
+ ## One trigger per event
41
+
42
+ **Register a separate trigger for each kind of event, each with its own `id`, `label`, `result` sample and
43
+ filter `params`.** Do not declare one trigger that takes an event-type parameter and switches inside its own
44
+ handler: its `result` then describes none of the shapes it emits, and a flow author has to configure which
45
+ event they meant instead of choosing it by name.
46
+
47
+ Where an API delivers several event kinds through **one consuming endpoint** — a cursor or offset feed that
48
+ hands each item to a single reader — separate polling triggers would compete for it, and the one that polls
49
+ first takes the update the others never see. That is a reason to deliver those events over
50
+ [09-realtime-triggers.md](09-realtime-triggers.md), where one webhook registration fans out to as many
51
+ triggers as the service declares, not a reason to write a universal polling trigger. If the API offers no
52
+ webhook at all, say so in the service `README.md` and declare the one trigger the endpoint can support.
53
+
54
+ The handler bag also carries the shared context (see [07-actions.md](07-actions.md)).
@@ -0,0 +1,269 @@
1
+ # 09 — Realtime Triggers
2
+
3
+ Realtime triggers are driven by runtime-owned SYSTEM methods — you never write them. Declarative config
4
+ maps onto them:
5
+
6
+ | SYSTEM method (runtime-owned) | Phase | What you declare |
7
+ |---|---|---|
8
+ | `handleTriggerUpsertWebhook` | flow start | `subscribe` |
9
+ | `handleTriggerResolveEvents` | inbound (shape/handshake) | `extractProviderEventName` + `extractProviderEventData` (+ `handshake`) — or `resolveEvents` |
10
+ | `handleTriggerSelectMatched` | inbound (select/enrich) | per-trigger `match` (+ `extendResult`) |
11
+ | `handleTriggerRefreshWebhook` | refresh timer | `refresh` |
12
+ | `handleTriggerDeleteWebhook` | flow stop | `unsubscribe` |
13
+
14
+ ## Unknown trigger names
15
+
16
+ An `id` or `eventName` the service does not declare as a trigger is reachable in normal operation — a flow
17
+ built against an older version of the service, whose trigger was later renamed or removed, keeps sending the
18
+ old name. What happens then is **not** uniform across the SYSTEM methods, and the split is deliberate:
19
+
20
+ **Control plane throws, data plane declines.**
21
+
22
+ | SYSTEM method | Unknown name | Why |
23
+ |---|---|---|
24
+ | `handleTriggerUpsertWebhook` | **throws** `UnknownTriggerError` (404) | control plane |
25
+ | `handleTriggerRefreshWebhook` | **throws** `UnknownTriggerError` (404) | control plane |
26
+ | `handleTriggerPollingForEvent` | **throws** `UnknownTriggerError` (404) | control plane |
27
+ | `handleTriggerSelectMatched` | **declines** — `{ ids: [], enrichedEventData: null }` | data plane |
28
+ | `handleTriggerDeleteWebhook` | n/a — carries no trigger name | tears down the whole webhook |
29
+
30
+ - **Control plane** — upsert, refresh, polling. FlowRunner initiates these itself (enabling a flow, a
31
+ scheduled renewal). Something is waiting on the result, the error reaches a place where it can be acted
32
+ on, and no third party is affected. Upsert in particular is the platform asking *"is this flow
33
+ startable?"* — a version only goes LIVE once upsert has succeeded, so answering `{}` to a trigger that was
34
+ never registered with the provider produces a flow that reports LIVE and can never fire.
35
+ - **Data plane** — `selectMatched`. It runs *after* the provider has already been answered, on a detached
36
+ thread, with nothing waiting. A throw reaches nobody, and it would abort the remaining events of the same
37
+ delivery — dropping good events beside the stale name.
38
+
39
+ An upsert carries **every** realtime trigger of the flow version being enabled, so one unknown name blocks
40
+ the whole batch from subscribing. That is intended: a flow that refuses to start beats a live flow with half
41
+ its triggers registered.
42
+
43
+ Note the two callers of the same throw differ in where it surfaces: **upsert** fails a user's flow-enable
44
+ request and the error reaches the client, while **refresh** runs from a scheduled job — the flow keeps
45
+ running and the error appears in the customer's **workspace log** on each refresh. Neither is silent.
46
+
47
+ ## `ext.setupRealtimeTriggers(props)`
48
+
49
+ | Property | Type | Description |
50
+ |---|---|---|
51
+ | `scope` | `'SINGLE_APP' \| 'ALL_APPS'` | Per-app webhook vs one shared callback. |
52
+ | `extractProviderEventName` | path \| fn `({requestBody})=>name\|null` | Discriminator → routes to triggers by `providerEventName` (fan-out: matches every trigger with that value). |
53
+ | `extractProviderEventData` | path \| fn | Base `providerEventData` handed to matched triggers. Default = whole body. |
54
+ | `scopeAt` | path | ALL_APPS routing key path (route where `scopeAt === eventScopeId`). |
55
+ | `verify` | object | Declarative signature check — see the field table below. |
56
+ | `handshake` | fn | Endpoint verification (see table). |
57
+ | `subscribe` | fn | Required (see table). |
58
+ | `unsubscribe` | fn | Required (see table). |
59
+ | `refresh` | fn | Optional. |
60
+ | `resolveEvents` | fn | Escape hatch — replaces `extract*`/`handshake` for irregular/multi-shape payloads. |
61
+ | `verifyRequest` | fn | Escape hatch — replaces `verify`. |
62
+
63
+ **Function args → returns.** All of these also receive the full ctx bag — `config, context, apiRequest,
64
+ oauth, logger, helpers` — in the *same* single object as their own arguments. That includes `verifyRequest`,
65
+ so a value derived in `initContext` is reachable there; prefer it over re-deriving from `config`
66
+ ([16-gotchas.md](16-gotchas.md) on normalizing once).
67
+
68
+ **`headers` arrive verbatim**, in whatever casing the provider sent — they are *not* lowercased or otherwise
69
+ normalized on the way to `verifyRequest`. Look them up case-insensitively. (The declarative `verify` block
70
+ does its own lowercased retry; that behaviour does not extend to `verifyRequest`.)
71
+
72
+ | Function | Arguments | Returns |
73
+ |---|---|---|
74
+ | `subscribe` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` (null first), `connectionId` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
75
+ | `unsubscribe` | `callbackUrl`, `webhookData`, `connectionId` | `{ webhookData? }` |
76
+ | `refresh` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` | `{ webhookData?, refreshIntervalInSeconds }` |
77
+ | `handshake` | `{ requestBody, headers, rawBody }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
78
+ | `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
79
+
80
+ Both also still accept the **deprecated** `responseToExternalService` / `responseHeaders` — see
81
+ [below](#responsetoexternalservice--deprecated).
82
+ | `verifyRequest` | `{ rawBody, headers }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
83
+
84
+ **The `triggers` bag holds one entry per (trigger × `providerEventName`)**, so a trigger declaring several
85
+ names appears several times. A trigger that declares **no** `providerEventName` — what you write when
86
+ `resolveEvents` emits `id` directly — appears **once, with `providerEventName` absent**: it is a routing
87
+ declaration, and having none does not stop the trigger running or stop `subscribe`/`refresh` having to
88
+ reconcile it. Guard the field rather than assuming it (`if (t.providerEventName)`), and never key a lookup
89
+ on it unconditionally. Nothing is left out of the bag: a name resolving to no trigger **rejects the whole
90
+ call** — see [Unknown trigger names](#unknown-trigger-names) below.
91
+
92
+ ### `responseToWebhook` — answering the provider
93
+
94
+ Some providers do not accept a generic `200`. Xero's *Intent to Receive* validation sends two deliveries and
95
+ checks both answers: a correctly signed one must get **2xx**, a deliberately mis-signed one must get **401**.
96
+ Return `responseToWebhook` from `handshake` or `resolveEvents` to say exactly what the provider receives.
97
+
98
+ ```js
99
+ return {
100
+ events: [],
101
+ responseToWebhook: {
102
+ httpStatus: 401, // optional, 200 by default
103
+ headers : { 'X-Ack': 'ok' }, // optional
104
+ body : { ok: true }, // optional, JSON-serialized
105
+ rawBody : '', // optional, sent as-is — wins over `body`
106
+ },
107
+ }
108
+ ```
109
+
110
+ - **`rawBody` beats `body`.** `body` is always JSON-serialized, so a String passed there arrives quoted. Use
111
+ `rawBody` when the answer is not a JSON document — a challenge token, or an empty body.
112
+ - **Content type** defaults to `application/json` for `body` and `text/plain` for `rawBody`, unless `headers`
113
+ sets one.
114
+ - **Allowed `httpStatus`:** `200, 201, 202, 204, 400, 401, 403, 404, 409, 410, 422, 429`. Anything else falls
115
+ back to `200` with a warning. **3xx is refused on purpose** — these callback URLs are handed to third
116
+ parties, so honouring a redirect would make any service an open redirector.
117
+ - **Dropped headers:** `Set-Cookie`, `Content-Length`, `Transfer-Encoding` and other hop-by-hop names, and
118
+ any header whose name or value contains CR/LF (response splitting).
119
+ - **Omit it and nothing changes** — the delivery is answered `200` with an empty body, as before.
120
+
121
+ #### `responseToExternalService` — deprecated
122
+
123
+ `responseToExternalService` and `responseHeaders` are **deprecated**. They still work — the runtime forwards
124
+ them to the platform untouched, so an existing service keeps behaving exactly as it did and needs no edit —
125
+ but they can only say *what the body is*, never what status or headers go with it. **Write
126
+ `responseToWebhook` in new code**, and move an old handler over when you next touch it:
127
+
128
+ | Deprecated | Write instead | Why |
129
+ |---|---|---|
130
+ | `responseToExternalService: 'token'` | `responseToWebhook: { rawBody: 'token' }` | a String was sent as raw `text/plain` — `body` is JSON, so it would arrive **quoted** |
131
+ | `responseToExternalService: { ok: true }` | `responseToWebhook: { body: { ok: true } }` | an object was JSON-serialized, and still is |
132
+ | `responseHeaders: { 'X-Echo': 'ok' }` | `responseToWebhook: { headers: { 'X-Echo': 'ok' } }` | |
133
+
134
+ ⚠️ The String case is the one that bites: `body` would deliver `"token"` with the quotes, and a provider
135
+ comparing it to the token it sent sees a mismatch. **A String is always `rawBody`.**
136
+
137
+ ⚠️ Do not return both from one response. They are forwarded side by side and the platform picks one — which
138
+ one is not yours to choose. Write one or the other.
139
+
140
+ **Reject by returning, never by throwing.** A throw on this path answers the provider **500**, and inbound
141
+ deliveries are **not retried** (every other trigger request type still is), so a rejection expressed as an
142
+ error is simply a failed delivery. The declarative `verify` block already follows this rule: a failed
143
+ signature check answers `{ events: [], responseToWebhook: { httpStatus: 401, rawBody: '' } }` — it does not
144
+ throw.
145
+
146
+ ### ⚠️ `rawBody` is absent, never empty
147
+
148
+ `rawBody` is the unmodified bytes of the request, decoded as UTF-8 — and it is **absent** when there is
149
+ nothing to verify: a `GET`, a request with no body, a request sent without `Content-Length`, or a body over
150
+ 5 MB. **Treat absent as "cannot verify"**, and answer accordingly:
151
+
152
+ ```js
153
+ verifyRequest: ({ rawBody, headers }) => {
154
+ if (typeof rawBody !== 'string') {
155
+ return false // ✓ nothing to hash — this is not the same as a bad signature
156
+ }
157
+ …
158
+ }
159
+ ```
160
+
161
+ Hashing `''` instead produces a digest that can never match, which reads as a *signature mismatch* rather
162
+ than the missing input it is — and sends you hunting for a wrong secret.
163
+
164
+ ### `verify` fields
165
+
166
+ HMACs the **raw body alone** with `secret(config)` and compares it to the header in constant time.
167
+
168
+ | Field | Req | Description |
169
+ |---|---|---|
170
+ | `header` | ✓ | Signature header. Read as declared, then retried lowercased. Absent header → fail. |
171
+ | `algo` | ✓ | Hash algorithm, e.g. `'sha256'`. |
172
+ | `encoding` | ✓ | `'hex' \| 'base64'` — the digest encoding the provider sends. |
173
+ | `secret` | ✓ | `(config) => key`. |
174
+ | `timestampHeader` | – | Header carrying the request timestamp. **Required for `freshness` to run.** |
175
+ | `freshness` | – | Max age in seconds. **Only checked when `timestampHeader` is also declared** — on its own it is silently inert. A declared-but-absent timestamp header passes. |
176
+
177
+ The signed payload is `rawBody` and nothing else. A provider that signs a **composed** string
178
+ (`{timestamp}.{body}`, a URL, a concatenation of fields) cannot be expressed here — use `verifyRequest` with
179
+ `Flowrunner.crypto`.
180
+
181
+ `subscribe` **is an upsert** (re-runs with the full desired set + prior `webhookData`; `unsubscribe` only
182
+ on flow stop). Two strategies:
183
+
184
+ - **Recreate** (Calendly, Backendless, joggai) — delete prior `webhookData` first, then create.
185
+ - **Reconcile/diff** (Slack, Box) — apply only additions/removals (no teardown).
186
+
187
+ Runtime provides `Flowrunner.crypto.hmac(algo,key,data,'hex'|'base64')` — **synchronous**, returning the
188
+ encoded digest as a string, not a Promise — `timingSafeEqual(a,b)` (false — not a throw — on nullish or
189
+ length mismatch, so a caller can `return` it), and `ageSeconds(timestamp)`.
190
+ `connectionId` + `webhookData` are runtime-owned/persisted.
191
+
192
+ ## One trigger per event
193
+
194
+ **Register a separate trigger for each provider event. Never a single trigger with an event-type
195
+ parameter.** A "universal" trigger that takes `eventTypes: z.array(z.enum([...]))` and fans out inside its
196
+ own handler is wrong here, and the mechanism above is why: `extractProviderEventName` already routes each
197
+ inbound delivery to every trigger claiming that `providerEventName`, over **one** shared webhook
198
+ registration. `subscribe` receives the full desired trigger set, so it registers one URL for all of them.
199
+
200
+ Splitting them costs nothing at the transport level and buys everything at the flow level: each trigger gets
201
+ its own `label`, its own `description`, its own `result` sample and its own `params` — so a flow author picks
202
+ "On Message Edited" from a list instead of picking a generic trigger and then configuring which event they
203
+ meant. A `result` on a universal trigger cannot describe anything precise, because the payload differs per
204
+ event.
205
+
206
+ ```js
207
+ // ✗ one trigger, an event-type param, and a result sample that fits none of them
208
+ ext.addRealtimeTrigger({
209
+ id : 'onUpdate',
210
+ params: z.object({ updateTypes: z.array(z.enum(['message', 'edited_message', 'callback_query'])) }),
211
+ result: { update_id: 1 },
212
+ })
213
+
214
+ // ✓ one per event — each with the shape that event actually delivers
215
+ ext.addRealtimeTrigger({ id: 'onMessage', providerEventName: 'message', result: { … } })
216
+ ext.addRealtimeTrigger({ id: 'onEditedMessage', providerEventName: 'edited_message', result: { … } })
217
+ ext.addRealtimeTrigger({ id: 'onCallbackQuery', providerEventName: 'callback_query', result: { … } })
218
+ ```
219
+
220
+ Use `params` for **filters** — which chat, which board, which status — never for choosing the event.
221
+
222
+ ## `ext.addRealtimeTrigger(props)`
223
+
224
+ | Property | Type | Req | Description |
225
+ |---|---|---|---|
226
+ | `category`/`id`/`label`/`description` | string | ✓ | `id` is persisted and never changes. |
227
+ | `providerEventName` | string \| string[] \| `({params})=>string[]` | ✓* | Provider event(s) this trigger claims (routing). *Omitted when `resolveEvents` emits `id` directly. |
228
+ | `params` | `z.object` | – | Trigger config — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
229
+ | `result` | value \| schema \| loader | ✓ | Emitted event shape (post-`extendResult`). |
230
+ | `extendEventData` | fn | – | see table. |
231
+ | `match` | object \| fn | – | Instance selection (declarative object or predicate fn). |
232
+ | `extendResult` | fn | – | see table. |
233
+ | `oauth2Scopes` | string[] | – | Extra scopes. |
234
+
235
+ | Function | Arguments | Returns |
236
+ |---|---|---|
237
+ | `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
238
+ | `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
239
+ | `match` (fn) | `{ params, providerEventData }` | `boolean` — for ranges/contains/derived logic |
240
+ | `extendResult` | `{ providerEventData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
241
+
242
+ **Inbound runtime flow:** `handshake?` → `verify`/`verifyRequest` → read `extractProviderEventName` → for
243
+ each trigger whose `providerEventName` matches, build `providerEventData` (`extractProviderEventData` +
244
+ `extendEventData`) → `match` per instance → if ≥1 matched, `extendResult` once → fire.
245
+
246
+ **A trigger declaring no `match` fires every configured instance** — "no filter" means "fires always", and
247
+ that is a different case from a name this service does not declare, which selects nothing (see
248
+ [Unknown trigger names](#unknown-trigger-names)). Declining an unknown name never runs `extendResult`, so it
249
+ costs no provider call.
250
+
251
+ ## `webhookData` lifecycle (persisted; realtime analog of polling `state`)
252
+
253
+ | Phase | Effect |
254
+ |---|---|
255
+ | subscribe (flow start) | `null → webhookData` (create webhook / resolve `eventScopeId`) |
256
+ | subscribe (set changed) | `webhookData → webhookData'` (recreate: delete prior + create; or diff) |
257
+ | inbound event | unchanged \| emits matched instances |
258
+ | refresh (opt) | `webhookData → webhookData'` (renew) |
259
+ | unsubscribe (flow stop) | `webhookData → {}` (tear down) |
260
+
261
+ ## Frozen contract
262
+
263
+ These are persisted or read by live flows, so they are fixed once a service is deployed — changing one breaks
264
+ running automations:
265
+
266
+ `id` (trigger/action) · `params` keys · **`webhookData` shape** · `eventScopeId` ·
267
+ `refreshIntervalInSeconds` (seconds).
268
+
269
+ Transient and free to change: shaped events, matched ids, handshake responses.
@@ -0,0 +1,148 @@
1
+ # 10 — Files API
2
+
3
+ File storage is opt-in per extension. Set `usesFileStorage: true` in
4
+ `Flowrunner.createExtension(...)` (see [01-service-structure.md](01-service-structure.md)) to provision
5
+ `ctx.files` in every handler's context bag. When `usesFileStorage` is false (the default), `ctx.files` is
6
+ a **proxy that throws** — so accidental use fails loudly instead of silently no-op'ing.
7
+
8
+ - `files` appears in the [handler context bag](07-actions.md) only when `usesFileStorage: true`.
9
+ - A param that references a stored file is declared `z.url()` (or `z.string()`) and carries the file's URL.
10
+ There is no file-picker widget, so the flow author binds the URL from an earlier block or pastes it.
11
+
12
+ ## Method surface
13
+
14
+ `ctx.files` is the platform file-service client, and it is typed as such — the methods, options and
15
+ return shapes below are what an editor completes and checks, whether or not `usesFileStorage` is on (when
16
+ it is off the same type is backed by the proxy that throws). All options objects are optional.
17
+
18
+ | Method | Options | Returns | Options as a param |
19
+ |---|---|---|---|
20
+ | `uploadFile(buffer, options)` | `scope`, `filename`, `ttl`, `generateUrl` (default `true`), `objectTtl`, `overwrite` | `{ key, filename, url, size, urlExpiresAt, objectExpiresAt, overwritten }` | `z.filesUploadOptions([…])` |
21
+ | `list(options)` | `scope`, `ttl`, `generateUrl`, `limit`, `cursor` | `{ files: FileInfo[], cursor, hasMore }` | `z.filesListOptions([…])` |
22
+ | `get(filename, options)` | `scope`, `ttl`, `generateUrl` | `FileInfo` — `{ key, filename, url, size, createdAt, urlExpiresAt, objectExpiresAt }` | `z.filesGetOptions([…])` |
23
+ | `delete(filename, options)` | `scope` | `{ key, freedBytes, deleted }` | `z.filesDeleteOptions([…])` |
24
+ | `usage()` | — | `{ workspaceId, usedBytes, quotaBytes, usedFormatted, quotaFormatted, utilizationPercent, fileCount }` | — |
25
+
26
+ The last column is the same option list **as a parameter the flow author fills in** — see below.
27
+
28
+ | Option | Meaning |
29
+ |---|---|
30
+ | `scope` | which storage layer — **defaults to `'FLOW'`**. Name it with `filesScope` rather than a string; `usage()` is always workspace-scoped |
31
+ | `ttl` | signed-URL lifetime, in seconds |
32
+ | `generateUrl` | whether to include a pre-signed URL in the result |
33
+ | `objectTtl` | how long the stored object lives; omit for permanent |
34
+ | `overwrite` | replace an existing file with the same name instead of failing |
35
+ | `limit` / `cursor` | pagination for `list` |
36
+
37
+ ### Letting the flow author choose — the option groups
38
+
39
+ Every option in the tables above is also available as a **param group the platform ships**, one per call. So
40
+ a flow author can pick the storage layer — or a filename, a limit, a link lifetime — without you redeclaring
41
+ the dropdown, its values, its labels and its default:
42
+
43
+ ```js
44
+ params: z.object({
45
+ fileOptions: z.filesUploadOptions(['scope']).label('File Settings').optional(),
46
+ })
47
+ ```
48
+
49
+ The argument is the whitelist of fields to expose, and the parsed object goes straight into the matching
50
+ call — `params.fileOptions` into `uploadFile`, `params.listOptions` into `list`, and so on:
51
+
52
+ ```js
53
+ execute: async ({ params, files }) => {
54
+ const bytes = await Flowrunner.Request.get(params.url).toBuffer()
55
+
56
+ return files.uploadFile(bytes, { ...params.fileOptions, filename: 'agreement.pdf' })
57
+ }
58
+ ```
59
+
60
+ **Do not hand-write these objects.** A copy in your service is a copy that stops tracking the platform: when
61
+ an option is added, a label reworded or a default changed, every service using the group picks it up and
62
+ yours does not. It is also how a service ends up publishing a setting the runtime does not have — a field a
63
+ flow author fills in that is silently dropped.
64
+
65
+ See *Platform param schemas* in [03-parameters.md](03-parameters.md) for the whitelist rules, the runtime
66
+ contract, and which options are risky to expose.
67
+
68
+ ### Naming a layer — `filesScope`
69
+
70
+ The handler bag carries `filesScope`, the three layers as named constants, so a typo is a `TypeError` at the
71
+ call site instead of a scope that silently does not exist:
72
+
73
+ ```js
74
+ execute: async ({ files, filesScope }) => {
75
+ const scope = filesScope.WORKSPACE
76
+
77
+ const saved = await files.uploadFile(buffer, { scope, filename: 'report.txt' })
78
+
79
+ return files.list({ scope })
80
+ }
81
+ ```
82
+
83
+ | | |
84
+ |---|---|
85
+ | `filesScope.WORKSPACE` | shared by the whole workspace, outlives every run |
86
+ | `filesScope.FLOW` | one flow, shared across its executions — the **default** |
87
+ | `filesScope.EXECUTION` | a single run; intermediate artifacts |
88
+
89
+ It is in the bag whether or not `usesFileStorage` is on — it is a set of constants, not a capability. Plain
90
+ strings still work, so nothing existing breaks.
91
+
92
+ `FLOW` and `EXECUTION` scopes require the flow / execution ids to be present in the execution context — the
93
+ runtime supplies them, but a call made outside a flow run (e.g. a design-time sample loader) can only use
94
+ `WORKSPACE`.
95
+
96
+ ```js
97
+ const ext = Flowrunner.createExtension({ /* … */ usesFileStorage: true })
98
+
99
+ ext.addAction({
100
+ category: 'Files', id: 'saveReport', label: 'Save Report', description: '…',
101
+ params : z.object({ name: z.string().label('File name') }),
102
+ result : { url: 'https://…', size: 1024 },
103
+ execute: async ({ params, files, filesScope, apiRequest }) => {
104
+ const report = await apiRequest({ url: '/reports/export' })
105
+ const saved = await files.uploadFile(Buffer.from(report), {
106
+ scope: filesScope.FLOW, filename: params.name, generateUrl: true, ttl: 3600,
107
+ })
108
+
109
+ return { url: saved.url, size: saved.size }
110
+ },
111
+ })
112
+ ```
113
+
114
+ > **`uploadFile` takes bytes, so fetch bytes.** `Buffer.from(text)` is right only when the source really is
115
+ > text. Download a PDF, an image or a zip with **`.toBuffer()`** and hand it over as it comes; fetching one
116
+ > through `apiRequest` decodes and parses it, and the corruption only shows up when someone opens the stored
117
+ > file ([04-http-requests.md](04-http-requests.md)).
118
+ >
119
+ > ```js
120
+ > const bytes = await Flowrunner.Request.get(params.fileUrl).toBuffer()
121
+ > const saved = await files.uploadFile(bytes, { scope: filesScope.FLOW, filename: 'report.pdf' })
122
+ > ```
123
+
124
+ > **Substituting the store.** A host can replace this client for one invocation by passing
125
+ > `runServiceMethod({ createFiles })`. The factory receives the file-service context —
126
+ > `{ serverURL, appId, apiKey, runtimeKey, flowId, executionId, retrieveNewS3Token }` — and returns anything
127
+ > satisfying **`FilesApi`**: the same five methods tabled above. `FilesApi` and its value types are exported
128
+ > from the package root, so an implementation can be type-checked against the contract. It is consulted only
129
+ > when the extension declares `usesFileStorage: true`; otherwise the throwing proxy is used as before.
130
+ >
131
+ > **Service code is unaffected and unaware** — it still calls `files.uploadFile(...)` and reads `url` off the
132
+ > result, and whatever URL the implementation returns is the URL the service passes on. The case this exists
133
+ > for is end-to-end testing: a harness implements `FilesApi` over its own storage (a local MinIO, a scratch
134
+ > bucket) and returns presigned URLs, so a third party in the test can really fetch what the service
135
+ > uploaded — no HTTP to the platform, no patching of runtime internals.
136
+ >
137
+ > Writing one, two things matter. Lay keys out per storage layer and list **one level at a time**: the
138
+ > execution prefix nests inside the flow prefix, so a recursive listing leaks a run's files into its flow —
139
+ > list with a delimiter. And clean up between runs yourself; there is no teardown hook, so deleting the test
140
+ > prefix is the harness's job.
141
+
142
+ > **Scopes need a flow.** `FLOW` and `EXECUTION` scopes address a path built from the running flow and
143
+ > execution, so they only work when there *is* one. A method invoked outside a flow execution — an OAuth
144
+ > step, a dictionary or loader, a manual run from the console — has neither, and a `FLOW`-scoped call (the
145
+ > default for `uploadFile` / `list` / `get` / `delete`) fails there. Use `WORKSPACE` scope for anything such
146
+ > a method has to read or write, and keep `FLOW`/`EXECUTION` for work that happens inside a flow.
147
+ >
148
+ > The same applies to `usage()`, which is always workspace-scoped and therefore works everywhere.