@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,193 @@
1
+ # 03 — Parameters
2
+
3
+ All params are **body params**. A handler's `execute` receives the parsed, typed `params`
4
+ (`z.infer<typeof params>`) — the schema you declare here is exactly what the handler sees, down to
5
+ optionality: `.optional()` gives `T | undefined`, and adding `.default(v)` drops the `undefined` because
6
+ the runtime fills it in first. Widgets and behaviors come from the zod type + plugins
7
+ (see [02-zod-types.md](02-zod-types.md)); the rest of the bag is typed too — see
8
+ [07-actions.md](07-actions.md#inferred-types).
9
+
10
+ ```js
11
+ params: z.object({
12
+ chatId: chatIdParam,
13
+ text : z.text().label('Message'),
14
+ mode : z.enum(['A', 'B']).optional().label('Mode'),
15
+ })
16
+ ```
17
+
18
+ ## `params` is optional — but if you declare it, it must be a `z.object`
19
+
20
+ An action or trigger that takes no input either leaves `params` out or declares `params: z.object({})`.
21
+ Both are correct; omitting is the shorter one.
22
+
23
+ ```js
24
+ svc.addAction({
25
+ category: 'Account', id: 'ping', label: 'Ping', description: 'Health check.',
26
+ result : { ok: true },
27
+ execute : () => ({ ok: true }), // no `params` — the handler receives `params: {}`
28
+ })
29
+ ```
30
+
31
+ Anything that is **not** a `z.object` is rejected. The runtime needs a container of named fields — that is
32
+ what it validates input against and what it publishes as the method's input scheme — so there is exactly one
33
+ way to declare params, and it is checked the moment the service registers:
34
+
35
+ ```js
36
+ params: z.object({ chatId: z.string() }) // ✓ the only form for declared params
37
+ params: z.object({}) // ✓ or omit the property
38
+ params: z.string() // ✗ FR_EXT_INVALID_SCHEMA
39
+ params: { chatId: z.string() } // ✗ a raw shape is never auto-wrapped
40
+ params: {} // ✗
41
+ params: z.object({ … }).optional() // ✗ a container cannot be optional
42
+ params: z.object({ chatId: z.string().optional() }) // ✓ mark the FIELDS optional
43
+ ```
44
+
45
+ A raw `{ … }` is never treated as sugar for `z.object({ … })`. Beyond keeping one way to write one thing, a
46
+ raw shape is not a zod type — so `params` in your handler would silently degrade from its inferred shape to
47
+ `Record<string, unknown>`.
48
+
49
+ The check runs while the service module loads, so `flowrunner deploy` fails before uploading and names the
50
+ item and the slot:
51
+
52
+ ```
53
+ [flow-extension:hubspot] action "createContact": `params` must be a z.object({ … }) —
54
+ received z.string(); omit `params` entirely if there is nothing to declare
55
+ ```
56
+
57
+ The same rule applies to every schema slot: `configItems`, a dictionary's `criteria`,
58
+ `dynamicParams.criteria`, and the object `dynamicParams.resolve()` returns.
59
+
60
+ ## Shared param schemas — one plugin call per line
61
+
62
+ A param reused across actions is declared once, named with a `Param` suffix, and **its chained plugin calls
63
+ each go on their own line, in a column**:
64
+
65
+ ```js
66
+ const chatIdParam = z.string()
67
+ .label('Chat')
68
+ .dictionary(getChatsDictionary)
69
+ .describe('Numeric chat ID or @channelusername.')
70
+ ```
71
+
72
+ Not `z.string().label('Chat').dictionary(getChatsDictionary).describe('…')`. The chain is a list of
73
+ independent facts about the field; one per line means a diff touches only the fact that changed, and a long
74
+ chain stays readable instead of running off the edge.
75
+
76
+ Inline params inside a `z.object({ … })` — the ones used by a single action and not worth naming — stay on
77
+ one line while they are short. The rule is about the shared, named schemas.
78
+
79
+ ## Platform param schemas — file options
80
+
81
+ Some params are not yours to define. Wherever a flow author reaches into **file storage** — choosing which
82
+ layer a file lands in, which layer to list, how long a download link lives — the options, their labels, their
83
+ wording and their defaults belong to the platform, not to your service. `Flowrunner.z` ships them, so the
84
+ definition lives in one place instead of being retyped in every service that touches a file:
85
+
86
+ ```js
87
+ params: z.object({
88
+ url : z.url().label('PDF URL'),
89
+ fileOptions: z.filesUploadOptions(['scope'])
90
+ .label('File Settings')
91
+ .describe('Where to store the downloaded PDF in FlowRunner file storage.')
92
+ .optional(),
93
+ })
94
+ ```
95
+
96
+ **There is one group per Files call**, and each one's fields are that call's options — so the group you want
97
+ is decided by the method your handler ends up calling:
98
+
99
+ | Factory | Feeds | Fields, in publish order |
100
+ |---|---|---|
101
+ | `z.filesUploadOptions()` | `files.uploadFile(bytes, options)` | `scope`, `filename`, `ttl`, `objectTtl`, `overwrite`, `generateUrl` |
102
+ | `z.filesListOptions()` | `files.list(options)` | `scope`, `limit`, `ttl`, `generateUrl`, `cursor` |
103
+ | `z.filesGetOptions()` | `files.get(filename, options)` | `scope`, `ttl`, `generateUrl` |
104
+ | `z.filesDeleteOptions()` | `files.delete(filename, options)` | `scope` |
105
+
106
+ What each field *means* is in [10-files-api.md](10-files-api.md) — it is the same option list, documented
107
+ once. Each factory returns a plain `z.object`, so it composes like any other schema: wrap it in your own
108
+ `.label()`, `.describe()` and `.optional()`, exactly as above. What comes from the platform is the *inside* —
109
+ the dropdown values, the labels, the help text and the defaults. Reword one of those and every service picks
110
+ the change up; hand-copy them and yours is the one that goes stale.
111
+
112
+ ### One per call
113
+
114
+ ```js
115
+ // upload — where should this file go?
116
+ fileOptions: z.filesUploadOptions(['scope']).label('File Settings').optional(),
117
+
118
+ // list — which layer, and how many?
119
+ listOptions: z.filesListOptions(['scope', 'limit']).label('Lookup').optional(),
120
+
121
+ // get — which layer, and how long should the link live?
122
+ getOptions: z.filesGetOptions(['scope', 'ttl']).label('Download').optional(),
123
+
124
+ // delete — which layer?
125
+ deleteOptions: z.filesDeleteOptions().label('Storage').optional(),
126
+ ```
127
+
128
+ `z.filesDeleteOptions()` declares one field, so it needs no whitelist; the others are usually worth
129
+ subsetting. Each one's parsed value goes straight into the matching call:
130
+
131
+ ```js
132
+ execute: async ({ params, files }) => {
133
+ const found = await files.list(params.listOptions)
134
+
135
+ return files.get(found.files[0].filename, params.getOptions)
136
+ }
137
+ ```
138
+
139
+ Each group also identifies itself in the published model — `uiComponent: { type: 'FILE_UPLOAD_OPTIONS' }`,
140
+ and `FILE_LIST_OPTIONS` / `FILE_GET_OPTIONS` / `FILE_DELETE_OPTIONS` for the others (see
141
+ [11-output-model.md](11-output-model.md)) — which is what lets the platform recognise its own options object
142
+ and render it as one. A hand-written copy is just an anonymous object, and gets the generic nested form.
143
+
144
+ **The argument is the field whitelist.** Expose only what the flow author should decide, and let the handler
145
+ choose the rest:
146
+
147
+ ```js
148
+ z.filesUploadOptions(['scope']) // one setting on screen — the common case
149
+ z.filesUploadOptions(['scope', 'filename']) // two
150
+ z.filesUploadOptions() // all six
151
+ ```
152
+
153
+ Two things about that list. The published order is the **group's**, not the list's — `['filename', 'scope']`
154
+ still shows `scope` first. And an unknown name throws while the service registers, naming the valid fields,
155
+ rather than quietly publishing an empty settings panel.
156
+
157
+ > **Think before exposing `generateUrl`.** It is the one option whose wrong value fails *quietly*: with it
158
+ > off, the call succeeds and the result's `url` is empty, so an action that returns a URL reports success and
159
+ > hands the flow nothing. If your action's result carries a URL, leave `generateUrl` out of the whitelist and
160
+ > pass `true` yourself — the flow author has no way to know that turning it off breaks the block.
161
+
162
+ **The group is also the contract at runtime.** A `z.object` strips what it does not declare, so
163
+ `z.filesUploadOptions(['scope'])` hands your handler `{ scope }` and nothing else, with the platform default
164
+ already filled in. Anything you did not expose is yours to pass:
165
+
166
+ ```js
167
+ execute: async ({ params, files }) => {
168
+ const bytes = await Flowrunner.Request.get(params.url).toBuffer()
169
+
170
+ return files.uploadFile(bytes, { ...params.fileOptions, filename: 'agreement.pdf' })
171
+ }
172
+ ```
173
+
174
+ Spread the caller's options **first** — a hardcoded value after the spread is the one you meant to be
175
+ non-negotiable, and one before it is silently overridable.
176
+
177
+ See [10-files-api.md](10-files-api.md) for what each option does.
178
+
179
+ ## Dynamic params — `dynamicParams`
180
+
181
+ Generate additional top-level param fields at runtime (e.g. fields that depend on a chosen resource):
182
+
183
+ | Property | Type | Description |
184
+ |---|---|---|
185
+ | `criteria` | `z.object` | Dependency inputs → become `dependsOn`. |
186
+ | `resolve` | fn | `({ criteria, context, apiRequest }) => z.object({...})` — extra params merged into `params`. |
187
+
188
+ The `resolve` function returns a `z.object(...)` whose fields are merged into the static `params`. The
189
+ declared `criteria` inputs become the `dependsOn` set that triggers re-resolution when they change.
190
+
191
+ `resolve` must return a `z.object` — anything else fails with `FR_EXT_INVALID_SCHEMA` when the console calls
192
+ it. This is the one slot that cannot be checked while the service loads, since the schema does not exist
193
+ until the resolver runs.
@@ -0,0 +1,257 @@
1
+ # 04 — HTTP Requests
2
+
3
+ Services make HTTP calls through a **shared `apiRequest` helper** declared once on the extension
4
+ (`createExtension({ apiRequest })`, see [01-service-structure.md](01-service-structure.md)). It centralizes
5
+ base URL, auth, envelope-unwrapping, error-normalization and redacted logging so individual handlers stay
6
+ declarative.
7
+
8
+ ```js
9
+ apiRequest: async ({ url, method = 'get', body, query, context }) =>
10
+ new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
11
+ .set({ Authorization: `Bearer ${ context.apiKey }` })
12
+ .query(query),
13
+ ```
14
+
15
+ The constructor form takes the verb as a value, which is what you want when `method` arrives as an argument.
16
+ Avoid `Flowrunner.Request[method.toLowerCase()](url)`: an object lookup keyed by a variable resolves
17
+ inherited names such as `constructor` when the value is ever anything unexpected
18
+ ([16-gotchas.md](16-gotchas.md)).
19
+
20
+ ## `apiRequest` argument
21
+
22
+ Author-defined, but conventionally:
23
+
24
+ ```
25
+ { url, method = 'get', body, query, context, logger, logTag, ...custom }
26
+ ```
27
+
28
+ - `context` is the return of `initContext` (see [01-service-structure.md](01-service-structure.md)) — the
29
+ place to read resolved credentials/tokens.
30
+ - The helper is exposed in every handler's context bag as `apiRequest` (see [07-actions.md](07-actions.md)),
31
+ and is also the natural building block for `helpers`.
32
+
33
+ The rest of this document is the client surface underneath that helper — `Flowrunner.Request`, the runtime
34
+ HTTP client, always on the global ([13-runtime-contracts.md](13-runtime-contracts.md)) and requiring no
35
+ import.
36
+
37
+ ## Sending: the instance is thenable
38
+
39
+ Every chainable below returns the **same request instance**, and the instance has a `.then`. Nothing is sent
40
+ while you build the chain — **`await` is what issues the request**:
41
+
42
+ ```js
43
+ await Flowrunner.Request.get(url) // sends
44
+ await Flowrunner.Request.post(url).set(headers) // sends
45
+ await Flowrunner.Request.post(url).form(formData) // sends
46
+ ```
47
+
48
+ **Two methods are terminal instead: `.send(body?)` and `.toBuffer()`.** They issue the request immediately
49
+ and return a plain `Promise`, not the request — so nothing can be chained after them, and they must come
50
+ last:
51
+
52
+ ```js
53
+ await Flowrunner.Request.post(url).set(headers).send(body) // correct — .send() last
54
+ Flowrunner.Request.post(url).send(body).set(headers) // TypeError: .set is not a function
55
+
56
+ await Flowrunner.Request.get(url).set(headers).toBuffer() // correct — .toBuffer() last
57
+ ```
58
+
59
+ By default the promise resolves to the **response body**. A non-2xx rejects — see *Failures*.
60
+
61
+ ## Methods
62
+
63
+ | Static | Body argument |
64
+ |---|---|
65
+ | `Flowrunner.Request.get(url)` | – |
66
+ | `Flowrunner.Request.head(url)` | – |
67
+ | `Flowrunner.Request.options(url)` | – |
68
+ | `Flowrunner.Request.post(url, body?)` | ✓ |
69
+ | `Flowrunner.Request.put(url, body?)` | ✓ |
70
+ | `Flowrunner.Request.patch(url, body?)` | ✓ |
71
+ | `Flowrunner.Request.delete(url, body?)` | ✓ |
72
+ | `new Flowrunner.Request(url, method, body?)` | ✓ — verb as a value, either case |
73
+
74
+ The optional second argument is the body, identical to `.send(body)` except that it leaves the chain open:
75
+
76
+ ```js
77
+ await Flowrunner.Request.post(url, { name: 'Bob' }).set(headers) // body first, still chainable
78
+ await Flowrunner.Request.post(url).set(headers).send({ name: 'Bob' })
79
+ ```
80
+
81
+ ## Query parameters
82
+
83
+ `.query(obj)` appends to the URL's query string:
84
+
85
+ ```js
86
+ await Flowrunner.Request.get('https://api.vendor.com/items')
87
+ .query({ str: 'abc', num: 123, bool: true, list: [1, 2, 3] })
88
+ // → /items?str=abc&num=123&bool=true&list=1&list=2&list=3
89
+ ```
90
+
91
+ - An **array repeats the key** (`list=1&list=2&list=3`); there is no bracket or comma form.
92
+ - `undefined` values are **dropped**; `null` is **serialized as the string `null`** (`nil=null`), which is
93
+ almost never what an API wants. Strip empties before calling `.query()` — on `undefined`/`null` rather than
94
+ on falsiness, because an empty string is a value ([16-gotchas.md](16-gotchas.md)).
95
+
96
+ > **Do not combine an inline query string with `.query()`.** The two are concatenated without normalizing the
97
+ > separator, so `Request.get('/p?a=1').query({ b: 2 })` puts **`/p?a=1?b=2`** on the wire — a second `?`
98
+ > instead of an `&`. Pass a bare path and put every parameter in `.query()`; a unit suite then reads `query`
99
+ > back as a parsed object ([15-unit-tests.md](15-unit-tests.md)).
100
+
101
+ ## Headers
102
+
103
+ `.set()` takes either a name and a value, or an object, and may be called repeatedly:
104
+
105
+ ```js
106
+ await Flowrunner.Request.get(url)
107
+ .set('X-Api-Key', apiKey)
108
+ .set({ Accept: 'application/json', 'X-Trace': traceId })
109
+ ```
110
+
111
+ `.type(contentType)` is shorthand for setting `Content-Type`. One is set for you when the body is an object
112
+ (`application/json`) or a form (multipart with a generated boundary), so set it by hand only to override
113
+ that. `.basicAuth({ token })` and `.authKey(key)` are shorthands for the two common schemes; anything else is
114
+ an ordinary header.
115
+
116
+ ## Request body
117
+
118
+ An object body is serialized as JSON:
119
+
120
+ ```js
121
+ await Flowrunner.Request.post(url).send({ name: 'Bob', tags: ['a', 'b'] })
122
+ await Flowrunner.Request.post(url).type('text/plain').send('raw text')
123
+ ```
124
+
125
+ ### Forms and file uploads
126
+
127
+ `.form(data)` sets a form-data body — this is the multipart path, and there is no `.attach()`. It takes a
128
+ **plain object**, the **global WHATWG `FormData`** (the Node 18+ one, same as a browser's), or a
129
+ `Flowrunner.Request.FormData`. The plain object is the shortest and the one to reach for:
130
+
131
+ ```js
132
+ await request.form({
133
+ chat_id: String(chatId), // text part
134
+ photo : new File([bytes], 'shot.png', { type: 'image/png' }), // name + type in one go
135
+
136
+ // the explicit form, when the value is a Buffer or a stream
137
+ doc : { value: bytes, options: { filename: 'report.pdf', contentType: 'application/pdf' } },
138
+ }) // note: awaited, not .send()
139
+ ```
140
+
141
+ An array value repeats the key, one part per element. Whichever shape you pass, this is a Node-style
142
+ **streaming** multipart body underneath, and these are the values a part may hold:
143
+
144
+ | Value | What is sent |
145
+ |---|---|
146
+ | string, number, boolean | a text part — numbers and booleans are coerced to strings |
147
+ | `Buffer`, `Uint8Array` | a binary part; give it a name via the `{ value, options }` form |
148
+ | `File` | a binary part, **streamed** — the shortest way to send a named file: `filename` comes from its name and `contentType` from its type, so no options are needed. `size` sets `Content-Length`, so a large file is not held in memory twice |
149
+ | `Blob` | the same, but it has no name — every Blob part is sent as `filename="blob"`, and a Blob with no `type` as `application/octet-stream`. Use a `File`, or the `{ value, options }` form, when the filename matters |
150
+ | a stream | a binary part; pass `knownLength` in the options or the length cannot be computed |
151
+ | `{ value, options }` | any of the above plus explicit `filename` / `contentType` / `knownLength` — **these options win** over anything derived from a Blob. **Both keys must be present**: `{ value: bytes }` alone is read as an ordinary object and refused |
152
+
153
+ Pass `contentType` explicitly for a Buffer or a stream — omitted, one is derived from `filename` and you
154
+ inherit whatever that lookup returns (`a.bin` → `application/octet-stream`).
155
+
156
+ Anything else — a plain object, a class instance — is refused **with the field named**, before the body
157
+ starts streaming:
158
+
159
+ ```
160
+ The form field "photo" can not be sent, expected a Buffer, a stream, a Blob or a primitive value,
161
+ received an instance of ReadableStream.
162
+ ```
163
+
164
+ > **A `Blob` or a `File` goes to `.form()`, never onto a `Flowrunner.Request.FormData`.** That instance
165
+ > takes only a Buffer, a stream or a primitive, so `form.append('file', new Blob([bytes]), 'a.png')` throws
166
+ > **`source.on is not a function`**. Put it in the object you hand to `.form()`, or on a global `FormData`,
167
+ > and it is streamed for you.
168
+
169
+ Reach for `Flowrunner.Request.FormData` when you want the encoded body in hand: it exposes `getBoundary()`,
170
+ `getHeaders()`, `getBuffer()` and `getLength()`, which are how a test or a scratch check inspects what would
171
+ go out.
172
+
173
+ > **Never follow `.form(data)` with `.send()`.** `.form()` only stages the body; `.send()` is what issues the
174
+ > request, and a bare `.send()` issues it with **no body at all** — no `Content-Type`, no fields,
175
+ > `Content-Length: 0`. The vendor then answers as though no parameters were passed, which reads like a bug in
176
+ > your parameter mapping rather than in the transport.
177
+ >
178
+ > ```js
179
+ > await request.form(form) // correct
180
+ > await request.send(form) // also correct — .send() accepts the form
181
+ > request.form(form).send() // WRONG — one empty request, silently
182
+ > ```
183
+
184
+ ## Response handling
185
+
186
+ | Call | Effect |
187
+ |---|---|
188
+ | *(default)* | resolves to the response **body** |
189
+ | `.unwrapBody(false)` | resolves to `{ status, statusText, headers, body }` |
190
+ | `.toBuffer()` | **terminal** — sends, and resolves the body as raw bytes |
191
+ | `.setTimeout(ms)` | per-request client timeout |
192
+
193
+ Use `.unwrapBody(false)` when the status or a response header carries meaning — a pagination cursor in a
194
+ `Link` header, a `Retry-After`, a `204` that must be told apart from an empty body.
195
+
196
+ ### Binary downloads
197
+
198
+ **`.toBuffer()` downloads bytes** — a PDF, an image, a video. It is terminal, so it comes last, and it
199
+ resolves a `Buffer` you pass straight on:
200
+
201
+ ```js
202
+ const bytes = await Flowrunner.Request.get(fileUrl).set(headers).toBuffer()
203
+
204
+ await request.form({ file: new File([bytes], 'report.pdf', { type: 'application/pdf' }) }) // forward it
205
+ await files.uploadFile(bytes, { filename: 'report.pdf' }) // or store it
206
+ ```
207
+
208
+ - The body is returned byte for byte, including when its content happens to be valid JSON.
209
+ - A response with no body — a `204`, a `Content-Length: 0` — resolves to an **empty buffer**, never `''`.
210
+ - A non-2xx rejects as everywhere else, with the *error* body parsed when it is JSON, so
211
+ `error.status` and `error.body.message` read normally.
212
+ - `.unwrapBody(false)` composes: the whole response resolves and `body` is the bytes.
213
+
214
+ Use it for **every** binary download; do not reach for a response encoding.
215
+
216
+ Per platform policy **no execution timeout** is imposed around service code; `.setTimeout(ms)` is a
217
+ per-request client timeout, which is a different thing.
218
+
219
+ ## Client certificates
220
+
221
+ An API that requires mutual TLS needs a client certificate on **every** call, including the OAuth2 token
222
+ request, so it belongs in `apiRequest` rather than in individual actions:
223
+
224
+ ```js
225
+ apiRequest: async ({ url, method = 'get', body, query, context }) =>
226
+ new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
227
+ .cert({ cert: context.clientCert, key: context.clientKey })
228
+ .query(query),
229
+ ```
230
+
231
+ `.cert()` and its failure modes are [17-client-certificates.md](17-client-certificates.md); read it when the
232
+ vendor requires one.
233
+
234
+ ## Failures
235
+
236
+ A non-2xx **rejects** with a `ResponseError`:
237
+
238
+ | Property | Value |
239
+ |---|---|
240
+ | `status` | HTTP status |
241
+ | `headers` | response headers |
242
+ | `body` | parsed response body |
243
+ | `message` | the response body when there is one — **so it is not always a string** — else `Status Code <status> (<statusText>)`. A 502 is `No connection with server`. |
244
+
245
+ Because `message` is the raw body for most JSON APIs, reading it as a string used to produce an unreadable
246
+ `[object Object]`. The platform now renders an unhandled failure as the provider's response body — the
247
+ Execute tab, a Run Block result and a flow's error exit all show that body rather than `[object Object]` —
248
+ so a service that does nothing still fails legibly.
249
+
250
+ Normalising it yourself in `apiRequest` is still worth doing, and is still the main reason `apiRequest`
251
+ exists: the raw body is whatever the vendor chose to send, often wrapped in an envelope and carrying fields
252
+ a flow author has no use for. A one-line `Error` naming the service and the actual reason reads better than
253
+ a dump of it, and you write it once here rather than per action.
254
+
255
+ A transport failure — a dropped connection, DNS, a refused socket — rejects with **no `status` and no
256
+ `body`**. Services routinely handle one kind and not the other; both are worth a test
257
+ ([15-unit-tests.md](15-unit-tests.md)).
@@ -0,0 +1,103 @@
1
+ # 05 — Dictionaries
2
+
3
+ Dictionaries provide **dynamic options** for a param dropdown. `ext.dictionary(props)` returns a ref used
4
+ via `.dictionary(ref)` on a param (see [02-zod-types.md](02-zod-types.md)). A dictionary declares its
5
+ `criteria` once, and consumers auto-derive their `dependsOn` from it.
6
+
7
+ | Property | Type | Description |
8
+ |---|---|---|
9
+ | `id` | string | Dictionary id — **starts with `get`, ends with `Dictionary`** (`getChatsDictionary`). |
10
+ | `category` | string | Optional grouping label. Defaults to `''` — unlike an action's `category`, which is required. The v1 convention was to leave dictionaries uncategorised, so set it only to match a v1 dictionary that declared one. |
11
+ | `label` | string | **Human-readable name** → `operationName`. Dictionaries are shown in the UI and exposed to AI tools, so **always set a label**. Falls back to `id` when omitted. |
12
+ | `description` | string | Description. |
13
+ | `criteria` | `z.object` | Optional dependency inputs (become `dependsOn` on consumers). Omit when the dictionary depends on nothing; declared ⇒ must be a `z.object` (see [03-parameters.md](03-parameters.md)). |
14
+ | `result` | `{ items, cursor }` \| `z.` schema | Optional sample output → `metaInfo.sampleResult` + `OBJECT` `returnType`. Omit → `sampleResult: null`, `returnType: OBJECT`. |
15
+ | `execute` | fn | see below. |
16
+
17
+ | `execute` arguments | Returns |
18
+ |---|---|
19
+ | `{ search, cursor, criteria, context, apiRequest, helpers }` | `{ items: [{ label, value, note? }], cursor? }` (bare array ok if no pagination) |
20
+
21
+ ```js
22
+ const getTablesDictionary = ext.dictionary({
23
+ id : 'getTablesDictionary',
24
+ label : 'Tables',
25
+ description: 'Tables in the base',
26
+ criteria : z.object({ baseId: z.string().label('Base ID') }),
27
+ result : { items: [{ label: 'Base A', value: 'a' }], cursor: null },
28
+ execute : async ({ search, criteria, apiRequest }) => {
29
+ return { items: [], cursor: null }
30
+ },
31
+ })
32
+
33
+ // consumer:
34
+ const tableIdParam = z.string()
35
+ .label('Table')
36
+ .dictionary(getTablesDictionary) // auto dependsOn: ['baseId']
37
+ ```
38
+
39
+ - The `execute` bag is the shared handler context (see [07-actions.md](07-actions.md)) plus `search`,
40
+ `cursor`, and the resolved `criteria`.
41
+ - Return `{ items, cursor }` for paginated sources, or a bare `items` array when there is no pagination.
42
+ - **The `id` starts with `get` and ends with `Dictionary`**, and the const holding the ref carries the same
43
+ name — so the declaration and every `.dictionary(ref)` read alike.
44
+
45
+ ## Browse versus resolve — a dictionary does not need a listing endpoint
46
+
47
+ `execute` receives **`search`**, the text the flow author has typed. That makes two different dictionaries
48
+ possible, and only the first needs an endpoint that enumerates anything:
49
+
50
+ - **Browse** — the API has a listing endpoint. Ignore or filter by `search`, page with `cursor`, return the
51
+ set. This is the common case.
52
+ - **Resolve** — the API has no listing endpoint but *can* look up one entity by id, handle or URL. Call that
53
+ lookup with `search` and return the single hit, labelled with something human (`'Team Standup (group)'`)
54
+ and valued with the id. Return an empty array for empty or unmatched `search`, and use `description` to
55
+ tell the author what to type.
56
+
57
+ **"The API has no endpoint that lists these" is not a reason to leave a parameter as free text.** It rules
58
+ out *browse*, not *resolve*. A resolve dictionary still validates the value before the flow runs, still shows
59
+ the author the name of the thing they picked instead of a bare id, and still surfaces the parameter to AI
60
+ tools as a resolvable option. Reach for plain free text only when the API can neither list nor look up the
61
+ value — and say so in the service `README.md` when that happens.
62
+
63
+ ```js
64
+ // Resolve: no "list my chats" endpoint exists, but a single chat can be fetched by id or @username
65
+ const getChatsDictionary = ext.dictionary({
66
+ id : 'getChatsDictionary',
67
+ label : 'Chats',
68
+ description: 'Type a numeric chat ID or @username to resolve the chat.',
69
+ result : { items: [{ label: 'Team Standup (group)', value: '-1001234567890' }], cursor: null },
70
+ execute : async ({ search, apiRequest }) => {
71
+ if (!search?.trim()) {
72
+ return { items: [], cursor: null }
73
+ }
74
+
75
+ try {
76
+ const chat = await apiRequest({ url: '/getChat', query: { chat_id: search.trim() } })
77
+
78
+ return { items: [{ label: `${ chat.title ?? chat.username } (${ chat.type })`, value: String(chat.id) }] }
79
+ } catch (error) {
80
+ if (isUnresolvableInput(error)) {
81
+ return { items: [], cursor: null } // unresolvable input is an empty list, not an error
82
+ }
83
+
84
+ throw error // a credential or transport failure is not "no matches"
85
+ }
86
+ },
87
+ })
88
+ ```
89
+
90
+ A resolve dictionary usually declares no `criteria` — the input is `search`, not a dependency on another
91
+ field.
92
+
93
+ **Validation note.** The payload is validated in two steps: the `{ search, cursor, criteria }` envelope,
94
+ then `criteria` on its own against the declared schema. A criteria failure is reported separately
95
+ (`FR_EXT_INVALID_CRITERIA`) so the UI can point at the dependent fields — which is why `criteria` should
96
+ list exactly the inputs `execute` needs, and mark anything genuinely optional as such. `execute` receives
97
+ the parsed criteria (defaults applied, unknown fields dropped).
98
+
99
+ **Model note.** A dictionary is invoked through the helper-method route with a single `payload`
100
+ (`{ search, cursor, criteria }`) — the runner synthesizes a `payload` OBJECT bodyParam describing
101
+ `search` + `cursor` (+ a nested `criteria` object when `criteria` is declared) and puts the `"Payload"`
102
+ label in `metaInfo.args`. You do **not** declare `search`/`cursor` yourself. See
103
+ [11-output-model.md](11-output-model.md).
@@ -0,0 +1,42 @@
1
+ # 06 — OAuth2
2
+
3
+ Declare OAuth with `ext.setupOauth2(props)`. Its **presence ⇒ `requireOAuth = true`**. It is declarative
4
+ for the common case; any handler below overrides its step. Combined scopes = `scopes` ∪ every op's
5
+ `oauth2Scopes` (deduped), passed to handlers as `scopes`.
6
+
7
+ | Property | Type | Description |
8
+ |---|---|---|
9
+ | `scopes` | string[] | Base scope list. |
10
+ | `authorizeUrl` / `tokenUrl` | string | Declarative endpoints. |
11
+ | `pkce` | boolean | Runtime generates verifier/challenge + threads state. |
12
+ | `clientAuth` | `'basic' \| 'body'` | Client credential placement. |
13
+ | `identityRequest` | fn | `({ apiRequest }) => raw` — fetch the account identity. |
14
+ | `identity` | fn | `(raw) => { name, imageUrl?, userData? }`. |
15
+ | `getConnectionURL` (esc) | fn | see below. |
16
+ | `executeCallback` (esc) | fn | see below. |
17
+ | `refreshToken` (esc) | fn | see below. |
18
+ | `serializeToken` / `deserializeToken` | fn | Composite-token (de)serialization; runtime deserializes the header token into `oauth.token` before `initContext`. |
19
+
20
+ ## Escape-hatch handlers → returns
21
+
22
+ | Handler | Arguments | Returns |
23
+ |---|---|---|
24
+ | `getConnectionURL` | `{ config, context, scopes }` | `string` (authorize URL) |
25
+ | `executeCallback` | `{ callbackObject, config, context }` | `{ token, expirationInSeconds?, refreshToken?, connectionIdentityName?, connectionIdentityImageURL?, overwrite?, userData? }` |
26
+ | `refreshToken` | `{ refreshToken, config, context }` | `{ token, expirationInSeconds?, refreshToken? }` |
27
+
28
+ ## Using OAuth in handlers
29
+
30
+ `oauth` derives only from the `oauth-access-token` header → `oauth = { accessToken, token? }` (`token` =
31
+ `deserializeToken(accessToken)`). Per-op opt-in for extra scopes: set `oauth2Scopes: ['extra.scope']` on
32
+ any action, **polling** trigger, or dictionary.
33
+
34
+ `token` is the one slot in the handler bag left open rather than inferred: `setupOauth2` runs after
35
+ `createExtension` has already resolved the service shape, so a `deserializeToken` return cannot flow back
36
+ into every handler. Annotate it where you read it if the composite shape matters.
37
+
38
+ > Scopes declared on a **realtime** trigger are currently **not** collected into the authorize URL — the
39
+ > runtime unions `scopes` with the `oauth2Scopes` of actions, polling triggers and dictionaries only. Put a
40
+ > realtime trigger's scopes in the extension-level `scopes` instead.
41
+
42
+ Client id/secret are typically `configItems` marked `.shared()` (see [02-zod-types.md](02-zod-types.md)).