@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.
- package/README.md +148 -0
- package/ai-docs/instructions/service-code-format/01-service-structure.md +180 -0
- package/ai-docs/instructions/service-code-format/02-zod-types.md +260 -0
- package/ai-docs/instructions/service-code-format/03-parameters.md +193 -0
- package/ai-docs/instructions/service-code-format/04-http-requests.md +257 -0
- package/ai-docs/instructions/service-code-format/05-dictionaries.md +103 -0
- package/ai-docs/instructions/service-code-format/06-oauth2.md +42 -0
- package/ai-docs/instructions/service-code-format/07-actions.md +171 -0
- package/ai-docs/instructions/service-code-format/08-polling-triggers.md +54 -0
- package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +269 -0
- package/ai-docs/instructions/service-code-format/10-files-api.md +148 -0
- package/ai-docs/instructions/service-code-format/11-output-model.md +142 -0
- package/ai-docs/instructions/service-code-format/12-service-readme.md +69 -0
- package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +193 -0
- package/ai-docs/instructions/service-code-format/14-reference-service.md +341 -0
- package/ai-docs/instructions/service-code-format/15-unit-tests.md +361 -0
- package/ai-docs/instructions/service-code-format/16-gotchas.md +201 -0
- package/ai-docs/instructions/service-code-format/17-client-certificates.md +162 -0
- package/ai-docs/instructions/service-code-format/18-test-recipes.md +160 -0
- package/ai-docs/instructions/service-code-format/README.md +120 -0
- package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +139 -0
- package/ai-docs/providers/claude/agents/flowrunner-service-test-engineer.md +497 -0
- package/ai-docs/providers/claude/main-orchestrator-segment.md +51 -0
- package/bin/flowrunner.js +66 -0
- package/bin/resolve-local.js +98 -0
- package/dist/cli.js +10972 -0
- package/dist/cli.js.map +7 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +10131 -0
- package/dist/index.js.map +7 -0
- package/dist/types/flow-extension-runner/src/common/config.d.ts +12 -0
- package/dist/types/flow-extension-runner/src/common/constants.d.ts +9 -0
- package/dist/types/flow-extension-runner/src/common/context-files.d.ts +107 -0
- package/dist/types/flow-extension-runner/src/common/context.d.ts +6 -0
- package/dist/types/flow-extension-runner/src/common/types.d.ts +11 -0
- package/dist/types/flow-extension-runner/src/errors/base.d.ts +17 -0
- package/dist/types/flow-extension-runner/src/errors/codes.d.ts +17 -0
- package/dist/types/flow-extension-runner/src/errors/errors.d.ts +48 -0
- package/dist/types/flow-extension-runner/src/errors/index.d.ts +3 -0
- package/dist/types/flow-extension-runner/src/global.d.ts +34 -0
- package/dist/types/flow-extension-runner/src/index.d.ts +15 -0
- package/dist/types/flow-extension-runner/src/namespace.d.ts +3 -0
- package/dist/types/flow-extension-runner/src/v1/config.d.ts +3 -0
- package/dist/types/flow-extension-runner/src/v1/constants.d.ts +4 -0
- package/dist/types/flow-extension-runner/src/v1/index.d.ts +11 -0
- package/dist/types/flow-extension-runner/src/v1/namespace.d.ts +9 -0
- package/dist/types/flow-extension-runner/src/v1/service.d.ts +29 -0
- package/dist/types/flow-extension-runner/src/v1/types.d.ts +13 -0
- package/dist/types/flow-extension-runner/src/v2/actions/action-method.d.ts +34 -0
- package/dist/types/flow-extension-runner/src/v2/context/execution-context.d.ts +25 -0
- package/dist/types/flow-extension-runner/src/v2/context/logger.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/context/method-input.d.ts +27 -0
- package/dist/types/flow-extension-runner/src/v2/context/proxies.d.ts +1 -0
- package/dist/types/flow-extension-runner/src/v2/create-extension.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/crypto.d.ts +6 -0
- package/dist/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +24 -0
- package/dist/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +10 -0
- package/dist/types/flow-extension-runner/src/v2/extension.d.ts +51 -0
- package/dist/types/flow-extension-runner/src/v2/index.d.ts +39 -0
- package/dist/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +31 -0
- package/dist/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +17 -0
- package/dist/types/flow-extension-runner/src/v2/loaders/payload-schema.d.ts +3 -0
- package/dist/types/flow-extension-runner/src/v2/method.d.ts +22 -0
- package/dist/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +10 -0
- package/dist/types/flow-extension-runner/src/v2/model/method-model.d.ts +3 -0
- package/dist/types/flow-extension-runner/src/v2/model/model-types.d.ts +70 -0
- package/dist/types/flow-extension-runner/src/v2/model/params-model.d.ts +16 -0
- package/dist/types/flow-extension-runner/src/v2/oauth/method-names.d.ts +5 -0
- package/dist/types/flow-extension-runner/src/v2/oauth/oauth2.d.ts +9 -0
- package/dist/types/flow-extension-runner/src/v2/oauth/system-params.d.ts +6 -0
- package/dist/types/flow-extension-runner/src/v2/oauth/types.d.ts +54 -0
- package/dist/types/flow-extension-runner/src/v2/params/config-params.d.ts +14 -0
- package/dist/types/flow-extension-runner/src/v2/params/files-options.d.ts +58 -0
- package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +19 -0
- package/dist/types/flow-extension-runner/src/v2/params/json/checks.d.ts +26 -0
- package/dist/types/flow-extension-runner/src/v2/params/json/decode.d.ts +24 -0
- package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +20 -0
- package/dist/types/flow-extension-runner/src/v2/params/json/types.d.ts +86 -0
- package/dist/types/flow-extension-runner/src/v2/params/json/values.d.ts +5 -0
- package/dist/types/flow-extension-runner/src/v2/params/method-params.d.ts +17 -0
- package/dist/types/flow-extension-runner/src/v2/params/params.d.ts +26 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/assert-object-schema.d.ts +6 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/assert-supported-schema.d.ts +8 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/coerce.d.ts +54 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/dates.d.ts +40 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +36 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +33 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +58 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/labels.d.ts +3 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/messages.d.ts +16 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/normalize.d.ts +8 -0
- package/dist/types/flow-extension-runner/src/v2/params/schema/parse.d.ts +7 -0
- package/dist/types/flow-extension-runner/src/v2/params/types.d.ts +29 -0
- package/dist/types/flow-extension-runner/src/v2/params/widget-types.d.ts +40 -0
- package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +86 -0
- package/dist/types/flow-extension-runner/src/v2/path.d.ts +1 -0
- package/dist/types/flow-extension-runner/src/v2/polling-triggers/mechanisms.d.ts +19 -0
- package/dist/types/flow-extension-runner/src/v2/polling-triggers/method-names.d.ts +1 -0
- package/dist/types/flow-extension-runner/src/v2/polling-triggers/polling-triggers.d.ts +11 -0
- package/dist/types/flow-extension-runner/src/v2/polling-triggers/system-params.d.ts +7 -0
- package/dist/types/flow-extension-runner/src/v2/polling-triggers/trigger-method.d.ts +25 -0
- package/dist/types/flow-extension-runner/src/v2/polling-triggers/types.d.ts +46 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/method-names.d.ts +7 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/realtime-setup.d.ts +10 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +29 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +33 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +147 -0
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +2 -0
- package/dist/types/flow-extension-runner/src/v2/registry.d.ts +20 -0
- package/dist/types/flow-extension-runner/src/v2/result.d.ts +13 -0
- package/dist/types/flow-extension-runner/src/v2/system-method.d.ts +41 -0
- package/dist/types/flow-extension-runner/src/v2/types.d.ts +126 -0
- package/dist/types/jsdoc-parser/src/custom-type-defs/files.d.ts +2 -0
- package/dist/types/jsdoc-parser/src/index.d.ts +2 -0
- package/dist/types/jsdoc-parser/src/lib.d.ts +42 -0
- package/dist/types/jsdoc-parser/src/types.d.ts +2 -0
- package/dist/types/packages/cli/src/api/console-client.d.ts +69 -0
- package/dist/types/packages/cli/src/constants/index.d.ts +5 -0
- package/dist/types/packages/cli/src/constants/packaging.d.ts +7 -0
- package/dist/types/packages/cli/src/constants/project.d.ts +9 -0
- package/dist/types/packages/cli/src/constants/providers.d.ts +30 -0
- package/dist/types/packages/cli/src/constants/server.d.ts +29 -0
- package/dist/types/packages/cli/src/constants/testing.d.ts +32 -0
- package/dist/types/packages/cli/src/errors.d.ts +131 -0
- package/dist/types/packages/cli/src/index.d.ts +29 -0
- package/dist/types/packages/cli/src/operations/deploy/discover-services.d.ts +26 -0
- package/dist/types/packages/cli/src/operations/deploy/hash.d.ts +1 -0
- package/dist/types/packages/cli/src/operations/deploy/index.d.ts +94 -0
- package/dist/types/packages/cli/src/operations/deploy/public-files.d.ts +20 -0
- package/dist/types/packages/cli/src/operations/deploy/select.d.ts +9 -0
- package/dist/types/packages/cli/src/operations/deploy/zip.d.ts +1 -0
- package/dist/types/packages/cli/src/operations/init/answers.d.ts +35 -0
- package/dist/types/packages/cli/src/operations/init/create-service.d.ts +39 -0
- package/dist/types/packages/cli/src/operations/init/index.d.ts +79 -0
- package/dist/types/packages/cli/src/operations/init/testing.d.ts +13 -0
- package/dist/types/packages/cli/src/operations/init-claude/index.d.ts +40 -0
- package/dist/types/packages/cli/src/operations/init-claude/segment.d.ts +25 -0
- package/dist/types/packages/cli/src/operations/login.d.ts +38 -0
- package/dist/types/packages/cli/src/operations/logout.d.ts +19 -0
- package/dist/types/packages/cli/src/operations/pull/extract.d.ts +23 -0
- package/dist/types/packages/cli/src/operations/pull/index.d.ts +87 -0
- package/dist/types/packages/cli/src/operations/server-target.d.ts +14 -0
- package/dist/types/packages/cli/src/operations/types.d.ts +20 -0
- package/dist/types/packages/cli/src/operations/use-server.d.ts +17 -0
- package/dist/types/packages/cli/src/project/auth.d.ts +41 -0
- package/dist/types/packages/cli/src/project/config.d.ts +31 -0
- package/dist/types/packages/cli/src/project/token.d.ts +5 -0
- package/dist/types/packages/cli/src/server/index.d.ts +14 -0
- package/dist/types/packages/cli/src/server/pages.d.ts +2 -0
- package/dist/types/packages/cli/src/server/routes/callback.d.ts +6 -0
- package/dist/types/packages/cli/src/server/types.d.ts +12 -0
- package/dist/types/packages/cli/src/templates/index.d.ts +8 -0
- package/dist/types/packages/cli/src/templates/manifest.d.ts +97 -0
- package/dist/types/packages/cli/src/templates/package-root.d.ts +3 -0
- package/dist/types/packages/cli/src/templates/paths.d.ts +3 -0
- package/dist/types/packages/cli/src/templates/registry.d.ts +13 -0
- package/dist/types/packages/cli/src/templates/render.d.ts +13 -0
- package/dist/types/packages/cli/src/templates/scaffold.d.ts +25 -0
- package/dist/types/packages/cli/src/utils/invocation.d.ts +28 -0
- package/dist/types/packages/cli/src/utils/open-browser.d.ts +2 -0
- package/dist/types/shared/src/constants/ai-agent-tools.d.ts +20 -0
- package/dist/types/shared/src/constants/ai.d.ts +11 -0
- package/dist/types/shared/src/constants/api-keys.d.ts +1 -0
- package/dist/types/shared/src/constants/app.d.ts +58 -0
- package/dist/types/shared/src/constants/billing.d.ts +16 -0
- package/dist/types/shared/src/constants/compliances.d.ts +3 -0
- package/dist/types/shared/src/constants/data-types.d.ts +26 -0
- package/dist/types/shared/src/constants/error-codes.d.ts +16 -0
- package/dist/types/shared/src/constants/flow.d.ts +12 -0
- package/dist/types/shared/src/constants/index.d.ts +16 -0
- package/dist/types/shared/src/constants/knowledge-base.d.ts +13 -0
- package/dist/types/shared/src/constants/notification-types.d.ts +985 -0
- package/dist/types/shared/src/constants/notifications.d.ts +10 -0
- package/dist/types/shared/src/constants/patterns.d.ts +28 -0
- package/dist/types/shared/src/constants/retry-policy.d.ts +30 -0
- package/dist/types/shared/src/constants/severity.d.ts +9 -0
- package/dist/types/shared/src/constants/shared-extensions-search.d.ts +6 -0
- package/dist/types/shared/src/constants/shared-extensions.d.ts +35 -0
- package/dist/types/shared/src/constants/zod.d.ts +2 -0
- package/dist/types/shared/src/errors/api.d.ts +4 -0
- package/dist/types/shared/src/errors/base.d.ts +38 -0
- package/dist/types/shared/src/errors/common.d.ts +39 -0
- package/dist/types/shared/src/errors/index.d.ts +13 -0
- package/dist/types/shared/src/errors/k8s.d.ts +4 -0
- package/dist/types/shared/src/errors/message.d.ts +48 -0
- package/dist/types/shared/src/errors/open-search.d.ts +4 -0
- package/dist/types/shared/src/errors/s3.d.ts +11 -0
- package/dist/types/shared/src/extensions/zod.d.ts +25 -0
- package/dist/types/shared/src/scheme/account/dto.d.ts +60 -0
- package/dist/types/shared/src/scheme/account/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/ai-agent-tools/dto.d.ts +69 -0
- package/dist/types/shared/src/scheme/ai-agent-tools/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/ai-agent-tools/parameters.d.ts +7 -0
- package/dist/types/shared/src/scheme/ai-router/dto.d.ts +23 -0
- package/dist/types/shared/src/scheme/ai-router/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/api-keys/dto.d.ts +28 -0
- package/dist/types/shared/src/scheme/api-keys/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/app/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/app/java.dto.d.ts +6 -0
- package/dist/types/shared/src/scheme/billing/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/billing/java.dto.d.ts +163 -0
- package/dist/types/shared/src/scheme/crm/billing.d.ts +149 -0
- package/dist/types/shared/src/scheme/crm/dto.d.ts +212 -0
- package/dist/types/shared/src/scheme/crm/index.d.ts +3 -0
- package/dist/types/shared/src/scheme/data-types/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/data-types/java.dto.d.ts +23 -0
- package/dist/types/shared/src/scheme/dynamic-forms/dto.d.ts +30 -0
- package/dist/types/shared/src/scheme/dynamic-forms/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/extensions/index.d.ts +1 -0
- package/dist/types/shared/src/scheme/extensions/params-to-zod.d.ts +14 -0
- package/dist/types/shared/src/scheme/flowrunner/custom-elements.d.ts +368 -0
- package/dist/types/shared/src/scheme/flowrunner/index.d.ts +3 -0
- package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +628 -0
- package/dist/types/shared/src/scheme/index.d.ts +19 -0
- package/dist/types/shared/src/scheme/integration-connection/dto.d.ts +81 -0
- package/dist/types/shared/src/scheme/integration-connection/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +540 -0
- package/dist/types/shared/src/scheme/knowledge-base/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -0
- package/dist/types/shared/src/scheme/mcp-oauth/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/notifications/dto.d.ts +111 -0
- package/dist/types/shared/src/scheme/notifications/index.d.ts +3 -0
- package/dist/types/shared/src/scheme/notifications/rest.d.ts +148 -0
- package/dist/types/shared/src/scheme/properties/account.d.ts +3 -0
- package/dist/types/shared/src/scheme/properties/app.d.ts +5 -0
- package/dist/types/shared/src/scheme/properties/billing.d.ts +12 -0
- package/dist/types/shared/src/scheme/properties/common.d.ts +2 -0
- package/dist/types/shared/src/scheme/properties/db.d.ts +8 -0
- package/dist/types/shared/src/scheme/properties/flow-extensions.d.ts +7 -0
- package/dist/types/shared/src/scheme/properties/index.d.ts +7 -0
- package/dist/types/shared/src/scheme/remote-mcp-server/dto.d.ts +278 -0
- package/dist/types/shared/src/scheme/remote-mcp-server/index.d.ts +2 -0
- package/dist/types/shared/src/scheme/shared-extensions/base.d.ts +56 -0
- package/dist/types/shared/src/scheme/shared-extensions/config.d.ts +96 -0
- package/dist/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +485 -0
- package/dist/types/shared/src/scheme/shared-extensions/extension.d.ts +387 -0
- package/dist/types/shared/src/scheme/shared-extensions/flow-extensions.d.ts +64 -0
- package/dist/types/shared/src/scheme/shared-extensions/index.d.ts +15 -0
- package/dist/types/shared/src/scheme/shared-extensions/light.d.ts +38 -0
- package/dist/types/shared/src/scheme/shared-extensions/logs.d.ts +21 -0
- package/dist/types/shared/src/scheme/shared-extensions/methods.d.ts +80 -0
- package/dist/types/shared/src/scheme/shared-extensions/params-schema.d.ts +47 -0
- package/dist/types/shared/src/scheme/shared-extensions/popular-pool.d.ts +11 -0
- package/dist/types/shared/src/scheme/shared-extensions/resolve.d.ts +364 -0
- package/dist/types/shared/src/scheme/shared-extensions/rest.d.ts +9 -0
- package/dist/types/shared/src/scheme/shared-extensions/search.d.ts +177 -0
- package/dist/types/shared/src/scheme/shared-extensions/service-identity.d.ts +10 -0
- package/dist/types/shared/src/scheme/shared-extensions/service-info.d.ts +15 -0
- package/dist/types/shared/src/scheme/workspace/dto.d.ts +40 -0
- package/dist/types/shared/src/scheme/workspace/index.d.ts +1 -0
- package/dist/types/shared/src/utils/object.d.ts +8 -0
- package/dist/types/shared/src/utils/uuid.d.ts +5 -0
- package/dist/types/shared/src/utils/versions.d.ts +4 -0
- package/dist/types/types/backendless-request.d.ts +40 -0
- package/package.json +66 -0
- package/project-files/jest.config.js +38 -0
- package/project-files/jest.setup.js +24 -0
- package/project-files/sandbox/files-mock.js +654 -0
- package/project-files/sandbox/index.js +32 -0
- package/project-files/sandbox/nock-mock.js +600 -0
- package/project-files/sandbox/service.js +145 -0
- package/runtime/index.d.ts +2 -0
- package/runtime/index.js +5665 -0
- package/runtime/index.js.map +7 -0
- package/runtime/types/flow-extension-runner/src/common/config.d.ts +12 -0
- package/runtime/types/flow-extension-runner/src/common/constants.d.ts +9 -0
- package/runtime/types/flow-extension-runner/src/common/context-files.d.ts +107 -0
- package/runtime/types/flow-extension-runner/src/common/context.d.ts +6 -0
- package/runtime/types/flow-extension-runner/src/common/types.d.ts +11 -0
- package/runtime/types/flow-extension-runner/src/errors/base.d.ts +17 -0
- package/runtime/types/flow-extension-runner/src/errors/codes.d.ts +17 -0
- package/runtime/types/flow-extension-runner/src/errors/errors.d.ts +48 -0
- package/runtime/types/flow-extension-runner/src/errors/index.d.ts +3 -0
- package/runtime/types/flow-extension-runner/src/global.d.ts +34 -0
- package/runtime/types/flow-extension-runner/src/index.d.ts +15 -0
- package/runtime/types/flow-extension-runner/src/namespace.d.ts +3 -0
- package/runtime/types/flow-extension-runner/src/v1/config.d.ts +3 -0
- package/runtime/types/flow-extension-runner/src/v1/constants.d.ts +4 -0
- package/runtime/types/flow-extension-runner/src/v1/index.d.ts +11 -0
- package/runtime/types/flow-extension-runner/src/v1/namespace.d.ts +9 -0
- package/runtime/types/flow-extension-runner/src/v1/service.d.ts +29 -0
- package/runtime/types/flow-extension-runner/src/v1/types.d.ts +13 -0
- package/runtime/types/flow-extension-runner/src/v2/actions/action-method.d.ts +34 -0
- package/runtime/types/flow-extension-runner/src/v2/context/execution-context.d.ts +25 -0
- package/runtime/types/flow-extension-runner/src/v2/context/logger.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/context/method-input.d.ts +27 -0
- package/runtime/types/flow-extension-runner/src/v2/context/proxies.d.ts +1 -0
- package/runtime/types/flow-extension-runner/src/v2/create-extension.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/crypto.d.ts +6 -0
- package/runtime/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +24 -0
- package/runtime/types/flow-extension-runner/src/v2/dictionaries/payload-schema.d.ts +10 -0
- package/runtime/types/flow-extension-runner/src/v2/extension.d.ts +51 -0
- package/runtime/types/flow-extension-runner/src/v2/index.d.ts +39 -0
- package/runtime/types/flow-extension-runner/src/v2/loaders/loader-method.d.ts +31 -0
- package/runtime/types/flow-extension-runner/src/v2/loaders/loader-owner.d.ts +17 -0
- package/runtime/types/flow-extension-runner/src/v2/loaders/payload-schema.d.ts +3 -0
- package/runtime/types/flow-extension-runner/src/v2/method.d.ts +22 -0
- package/runtime/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +10 -0
- package/runtime/types/flow-extension-runner/src/v2/model/method-model.d.ts +3 -0
- package/runtime/types/flow-extension-runner/src/v2/model/model-types.d.ts +70 -0
- package/runtime/types/flow-extension-runner/src/v2/model/params-model.d.ts +16 -0
- package/runtime/types/flow-extension-runner/src/v2/oauth/method-names.d.ts +5 -0
- package/runtime/types/flow-extension-runner/src/v2/oauth/oauth2.d.ts +9 -0
- package/runtime/types/flow-extension-runner/src/v2/oauth/system-params.d.ts +6 -0
- package/runtime/types/flow-extension-runner/src/v2/oauth/types.d.ts +54 -0
- package/runtime/types/flow-extension-runner/src/v2/params/config-params.d.ts +14 -0
- package/runtime/types/flow-extension-runner/src/v2/params/files-options.d.ts +58 -0
- package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +19 -0
- package/runtime/types/flow-extension-runner/src/v2/params/json/checks.d.ts +26 -0
- package/runtime/types/flow-extension-runner/src/v2/params/json/decode.d.ts +24 -0
- package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +20 -0
- package/runtime/types/flow-extension-runner/src/v2/params/json/types.d.ts +86 -0
- package/runtime/types/flow-extension-runner/src/v2/params/json/values.d.ts +5 -0
- package/runtime/types/flow-extension-runner/src/v2/params/method-params.d.ts +17 -0
- package/runtime/types/flow-extension-runner/src/v2/params/params.d.ts +26 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/assert-object-schema.d.ts +6 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/assert-supported-schema.d.ts +8 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/coerce.d.ts +54 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/dates.d.ts +40 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/defaults.d.ts +36 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/field-plan.d.ts +33 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/introspect.d.ts +58 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/labels.d.ts +3 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/messages.d.ts +16 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/normalize.d.ts +8 -0
- package/runtime/types/flow-extension-runner/src/v2/params/schema/parse.d.ts +7 -0
- package/runtime/types/flow-extension-runner/src/v2/params/types.d.ts +29 -0
- package/runtime/types/flow-extension-runner/src/v2/params/widget-types.d.ts +40 -0
- package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +86 -0
- package/runtime/types/flow-extension-runner/src/v2/path.d.ts +1 -0
- package/runtime/types/flow-extension-runner/src/v2/polling-triggers/mechanisms.d.ts +19 -0
- package/runtime/types/flow-extension-runner/src/v2/polling-triggers/method-names.d.ts +1 -0
- package/runtime/types/flow-extension-runner/src/v2/polling-triggers/polling-triggers.d.ts +11 -0
- package/runtime/types/flow-extension-runner/src/v2/polling-triggers/system-params.d.ts +7 -0
- package/runtime/types/flow-extension-runner/src/v2/polling-triggers/trigger-method.d.ts +25 -0
- package/runtime/types/flow-extension-runner/src/v2/polling-triggers/types.d.ts +46 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/method-names.d.ts +7 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/realtime-setup.d.ts +10 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +29 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +33 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +147 -0
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +2 -0
- package/runtime/types/flow-extension-runner/src/v2/registry.d.ts +20 -0
- package/runtime/types/flow-extension-runner/src/v2/result.d.ts +13 -0
- package/runtime/types/flow-extension-runner/src/v2/system-method.d.ts +41 -0
- package/runtime/types/flow-extension-runner/src/v2/types.d.ts +126 -0
- package/runtime/types/jsdoc-parser/src/custom-type-defs/files.d.ts +2 -0
- package/runtime/types/jsdoc-parser/src/index.d.ts +2 -0
- package/runtime/types/jsdoc-parser/src/lib.d.ts +42 -0
- package/runtime/types/jsdoc-parser/src/types.d.ts +2 -0
- package/runtime/types/packages/cli/src/runtime/index.d.ts +5 -0
- package/runtime/types/shared/src/constants/ai-agent-tools.d.ts +20 -0
- package/runtime/types/shared/src/constants/ai.d.ts +11 -0
- package/runtime/types/shared/src/constants/api-keys.d.ts +1 -0
- package/runtime/types/shared/src/constants/app.d.ts +58 -0
- package/runtime/types/shared/src/constants/billing.d.ts +16 -0
- package/runtime/types/shared/src/constants/compliances.d.ts +3 -0
- package/runtime/types/shared/src/constants/data-types.d.ts +26 -0
- package/runtime/types/shared/src/constants/error-codes.d.ts +16 -0
- package/runtime/types/shared/src/constants/flow.d.ts +12 -0
- package/runtime/types/shared/src/constants/index.d.ts +16 -0
- package/runtime/types/shared/src/constants/knowledge-base.d.ts +13 -0
- package/runtime/types/shared/src/constants/notification-types.d.ts +985 -0
- package/runtime/types/shared/src/constants/notifications.d.ts +10 -0
- package/runtime/types/shared/src/constants/patterns.d.ts +28 -0
- package/runtime/types/shared/src/constants/retry-policy.d.ts +30 -0
- package/runtime/types/shared/src/constants/severity.d.ts +9 -0
- package/runtime/types/shared/src/constants/shared-extensions-search.d.ts +6 -0
- package/runtime/types/shared/src/constants/shared-extensions.d.ts +35 -0
- package/runtime/types/shared/src/constants/zod.d.ts +2 -0
- package/runtime/types/shared/src/errors/api.d.ts +4 -0
- package/runtime/types/shared/src/errors/base.d.ts +38 -0
- package/runtime/types/shared/src/errors/common.d.ts +39 -0
- package/runtime/types/shared/src/errors/index.d.ts +13 -0
- package/runtime/types/shared/src/errors/k8s.d.ts +4 -0
- package/runtime/types/shared/src/errors/message.d.ts +48 -0
- package/runtime/types/shared/src/errors/open-search.d.ts +4 -0
- package/runtime/types/shared/src/errors/s3.d.ts +11 -0
- package/runtime/types/shared/src/extensions/zod.d.ts +25 -0
- package/runtime/types/shared/src/scheme/account/dto.d.ts +60 -0
- package/runtime/types/shared/src/scheme/account/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/ai-agent-tools/dto.d.ts +69 -0
- package/runtime/types/shared/src/scheme/ai-agent-tools/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/ai-agent-tools/parameters.d.ts +7 -0
- package/runtime/types/shared/src/scheme/ai-router/dto.d.ts +23 -0
- package/runtime/types/shared/src/scheme/ai-router/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/api-keys/dto.d.ts +28 -0
- package/runtime/types/shared/src/scheme/api-keys/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/app/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/app/java.dto.d.ts +6 -0
- package/runtime/types/shared/src/scheme/billing/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +163 -0
- package/runtime/types/shared/src/scheme/crm/billing.d.ts +149 -0
- package/runtime/types/shared/src/scheme/crm/dto.d.ts +212 -0
- package/runtime/types/shared/src/scheme/crm/index.d.ts +3 -0
- package/runtime/types/shared/src/scheme/data-types/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/data-types/java.dto.d.ts +23 -0
- package/runtime/types/shared/src/scheme/dynamic-forms/dto.d.ts +30 -0
- package/runtime/types/shared/src/scheme/dynamic-forms/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/extensions/index.d.ts +1 -0
- package/runtime/types/shared/src/scheme/extensions/params-to-zod.d.ts +14 -0
- package/runtime/types/shared/src/scheme/flowrunner/custom-elements.d.ts +368 -0
- package/runtime/types/shared/src/scheme/flowrunner/index.d.ts +3 -0
- package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +628 -0
- package/runtime/types/shared/src/scheme/index.d.ts +19 -0
- package/runtime/types/shared/src/scheme/integration-connection/dto.d.ts +81 -0
- package/runtime/types/shared/src/scheme/integration-connection/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +540 -0
- package/runtime/types/shared/src/scheme/knowledge-base/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/mcp-oauth/dto.d.ts +7 -0
- package/runtime/types/shared/src/scheme/mcp-oauth/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/notifications/dto.d.ts +111 -0
- package/runtime/types/shared/src/scheme/notifications/index.d.ts +3 -0
- package/runtime/types/shared/src/scheme/notifications/rest.d.ts +148 -0
- package/runtime/types/shared/src/scheme/properties/account.d.ts +3 -0
- package/runtime/types/shared/src/scheme/properties/app.d.ts +5 -0
- package/runtime/types/shared/src/scheme/properties/billing.d.ts +12 -0
- package/runtime/types/shared/src/scheme/properties/common.d.ts +2 -0
- package/runtime/types/shared/src/scheme/properties/db.d.ts +8 -0
- package/runtime/types/shared/src/scheme/properties/flow-extensions.d.ts +7 -0
- package/runtime/types/shared/src/scheme/properties/index.d.ts +7 -0
- package/runtime/types/shared/src/scheme/remote-mcp-server/dto.d.ts +278 -0
- package/runtime/types/shared/src/scheme/remote-mcp-server/index.d.ts +2 -0
- package/runtime/types/shared/src/scheme/shared-extensions/base.d.ts +56 -0
- package/runtime/types/shared/src/scheme/shared-extensions/config.d.ts +96 -0
- package/runtime/types/shared/src/scheme/shared-extensions/custom-extensions.d.ts +485 -0
- package/runtime/types/shared/src/scheme/shared-extensions/extension.d.ts +387 -0
- package/runtime/types/shared/src/scheme/shared-extensions/flow-extensions.d.ts +64 -0
- package/runtime/types/shared/src/scheme/shared-extensions/index.d.ts +15 -0
- package/runtime/types/shared/src/scheme/shared-extensions/light.d.ts +38 -0
- package/runtime/types/shared/src/scheme/shared-extensions/logs.d.ts +21 -0
- package/runtime/types/shared/src/scheme/shared-extensions/methods.d.ts +80 -0
- package/runtime/types/shared/src/scheme/shared-extensions/params-schema.d.ts +47 -0
- package/runtime/types/shared/src/scheme/shared-extensions/popular-pool.d.ts +11 -0
- package/runtime/types/shared/src/scheme/shared-extensions/resolve.d.ts +364 -0
- package/runtime/types/shared/src/scheme/shared-extensions/rest.d.ts +9 -0
- package/runtime/types/shared/src/scheme/shared-extensions/search.d.ts +177 -0
- package/runtime/types/shared/src/scheme/shared-extensions/service-identity.d.ts +10 -0
- package/runtime/types/shared/src/scheme/shared-extensions/service-info.d.ts +15 -0
- package/runtime/types/shared/src/scheme/workspace/dto.d.ts +40 -0
- package/runtime/types/shared/src/scheme/workspace/index.d.ts +1 -0
- package/runtime/types/shared/src/utils/object.d.ts +8 -0
- package/runtime/types/shared/src/utils/uuid.d.ts +5 -0
- package/runtime/types/shared/src/utils/versions.d.ts +4 -0
- package/runtime/types/types/backendless-request.d.ts +40 -0
- package/templates/blank/files/README.md +28 -0
- package/templates/blank/files/package.json +8 -0
- package/templates/blank/files/public/icon.svg +5 -0
- package/templates/blank/files/src/index.js +130 -0
- package/templates/blank/template.json +61 -0
- package/templates/demo-todo-list/files/README.md +54 -0
- package/templates/demo-todo-list/files/package.json +8 -0
- package/templates/demo-todo-list/files/public/icon.svg +8 -0
- package/templates/demo-todo-list/files/src/index.js +590 -0
- package/templates/demo-todo-list/template.json +44 -0
- package/templates/qa-test/files/README.md +88 -0
- package/templates/qa-test/files/package.json +8 -0
- package/templates/qa-test/files/public/icon.svg +8 -0
- package/templates/qa-test/files/src/index.js +755 -0
- 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).
|