@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
package/README.md ADDED
@@ -0,0 +1,148 @@
1
+ # flowrunner-cli
2
+
3
+ **[FlowRunner](https://flowrunner.ai/)** is the orchestration layer for AI agents in production. Model
4
+ providers and tools arrive as verified connectors, flows are built no-code or in code, and an agent facing a
5
+ consequential decision pauses for a human instead of guessing — human-in-the-loop by design, with an audit
6
+ trail to match.
7
+
8
+ This package is the `flowrunner` CLI: author and deploy **custom extensions** — your own connectors — from
9
+ your own repository. It builds every service definition locally and uploads it with the package, so the
10
+ server never has to execute extension code to model it.
11
+
12
+ ## Install
13
+
14
+ ### A new project — `npx`, once
15
+
16
+ `init` installs the CLI into the project it creates, so the only command you need `npx` for is the very
17
+ first one:
18
+
19
+ ```bash
20
+ npx flowrunner-cli init # set up the project in the current directory
21
+ npx flowrunner-cli init -d my-extensions # ...or in ./my-extensions, creating it if needed
22
+ npx flowrunner-cli init blank # ...and scaffold a first service from a template
23
+ ```
24
+
25
+ Then work inside the project, where `flowrunner` is already available:
26
+
27
+ ```bash
28
+ cd my-extensions
29
+ flowrunner --help
30
+ ```
31
+
32
+ ### An existing project — `npm install`
33
+
34
+ Add the CLI to a repository you already have, then set it up in place:
35
+
36
+ ```bash
37
+ npm install --save-dev flowrunner-cli
38
+ flowrunner init
39
+ ```
40
+
41
+ `init` never overwrites: files that already exist are left alone, so adding FlowRunner to an existing
42
+ repository is the same operation as starting from nothing, minus the files that are already there.
43
+
44
+ ## Quick start
45
+
46
+ ```bash
47
+ npx flowrunner-cli init -d my-extensions blank # project + first service, npm install, git repo
48
+ cd my-extensions
49
+ flowrunner login # browser authorization → .flowrunner/token
50
+ flowrunner deploy # discover → model → hash → zip → upload
51
+ ```
52
+
53
+ ## Commands
54
+
55
+ | Command | Purpose |
56
+ |---|---|
57
+ | `flowrunner init [template]` | Create the project: `package.json`, `flowrunner.json`, `.gitignore`, `README.md`, the unit-test harness, git repo, optional first service |
58
+ | `flowrunner init-claude` | Install the FlowRunner subagents into `.claude/agents/` and add a block to `CLAUDE.md` |
59
+ | `flowrunner use [target]` | Point the project at a cluster — `prod`, `dev`, `local`, or a full URL. Omit to list them |
60
+ | `flowrunner login` | Browser-based authorization; stores the deploy token and `workspaceId` |
61
+ | `flowrunner logout` | Revoke the token server-side and delete it locally |
62
+ | `flowrunner create-service [template]` (`cs`) | Scaffold a service into `services/` from a bundled template |
63
+ | `flowrunner deploy` | Deploy every service in `services/` to the connected workspace |
64
+
65
+ Common flags: `-y, --yes` (accept every default, ask nothing), `--id` / `--name` / `--set name=value`
66
+ (answer template prompts non-interactively), `-s, --server <target>` on `init` and `login`,
67
+ `--no-install` / `--no-git` / `--no-tests` on `init`, `--list` on `create-service`.
68
+
69
+ Every command works non-interactively — prompts appear only on a TTY, and anything unanswerable becomes an
70
+ error with a stable code rather than a hang.
71
+
72
+ ## Testing
73
+
74
+ `init` puts a unit-test harness in the project — `sandbox/` at the root, a jest config, and one suite per
75
+ service in `services/{id}/tests/`:
76
+
77
+ ```bash
78
+ npm test # every suite
79
+ npx jest services/weather/tests # one service
80
+ ```
81
+
82
+ A suite runs your service through the **real** runtime, with HTTP intercepted at the socket, so what it
83
+ asserts on is what the pod would have sent — the request, the headers, the query, the body. Nothing reaches
84
+ the network.
85
+
86
+ ```js
87
+ const { createNockMock, getServiceConfigItems, runServiceMethod } = require('../../../sandbox')
88
+
89
+ httpMock.onGet(`${ BASE }/current`).reply({ temp_c: 21.4 })
90
+
91
+ const result = await runServiceMethod({
92
+ serviceId, serviceEntryPointPath, configs: { apiKey: 'test-key' },
93
+ methodName: 'getCurrent', methodData: { city: 'Lisbon' },
94
+ })
95
+
96
+ expect(httpMock.history[0].query).toEqual({ q: 'Lisbon', key: 'test-key' })
97
+ ```
98
+
99
+ The harness is **copied** into the project, not linked, so it is yours to edit — and `init` never overwrites
100
+ it. Running `flowrunner init` again in an existing project is how a project created before the harness
101
+ existed gets one. `--no-tests` skips it.
102
+
103
+ The full guide is in `node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/15-unit-tests.md`.
104
+
105
+ ## Writing services with an AI agent
106
+
107
+ This package ships the authoring reference itself, under
108
+ `node_modules/flowrunner-cli/ai-docs/instructions/service-code-format/`. That location is the point: the
109
+ instructions your agent reads are pinned to the CLI version your project installed, so they describe the
110
+ format this CLI actually deploys rather than whatever a model remembers about it.
111
+
112
+ Point your agent at that path however your tool expects, or use the command for it. There is one per
113
+ provider, because every provider differs on which file it reads and where subagents live — Claude Code reads
114
+ `CLAUDE.md` and ignores `AGENTS.md`, so there is no single file `init` could write for everyone.
115
+
116
+ ### Claude Code
117
+
118
+ ```bash
119
+ flowrunner init-claude
120
+ ```
121
+
122
+ Two things happen:
123
+
124
+ - **`.claude/agents/` gets two subagents.** `flowrunner-service-code-engineer` creates, reviews and fixes
125
+ services, and keeps each one's README in step. `flowrunner-service-test-engineer` writes the unit suites
126
+ against the harness above. Both already know the format, so you don't re-explain it every session — and
127
+ they are separate on purpose: an engineer that owns both a service and its tests ends up fixing the
128
+ service to make its own test pass.
129
+ - **`CLAUDE.md` gets a block** telling Claude the agents exist, when to reach for each, and where the
130
+ authoring reference lives.
131
+
132
+ It is safe to run over a `CLAUDE.md` you already have. The command owns exactly the region between its own
133
+ markers:
134
+
135
+ ```md
136
+ # Our own house rules ← yours, never touched
137
+
138
+ <!-- flowrunner-cli:ai:start -->
139
+ ...the FlowRunner block... ← the CLI's, replaced on every run
140
+ <!-- flowrunner-cli:ai:end -->
141
+
142
+ # More of our rules ← also yours, also never touched
143
+ ```
144
+
145
+ Re-run it after upgrading the CLI and only that block changes — nothing is duplicated, and everything outside
146
+ the markers survives byte-for-byte. The `flowrunner-*` files under `.claude/agents/` are the CLI's and *are*
147
+ overwritten, which is how an upgrade ships you a better agent; keep your own agents under your own names and
148
+ they are left alone.
@@ -0,0 +1,180 @@
1
+ # 01 — Service Structure
2
+
3
+ A service is one JavaScript module per folder — `services/{id}/src/index.js` — that calls the global
4
+ `Flowrunner.createExtension(props)` factory and then registers actions / dictionaries / triggers on the
5
+ returned `ext`. Everything is declared through the factory props and zod schemas.
6
+
7
+ ## Folder layout
8
+
9
+ ```
10
+ services/{id}/
11
+ ├── package.json the service's OWN manifest — its dependencies
12
+ ├── package-lock.json
13
+ ├── node_modules/ installed here; ships inside the deployed package
14
+ ├── src/
15
+ │ └── index.js the service module — all logic lives here
16
+ ├── public/
17
+ │ └── icon.svg the logo, and any other publicly served asset
18
+ └── README.md ships with the service (see 12-service-readme.md)
19
+ ```
20
+
21
+ ## A service is its own npm package
22
+
23
+ **`services/{id}/` has its own `package.json`, and dependencies are installed inside it.** The deployed
24
+ package is that folder — its source, its manifest, its `node_modules` — and nothing from the project root
25
+ travels with it.
26
+
27
+ So to add a dependency to a service, install it **in the service's folder**:
28
+
29
+ ```bash
30
+ cd services/{id}
31
+ npm install axios
32
+ ```
33
+
34
+ Installing at the project root instead is the mistake to avoid: the module resolves fine while you are
35
+ testing locally, because node walks up the directory tree — and then the deployed service throws
36
+ `MODULE_NOT_FOUND` at its first execution, because the root `node_modules` was never packed.
37
+
38
+ The project root keeps its own `package.json` for the tooling — the CLI and the test harness. That one is
39
+ not deployed.
40
+
41
+ **The icon belongs in `public/`, not beside `src/`.** Only `public/` is served: the platform exposes it at
42
+ `…/{serviceId}/file/{path}`, rooted at that folder and refusing to escape it. A file at the service root is
43
+ never reachable, so a logo placed there resolves to a 404 and the service renders with no icon — a failure
44
+ that shows up only after deploy, not at build time.
45
+
46
+ `logo` is then the path *within* `public/`. A leading slash is stripped, so `'/icon.svg'` and `'icon.svg'`
47
+ are equivalent and both mean `public/icon.svg`; the leading-slash form is the convention. Subfolders work
48
+ (`'logos/icon.svg'` → `public/logos/icon.svg`). An absolute `https://` URL is **not** supported — the value
49
+ is always resolved against `public/`.
50
+
51
+ Actions and triggers accept their own optional `logo`, resolved the same way, which overrides the service
52
+ logo for that one item. Omit it and the item inherits the service's.
53
+
54
+ ## `Flowrunner.createExtension(props)`
55
+
56
+ | Property | Type | Req | Description |
57
+ |---|---|---|---|
58
+ | `id` | string | ✓ | Stable service id (→ `SharedExtensionServiceInfo.id`). |
59
+ | `name` | string | ✓ | Human display name. |
60
+ | `description` | string | ✓ | Service description. |
61
+ | `logo` | string | ✓ | Icon path, resolved **inside the service's `public/` folder** — see [Folder layout](#folder-layout). |
62
+ | `appearanceColors` | `[string, string]` | – | `[primary, secondary]`. |
63
+ | `usesFileStorage` | boolean | – | `true` provisions `ctx.files`; when false, `ctx.files` is a proxy that throws. Default false. See [10-files-api.md](10-files-api.md). |
64
+ | `configItems` | `z.object` | – | App + shared config (see [02-zod-types.md](02-zod-types.md)). → `appConfigDescriptions` / `sharedConfigDescriptions`. Omit when the service needs none; a plain object of fields is **not** accepted (see [03-parameters.md](03-parameters.md)). |
65
+ | `initContext` | fn | – | `({ config, oauth }) => context`; runs once per invocation. Runs for OAuth flows too (`oauth` may be empty). |
66
+ | `apiRequest` | fn | – | Shared HTTP helper (envelope-unwrap, error-normalize, redacted logging). See [04-http-requests.md](04-http-requests.md). |
67
+ | `helpers` | fn | – | ctx factory `(ctx) => ({ ... })` for **genuinely reusable service logic**; result exposed as `helpers` in every handler bag. `ctx` = `{ config, context, oauth, apiRequest, files, filesScope, logger }` (no `params`). |
68
+
69
+ ```js
70
+ const ext = Flowrunner.createExtension({
71
+ id: 'svc', name: 'Svc', description: '…', logo: '/icon.png', appearanceColors: ['#111','#222'],
72
+ usesFileStorage: false,
73
+ configItems: z.object({ apiKey: z.string().label('API Key') }),
74
+ initContext: ({ config, oauth }) => ({ apiKey: config.apiKey, accessToken: oauth?.accessToken }),
75
+ apiRequest : async ({ url, method = 'get', body, query, context }) =>
76
+ new Flowrunner.Request(url, method, body).set({ Authorization: `Bearer ${ context.apiKey }` }).query(query),
77
+ helpers : ({ apiRequest }) => ({ collectPages: (url) => collectPages(apiRequest, url) }),
78
+ })
79
+ ```
80
+
81
+ ## Identity & naming
82
+
83
+ - Every registered item (action / trigger / dictionary) is keyed by **`id`** (not `name`). `id` is
84
+ persisted and drives execution — once a service is deployed an `id` can never change. `name` is the
85
+ service display label only; per-item human text is `label`.
86
+ - **Ids must be unique across *all* kinds**, not just within one — an action and a dictionary cannot share
87
+ an id, and registration fails with `FR_EXT_DUPLICATE_ITEM_ID` if they do. Generated loader names count
88
+ too: an action `foo` with a loader `result` claims `foo_SampleResultLoader`, and `dynamicParams` claims
89
+ `foo_DynamicParams`, so don't register anything under those names by hand.
90
+ - **A dictionary `id` starts with `get` and ends with `Dictionary`** — `getChatsDictionary`,
91
+ `getBoardsDictionary`. Name the const holding the ref the same as the id, so the declaration and every
92
+ `.dictionary(ref)` read alike.
93
+ - Reused param schemas end `Param` (`appIdParam`).
94
+
95
+ ## `initContext` and `helpers`
96
+
97
+ - `initContext({ config, oauth })` runs once per invocation and returns the `context` object handed to
98
+ every handler — the place to derive base URLs, resolved credentials and anything else every handler needs.
99
+ It also runs during OAuth flows, where `oauth` may be empty.
100
+ - `helpers(ctx)` builds reusable bound helpers exposed as `helpers` in each handler's context bag; its
101
+ `ctx` is `{ config, context, oauth, apiRequest, files, filesScope, logger }` (no `params`).
102
+
103
+ **Put real service logic in `helpers`, not plumbing.** A helper earns its place when several handlers share
104
+ non-trivial behaviour — paging a list endpoint to the end, resolving an id through two calls, normalising a
105
+ paginated envelope. It does **not** earn its place by wrapping something the bag already provides:
106
+
107
+ | ✗ Not a helper | Why |
108
+ |---|---|
109
+ | `call: (method, body) => apiRequest({ url: `/${ method }`, method: 'post', body })` | `apiRequest` is already in every handler bag. A rename adds a layer to read through and hides the URL each action calls. |
110
+ | `upload: (...) => apiRequest(...)` with a form | Same — it is `apiRequest` with a different body. Build the form in the action, or in a module-level function. |
111
+ | `readFile` / `storeFile` wrapping `files.*` | `files` is already in the bag ([10-files-api.md](10-files-api.md)). Wrapping it buys nothing and obscures which scope was used. |
112
+
113
+ If the thing you want to share needs no `ctx` at all, it is not a helper either — make it a module-level
114
+ function (see below).
115
+
116
+ ## Module layout
117
+
118
+ One file, read top to bottom in the order the platform resolves it:
119
+
120
+ ```js
121
+ const z = Flowrunner.z // 1. the zod handle
122
+
123
+ const ext = Flowrunner.createExtension({ … }) // 2. the factory: config, initContext, apiRequest, helpers
124
+
125
+ const getBoardsDictionary = ext.dictionary({ … }) // 3. dictionaries — declared before the params that use them
126
+
127
+ const boardIdParam = z.string() // 4. shared param schemas
128
+ .label('Board')
129
+ .dictionary(getBoardsDictionary)
130
+
131
+ ext.addAction({ … }) // 5. actions
132
+ ext.addPollingTrigger({ … }) // 6. triggers
133
+ ext.addRealtimeTrigger({ … })
134
+
135
+ // 7. helper functions, at the end
136
+ function asInteger(value, label) {
137
+ …
138
+ }
139
+ ```
140
+
141
+ **Module-level helpers are function declarations, and they go at the bottom.** Write
142
+ `function asInteger(value, label) { … }`, not `const asInteger = (value, label) => { … }`. Declarations
143
+ hoist, so a helper used by an action above it still resolves, which is what lets the file read in
144
+ declaration order — the service's shape first, its plumbing last. A `const` arrow forces the opposite: every
145
+ utility has to appear before its first use, so the file opens with a wall of helpers and the actions are
146
+ buried.
147
+
148
+ This applies to anything outside the service's context — pure conversions, formatting, guards. Anything that
149
+ needs `apiRequest`, `config` or `files` belongs in `helpers` instead.
150
+
151
+ These two props are also where the handler **types** come from. `createExtension` resolves the service's
152
+ shape once, and every registrar carries it into every handler:
153
+
154
+ | Declared here | Becomes | Typed as |
155
+ |---|---|---|
156
+ | `configItems` | `config` in every handler (and in `initContext`) | `z.infer` of the schema |
157
+ | `initContext` | `context` in every handler | its return type |
158
+ | `helpers` | `helpers` in every handler | its return type |
159
+ | `apiRequest` | `apiRequest` in every handler | your own signature, minus the `context` / `logger` the runtime injects |
160
+
161
+ So the object `initContext` returns is the one every handler sees — widen it there, not at the call site:
162
+
163
+ ```js
164
+ const ext = Flowrunner.createExtension({
165
+ configItems: z.object({ apiKey: z.string() }),
166
+ initContext: ({ config }) => ({ base: `https://api.svc.io/${config.apiKey}` }),
167
+ })
168
+
169
+ ext.addAction({
170
+ // …
171
+ execute: ({ context, config }) => {
172
+ context.base // string
173
+ config.apiKey // string
174
+ context.typo // ✗ context only carries what initContext returned
175
+ },
176
+ })
177
+ ```
178
+
179
+ The full per-handler context bag, and how each key is inferred, is documented in
180
+ [07-actions.md](07-actions.md#inferred-types).
@@ -0,0 +1,260 @@
1
+ # 02 — zod Types & Plugins
2
+
3
+ Config fields, params, and result shapes are declared with zod. The **UI widget is derived from the zod
4
+ type** — there is no `.uiComponent()`. Plugins (chained methods) attach labels, descriptions, defaults,
5
+ and behaviors.
6
+
7
+ | Type | Widget | | Plugin call | Applies to | Effect |
8
+ |---|---|---|---|---|---|
9
+ | `z.string()` | single-line | | `.label(text)` | any field | display label (native `meta.title`) |
10
+ | `z.text()` | multi-line | | `.describe(text)` | any field | description / config hint |
11
+ | `z.json()` | multi-line — arbitrary JSON, **parsed for you** | | | | |
12
+ | `z.number()` | numeric stepper | | `.example(v)` | field / result | sample value (native `meta.examples`) |
13
+ | `z.boolean()` | toggle | | `.optional()` | any field | not required (required is default) |
14
+ | `z.enum([...])` | dropdown | | `.default(v)` | any field | default value |
15
+ | `z.date()` | date picker | | `.shared()` | config field | `shared:true` (OAuth client id/secret) |
16
+ | `z.object({...})` | nested form | | `.dictionary(ref)` | param field | dynamic options + auto `dependsOn` (see [05-dictionaries.md](05-dictionaries.md)) |
17
+ | `z.array(inner)` | list | | `.labels({ value: 'Label' })` | `z.enum` | UI shows the label; the flow stores and `execute` receives the VALUE |
18
+ | `z.union([...])` | the **first** branch's widget — see below | | | | |
19
+ | `z.filesUploadOptions([...])`, `z.filesListOptions([...])`, `z.filesGetOptions([...])`, `z.filesDeleteOptions([...])` | nested form — the platform's own file-storage options, one group per Files call (see [03-parameters.md](03-parameters.md)) | | | | |
20
+ | | | | `.secret()` | `z.string()` config field | Masks the input, with a reveal toggle. **Display only** — see below |
21
+
22
+ Notes:
23
+
24
+ - **The Widget column is the PARAM rendering.** A `configItems` field publishes a smaller, closed set of
25
+ types — notably `z.number()` lands on `string` and gets a plain text box, not a stepper. See
26
+ [Config fields publish a smaller set of types](#config-fields-publish-a-smaller-set-of-types).
27
+ - **Required is the default** — mark optional fields with `.optional()`.
28
+ - `.shared()` marks a config field as a **shared** (global) config value rather than per-app — used for
29
+ OAuth client id/secret and other secrets. It is a **UI directive**: it decides who fills the field in and
30
+ in which dialog, not how your handler reads it. `config.clientId` is the same either way, and a service
31
+ installed as a *custom* extension has no shared tier at all — the customer fills in every item in one
32
+ dialog. See `configItems` in [01-service-structure.md](01-service-structure.md) and the output mapping in
33
+ [11-output-model.md](11-output-model.md).
34
+ - `.secret()` marks a **`z.string()` config field** as sensitive: the console renders it masked, with a
35
+ toggle to reveal it. It is **display only** — the value is stored, sent and validated exactly as it would
36
+ be without it, so it hides a credential from someone looking over a shoulder rather than protecting it.
37
+ It has no effect anywhere else: not on `z.text()`, which has no password mode, and not on an action or
38
+ trigger param, whose value lives in the flow definition and is readable through the API — masking that
39
+ input would suggest a protection that is not there. Put credentials in a `z.string()` config item.
40
+ - `.dictionary(ref)` binds a param to a dictionary for dynamic options and auto-derives its `dependsOn`.
41
+ - `.labels({ value: 'Label' })` gives each declared VALUE a display name. The dropdown shows the label, the
42
+ flow element stores the value, and your handler receives the value — so **renaming a label never breaks a
43
+ saved flow**. `.default(v)` takes a value, not a label.
44
+ (There is no `.map({ Label: value })` — it took its argument the other way round, treating labels as the
45
+ accepted values. It throws when the service loads, naming `.labels()`.)
46
+
47
+ ## `z.json()` — a JSON value typed into a textarea
48
+
49
+ Use it for a parameter whose shape you do not want to declare: a request body to pass through, a bag of
50
+ options an API takes verbatim.
51
+
52
+ ```js
53
+ params: z.object({
54
+ payload: z.json().label('Payload').describe('Sent as the request body.'),
55
+ }),
56
+ execute: async ({ params }) => {
57
+ // `params.payload` is already a JSON VALUE — an object, an array, a number. Not text.
58
+ return apiRequest({ url: '/items', method: 'POST', body: params.payload })
59
+ }
60
+ ```
61
+
62
+ The field renders as a textarea and the caller supplies **text**, so the parameter publishes as a string —
63
+ but the runtime parses it before your handler runs, and `execute` receives the parsed value. **Never call
64
+ `JSON.parse` on it yourself.**
65
+
66
+ - **Text that will not parse is rejected** the way any wrong-typed value is: the user sees
67
+ `«Payload» must be valid JSON` against the field, before your handler is reached.
68
+ - **A value that is already a structure passes through untouched** — a flow can bind the parameter to an
69
+ expression that evaluates to an object rather than to text, and both work.
70
+ - **Every JSON value is accepted**, not just objects and arrays: `42`, `"text"`, `true` and `null` all parse.
71
+ Bare words do not — JSON wants a string quoted, so `hello` is refused and `"hello"` is accepted.
72
+ - **Required by default**, like every other field; add `.optional()` if it is not.
73
+ - Its inferred TypeScript type is `unknown`, because that is honestly what arbitrary JSON is. Narrow it in
74
+ your handler before reading properties off it.
75
+
76
+ `z.json()` declares nothing about the value's SHAPE. When you do know the shape, declare it — a
77
+ `z.object({ … })` gives the user a real form and gives you a checked value, where this gives a textarea and
78
+ `unknown`.
79
+
80
+ ## The type list is CLOSED
81
+
82
+ The table above is what a service declares day to day. A few more types are accepted and rarely reached for:
83
+
84
+ | Type | Widget | Notes |
85
+ |---|---|---|
86
+ | `z.bigint()` | numeric stepper | your handler receives a `BigInt`. A fractional value is refused rather than rounded, since the conversion would lose information |
87
+ | `z.literal(v)` | the widget of `v`'s own type — a toggle for `z.literal(true)`, a stepper for `z.literal(7)` | a literal of several values of *different* types has no such type and publishes as text |
88
+ | `z.record(k, v)` | nested form with no declared fields, because the keys are open | the values are converted against `v` like any other declaration |
89
+ | `z.any()` / `z.unknown()` | single-line | declares nothing: the value reaches your handler exactly as it arrived, unconverted |
90
+
91
+ **Those two tables together are the whole surface.** A declaration outside them — `z.tuple()`,
92
+ `z.intersection()`, a modifier a future zod release adds — **fails when the extension loads**, naming the
93
+ parameter and what it declared. It is not published as a best guess. A `z.union([...])` is supported, but it
94
+ is not a way round this: **every branch is held to the same surface**, so a union with a `z.tuple()` in it is
95
+ refused exactly as a bare one is.
96
+
97
+ That is deliberate, and it is worth knowing why the runtime is strict here rather than permissive. A type it
98
+ cannot classify used to fall through to `STRING`, which broke two things at once and neither of them loudly:
99
+ the parameter published as text (a list stopped being a list, a toggle became a text box) **and** the field
100
+ dropped out of type coercion, so the string values a flow supplies were never converted. A `z.boolean()`
101
+ under an unrecognised modifier therefore handed `execute` `false` for an explicit `'true'`. A deploy that
102
+ stops is better than a parameter that looks fine and is wrong.
103
+
104
+ These modifiers are looked THROUGH — the parameter publishes and coerces as the type underneath:
105
+
106
+ | Modifier | Published as |
107
+ |---|---|
108
+ | `.optional()` / `.nullable()` / `.nullish()` | the inner type, not required |
109
+ | `.default(v)` / `.prefault(v)` | the inner type, not required, with `defaultValue` |
110
+ | `.readonly()` | the inner type |
111
+ | `.nonoptional()` | the inner type, required — it overrides an `.optional()` inside it |
112
+ | `.pipe(…)` / `.transform(fn)` | the **input** side. `bodyParams` describes what a caller supplies, which is what the console renders a form for; what your handler receives afterwards is the pipe's business |
113
+ | `z.lazy(() => …)` | the type the thunk returns |
114
+
115
+ ### `.catch(v)` is refused — use `.default(v)`
116
+
117
+ `.catch(v)` looks like the natural way to say "if this isn't a valid list, use an empty one", so it is what
118
+ a migrator reaches for. A parameter may not use it, and the extension will not load if one does.
119
+
120
+ The reason is not the published type: `.catch()` **replaces an invalid value with the fallback instead of
121
+ reporting it**. A user who typed something wrong gets no error and their input is silently discarded.
122
+
123
+ ```js
124
+ tags: z.array(z.string()).catch([]) // ✗ refused — a bad value becomes [] with no error
125
+ tags: z.array(z.string()).default([]) // ✓ same fallback when ABSENT; a bad value still fails
126
+ ```
127
+
128
+ ## `z.union([...])` — branch order is the contract
129
+
130
+ A union is how a parameter accepts more than one shape — an id or a list of ids, a URL or a blank. Two rules
131
+ govern it, and **both read the branches left to right, in the order you declared them.**
132
+
133
+ ### The first branch decides what is published
134
+
135
+ The console draws one widget, so it draws the first branch's.
136
+
137
+ ```js
138
+ recordIds: z.union([z.array(z.string()), z.string()]) // a LIST — accepts a list AND a single string
139
+ recordIds: z.union([z.string(), z.array(z.string())]) // a text box — accepts exactly the same two
140
+ ```
141
+
142
+ Both declarations validate identically. They **publish differently**, and nothing in the declaration says so
143
+ — so reordering branches to read more nicely silently changes what the flow author is shown. Put the shape
144
+ you want on the form first, and treat the order as part of the contract.
145
+
146
+ ### Coercion tries the branches in that same order, and the first that fits wins
147
+
148
+ A flow supplies every value as text, so a union has to convert before it can tell which branch applies.
149
+
150
+ ```js
151
+ flag: z.union([z.boolean(), z.string()]) // 'true' → your handler receives the boolean true
152
+ flag: z.union([z.string(), z.boolean()]) // 'true' → your handler receives the string 'true'
153
+ ```
154
+
155
+ **A branch that accepts anything hides every branch after it.** `z.string()` takes `'true'` as-is, so the
156
+ boolean branch is never reached. If one branch is a fallback, declare it last.
157
+
158
+ That is worth spelling out for booleans, because the failure is silent. In `z.union([z.string(),
159
+ z.boolean()])` the field draws as the **first** branch's widget — a text box, not a toggle — the boolean
160
+ vocabulary below is never applied, and `execute` receives the string `'false'`, which is truthy: `if
161
+ (params.flag)` runs the *on* path for an explicit *off*. Put the boolean branch first.
162
+
163
+ ### A blank means "not set"
164
+
165
+ `''` is a real value on a plain `z.string()`, which is why a cleared text box fails an optional formatted
166
+ field. On a union it is absence, and that is the spelling to reach for:
167
+
168
+ ```js
169
+ webhookUrl: z.url().optional() // blank → «Webhook URL» is invalid — expects a URL
170
+ webhookUrl: z.union([z.url(), z.literal('')]).optional() // blank → not provided
171
+ ```
172
+
173
+ See [16-gotchas.md](16-gotchas.md) for the rest of that trap.
174
+
175
+ ## Config fields publish a smaller set of types
176
+
177
+ A `configItems` field is drawn from its declaration much as a param is — `z.boolean()` is a toggle,
178
+ `z.enum([...])` a dropdown, `z.text()` a textarea — but a config item is published through a **smaller,
179
+ closed vocabulary** than a param, and anything outside it lands on `string`:
180
+
181
+ | Declared in `configItems` | Published `type` | Control |
182
+ |---|---|---|
183
+ | `z.string()` | `string` | single-line text |
184
+ | `z.text()` | `text` | textarea |
185
+ | `z.boolean()` | `bool` | checkbox |
186
+ | `z.enum([...])` | `choice` | dropdown |
187
+ | `z.date()` | `date` | date picker |
188
+ | **`z.number()`** | **`string`** | **single-line text — there is no numeric config type, so no stepper** |
189
+
190
+ `z.number()` is the one that surprises: as a *param* it publishes `NUMBER` and renders a numeric stepper, in
191
+ `configItems` it publishes `type: "string"` and renders a plain text box. `getServiceConfigItems()` reports
192
+ `"string"` for it, and a test asserting the published config items must expect that. **Your handler still
193
+ receives a number** — the declared type is what the value is converted to before validation (see below), so
194
+ the widget is the only thing that differs. Declare `z.number()` anyway when the value is a number: it is
195
+ what gives you the conversion and the validation.
196
+
197
+ The two other differences are structural:
198
+
199
+ | Declared in `configItems` | What happens |
200
+ |---|---|
201
+ | `z.object({...})`, `z.array(inner)` | **no config control** — a config value is one field, not a form. Declare structured input as a param |
202
+ | `.dictionary(ref)` | **ignored** — a config value is resolved before any method runs, so there is no invocation to fetch options for. Use `z.enum([...])` for a fixed set of choices |
203
+
204
+ `z.date()` in a config field is a date, with no time of day. Declare a string if you need one.
205
+
206
+ **Every value is converted to the declared type before validation, and you never declare that
207
+ conversion.** `z.coerce.*` does not add to it, so `z.coerce.number()` and `z.number()` behave identically,
208
+ as do the boolean and string forms. The one exception is `z.date()` — declare **`z.coerce.date()`** when your handler wants a real `Date`
209
+ instance rather than the string or epoch-millis the caller sent.
210
+
211
+ ### What a boolean accepts
212
+
213
+ A `z.boolean()` is rarely filled in by hand — its value usually arrives from a spreadsheet column, a CSV
214
+ export or an upstream vendor's payload, and each of those spells *yes* its own way. So the conversion
215
+ recognises all of these, after trimming surrounding whitespace and lower-casing, along with the real
216
+ booleans `true`/`false` and the numbers `1`/`0`:
217
+
218
+ | | Accepted spellings |
219
+ |---|---|
220
+ | **true** | `true` `1` `yes` `y` `t` `on` `checked` `enabled` `enable` `active` |
221
+ | **false** | `false` `0` `no` `n` `f` `off` `unchecked` `disabled` `disable` `inactive` |
222
+
223
+ So `'YES'`, `' Off '` and `'Enabled'` all work.
224
+
225
+ **Anything else is a validation error, not a guess.** `'maybe'`, `'2'`, `'tr'`, a list or an object each
226
+ fail with `«Field» is invalid — expects true or false`. That matters more than the width of the list: a
227
+ conversion that quietly turned an unrecognised value into `false` would read an explicit *on* as *off* and
228
+ never say so.
229
+
230
+ A blank is absence rather than `false` — see [16-gotchas.md](16-gotchas.md).
231
+
232
+ If you need a spelling that is not listed, the test for adding one is that **it has an unambiguous opposite
233
+ and the pair is added together.** A word with no opposite is a status, not a boolean, and belongs in a
234
+ `z.enum([...])`.
235
+
236
+ ## Your constraints are enforced, in two places
237
+
238
+ Everything you declare on a field — `.min()`, `.max()`, `.int()`, `.regex()`, `z.email()`, enum membership,
239
+ your own message in `.min(3, 'Too short')` — is checked before your handler runs, and the failure names the
240
+ field by its `.label()`:
241
+
242
+ ```
243
+ «Retries» must be at least 1
244
+ «Site» is invalid — expects a URL, e.g. https://example.com
245
+ «Region» must be one of: us, eu
246
+ ```
247
+
248
+ The console checks the *same* schema while the form is being filled in, so a config dialog reports the same
249
+ problem in the same words rather than letting a bad value through to a failed run. Two consequences worth
250
+ knowing:
251
+
252
+ - **A function-backed rule cannot be checked in the form.** `.refine()`, `.superRefine()`, `.transform()` and
253
+ `.trim()` do not survive the trip to the browser, so the console cannot apply them. They still run at
254
+ execution time. The form is never *stricter* than your schema — only ever more permissive — so a value the
255
+ form accepts may still be rejected by a run.
256
+ - **Absence follows your modifiers, not the transport.** Whether an empty field arrives as `undefined`,
257
+ `null`, or the declared `.default(v)` is decided by what your schema accepts, so you write `.optional()` or
258
+ `.nullable()` — whichever reads naturally — instead of guarding for all three. One exception: an empty
259
+ string on a `z.string()` field is a *value*, not absence, so it does not fail a required field. See
260
+ [16-gotchas.md](16-gotchas.md).