@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,171 @@
|
|
|
1
|
+
# 07 — Actions & the Context Bag
|
|
2
|
+
|
|
3
|
+
Actions are the primary operations a service exposes. Register one with `ext.addAction(props)`.
|
|
4
|
+
|
|
5
|
+
| Property | Type | Req | Description |
|
|
6
|
+
|---|---|---|---|
|
|
7
|
+
| `category` | string | ✓ | Grouping label. |
|
|
8
|
+
| `id` | string | ✓ | Stable action id — persisted, never changes. |
|
|
9
|
+
| `label` | string | ✓ | Display name. |
|
|
10
|
+
| `description` | string | ✓ | Description. |
|
|
11
|
+
| `params` | `z.object` | – | Input params — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
|
|
12
|
+
| `dynamicParams` | object | – | Runtime-generated params (see [03-parameters.md](03-parameters.md)). |
|
|
13
|
+
| `result` | sample object | ✓ | A literal sample of what `execute` returns — see below. |
|
|
14
|
+
| `logo` / `appearanceColors` | – | – | Default to the extension's. |
|
|
15
|
+
| `oauth2Scopes` | string[] | – | Extra OAuth scopes (unioned). |
|
|
16
|
+
| `execute` | fn | ✓ | Handler; receives the ctx bag. |
|
|
17
|
+
|
|
18
|
+
## Input validation
|
|
19
|
+
|
|
20
|
+
The runtime parses the incoming input against `params` **before** `execute` runs, so a handler can trust
|
|
21
|
+
what it receives: defaults are applied, values are coerced by the schema, and unknown fields are stripped
|
|
22
|
+
(an action with `dynamicParams` keeps them — its generated fields aren't in the static schema). A violation
|
|
23
|
+
rejects the call with `FR_EXT_INVALID_METHOD_INPUT` and the offending param paths; don't re-check required
|
|
24
|
+
params by hand inside `execute`. Declare optionality honestly — a `z.string()` that the flow may legitimately
|
|
25
|
+
leave empty must be `.optional()`.
|
|
26
|
+
|
|
27
|
+
**Not every slot is equally strict**, because not every slot has the same producer. Worth knowing so you
|
|
28
|
+
declare schemas that hold up in each:
|
|
29
|
+
|
|
30
|
+
| Slot | Strictness |
|
|
31
|
+
|---|---|
|
|
32
|
+
| Action `params`, SYSTEM invocations | **strict** — required fields enforced, unknown stripped. The flow engine produces these against the published model, so a violation is a real contract break |
|
|
33
|
+
| Dictionary `criteria` | **strict** — the console only calls a dictionary once its `dependsOn` fields are filled |
|
|
34
|
+
| Sample-result / dynamic-params loader `criteria` | **lenient** — the schema is relaxed so nothing is required, and unknown fields ride through. These fire on every keystroke while the form is half-filled |
|
|
35
|
+
| Polling trigger `params` | **lenient** — the runtime polls with whatever the instance was saved with; rejecting a poll would silently stop a live automation |
|
|
36
|
+
|
|
37
|
+
So a loader's `result` fn must tolerate partial criteria, and a trigger's `fetch`/`poll` must tolerate a
|
|
38
|
+
partially configured instance. Handlers reached through a strict slot need no such defence.
|
|
39
|
+
|
|
40
|
+
## `result` — return the sample object
|
|
41
|
+
|
|
42
|
+
**`result` is a literal sample of what `execute` returns. Write the object, nothing else.**
|
|
43
|
+
|
|
44
|
+
```js
|
|
45
|
+
result: {
|
|
46
|
+
message_id: 42,
|
|
47
|
+
date : 1714000000,
|
|
48
|
+
chat : { id: -1001234567890, type: 'supergroup', title: 'Team Standup' },
|
|
49
|
+
text : 'Hello',
|
|
50
|
+
},
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Do **not** declare a zod schema and then attach a sample to it. A schema here is a second description of the
|
|
54
|
+
same thing: it has to be kept in step with the handler by hand, it is not validated against what `execute`
|
|
55
|
+
actually returns, and the platform publishes only the sample from it anyway
|
|
56
|
+
([11-output-model.md](11-output-model.md)). The object is the shorter, truer statement.
|
|
57
|
+
|
|
58
|
+
Two cases still justify something else:
|
|
59
|
+
|
|
60
|
+
- **A schema you genuinely reuse** — the same shape returned by several actions, declared once and
|
|
61
|
+
referenced. Use `z.object(...).example({...})` then, and only then; the value is the reuse, not the typing.
|
|
62
|
+
- **A loader** — `({ params, context, apiRequest }) => sample` — when the shape is not known until the flow
|
|
63
|
+
author has configured the action, because it comes from the user's own data.
|
|
64
|
+
|
|
65
|
+
Take the sample from a real response. An invented one drifts from the API and misleads every flow author who
|
|
66
|
+
builds against it.
|
|
67
|
+
|
|
68
|
+
## `execute`
|
|
69
|
+
|
|
70
|
+
**Always use a block body with an explicit `return`.** A concise arrow returning an object literal reads as
|
|
71
|
+
a shape declaration rather than a call, and it is where responses get quietly reshaped:
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
execute: async ({ params, apiRequest }) => {
|
|
75
|
+
return apiRequest({ url: `/messages/${ params.messageId }`, method: 'delete' })
|
|
76
|
+
},
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Return the provider's response, do not narrow it
|
|
80
|
+
|
|
81
|
+
**An action returns what the API returned.** Extend it or rename fields when the vendor's shape is genuinely
|
|
82
|
+
unusable, but do not reduce a response to the part you happen to care about — every field you drop is one a
|
|
83
|
+
flow author cannot reach, and no amount of extra actions gives it back.
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
// ✗ throws the entire response away and answers with a boolean the API never sent
|
|
87
|
+
execute: async ({ params, apiRequest }) => {
|
|
88
|
+
return {
|
|
89
|
+
success: Boolean(await apiRequest({ url: '/deleteMessage', method: 'post', body: { … } })),
|
|
90
|
+
}
|
|
91
|
+
},
|
|
92
|
+
|
|
93
|
+
// ✓ hands back what the API said
|
|
94
|
+
execute: async ({ params, apiRequest }) => {
|
|
95
|
+
return apiRequest({ url: '/deleteMessage', method: 'post', body: { … } })
|
|
96
|
+
},
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The same applies to a list endpoint: return the items **and** the paging fields around them, not a bare
|
|
100
|
+
array. Adding a derived field is fine — spread the response and add to it — but the original fields stay.
|
|
101
|
+
|
|
102
|
+
## `execute` context bag
|
|
103
|
+
|
|
104
|
+
The same bag is passed to actions, dictionaries, triggers, and result-loaders (accessed via arguments,
|
|
105
|
+
never `this`). Every key is typed — nothing in the bag is `unknown`, and the **Inferred as** column says
|
|
106
|
+
where each type comes from:
|
|
107
|
+
|
|
108
|
+
| Key | Inferred as | Description |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `params` | `z.infer` of **this handler's own** `params` | Parsed input — defaults applied, values coerced, unknown fields stripped. `{}` when the method declares none. |
|
|
111
|
+
| `context` | return type of `initContext` | Whatever the factory built (see [01-service-structure.md](01-service-structure.md)). |
|
|
112
|
+
| `config` | `z.infer` of `configItems` | Resolved config values. |
|
|
113
|
+
| `oauth` | `{ accessToken?: string, token?: unknown }` | From the `oauth-access-token` header only; see [06-oauth2.md](06-oauth2.md). |
|
|
114
|
+
| `apiRequest` | your own `apiRequest`, minus `context` / `logger` | Shared HTTP helper — the runtime injects those two, so you never pass them (see [04-http-requests.md](04-http-requests.md)). |
|
|
115
|
+
| `files` | the file-service client | Present only when `usesFileStorage:true` (else a proxy that throws; see [10-files-api.md](10-files-api.md)). |
|
|
116
|
+
| `filesScope` | `{ WORKSPACE, FLOW, EXECUTION }` | The storage layers, so you name one instead of spelling the string. Always present, opt-in or not. |
|
|
117
|
+
| `logger` | `{ debug, info, warn, error }` | Runtime logger (no bare `console.log`). |
|
|
118
|
+
| `helpers` | return type of `helpers(ctx)` | Bound helpers (present when `createExtension({ helpers })`). |
|
|
119
|
+
|
|
120
|
+
## Inferred types
|
|
121
|
+
|
|
122
|
+
You declare the schemas; the types follow. `createExtension` resolves `config` / `context` / `helpers` /
|
|
123
|
+
`apiRequest` **once** for the whole service, and each registrar infers its own `params` from the schema
|
|
124
|
+
sitting next to the handler — so two actions see two different `params` types, over the same `context`:
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
const ext = Flowrunner.createExtension({
|
|
128
|
+
configItems: z.object({ apiKey: z.string(), retries: z.number().optional() }),
|
|
129
|
+
initContext: ({ config }) => ({ base: `key:${config.apiKey}` }),
|
|
130
|
+
apiRequest : async ({ url, context }) => Flowrunner.Request.get(`${context.base}${url}`),
|
|
131
|
+
helpers : ({ apiRequest }) => ({ listAll: (url) => listAll(apiRequest, url) }),
|
|
132
|
+
})
|
|
133
|
+
|
|
134
|
+
ext.addAction({
|
|
135
|
+
// …
|
|
136
|
+
params : z.object({
|
|
137
|
+
name : z.string(),
|
|
138
|
+
count : z.number().optional().default(1),
|
|
139
|
+
mode : z.enum(['fast', 'slow']).optional(),
|
|
140
|
+
}),
|
|
141
|
+
execute: ({ params, context, config, helpers }) => {
|
|
142
|
+
params.name // string
|
|
143
|
+
params.count // number — a .default() means it is always there
|
|
144
|
+
params.mode // 'fast' | 'slow' | undefined
|
|
145
|
+
context.base // string — from initContext
|
|
146
|
+
config.apiKey // string
|
|
147
|
+
config.retries // number | undefined — .optional() with no default
|
|
148
|
+
params.nope // ✗ not a declared param
|
|
149
|
+
|
|
150
|
+
return helpers.listAll('/things')
|
|
151
|
+
},
|
|
152
|
+
})
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Optionality carries through exactly as declared: `.optional()` yields `T | undefined`, and adding
|
|
156
|
+
`.default(v)` removes the `undefined` because the runtime fills it in before `execute` runs.
|
|
157
|
+
|
|
158
|
+
The same inference reaches every other handler that owns a schema — a dictionary's `criteria`, a polling
|
|
159
|
+
trigger's `params` in `fetch` / `poll` / `watermark.by`, a realtime trigger's `params` in `providerEventName`
|
|
160
|
+
and `match`, and a loader `result` fn, which is typed by its owner's params.
|
|
161
|
+
|
|
162
|
+
**Payloads shaped by a third party stay open on purpose** — a webhook `requestBody`, a `providerEventData`,
|
|
163
|
+
a stored `webhookData`. The runtime cannot know their shape, and requiring a cast before every field read
|
|
164
|
+
would be noise, so they are left free to read into. Validate what matters before you trust it.
|
|
165
|
+
|
|
166
|
+
`oauth.token` is also open: `setupOauth2` runs after the service shape is resolved, so a
|
|
167
|
+
`deserializeToken` return can't flow back into the bag — annotate it at the point of use if it matters.
|
|
168
|
+
|
|
169
|
+
> **Editor support.** Services are plain `.js`, so these types show up as hover text and autocompletion via
|
|
170
|
+
> the global `Flowrunner` declaration; they are not reported as inline errors unless the project opts into
|
|
171
|
+
> checking JS. A service authored in TypeScript gets the same types as real compile errors.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# 08 — Polling Triggers
|
|
2
|
+
|
|
3
|
+
Register with `ext.addPollingTrigger(props)`. The runtime drives the loop (interval ≥ 30s, auto-noted in
|
|
4
|
+
the description), persists `state`, seeds on the first poll, and owns `handleTriggerPollingForEvent`.
|
|
5
|
+
Declare **exactly one** mechanism.
|
|
6
|
+
|
|
7
|
+
| Property | Type | Req | Description |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| `category`/`id`/`label`/`description` | string | ✓ | `id` is persisted and never changes. |
|
|
10
|
+
| `params` | `z.object` | – | Trigger config — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
|
|
11
|
+
| `result` | value \| schema \| loader | ✓ | Emitted item shape. |
|
|
12
|
+
| `fetch` | fn | – | Feeds `dedupe`/`watermark` (not used with `poll`). |
|
|
13
|
+
| `dedupe` \| `watermark` \| `poll` | see below | ✓ | Exactly one. |
|
|
14
|
+
|
|
15
|
+
| Function | Arguments | Returns |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `fetch` | `{ params, isLearningMode, context, apiRequest, … }` | `items[]` |
|
|
18
|
+
| `poll` | `{ params, state, isLearningMode, context, apiRequest, … }` | `{ events, state }` |
|
|
19
|
+
|
|
20
|
+
## Mechanisms
|
|
21
|
+
|
|
22
|
+
| Mechanism | Config | Runtime behavior |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `dedupe` (seen-set) | `item => id` (or field path); or `{ by, stateKey='seen', max=500 }` | Keeps a bounded id set under `stateKey`; emits items whose id is new. Covers new-by-id + stateless-newest (head-only `fetch`). |
|
|
25
|
+
| `watermark` (marker) | `{ by, stateKey='watermark', sortedDesc? }` — `by` = field path or `(item,{params})=>value` | Stores newest marker, emits items past it, advances. `sortedDesc:true` early-breaks. Covers new-by-date + new-or-updated. |
|
|
26
|
+
| `poll` (escape hatch) | fn (above) | Full control; author owns `state` shape. Covers overlap-window+dedup, lag-held cursor, consuming/offset feeds. |
|
|
27
|
+
|
|
28
|
+
## Lifecycle — `state` before → after \| emits
|
|
29
|
+
|
|
30
|
+
| Phase | `dedupe` | `watermark` | `poll` |
|
|
31
|
+
|---|---|---|---|
|
|
32
|
+
| start (no state) | `null → { seen:{…} }` \| `[]` (seed) | `null → { <marker> }` \| `[]` (seed) | `null → seeded` \| `[]` (seed yourself) |
|
|
33
|
+
| learningMode | `null → null` \| `[newest]` (reset) | `null → null` \| `[newest]` (reset) | `null → null` \| `[newest]` (reset) |
|
|
34
|
+
| timer | `{seen} → {seen+new}` \| `[new]` | `{marker} → {advanced}` \| `[past marker]` | yours → yours \| your delta |
|
|
35
|
+
|
|
36
|
+
`isLearningMode`: during setup the runtime calls `fetch`/`poll` with `isLearningMode:true`; return a real
|
|
37
|
+
(limited) sample; the runtime emits it and does **not** persist state. This is distinct from `result`
|
|
38
|
+
(which describes shape only).
|
|
39
|
+
|
|
40
|
+
## One trigger per event
|
|
41
|
+
|
|
42
|
+
**Register a separate trigger for each kind of event, each with its own `id`, `label`, `result` sample and
|
|
43
|
+
filter `params`.** Do not declare one trigger that takes an event-type parameter and switches inside its own
|
|
44
|
+
handler: its `result` then describes none of the shapes it emits, and a flow author has to configure which
|
|
45
|
+
event they meant instead of choosing it by name.
|
|
46
|
+
|
|
47
|
+
Where an API delivers several event kinds through **one consuming endpoint** — a cursor or offset feed that
|
|
48
|
+
hands each item to a single reader — separate polling triggers would compete for it, and the one that polls
|
|
49
|
+
first takes the update the others never see. That is a reason to deliver those events over
|
|
50
|
+
[09-realtime-triggers.md](09-realtime-triggers.md), where one webhook registration fans out to as many
|
|
51
|
+
triggers as the service declares, not a reason to write a universal polling trigger. If the API offers no
|
|
52
|
+
webhook at all, say so in the service `README.md` and declare the one trigger the endpoint can support.
|
|
53
|
+
|
|
54
|
+
The handler bag also carries the shared context (see [07-actions.md](07-actions.md)).
|
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
# 09 — Realtime Triggers
|
|
2
|
+
|
|
3
|
+
Realtime triggers are driven by runtime-owned SYSTEM methods — you never write them. Declarative config
|
|
4
|
+
maps onto them:
|
|
5
|
+
|
|
6
|
+
| SYSTEM method (runtime-owned) | Phase | What you declare |
|
|
7
|
+
|---|---|---|
|
|
8
|
+
| `handleTriggerUpsertWebhook` | flow start | `subscribe` |
|
|
9
|
+
| `handleTriggerResolveEvents` | inbound (shape/handshake) | `extractProviderEventName` + `extractProviderEventData` (+ `handshake`) — or `resolveEvents` |
|
|
10
|
+
| `handleTriggerSelectMatched` | inbound (select/enrich) | per-trigger `match` (+ `extendResult`) |
|
|
11
|
+
| `handleTriggerRefreshWebhook` | refresh timer | `refresh` |
|
|
12
|
+
| `handleTriggerDeleteWebhook` | flow stop | `unsubscribe` |
|
|
13
|
+
|
|
14
|
+
## Unknown trigger names
|
|
15
|
+
|
|
16
|
+
An `id` or `eventName` the service does not declare as a trigger is reachable in normal operation — a flow
|
|
17
|
+
built against an older version of the service, whose trigger was later renamed or removed, keeps sending the
|
|
18
|
+
old name. What happens then is **not** uniform across the SYSTEM methods, and the split is deliberate:
|
|
19
|
+
|
|
20
|
+
**Control plane throws, data plane declines.**
|
|
21
|
+
|
|
22
|
+
| SYSTEM method | Unknown name | Why |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `handleTriggerUpsertWebhook` | **throws** `UnknownTriggerError` (404) | control plane |
|
|
25
|
+
| `handleTriggerRefreshWebhook` | **throws** `UnknownTriggerError` (404) | control plane |
|
|
26
|
+
| `handleTriggerPollingForEvent` | **throws** `UnknownTriggerError` (404) | control plane |
|
|
27
|
+
| `handleTriggerSelectMatched` | **declines** — `{ ids: [], enrichedEventData: null }` | data plane |
|
|
28
|
+
| `handleTriggerDeleteWebhook` | n/a — carries no trigger name | tears down the whole webhook |
|
|
29
|
+
|
|
30
|
+
- **Control plane** — upsert, refresh, polling. FlowRunner initiates these itself (enabling a flow, a
|
|
31
|
+
scheduled renewal). Something is waiting on the result, the error reaches a place where it can be acted
|
|
32
|
+
on, and no third party is affected. Upsert in particular is the platform asking *"is this flow
|
|
33
|
+
startable?"* — a version only goes LIVE once upsert has succeeded, so answering `{}` to a trigger that was
|
|
34
|
+
never registered with the provider produces a flow that reports LIVE and can never fire.
|
|
35
|
+
- **Data plane** — `selectMatched`. It runs *after* the provider has already been answered, on a detached
|
|
36
|
+
thread, with nothing waiting. A throw reaches nobody, and it would abort the remaining events of the same
|
|
37
|
+
delivery — dropping good events beside the stale name.
|
|
38
|
+
|
|
39
|
+
An upsert carries **every** realtime trigger of the flow version being enabled, so one unknown name blocks
|
|
40
|
+
the whole batch from subscribing. That is intended: a flow that refuses to start beats a live flow with half
|
|
41
|
+
its triggers registered.
|
|
42
|
+
|
|
43
|
+
Note the two callers of the same throw differ in where it surfaces: **upsert** fails a user's flow-enable
|
|
44
|
+
request and the error reaches the client, while **refresh** runs from a scheduled job — the flow keeps
|
|
45
|
+
running and the error appears in the customer's **workspace log** on each refresh. Neither is silent.
|
|
46
|
+
|
|
47
|
+
## `ext.setupRealtimeTriggers(props)`
|
|
48
|
+
|
|
49
|
+
| Property | Type | Description |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| `scope` | `'SINGLE_APP' \| 'ALL_APPS'` | Per-app webhook vs one shared callback. |
|
|
52
|
+
| `extractProviderEventName` | path \| fn `({requestBody})=>name\|null` | Discriminator → routes to triggers by `providerEventName` (fan-out: matches every trigger with that value). |
|
|
53
|
+
| `extractProviderEventData` | path \| fn | Base `providerEventData` handed to matched triggers. Default = whole body. |
|
|
54
|
+
| `scopeAt` | path | ALL_APPS routing key path (route where `scopeAt === eventScopeId`). |
|
|
55
|
+
| `verify` | object | Declarative signature check — see the field table below. |
|
|
56
|
+
| `handshake` | fn | Endpoint verification (see table). |
|
|
57
|
+
| `subscribe` | fn | Required (see table). |
|
|
58
|
+
| `unsubscribe` | fn | Required (see table). |
|
|
59
|
+
| `refresh` | fn | Optional. |
|
|
60
|
+
| `resolveEvents` | fn | Escape hatch — replaces `extract*`/`handshake` for irregular/multi-shape payloads. |
|
|
61
|
+
| `verifyRequest` | fn | Escape hatch — replaces `verify`. |
|
|
62
|
+
|
|
63
|
+
**Function args → returns.** All of these also receive the full ctx bag — `config, context, apiRequest,
|
|
64
|
+
oauth, logger, helpers` — in the *same* single object as their own arguments. That includes `verifyRequest`,
|
|
65
|
+
so a value derived in `initContext` is reachable there; prefer it over re-deriving from `config`
|
|
66
|
+
([16-gotchas.md](16-gotchas.md) on normalizing once).
|
|
67
|
+
|
|
68
|
+
**`headers` arrive verbatim**, in whatever casing the provider sent — they are *not* lowercased or otherwise
|
|
69
|
+
normalized on the way to `verifyRequest`. Look them up case-insensitively. (The declarative `verify` block
|
|
70
|
+
does its own lowercased retry; that behaviour does not extend to `verifyRequest`.)
|
|
71
|
+
|
|
72
|
+
| Function | Arguments | Returns |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| `subscribe` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` (null first), `connectionId` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
|
|
75
|
+
| `unsubscribe` | `callbackUrl`, `webhookData`, `connectionId` | `{ webhookData? }` |
|
|
76
|
+
| `refresh` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` | `{ webhookData?, refreshIntervalInSeconds }` |
|
|
77
|
+
| `handshake` | `{ requestBody, headers, rawBody }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
|
|
78
|
+
| `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
|
|
79
|
+
|
|
80
|
+
Both also still accept the **deprecated** `responseToExternalService` / `responseHeaders` — see
|
|
81
|
+
[below](#responsetoexternalservice--deprecated).
|
|
82
|
+
| `verifyRequest` | `{ rawBody, headers }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
|
|
83
|
+
|
|
84
|
+
**The `triggers` bag holds one entry per (trigger × `providerEventName`)**, so a trigger declaring several
|
|
85
|
+
names appears several times. A trigger that declares **no** `providerEventName` — what you write when
|
|
86
|
+
`resolveEvents` emits `id` directly — appears **once, with `providerEventName` absent**: it is a routing
|
|
87
|
+
declaration, and having none does not stop the trigger running or stop `subscribe`/`refresh` having to
|
|
88
|
+
reconcile it. Guard the field rather than assuming it (`if (t.providerEventName)`), and never key a lookup
|
|
89
|
+
on it unconditionally. Nothing is left out of the bag: a name resolving to no trigger **rejects the whole
|
|
90
|
+
call** — see [Unknown trigger names](#unknown-trigger-names) below.
|
|
91
|
+
|
|
92
|
+
### `responseToWebhook` — answering the provider
|
|
93
|
+
|
|
94
|
+
Some providers do not accept a generic `200`. Xero's *Intent to Receive* validation sends two deliveries and
|
|
95
|
+
checks both answers: a correctly signed one must get **2xx**, a deliberately mis-signed one must get **401**.
|
|
96
|
+
Return `responseToWebhook` from `handshake` or `resolveEvents` to say exactly what the provider receives.
|
|
97
|
+
|
|
98
|
+
```js
|
|
99
|
+
return {
|
|
100
|
+
events: [],
|
|
101
|
+
responseToWebhook: {
|
|
102
|
+
httpStatus: 401, // optional, 200 by default
|
|
103
|
+
headers : { 'X-Ack': 'ok' }, // optional
|
|
104
|
+
body : { ok: true }, // optional, JSON-serialized
|
|
105
|
+
rawBody : '', // optional, sent as-is — wins over `body`
|
|
106
|
+
},
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- **`rawBody` beats `body`.** `body` is always JSON-serialized, so a String passed there arrives quoted. Use
|
|
111
|
+
`rawBody` when the answer is not a JSON document — a challenge token, or an empty body.
|
|
112
|
+
- **Content type** defaults to `application/json` for `body` and `text/plain` for `rawBody`, unless `headers`
|
|
113
|
+
sets one.
|
|
114
|
+
- **Allowed `httpStatus`:** `200, 201, 202, 204, 400, 401, 403, 404, 409, 410, 422, 429`. Anything else falls
|
|
115
|
+
back to `200` with a warning. **3xx is refused on purpose** — these callback URLs are handed to third
|
|
116
|
+
parties, so honouring a redirect would make any service an open redirector.
|
|
117
|
+
- **Dropped headers:** `Set-Cookie`, `Content-Length`, `Transfer-Encoding` and other hop-by-hop names, and
|
|
118
|
+
any header whose name or value contains CR/LF (response splitting).
|
|
119
|
+
- **Omit it and nothing changes** — the delivery is answered `200` with an empty body, as before.
|
|
120
|
+
|
|
121
|
+
#### `responseToExternalService` — deprecated
|
|
122
|
+
|
|
123
|
+
`responseToExternalService` and `responseHeaders` are **deprecated**. They still work — the runtime forwards
|
|
124
|
+
them to the platform untouched, so an existing service keeps behaving exactly as it did and needs no edit —
|
|
125
|
+
but they can only say *what the body is*, never what status or headers go with it. **Write
|
|
126
|
+
`responseToWebhook` in new code**, and move an old handler over when you next touch it:
|
|
127
|
+
|
|
128
|
+
| Deprecated | Write instead | Why |
|
|
129
|
+
|---|---|---|
|
|
130
|
+
| `responseToExternalService: 'token'` | `responseToWebhook: { rawBody: 'token' }` | a String was sent as raw `text/plain` — `body` is JSON, so it would arrive **quoted** |
|
|
131
|
+
| `responseToExternalService: { ok: true }` | `responseToWebhook: { body: { ok: true } }` | an object was JSON-serialized, and still is |
|
|
132
|
+
| `responseHeaders: { 'X-Echo': 'ok' }` | `responseToWebhook: { headers: { 'X-Echo': 'ok' } }` | |
|
|
133
|
+
|
|
134
|
+
⚠️ The String case is the one that bites: `body` would deliver `"token"` with the quotes, and a provider
|
|
135
|
+
comparing it to the token it sent sees a mismatch. **A String is always `rawBody`.**
|
|
136
|
+
|
|
137
|
+
⚠️ Do not return both from one response. They are forwarded side by side and the platform picks one — which
|
|
138
|
+
one is not yours to choose. Write one or the other.
|
|
139
|
+
|
|
140
|
+
**Reject by returning, never by throwing.** A throw on this path answers the provider **500**, and inbound
|
|
141
|
+
deliveries are **not retried** (every other trigger request type still is), so a rejection expressed as an
|
|
142
|
+
error is simply a failed delivery. The declarative `verify` block already follows this rule: a failed
|
|
143
|
+
signature check answers `{ events: [], responseToWebhook: { httpStatus: 401, rawBody: '' } }` — it does not
|
|
144
|
+
throw.
|
|
145
|
+
|
|
146
|
+
### ⚠️ `rawBody` is absent, never empty
|
|
147
|
+
|
|
148
|
+
`rawBody` is the unmodified bytes of the request, decoded as UTF-8 — and it is **absent** when there is
|
|
149
|
+
nothing to verify: a `GET`, a request with no body, a request sent without `Content-Length`, or a body over
|
|
150
|
+
5 MB. **Treat absent as "cannot verify"**, and answer accordingly:
|
|
151
|
+
|
|
152
|
+
```js
|
|
153
|
+
verifyRequest: ({ rawBody, headers }) => {
|
|
154
|
+
if (typeof rawBody !== 'string') {
|
|
155
|
+
return false // ✓ nothing to hash — this is not the same as a bad signature
|
|
156
|
+
}
|
|
157
|
+
…
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Hashing `''` instead produces a digest that can never match, which reads as a *signature mismatch* rather
|
|
162
|
+
than the missing input it is — and sends you hunting for a wrong secret.
|
|
163
|
+
|
|
164
|
+
### `verify` fields
|
|
165
|
+
|
|
166
|
+
HMACs the **raw body alone** with `secret(config)` and compares it to the header in constant time.
|
|
167
|
+
|
|
168
|
+
| Field | Req | Description |
|
|
169
|
+
|---|---|---|
|
|
170
|
+
| `header` | ✓ | Signature header. Read as declared, then retried lowercased. Absent header → fail. |
|
|
171
|
+
| `algo` | ✓ | Hash algorithm, e.g. `'sha256'`. |
|
|
172
|
+
| `encoding` | ✓ | `'hex' \| 'base64'` — the digest encoding the provider sends. |
|
|
173
|
+
| `secret` | ✓ | `(config) => key`. |
|
|
174
|
+
| `timestampHeader` | – | Header carrying the request timestamp. **Required for `freshness` to run.** |
|
|
175
|
+
| `freshness` | – | Max age in seconds. **Only checked when `timestampHeader` is also declared** — on its own it is silently inert. A declared-but-absent timestamp header passes. |
|
|
176
|
+
|
|
177
|
+
The signed payload is `rawBody` and nothing else. A provider that signs a **composed** string
|
|
178
|
+
(`{timestamp}.{body}`, a URL, a concatenation of fields) cannot be expressed here — use `verifyRequest` with
|
|
179
|
+
`Flowrunner.crypto`.
|
|
180
|
+
|
|
181
|
+
`subscribe` **is an upsert** (re-runs with the full desired set + prior `webhookData`; `unsubscribe` only
|
|
182
|
+
on flow stop). Two strategies:
|
|
183
|
+
|
|
184
|
+
- **Recreate** (Calendly, Backendless, joggai) — delete prior `webhookData` first, then create.
|
|
185
|
+
- **Reconcile/diff** (Slack, Box) — apply only additions/removals (no teardown).
|
|
186
|
+
|
|
187
|
+
Runtime provides `Flowrunner.crypto.hmac(algo,key,data,'hex'|'base64')` — **synchronous**, returning the
|
|
188
|
+
encoded digest as a string, not a Promise — `timingSafeEqual(a,b)` (false — not a throw — on nullish or
|
|
189
|
+
length mismatch, so a caller can `return` it), and `ageSeconds(timestamp)`.
|
|
190
|
+
`connectionId` + `webhookData` are runtime-owned/persisted.
|
|
191
|
+
|
|
192
|
+
## One trigger per event
|
|
193
|
+
|
|
194
|
+
**Register a separate trigger for each provider event. Never a single trigger with an event-type
|
|
195
|
+
parameter.** A "universal" trigger that takes `eventTypes: z.array(z.enum([...]))` and fans out inside its
|
|
196
|
+
own handler is wrong here, and the mechanism above is why: `extractProviderEventName` already routes each
|
|
197
|
+
inbound delivery to every trigger claiming that `providerEventName`, over **one** shared webhook
|
|
198
|
+
registration. `subscribe` receives the full desired trigger set, so it registers one URL for all of them.
|
|
199
|
+
|
|
200
|
+
Splitting them costs nothing at the transport level and buys everything at the flow level: each trigger gets
|
|
201
|
+
its own `label`, its own `description`, its own `result` sample and its own `params` — so a flow author picks
|
|
202
|
+
"On Message Edited" from a list instead of picking a generic trigger and then configuring which event they
|
|
203
|
+
meant. A `result` on a universal trigger cannot describe anything precise, because the payload differs per
|
|
204
|
+
event.
|
|
205
|
+
|
|
206
|
+
```js
|
|
207
|
+
// ✗ one trigger, an event-type param, and a result sample that fits none of them
|
|
208
|
+
ext.addRealtimeTrigger({
|
|
209
|
+
id : 'onUpdate',
|
|
210
|
+
params: z.object({ updateTypes: z.array(z.enum(['message', 'edited_message', 'callback_query'])) }),
|
|
211
|
+
result: { update_id: 1 },
|
|
212
|
+
})
|
|
213
|
+
|
|
214
|
+
// ✓ one per event — each with the shape that event actually delivers
|
|
215
|
+
ext.addRealtimeTrigger({ id: 'onMessage', providerEventName: 'message', result: { … } })
|
|
216
|
+
ext.addRealtimeTrigger({ id: 'onEditedMessage', providerEventName: 'edited_message', result: { … } })
|
|
217
|
+
ext.addRealtimeTrigger({ id: 'onCallbackQuery', providerEventName: 'callback_query', result: { … } })
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Use `params` for **filters** — which chat, which board, which status — never for choosing the event.
|
|
221
|
+
|
|
222
|
+
## `ext.addRealtimeTrigger(props)`
|
|
223
|
+
|
|
224
|
+
| Property | Type | Req | Description |
|
|
225
|
+
|---|---|---|---|
|
|
226
|
+
| `category`/`id`/`label`/`description` | string | ✓ | `id` is persisted and never changes. |
|
|
227
|
+
| `providerEventName` | string \| string[] \| `({params})=>string[]` | ✓* | Provider event(s) this trigger claims (routing). *Omitted when `resolveEvents` emits `id` directly. |
|
|
228
|
+
| `params` | `z.object` | – | Trigger config — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
|
|
229
|
+
| `result` | value \| schema \| loader | ✓ | Emitted event shape (post-`extendResult`). |
|
|
230
|
+
| `extendEventData` | fn | – | see table. |
|
|
231
|
+
| `match` | object \| fn | – | Instance selection (declarative object or predicate fn). |
|
|
232
|
+
| `extendResult` | fn | – | see table. |
|
|
233
|
+
| `oauth2Scopes` | string[] | – | Extra scopes. |
|
|
234
|
+
|
|
235
|
+
| Function | Arguments | Returns |
|
|
236
|
+
|---|---|---|
|
|
237
|
+
| `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
|
|
238
|
+
| `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
|
|
239
|
+
| `match` (fn) | `{ params, providerEventData }` | `boolean` — for ranges/contains/derived logic |
|
|
240
|
+
| `extendResult` | `{ providerEventData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
|
|
241
|
+
|
|
242
|
+
**Inbound runtime flow:** `handshake?` → `verify`/`verifyRequest` → read `extractProviderEventName` → for
|
|
243
|
+
each trigger whose `providerEventName` matches, build `providerEventData` (`extractProviderEventData` +
|
|
244
|
+
`extendEventData`) → `match` per instance → if ≥1 matched, `extendResult` once → fire.
|
|
245
|
+
|
|
246
|
+
**A trigger declaring no `match` fires every configured instance** — "no filter" means "fires always", and
|
|
247
|
+
that is a different case from a name this service does not declare, which selects nothing (see
|
|
248
|
+
[Unknown trigger names](#unknown-trigger-names)). Declining an unknown name never runs `extendResult`, so it
|
|
249
|
+
costs no provider call.
|
|
250
|
+
|
|
251
|
+
## `webhookData` lifecycle (persisted; realtime analog of polling `state`)
|
|
252
|
+
|
|
253
|
+
| Phase | Effect |
|
|
254
|
+
|---|---|
|
|
255
|
+
| subscribe (flow start) | `null → webhookData` (create webhook / resolve `eventScopeId`) |
|
|
256
|
+
| subscribe (set changed) | `webhookData → webhookData'` (recreate: delete prior + create; or diff) |
|
|
257
|
+
| inbound event | unchanged \| emits matched instances |
|
|
258
|
+
| refresh (opt) | `webhookData → webhookData'` (renew) |
|
|
259
|
+
| unsubscribe (flow stop) | `webhookData → {}` (tear down) |
|
|
260
|
+
|
|
261
|
+
## Frozen contract
|
|
262
|
+
|
|
263
|
+
These are persisted or read by live flows, so they are fixed once a service is deployed — changing one breaks
|
|
264
|
+
running automations:
|
|
265
|
+
|
|
266
|
+
`id` (trigger/action) · `params` keys · **`webhookData` shape** · `eventScopeId` ·
|
|
267
|
+
`refreshIntervalInSeconds` (seconds).
|
|
268
|
+
|
|
269
|
+
Transient and free to change: shaped events, matched ids, handshake responses.
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# 10 — Files API
|
|
2
|
+
|
|
3
|
+
File storage is opt-in per extension. Set `usesFileStorage: true` in
|
|
4
|
+
`Flowrunner.createExtension(...)` (see [01-service-structure.md](01-service-structure.md)) to provision
|
|
5
|
+
`ctx.files` in every handler's context bag. When `usesFileStorage` is false (the default), `ctx.files` is
|
|
6
|
+
a **proxy that throws** — so accidental use fails loudly instead of silently no-op'ing.
|
|
7
|
+
|
|
8
|
+
- `files` appears in the [handler context bag](07-actions.md) only when `usesFileStorage: true`.
|
|
9
|
+
- A param that references a stored file is declared `z.url()` (or `z.string()`) and carries the file's URL.
|
|
10
|
+
There is no file-picker widget, so the flow author binds the URL from an earlier block or pastes it.
|
|
11
|
+
|
|
12
|
+
## Method surface
|
|
13
|
+
|
|
14
|
+
`ctx.files` is the platform file-service client, and it is typed as such — the methods, options and
|
|
15
|
+
return shapes below are what an editor completes and checks, whether or not `usesFileStorage` is on (when
|
|
16
|
+
it is off the same type is backed by the proxy that throws). All options objects are optional.
|
|
17
|
+
|
|
18
|
+
| Method | Options | Returns | Options as a param |
|
|
19
|
+
|---|---|---|---|
|
|
20
|
+
| `uploadFile(buffer, options)` | `scope`, `filename`, `ttl`, `generateUrl` (default `true`), `objectTtl`, `overwrite` | `{ key, filename, url, size, urlExpiresAt, objectExpiresAt, overwritten }` | `z.filesUploadOptions([…])` |
|
|
21
|
+
| `list(options)` | `scope`, `ttl`, `generateUrl`, `limit`, `cursor` | `{ files: FileInfo[], cursor, hasMore }` | `z.filesListOptions([…])` |
|
|
22
|
+
| `get(filename, options)` | `scope`, `ttl`, `generateUrl` | `FileInfo` — `{ key, filename, url, size, createdAt, urlExpiresAt, objectExpiresAt }` | `z.filesGetOptions([…])` |
|
|
23
|
+
| `delete(filename, options)` | `scope` | `{ key, freedBytes, deleted }` | `z.filesDeleteOptions([…])` |
|
|
24
|
+
| `usage()` | — | `{ workspaceId, usedBytes, quotaBytes, usedFormatted, quotaFormatted, utilizationPercent, fileCount }` | — |
|
|
25
|
+
|
|
26
|
+
The last column is the same option list **as a parameter the flow author fills in** — see below.
|
|
27
|
+
|
|
28
|
+
| Option | Meaning |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `scope` | which storage layer — **defaults to `'FLOW'`**. Name it with `filesScope` rather than a string; `usage()` is always workspace-scoped |
|
|
31
|
+
| `ttl` | signed-URL lifetime, in seconds |
|
|
32
|
+
| `generateUrl` | whether to include a pre-signed URL in the result |
|
|
33
|
+
| `objectTtl` | how long the stored object lives; omit for permanent |
|
|
34
|
+
| `overwrite` | replace an existing file with the same name instead of failing |
|
|
35
|
+
| `limit` / `cursor` | pagination for `list` |
|
|
36
|
+
|
|
37
|
+
### Letting the flow author choose — the option groups
|
|
38
|
+
|
|
39
|
+
Every option in the tables above is also available as a **param group the platform ships**, one per call. So
|
|
40
|
+
a flow author can pick the storage layer — or a filename, a limit, a link lifetime — without you redeclaring
|
|
41
|
+
the dropdown, its values, its labels and its default:
|
|
42
|
+
|
|
43
|
+
```js
|
|
44
|
+
params: z.object({
|
|
45
|
+
fileOptions: z.filesUploadOptions(['scope']).label('File Settings').optional(),
|
|
46
|
+
})
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The argument is the whitelist of fields to expose, and the parsed object goes straight into the matching
|
|
50
|
+
call — `params.fileOptions` into `uploadFile`, `params.listOptions` into `list`, and so on:
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
execute: async ({ params, files }) => {
|
|
54
|
+
const bytes = await Flowrunner.Request.get(params.url).toBuffer()
|
|
55
|
+
|
|
56
|
+
return files.uploadFile(bytes, { ...params.fileOptions, filename: 'agreement.pdf' })
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**Do not hand-write these objects.** A copy in your service is a copy that stops tracking the platform: when
|
|
61
|
+
an option is added, a label reworded or a default changed, every service using the group picks it up and
|
|
62
|
+
yours does not. It is also how a service ends up publishing a setting the runtime does not have — a field a
|
|
63
|
+
flow author fills in that is silently dropped.
|
|
64
|
+
|
|
65
|
+
See *Platform param schemas* in [03-parameters.md](03-parameters.md) for the whitelist rules, the runtime
|
|
66
|
+
contract, and which options are risky to expose.
|
|
67
|
+
|
|
68
|
+
### Naming a layer — `filesScope`
|
|
69
|
+
|
|
70
|
+
The handler bag carries `filesScope`, the three layers as named constants, so a typo is a `TypeError` at the
|
|
71
|
+
call site instead of a scope that silently does not exist:
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
execute: async ({ files, filesScope }) => {
|
|
75
|
+
const scope = filesScope.WORKSPACE
|
|
76
|
+
|
|
77
|
+
const saved = await files.uploadFile(buffer, { scope, filename: 'report.txt' })
|
|
78
|
+
|
|
79
|
+
return files.list({ scope })
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
| | |
|
|
84
|
+
|---|---|
|
|
85
|
+
| `filesScope.WORKSPACE` | shared by the whole workspace, outlives every run |
|
|
86
|
+
| `filesScope.FLOW` | one flow, shared across its executions — the **default** |
|
|
87
|
+
| `filesScope.EXECUTION` | a single run; intermediate artifacts |
|
|
88
|
+
|
|
89
|
+
It is in the bag whether or not `usesFileStorage` is on — it is a set of constants, not a capability. Plain
|
|
90
|
+
strings still work, so nothing existing breaks.
|
|
91
|
+
|
|
92
|
+
`FLOW` and `EXECUTION` scopes require the flow / execution ids to be present in the execution context — the
|
|
93
|
+
runtime supplies them, but a call made outside a flow run (e.g. a design-time sample loader) can only use
|
|
94
|
+
`WORKSPACE`.
|
|
95
|
+
|
|
96
|
+
```js
|
|
97
|
+
const ext = Flowrunner.createExtension({ /* … */ usesFileStorage: true })
|
|
98
|
+
|
|
99
|
+
ext.addAction({
|
|
100
|
+
category: 'Files', id: 'saveReport', label: 'Save Report', description: '…',
|
|
101
|
+
params : z.object({ name: z.string().label('File name') }),
|
|
102
|
+
result : { url: 'https://…', size: 1024 },
|
|
103
|
+
execute: async ({ params, files, filesScope, apiRequest }) => {
|
|
104
|
+
const report = await apiRequest({ url: '/reports/export' })
|
|
105
|
+
const saved = await files.uploadFile(Buffer.from(report), {
|
|
106
|
+
scope: filesScope.FLOW, filename: params.name, generateUrl: true, ttl: 3600,
|
|
107
|
+
})
|
|
108
|
+
|
|
109
|
+
return { url: saved.url, size: saved.size }
|
|
110
|
+
},
|
|
111
|
+
})
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
> **`uploadFile` takes bytes, so fetch bytes.** `Buffer.from(text)` is right only when the source really is
|
|
115
|
+
> text. Download a PDF, an image or a zip with **`.toBuffer()`** and hand it over as it comes; fetching one
|
|
116
|
+
> through `apiRequest` decodes and parses it, and the corruption only shows up when someone opens the stored
|
|
117
|
+
> file ([04-http-requests.md](04-http-requests.md)).
|
|
118
|
+
>
|
|
119
|
+
> ```js
|
|
120
|
+
> const bytes = await Flowrunner.Request.get(params.fileUrl).toBuffer()
|
|
121
|
+
> const saved = await files.uploadFile(bytes, { scope: filesScope.FLOW, filename: 'report.pdf' })
|
|
122
|
+
> ```
|
|
123
|
+
|
|
124
|
+
> **Substituting the store.** A host can replace this client for one invocation by passing
|
|
125
|
+
> `runServiceMethod({ createFiles })`. The factory receives the file-service context —
|
|
126
|
+
> `{ serverURL, appId, apiKey, runtimeKey, flowId, executionId, retrieveNewS3Token }` — and returns anything
|
|
127
|
+
> satisfying **`FilesApi`**: the same five methods tabled above. `FilesApi` and its value types are exported
|
|
128
|
+
> from the package root, so an implementation can be type-checked against the contract. It is consulted only
|
|
129
|
+
> when the extension declares `usesFileStorage: true`; otherwise the throwing proxy is used as before.
|
|
130
|
+
>
|
|
131
|
+
> **Service code is unaffected and unaware** — it still calls `files.uploadFile(...)` and reads `url` off the
|
|
132
|
+
> result, and whatever URL the implementation returns is the URL the service passes on. The case this exists
|
|
133
|
+
> for is end-to-end testing: a harness implements `FilesApi` over its own storage (a local MinIO, a scratch
|
|
134
|
+
> bucket) and returns presigned URLs, so a third party in the test can really fetch what the service
|
|
135
|
+
> uploaded — no HTTP to the platform, no patching of runtime internals.
|
|
136
|
+
>
|
|
137
|
+
> Writing one, two things matter. Lay keys out per storage layer and list **one level at a time**: the
|
|
138
|
+
> execution prefix nests inside the flow prefix, so a recursive listing leaks a run's files into its flow —
|
|
139
|
+
> list with a delimiter. And clean up between runs yourself; there is no teardown hook, so deleting the test
|
|
140
|
+
> prefix is the harness's job.
|
|
141
|
+
|
|
142
|
+
> **Scopes need a flow.** `FLOW` and `EXECUTION` scopes address a path built from the running flow and
|
|
143
|
+
> execution, so they only work when there *is* one. A method invoked outside a flow execution — an OAuth
|
|
144
|
+
> step, a dictionary or loader, a manual run from the console — has neither, and a `FLOW`-scoped call (the
|
|
145
|
+
> default for `uploadFile` / `list` / `get` / `delete`) fails there. Use `WORKSPACE` scope for anything such
|
|
146
|
+
> a method has to read or write, and keep `FLOW`/`EXECUTION` for work that happens inside a flow.
|
|
147
|
+
>
|
|
148
|
+
> The same applies to `usage()`, which is always workspace-scoped and therefore works everywhere.
|