@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,361 @@
1
+ # 15 — Unit Tests
2
+
3
+ `flowrunner init` copied a unit-test harness into this project. This document is what it is and how to write
4
+ a suite against it.
5
+
6
+ The scope is deliberately narrow: **HTTP is mocked at the socket and nothing leaves the process.** There is
7
+ no live-API test kind here — validating a service against the real vendor means deploying it and running a
8
+ flow. What a unit suite is for is everything you can check without that: the request the service actually
9
+ sends, what it does with the answer, and what it does when the answer is a failure.
10
+
11
+ ## What is in the project
12
+
13
+ ```
14
+ jest.config.js the runner: one suite per service
15
+ jest.setup.js silences console output during a run
16
+ sandbox/
17
+ index.js the five exports below
18
+ service.js runServiceMethod, getServiceConfigItems, getServiceDefinition
19
+ nock-mock.js createNockMock — wire-level intercept + a history of every call
20
+ files-mock.js createFilesSandbox — a real Files API over local storage
21
+ services/{id}/tests/{id}.test.js one suite per service
22
+ ```
23
+
24
+ ```bash
25
+ npm test # every suite
26
+ npx jest services/{id}/tests # one service
27
+ npx jest services/{id}/tests -t 'getItems'
28
+ npm run test:coverage
29
+ ```
30
+
31
+ **The harness is yours.** It was copied in, not linked, and nothing overwrites it — a service wrapping an
32
+ awkward SDK that needs a shim in `nock-mock.js` is a reason to edit `nock-mock.js`. (`flowrunner init` is
33
+ safe to re-run and adds only what is missing, so it will not undo an edit.)
34
+
35
+ ## The five exports
36
+
37
+ There is no sandbox object to build, no `Flowrunner` global to install or clean up, and no service instance:
38
+ `runServiceMethod` owns all of that, per call.
39
+
40
+ | Export | For |
41
+ |---|---|
42
+ | `runServiceMethod(data)` | run one method the way the platform invokes it |
43
+ | `createNockMock()` | intercept and record HTTP at the socket |
44
+ | `createFilesSandbox()` | a real Files API, injected through `createFiles` |
45
+ | `getServiceConfigItems(id, entryPoint)` | the published config descriptions |
46
+ | `getServiceDefinition(id, entryPoint)` | the built model — what the platform can invoke |
47
+
48
+ ### `runServiceMethod`
49
+
50
+ ```js
51
+ const result = await runServiceMethod({
52
+ serviceId,
53
+ serviceEntryPointPath,
54
+ configs: { apiKey: 'test-api-key' }, // your configItems values, in ONE bag
55
+ methodName: 'getItems',
56
+ methodData: { limit: 10 }, // keyed by PARAM NAME
57
+ // A dictionary's one declared param is `payload`: methodData: { payload: { search, cursor, criteria } }
58
+ // — see the dictionary recipe in 18-test-recipes.md.
59
+ executionContext: { accessToken: 'test-oauth-access-token' }, // OAuth services only
60
+ })
61
+ ```
62
+
63
+ It resolves `methodName` in the built definition and assembles the handler's input from `methodData` **by
64
+ declared param name**, exactly as the platform does. Order in `methodData` never matters — which is what
65
+ makes a suite able to catch a param whose declared name disagrees with what the handler reads: the value
66
+ arrives `undefined` rather than arriving in the wrong slot.
67
+
68
+ A name that is not in the definition throws, naming the ones that are. That is a feature: a method the
69
+ platform cannot invoke is one no flow can reach.
70
+
71
+ The rest of `executionContext` is filled with stable `test-*` values you can assert against — `appId`,
72
+ `apiKey`, `serverURL`, `flowId`, `executionId`, `runtimeKey`.
73
+
74
+ ### `getServiceDefinition` — what to cover
75
+
76
+ `methodsMap` is every method the platform can invoke, and each entry's `registerAs` says what kind it is:
77
+
78
+ | `registerAs` | Registered by | The suite's group |
79
+ |---|---|---|
80
+ | `ACTION` | `ext.addAction(...)` | `Actions` |
81
+ | `DICTIONARY` | `ext.dictionary(...)` | `Dictionaries` |
82
+ | `POLLING_TRIGGER` | `ext.addPollingTrigger(...)` | `Polling Triggers` |
83
+ | `REALTIME_TRIGGER` | `ext.addRealtimeTrigger(...)` | `RealTime Triggers` |
84
+ | `SAMPLE_RESULT_LOADER` | a `result` declared as a function | `DynamicResults` |
85
+ | `PARAM_SCHEMA_DEFINITION` | `dynamicParams` | `DynamicParams` |
86
+ | `SYSTEM` | the runtime — trigger and OAuth seams | **no group of its own** — see below |
87
+
88
+ **A SYSTEM method never gets its own `describe`.** `handleTriggerResolveEvents`,
89
+ `handleTriggerSelectMatched`, `handleTriggerUpsertWebhook`, `handleTriggerDeleteWebhook` and
90
+ `handleTriggerPollingForEvent` are the *transport* the platform uses to reach a trigger — they are not
91
+ features, and a group named after one describes nothing a flow author would recognize. Exercise each of them
92
+ **inside the `describe` of the specific trigger it is driving** — `onMessage`, `onChannelPost`,
93
+ `onChatJoinRequest` — so every test reads as a statement about that trigger. OAuth SYSTEM methods are the
94
+ exception and keep the `OAuth` group, having no trigger to belong to.
95
+
96
+ Enumerate it rather than reading the source by eye:
97
+
98
+ ```js
99
+ // scratch.js, in the project root — run it, read it, delete it
100
+ const path = require('path')
101
+ const { getServiceDefinition } = require('./sandbox')
102
+
103
+ const definition = getServiceDefinition('todos', path.resolve('services/todos/src/index.js'))
104
+
105
+ for (const [name, method] of Object.entries(definition.methodsMap)) {
106
+ console.log(method.registerAs.padEnd(24), name)
107
+ }
108
+ ```
109
+
110
+ ## The HTTP mock
111
+
112
+ `createNockMock()` intercepts at the **socket**, so whatever the service used to send — `Flowrunner.Request`
113
+ ([04-http-requests.md](04-http-requests.md)), the file client, a bundled npm SDK — is recorded
114
+ identically, and a test never has to know which.
115
+
116
+ ```js
117
+ let httpMock
118
+ beforeAll(() => { httpMock = createNockMock() })
119
+ afterEach(() => { httpMock.reset() }) // drops recorded calls AND handlers
120
+ afterAll(() => { httpMock.dispose() }) // un-patches `http` — see below
121
+ ```
122
+
123
+ ```js
124
+ httpMock.onGet(url).reply({ items: [] }) // 200 + body
125
+ httpMock.onPost(url).reply(body, 201, headers) // explicit status / response headers
126
+ httpMock.onPut · onPatch · onDelete · onHead · onOptions
127
+ httpMock.on('propfind', url).reply(xmlString) // custom verbs
128
+ httpMock.onGet(url).replyWith(call => ({ … })) // dynamic: receives the history record
129
+ httpMock.onPost(url).replyWithError({ message: 'Nope' }, 422) // an error RESPONSE
130
+ httpMock.onGet(url).replyWithNetworkError('ECONNRESET') // a TRANSPORT failure
131
+ ```
132
+
133
+ Handlers match in registration order, first wins. A URL registered without a query string matches whatever
134
+ query the service added; one registered with a query string matches only that exact query.
135
+
136
+ > **`dispose()` is not optional.** nock patches the shared `http` module when it activates, and jest gives
137
+ > every test file its own module registry — its own copy of nock — but one `http`. A suite that skips
138
+ > `dispose()` leaves its activation stacked on `http` for the rest of the worker, and the layers corrupt
139
+ > each other: request bodies that vanish from `history`, wrappers left pointing into a torn-down realm
140
+ > throwing `Cannot convert undefined or null to object` with an empty stack. The damage lands on whichever
141
+ > suite runs *next*, which is why the symptom is "passes alone, fails in a full run".
142
+
143
+ **Test both failure kinds.** An error response and a dropped connection reach the service differently — the
144
+ first as a `ResponseError` with `status` and `body`, the second with neither — and services routinely handle
145
+ one and not the other. An SDK that wraps its own transport may never see the network-error sentinel; when
146
+ that happens, assert only that the method rejects and say in a comment why the message is not pinned.
147
+
148
+ ### The history record
149
+
150
+ ```js
151
+ expect(httpMock.history).toEqual([{
152
+ method: 'post',
153
+ url: `${ BASE }/sms/send`,
154
+ canonicalUrl: `${ BASE }/sms/send`, // scheme + host + path, no query
155
+ fullUrl: `${ BASE }/sms/send`, // with query string
156
+ headers: { 'Authorization': `Bearer ${ API_KEY }`, 'Content-Type': 'application/json' },
157
+ query: {},
158
+ body: { messages: [{ to: '+1', body: 'Hi' }] },
159
+ formData: undefined,
160
+ contentType: 'application/json',
161
+ contentLength: 38,
162
+ timeout: undefined,
163
+ }])
164
+ ```
165
+
166
+ Compare it whole. A field-by-field assertion checks what you already suspected; the whole-object compare is
167
+ what catches the field you did not know the service was sending.
168
+
169
+ Three things the wire flattens, and they are all assertion traps:
170
+
171
+ - **`query` values are re-typed by shape**, because a query string carries no types. `?limit=100&flag=true`
172
+ reads back as `{ limit: 100, flag: true }` — and an id sent as the string `'123'` reads back as `123`.
173
+ Assert the coerced value.
174
+ - **Header names come back in conventional casing.** The client lowercases them on the way out, so the mock
175
+ re-derives them: `X-Token` round-trips, `X-API-KEY` comes back as `X-Api-Key`.
176
+ - **`contentLength` is not guessable.** Write the assertion, run it, take the real number from the diff. It
177
+ varies by method and body shape — a bodyless POST is often `0`, a bodyless GET often `undefined`.
178
+
179
+ The record has no `encoding`, no `unwrapBody` and no `toBuffer`: all three are client-side response flags
180
+ with no wire footprint, so a socket-level mock cannot see them. To pin a binary path, reply with known bytes
181
+ and assert those exact bytes arrive — with `.toBuffer()` the assertion is on the resolved value, which is a
182
+ `Buffer` byte for byte, including when the reply happens to be valid JSON
183
+ ([04-http-requests.md](04-http-requests.md)).
184
+
185
+ ### Multipart uploads
186
+
187
+ `formData` and `body` are mutually exclusive: when the request is `multipart/form-data` the mock parses the
188
+ parts into `formData` and leaves **`body: undefined`**.
189
+
190
+ ```js
191
+ expect(httpMock.history).toEqual([{
192
+ method : 'post',
193
+ url : `${ BASE }/sendPhoto`,
194
+ // …
195
+ body : undefined,
196
+ formData: { _fields: [
197
+ { name: 'chat_id', value: '-1001234567890', filename: undefined, contentType: undefined },
198
+ { name: 'photo', value: Buffer.from([0x89, 0x50, 0x4e, 0x47]), filename: 'shot.png', contentType: 'image/png' },
199
+ ] },
200
+ contentType : expect.stringMatching(/^multipart\/form-data; boundary=/),
201
+ contentLength: 444,
202
+ timeout : undefined,
203
+ }])
204
+ ```
205
+
206
+ - A **text part** arrives as a string, with `filename` and `contentType` `undefined`. Numbers the service
207
+ appended arrive as strings — the wire has no types.
208
+ - A **binary part** arrives as a **Buffer**, byte-exact, carrying the `filename` and `contentType` the service
209
+ passed in the part's options ([04-http-requests.md](04-http-requests.md)).
210
+ - A part the service passed as a **`Blob`** is no different on the record — the bytes arrive as a `Buffer`,
211
+ with `filename` taken from `blob.name` (`'blob'` when it has none) and `contentType` from `blob.type`
212
+ (`undefined` when it has none).
213
+
214
+ **Assert the bytes literally** — `value: Buffer.from([0x89, 0x50, 0x4e, 0x47])`, not a length and not
215
+ `expect.any(Buffer)`. Reply to the file fetch with a short recognizable sequence so the comparison stays
216
+ readable. The per-part `contentType` is a deliberate choice by the service and nothing else on the record
217
+ exposes it, so pin it too.
218
+
219
+ The `boundary` is random per request, so match `contentType` with `expect.stringMatching(...)`. Its *length*
220
+ is fixed, so `contentLength` is still a stable number — take it from the diff as usual.
221
+
222
+ > **An empty `_fields` means the service sent nothing.** This is the assertion that catches a request built
223
+ > with `.form(data)` and then `.send()`-ed, which goes out with no body at all
224
+ > ([04-http-requests.md](04-http-requests.md)). Because that failure is silent at the transport level
225
+ > and only shows up as a confusing 400 from the vendor, a multipart action is not covered until a test pins
226
+ > the parts.
227
+ >
228
+ > If a part you expect is missing, check the harness before rewriting the service: `nock` hands the reply
229
+ > callback a **string**, and a body that is not valid UTF-8 — any real binary upload — arrives **hex-encoded**.
230
+ > `sandbox/nock-mock.js` hex-decodes it (`multipartText`) before parsing; a harness without that step reports
231
+ > `{ _fields: [] }` for a perfectly correct upload.
232
+
233
+ ## A suite
234
+
235
+ ```js
236
+ 'use strict'
237
+
238
+ const { createNockMock, getServiceConfigItems, runServiceMethod } = require('../../../sandbox')
239
+
240
+ const API_KEY = 'test-api-key'
241
+ const BASE = 'https://api.example.com/v1'
242
+ const HEADERS = { 'Authorization': `Bearer ${ API_KEY }`, 'Content-Type': 'application/json' }
243
+
244
+ describe('ServiceName Service', () => {
245
+ const serviceId = 'service-name'
246
+ const serviceEntryPointPath = require.resolve('../src/index.js')
247
+
248
+ let httpMock
249
+
250
+ const configs = { apiKey: API_KEY }
251
+
252
+ function runMethod({ methodName, methodData, data }) {
253
+ return runServiceMethod({ serviceId, serviceEntryPointPath, configs, ...data, methodName, methodData })
254
+ }
255
+
256
+ beforeAll(() => { httpMock = createNockMock() })
257
+ afterEach(() => { httpMock.reset() })
258
+ afterAll(() => { httpMock.dispose() })
259
+
260
+ it('service config items', () => {
261
+ expect(getServiceConfigItems(serviceId, serviceEntryPointPath)).toEqual([
262
+ {
263
+ name: 'apiKey', label: 'API Key', type: 'string',
264
+ required: true, shared: false, options: [],
265
+ description: 'Your API key, from Settings → Developers.',
266
+ },
267
+ ])
268
+ })
269
+
270
+ describe('Actions', () => {
271
+ describe('getItems', () => {
272
+ // One shortcut per describe, naming the method once.
273
+ function runGetItemsMethod(limit, offset, data) {
274
+ return runMethod({ methodName: 'getItems', methodData: { limit, offset }, data })
275
+ }
276
+
277
+ it('sends the defaults when no parameters are supplied', async () => {
278
+ httpMock.onGet(`${ BASE }/items`).reply({ items: [], total: 0 })
279
+
280
+ const result = await runGetItemsMethod()
281
+
282
+ expect(result).toEqual({ items: [], total: 0 })
283
+
284
+ expect(httpMock.history).toEqual([{
285
+ method: 'get',
286
+ url: `${ BASE }/items`,
287
+ canonicalUrl: `${ BASE }/items`,
288
+ fullUrl: `${ BASE }/items?limit=50&offset=0`,
289
+ headers: HEADERS,
290
+ query: { limit: 50, offset: 0 },
291
+ body: undefined,
292
+ formData: undefined,
293
+ contentType: undefined,
294
+ contentLength: 0,
295
+ timeout: undefined,
296
+ }])
297
+ })
298
+
299
+ // The `data` argument is how a suite proves auth is read from config rather than hardcoded.
300
+ it('reads the key from config rather than a hardcoded one', async () => {
301
+ httpMock.onGet(`${ BASE }/items`).reply({ items: [], total: 0 })
302
+
303
+ await runGetItemsMethod(undefined, undefined, { configs: { apiKey: 'other-key' } })
304
+
305
+ expect(httpMock.history[0].headers.Authorization).toBe('Bearer other-key')
306
+ })
307
+
308
+ it('rejects when the API answers with an error status', async () => {
309
+ httpMock.onGet(`${ BASE }/items`).replyWithError({ message: 'Unauthorized' }, 401)
310
+
311
+ await expect(runGetItemsMethod()).rejects.toThrow()
312
+ })
313
+
314
+ it('rejects when the connection drops', async () => {
315
+ httpMock.onGet(`${ BASE }/items`).replyWithNetworkError('ECONNRESET')
316
+
317
+ await expect(runGetItemsMethod()).rejects.toThrow()
318
+ })
319
+ })
320
+ })
321
+ })
322
+ ```
323
+
324
+ Nesting is fixed: `describe('<Service> Service')` → `describe('<Group>')` → `describe('<methodName>')` →
325
+ `it(...)`. Groups come from `registerAs`, never from subject matter — `sendPhoto` and `getChannel` are both
326
+ `Actions`.
327
+
328
+ ## Choices — the test that is almost always missing
329
+
330
+ A label→wire mapping must guard its lookup with `Object.prototype.hasOwnProperty.call(mapping, value)`, or
331
+ `'constructor'` / `'toString'` / `'__proto__'` resolve to an inherited **function** and are sent as a
332
+ parameter value. Asserting only the matching side never catches that — a known label maps identically either
333
+ way. What catches it is a wire-level assertion on a pass-through choice:
334
+
335
+ ```js
336
+ it('passes an unrecognized choice through as itself, even an inherited property name', async () => {
337
+ httpMock.onGet(url).reply({})
338
+
339
+ await runListThingsMethod(undefined, 'constructor')
340
+
341
+ expect(httpMock.history[0].query).toEqual({ order: 'constructor' }) // a literal string, not a function
342
+ })
343
+ ```
344
+
345
+ ## Per kind — dictionaries, triggers, files
346
+
347
+ Recipes for the kinds a service may or may not have are
348
+ **[18-test-recipes.md](18-test-recipes.md)**. Load it for the kinds this service actually registers,
349
+ alongside this document — a suite for an actions-only service does not need it at all.
350
+
351
+ ## What not to do
352
+
353
+ | | Why |
354
+ |---|---|
355
+ | `require()` the service entry file, or touch `global.Flowrunner` | Behaviour unreachable through a method call is not the service's contract |
356
+ | `jest.mock` a transport, or hand-write a fake client | The socket-level mock records what the service *sent*; a fake records what you expected it to send |
357
+ | `it.each`, or `expect` inside a loop | N results collapse into one unreadable failure |
358
+ | A catch-all `onAny()` handler | Every method under test calls a known URL; a catch-all only hides a wrong one |
359
+ | `toHaveProperty` / `toContain` as a default | They assert what you already suspected |
360
+ | Test that the vendor's API returns correct data | That is what deploying and running a flow is for |
361
+ | Change the service to make a test pass | A green test asserting a bug reads as "this is correct" — leave the path untested and report it |
@@ -0,0 +1,201 @@
1
+ # 16 — Gotchas
2
+
3
+ Cross-cutting traps that produce **silent** bugs — a service that builds, passes an obvious test, and is
4
+ wrong on the wire. Each one below has shipped at least once. This document is deliberately short; read it
5
+ in full.
6
+
7
+ ## An empty string is a value, not an absence
8
+
9
+ Request bodies are usually built by dropping unset params. Drop only `undefined` and `null`:
10
+
11
+ ```js
12
+ const prune = obj => Object.fromEntries(
13
+ Object.entries(obj).filter(([, v]) => v !== undefined && v !== null)
14
+ )
15
+ ```
16
+
17
+ Filtering on falsiness instead — `.filter(([, v]) => v)` or `if (!value) return` — also drops `''`, `0` and
18
+ `false`, and each of those is a legitimate value some API expects. The common casualty is **clearing a
19
+ field**: many APIs clear a description, a caption or a title by receiving an explicit empty string, so a body
20
+ builder that prunes `''` makes the documented "leave it blank to clear it" behaviour unreachable, with no
21
+ error anywhere.
22
+
23
+ **The inverse is equally sharp, and appears the moment you fix the first half.** Once `''` reaches the wire,
24
+ every optional string param sends one when the flow author leaves it blank — and for an API where an absent
25
+ field means *keep the current value*, a blank one now **overwrites** it. Copy/duplicate endpoints are the
26
+ usual place this bites: an absent caption keeps the original, an empty caption erases it.
27
+
28
+ So the rule is two-sided:
29
+
30
+ - Prune only `undefined` / `null` — never on falsiness.
31
+ - Then, per param, decide what blank *means*. Where blank means "don't send", convert it at the call site
32
+ with `params.caption || undefined`, and say so in a comment. Where blank means "clear it", let it through.
33
+
34
+ There is no safe global default here; it is a per-parameter decision that has to come from the vendor's
35
+ documentation.
36
+
37
+ ### The same `''` fails a format-constrained field
38
+
39
+ Because `''` is a value, it reaches the format check and fails it — and `.optional()` does not help, since
40
+ the field WAS provided. A cleared text box is what sends it, so this fires the first time a flow author
41
+ leaves an optional URL or email blank:
42
+
43
+ ```js
44
+ webhookUrl: z.url().optional().label('Webhook URL') // blank → «Webhook URL» is invalid — expects a URL
45
+ webhookUrl: z.union([z.url(), z.literal('')]).optional().label('Webhook URL') // blank → not provided
46
+ ```
47
+
48
+ Declare the union wherever blank has to mean "not set". A non-empty value still has to satisfy the format.
49
+
50
+ ## Guard a lookup table keyed by user input
51
+
52
+ An object literal used as a lookup table inherits from `Object.prototype`, so a key like `constructor`,
53
+ `__proto__`, `toString` or `hasOwnProperty` resolves to something that is not your data:
54
+
55
+ ```js
56
+ const MIME_BY_EXT = { png: 'image/png', pdf: 'application/pdf' }
57
+ MIME_BY_EXT['constructor'] // → function Object() { [native code] }
58
+ ```
59
+
60
+ When the key comes from a filename, a param, or an API response, that value goes straight onto the wire — a
61
+ file named `notes.constructor` produced a real `Content-Type: function Object() { [native code] }` header.
62
+ `??` does not save you, because the inherited value is neither `undefined` nor `null`.
63
+
64
+ Keep the table a plain object literal and **guard the read**:
65
+
66
+ ```js
67
+ const MIME_BY_EXT = {
68
+ png: 'image/png',
69
+ pdf: 'application/pdf',
70
+ }
71
+
72
+ const mime = Object.hasOwn(MIME_BY_EXT, ext) ? MIME_BY_EXT[ext] : 'application/octet-stream'
73
+ ```
74
+
75
+ One guard at the point of the lookup is the whole fix. Do not reach for `Object.create(null)` or
76
+ `Object.assign(Object.create(null), { … })` to build the table — it makes every declaration in the file
77
+ harder to read in order to defend a single line, and the line is where the defence belongs.
78
+
79
+ The same applies to a computed *write* (`out[key] = value`): a `__proto__` key assigns a prototype rather
80
+ than an own property. That is only reachable if the keys come from data, so prefer building bodies from
81
+ literal names rather than spreading a params object or an API response into one.
82
+
83
+ ## A dictionary's empty list must mean "nothing matched"
84
+
85
+ [05-dictionaries.md](05-dictionaries.md) is explicit that **unresolvable input** returns
86
+ `{ items: [], cursor: null }` rather than throwing. It is easy to over-apply that into a bare `try/catch`
87
+ around the whole handler, which then reports a 401, a 403 or a dropped connection as an empty dropdown. The
88
+ flow author sees a list with nothing in it and no way to learn that their credentials are wrong.
89
+
90
+ Only the *input* half is an empty list. Split it on what the API is telling you:
91
+
92
+ - **The value does not exist or is not visible** — typically `400`/`404`, e.g. `chat not found`,
93
+ `user not found`, `invalid file_id` — return the empty list.
94
+ - **The request could not be made** — `401`, `403`, `429`, `5xx`, transport failure — let the normalized
95
+ error propagate.
96
+
97
+ A **browse** path deserves more suspicion than a resolve path: where the endpoint always returns at least one
98
+ row, an empty list has no legitimate reading at all, so catching there hides every failure and helps nothing.
99
+
100
+ ## Normalize once, at the point of derivation
101
+
102
+ `initContext` routinely cleans a config value — trimming a pasted token, coercing a numeric string, defaulting
103
+ a blank. The cleaned copy then lives in `context` **alongside** the raw one in `config`, and both are in every
104
+ handler's bag. Derive the same thing from each and you get two different answers:
105
+
106
+ ```js
107
+ initContext: ({ config }) => ({ token: String(config.botToken ?? '').trim() }),
108
+
109
+ // one side signs with the trimmed token…
110
+ subscribe : ({ context }) => register({ secret: secretOf(context.token) }),
111
+ // …the other verifies with the raw one
112
+ verifyRequest: ({ config, rawBody }) => check(rawBody, secretOf(config.botToken)),
113
+ ```
114
+
115
+ With a clean value the two agree and every test passes. With a token pasted carrying a trailing space they
116
+ diverge, and the failure is **silent and total**: the webhook registers fine, every delivery is rejected, and
117
+ nothing is logged anywhere. It surfaces as "the trigger just never fires", in one workspace, after deploy.
118
+
119
+ The fix is not to pick the same field at both call sites — a later edit re-introduces the split. **Normalize
120
+ inside the shared derivation**, so no caller can get it wrong:
121
+
122
+ ```js
123
+ function secretOf(token) {
124
+ return hmac(String(token ?? '').trim(), …) // both call sites now collapse to one string
125
+ }
126
+ ```
127
+
128
+ The general rule: when one value is reachable in more than one form, either derive from it in exactly one
129
+ place, or make the derivation itself idempotent to the difference. This applies to anything `initContext`
130
+ touches — a base URL with or without a trailing slash, an id as a string or a number.
131
+
132
+ ## A schema slot must be a `z.object`, or the method quietly has no inputs
133
+
134
+ `params`, `criteria` and `configItems` are containers of named fields. Hand one anything else and there is
135
+ nothing to iterate:
136
+
137
+ ```js
138
+ params: { chatId: z.string() } // ✗ a plain object — no z.object(...) around it
139
+ params: z.string() // ✗ a single field where a container belongs
140
+ ```
141
+
142
+ Both used to sail through. The method published **no** params, the node rendered with no inputs, validation
143
+ became a passthrough, and the service deployed clean — the failure surfaced later, as an action that could
144
+ not be called correctly. The runtime now rejects it at registration with `FR_EXT_INVALID_SCHEMA`, naming the
145
+ item and the slot, so `flowrunner deploy` stops instead.
146
+
147
+ The trap that survives the guard is the *shape* of optionality:
148
+
149
+ ```js
150
+ params: z.object({ chatId: z.string() }).optional() // ✗ the CONTAINER cannot be optional
151
+ params: z.object({ chatId: z.string().optional() }) // ✓ the FIELDS are optional
152
+ ```
153
+
154
+ A wrapped container has no `.shape`, so every field inside it would be invisible. If the method takes no
155
+ input at all, omit `params` entirely, or declare `z.object({})` — see [03-parameters.md](03-parameters.md).
156
+
157
+ ## An inbound delivery is answered once — a throw is a 500
158
+
159
+ `handleTriggerResolveEvents` is **not retried**. Every other trigger request type — `subscribe`,
160
+ `refresh`, `unsubscribe`, `selectMatched`, polling — is attempted up to 5 times; this one is attempted once,
161
+ because a retry is not a recovery here. The usual failure on this path is the service *rejecting* the
162
+ payload, which is never transient, and retrying re-ran the handler five times over a delivery it had just
163
+ declined.
164
+
165
+ Two consequences for anything you write in `handshake`, `resolveEvents` or `verifyRequest`:
166
+
167
+ - **Never reject by throwing.** A throw answers the provider `500`, which fails the vendor's endpoint
168
+ validation and, for a forged delivery, hides a rejection behind what looks like an outage. Return
169
+ `responseToWebhook` instead ([09-realtime-triggers.md](09-realtime-triggers.md#responsetowebhook--answering-the-provider)).
170
+ - **A transient error is yours to absorb.** If a call inside this seam can fail and succeed on a second
171
+ attempt, retry it in the handler — nothing upstream will.
172
+
173
+ ## Do not hedge against an unclear runtime contract
174
+
175
+ When a runtime behaviour is not documented in [13-runtime-contracts.md](13-runtime-contracts.md), the
176
+ tempting move is defensive code that tries to work either way — feature-detecting a method, tolerating two
177
+ shapes. **That hedge is how a silent bug gets written**: it looks careful, it type-checks, and it picks the
178
+ wrong branch without complaining.
179
+
180
+ Establish the fact instead. A scratch script against `flowrunner-cli/runtime` settles most runtime questions
181
+ in a minute (see [13-runtime-contracts.md](13-runtime-contracts.md) for the pattern and the reload caveat),
182
+ and a local `http` server settles any question about what actually goes out on the wire. Then write the one
183
+ branch that is true — and add the fact to 13, which is the fix that stops the next service repeating it.
184
+
185
+ ## Where a fact already lives
186
+
187
+ Do not restate these here; they are covered where they belong.
188
+
189
+ | Trap | Document |
190
+ |---|---|
191
+ | A dependency installed at the **project root** is not deployed — install it in `services/{id}/` | [01-service-structure.md](01-service-structure.md) |
192
+ | `.form(data)` only stages a body; `.send()` after it issues an empty request | [04-http-requests.md](04-http-requests.md) |
193
+ | A `Blob` appended straight to `Request.FormData` throws `source.on is not a function` — pass it to `.form()` | [04-http-requests.md](04-http-requests.md) |
194
+ | A binary download is `.toBuffer()`, not a response encoding — an encoded body is parsed and corrupted | [04-http-requests.md](04-http-requests.md) |
195
+ | `ResponseError.message` is the response *body*, so it can be an object | [04-http-requests.md](04-http-requests.md) |
196
+ | A blank (`''`) fails `z.url().optional()` — `.optional()` does not cover it | this document |
197
+ | `.default()` is not applied to realtime-trigger `match` params | [13-runtime-contracts.md](13-runtime-contracts.md) |
198
+ | `rawBody` is **absent**, not empty, when there is nothing to verify — hashing `''` looks like a bad signature | [09-realtime-triggers.md](09-realtime-triggers.md) |
199
+ | `FLOW`/`EXECUTION` file scopes fail in a method that runs outside a flow execution | [10-files-api.md](10-files-api.md) |
200
+ | Unresolvable dictionary *input* is an empty list, not an error | [05-dictionaries.md](05-dictionaries.md) |
201
+ | `dynamicParams.resolve()` must return a `z.object` — checked when the loader runs, not at load | [03-parameters.md](03-parameters.md) |