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