@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,193 @@
|
|
|
1
|
+
# 03 — Parameters
|
|
2
|
+
|
|
3
|
+
All params are **body params**. A handler's `execute` receives the parsed, typed `params`
|
|
4
|
+
(`z.infer<typeof params>`) — the schema you declare here is exactly what the handler sees, down to
|
|
5
|
+
optionality: `.optional()` gives `T | undefined`, and adding `.default(v)` drops the `undefined` because
|
|
6
|
+
the runtime fills it in first. Widgets and behaviors come from the zod type + plugins
|
|
7
|
+
(see [02-zod-types.md](02-zod-types.md)); the rest of the bag is typed too — see
|
|
8
|
+
[07-actions.md](07-actions.md#inferred-types).
|
|
9
|
+
|
|
10
|
+
```js
|
|
11
|
+
params: z.object({
|
|
12
|
+
chatId: chatIdParam,
|
|
13
|
+
text : z.text().label('Message'),
|
|
14
|
+
mode : z.enum(['A', 'B']).optional().label('Mode'),
|
|
15
|
+
})
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## `params` is optional — but if you declare it, it must be a `z.object`
|
|
19
|
+
|
|
20
|
+
An action or trigger that takes no input either leaves `params` out or declares `params: z.object({})`.
|
|
21
|
+
Both are correct; omitting is the shorter one.
|
|
22
|
+
|
|
23
|
+
```js
|
|
24
|
+
svc.addAction({
|
|
25
|
+
category: 'Account', id: 'ping', label: 'Ping', description: 'Health check.',
|
|
26
|
+
result : { ok: true },
|
|
27
|
+
execute : () => ({ ok: true }), // no `params` — the handler receives `params: {}`
|
|
28
|
+
})
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Anything that is **not** a `z.object` is rejected. The runtime needs a container of named fields — that is
|
|
32
|
+
what it validates input against and what it publishes as the method's input scheme — so there is exactly one
|
|
33
|
+
way to declare params, and it is checked the moment the service registers:
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
params: z.object({ chatId: z.string() }) // ✓ the only form for declared params
|
|
37
|
+
params: z.object({}) // ✓ or omit the property
|
|
38
|
+
params: z.string() // ✗ FR_EXT_INVALID_SCHEMA
|
|
39
|
+
params: { chatId: z.string() } // ✗ a raw shape is never auto-wrapped
|
|
40
|
+
params: {} // ✗
|
|
41
|
+
params: z.object({ … }).optional() // ✗ a container cannot be optional
|
|
42
|
+
params: z.object({ chatId: z.string().optional() }) // ✓ mark the FIELDS optional
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
A raw `{ … }` is never treated as sugar for `z.object({ … })`. Beyond keeping one way to write one thing, a
|
|
46
|
+
raw shape is not a zod type — so `params` in your handler would silently degrade from its inferred shape to
|
|
47
|
+
`Record<string, unknown>`.
|
|
48
|
+
|
|
49
|
+
The check runs while the service module loads, so `flowrunner deploy` fails before uploading and names the
|
|
50
|
+
item and the slot:
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
[flow-extension:hubspot] action "createContact": `params` must be a z.object({ … }) —
|
|
54
|
+
received z.string(); omit `params` entirely if there is nothing to declare
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The same rule applies to every schema slot: `configItems`, a dictionary's `criteria`,
|
|
58
|
+
`dynamicParams.criteria`, and the object `dynamicParams.resolve()` returns.
|
|
59
|
+
|
|
60
|
+
## Shared param schemas — one plugin call per line
|
|
61
|
+
|
|
62
|
+
A param reused across actions is declared once, named with a `Param` suffix, and **its chained plugin calls
|
|
63
|
+
each go on their own line, in a column**:
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
const chatIdParam = z.string()
|
|
67
|
+
.label('Chat')
|
|
68
|
+
.dictionary(getChatsDictionary)
|
|
69
|
+
.describe('Numeric chat ID or @channelusername.')
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Not `z.string().label('Chat').dictionary(getChatsDictionary).describe('…')`. The chain is a list of
|
|
73
|
+
independent facts about the field; one per line means a diff touches only the fact that changed, and a long
|
|
74
|
+
chain stays readable instead of running off the edge.
|
|
75
|
+
|
|
76
|
+
Inline params inside a `z.object({ … })` — the ones used by a single action and not worth naming — stay on
|
|
77
|
+
one line while they are short. The rule is about the shared, named schemas.
|
|
78
|
+
|
|
79
|
+
## Platform param schemas — file options
|
|
80
|
+
|
|
81
|
+
Some params are not yours to define. Wherever a flow author reaches into **file storage** — choosing which
|
|
82
|
+
layer a file lands in, which layer to list, how long a download link lives — the options, their labels, their
|
|
83
|
+
wording and their defaults belong to the platform, not to your service. `Flowrunner.z` ships them, so the
|
|
84
|
+
definition lives in one place instead of being retyped in every service that touches a file:
|
|
85
|
+
|
|
86
|
+
```js
|
|
87
|
+
params: z.object({
|
|
88
|
+
url : z.url().label('PDF URL'),
|
|
89
|
+
fileOptions: z.filesUploadOptions(['scope'])
|
|
90
|
+
.label('File Settings')
|
|
91
|
+
.describe('Where to store the downloaded PDF in FlowRunner file storage.')
|
|
92
|
+
.optional(),
|
|
93
|
+
})
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**There is one group per Files call**, and each one's fields are that call's options — so the group you want
|
|
97
|
+
is decided by the method your handler ends up calling:
|
|
98
|
+
|
|
99
|
+
| Factory | Feeds | Fields, in publish order |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| `z.filesUploadOptions()` | `files.uploadFile(bytes, options)` | `scope`, `filename`, `ttl`, `objectTtl`, `overwrite`, `generateUrl` |
|
|
102
|
+
| `z.filesListOptions()` | `files.list(options)` | `scope`, `limit`, `ttl`, `generateUrl`, `cursor` |
|
|
103
|
+
| `z.filesGetOptions()` | `files.get(filename, options)` | `scope`, `ttl`, `generateUrl` |
|
|
104
|
+
| `z.filesDeleteOptions()` | `files.delete(filename, options)` | `scope` |
|
|
105
|
+
|
|
106
|
+
What each field *means* is in [10-files-api.md](10-files-api.md) — it is the same option list, documented
|
|
107
|
+
once. Each factory returns a plain `z.object`, so it composes like any other schema: wrap it in your own
|
|
108
|
+
`.label()`, `.describe()` and `.optional()`, exactly as above. What comes from the platform is the *inside* —
|
|
109
|
+
the dropdown values, the labels, the help text and the defaults. Reword one of those and every service picks
|
|
110
|
+
the change up; hand-copy them and yours is the one that goes stale.
|
|
111
|
+
|
|
112
|
+
### One per call
|
|
113
|
+
|
|
114
|
+
```js
|
|
115
|
+
// upload — where should this file go?
|
|
116
|
+
fileOptions: z.filesUploadOptions(['scope']).label('File Settings').optional(),
|
|
117
|
+
|
|
118
|
+
// list — which layer, and how many?
|
|
119
|
+
listOptions: z.filesListOptions(['scope', 'limit']).label('Lookup').optional(),
|
|
120
|
+
|
|
121
|
+
// get — which layer, and how long should the link live?
|
|
122
|
+
getOptions: z.filesGetOptions(['scope', 'ttl']).label('Download').optional(),
|
|
123
|
+
|
|
124
|
+
// delete — which layer?
|
|
125
|
+
deleteOptions: z.filesDeleteOptions().label('Storage').optional(),
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`z.filesDeleteOptions()` declares one field, so it needs no whitelist; the others are usually worth
|
|
129
|
+
subsetting. Each one's parsed value goes straight into the matching call:
|
|
130
|
+
|
|
131
|
+
```js
|
|
132
|
+
execute: async ({ params, files }) => {
|
|
133
|
+
const found = await files.list(params.listOptions)
|
|
134
|
+
|
|
135
|
+
return files.get(found.files[0].filename, params.getOptions)
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Each group also identifies itself in the published model — `uiComponent: { type: 'FILE_UPLOAD_OPTIONS' }`,
|
|
140
|
+
and `FILE_LIST_OPTIONS` / `FILE_GET_OPTIONS` / `FILE_DELETE_OPTIONS` for the others (see
|
|
141
|
+
[11-output-model.md](11-output-model.md)) — which is what lets the platform recognise its own options object
|
|
142
|
+
and render it as one. A hand-written copy is just an anonymous object, and gets the generic nested form.
|
|
143
|
+
|
|
144
|
+
**The argument is the field whitelist.** Expose only what the flow author should decide, and let the handler
|
|
145
|
+
choose the rest:
|
|
146
|
+
|
|
147
|
+
```js
|
|
148
|
+
z.filesUploadOptions(['scope']) // one setting on screen — the common case
|
|
149
|
+
z.filesUploadOptions(['scope', 'filename']) // two
|
|
150
|
+
z.filesUploadOptions() // all six
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Two things about that list. The published order is the **group's**, not the list's — `['filename', 'scope']`
|
|
154
|
+
still shows `scope` first. And an unknown name throws while the service registers, naming the valid fields,
|
|
155
|
+
rather than quietly publishing an empty settings panel.
|
|
156
|
+
|
|
157
|
+
> **Think before exposing `generateUrl`.** It is the one option whose wrong value fails *quietly*: with it
|
|
158
|
+
> off, the call succeeds and the result's `url` is empty, so an action that returns a URL reports success and
|
|
159
|
+
> hands the flow nothing. If your action's result carries a URL, leave `generateUrl` out of the whitelist and
|
|
160
|
+
> pass `true` yourself — the flow author has no way to know that turning it off breaks the block.
|
|
161
|
+
|
|
162
|
+
**The group is also the contract at runtime.** A `z.object` strips what it does not declare, so
|
|
163
|
+
`z.filesUploadOptions(['scope'])` hands your handler `{ scope }` and nothing else, with the platform default
|
|
164
|
+
already filled in. Anything you did not expose is yours to pass:
|
|
165
|
+
|
|
166
|
+
```js
|
|
167
|
+
execute: async ({ params, files }) => {
|
|
168
|
+
const bytes = await Flowrunner.Request.get(params.url).toBuffer()
|
|
169
|
+
|
|
170
|
+
return files.uploadFile(bytes, { ...params.fileOptions, filename: 'agreement.pdf' })
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Spread the caller's options **first** — a hardcoded value after the spread is the one you meant to be
|
|
175
|
+
non-negotiable, and one before it is silently overridable.
|
|
176
|
+
|
|
177
|
+
See [10-files-api.md](10-files-api.md) for what each option does.
|
|
178
|
+
|
|
179
|
+
## Dynamic params — `dynamicParams`
|
|
180
|
+
|
|
181
|
+
Generate additional top-level param fields at runtime (e.g. fields that depend on a chosen resource):
|
|
182
|
+
|
|
183
|
+
| Property | Type | Description |
|
|
184
|
+
|---|---|---|
|
|
185
|
+
| `criteria` | `z.object` | Dependency inputs → become `dependsOn`. |
|
|
186
|
+
| `resolve` | fn | `({ criteria, context, apiRequest }) => z.object({...})` — extra params merged into `params`. |
|
|
187
|
+
|
|
188
|
+
The `resolve` function returns a `z.object(...)` whose fields are merged into the static `params`. The
|
|
189
|
+
declared `criteria` inputs become the `dependsOn` set that triggers re-resolution when they change.
|
|
190
|
+
|
|
191
|
+
`resolve` must return a `z.object` — anything else fails with `FR_EXT_INVALID_SCHEMA` when the console calls
|
|
192
|
+
it. This is the one slot that cannot be checked while the service loads, since the schema does not exist
|
|
193
|
+
until the resolver runs.
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# 04 — HTTP Requests
|
|
2
|
+
|
|
3
|
+
Services make HTTP calls through a **shared `apiRequest` helper** declared once on the extension
|
|
4
|
+
(`createExtension({ apiRequest })`, see [01-service-structure.md](01-service-structure.md)). It centralizes
|
|
5
|
+
base URL, auth, envelope-unwrapping, error-normalization and redacted logging so individual handlers stay
|
|
6
|
+
declarative.
|
|
7
|
+
|
|
8
|
+
```js
|
|
9
|
+
apiRequest: async ({ url, method = 'get', body, query, context }) =>
|
|
10
|
+
new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
|
|
11
|
+
.set({ Authorization: `Bearer ${ context.apiKey }` })
|
|
12
|
+
.query(query),
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The constructor form takes the verb as a value, which is what you want when `method` arrives as an argument.
|
|
16
|
+
Avoid `Flowrunner.Request[method.toLowerCase()](url)`: an object lookup keyed by a variable resolves
|
|
17
|
+
inherited names such as `constructor` when the value is ever anything unexpected
|
|
18
|
+
([16-gotchas.md](16-gotchas.md)).
|
|
19
|
+
|
|
20
|
+
## `apiRequest` argument
|
|
21
|
+
|
|
22
|
+
Author-defined, but conventionally:
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
{ url, method = 'get', body, query, context, logger, logTag, ...custom }
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- `context` is the return of `initContext` (see [01-service-structure.md](01-service-structure.md)) — the
|
|
29
|
+
place to read resolved credentials/tokens.
|
|
30
|
+
- The helper is exposed in every handler's context bag as `apiRequest` (see [07-actions.md](07-actions.md)),
|
|
31
|
+
and is also the natural building block for `helpers`.
|
|
32
|
+
|
|
33
|
+
The rest of this document is the client surface underneath that helper — `Flowrunner.Request`, the runtime
|
|
34
|
+
HTTP client, always on the global ([13-runtime-contracts.md](13-runtime-contracts.md)) and requiring no
|
|
35
|
+
import.
|
|
36
|
+
|
|
37
|
+
## Sending: the instance is thenable
|
|
38
|
+
|
|
39
|
+
Every chainable below returns the **same request instance**, and the instance has a `.then`. Nothing is sent
|
|
40
|
+
while you build the chain — **`await` is what issues the request**:
|
|
41
|
+
|
|
42
|
+
```js
|
|
43
|
+
await Flowrunner.Request.get(url) // sends
|
|
44
|
+
await Flowrunner.Request.post(url).set(headers) // sends
|
|
45
|
+
await Flowrunner.Request.post(url).form(formData) // sends
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Two methods are terminal instead: `.send(body?)` and `.toBuffer()`.** They issue the request immediately
|
|
49
|
+
and return a plain `Promise`, not the request — so nothing can be chained after them, and they must come
|
|
50
|
+
last:
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
await Flowrunner.Request.post(url).set(headers).send(body) // correct — .send() last
|
|
54
|
+
Flowrunner.Request.post(url).send(body).set(headers) // TypeError: .set is not a function
|
|
55
|
+
|
|
56
|
+
await Flowrunner.Request.get(url).set(headers).toBuffer() // correct — .toBuffer() last
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
By default the promise resolves to the **response body**. A non-2xx rejects — see *Failures*.
|
|
60
|
+
|
|
61
|
+
## Methods
|
|
62
|
+
|
|
63
|
+
| Static | Body argument |
|
|
64
|
+
|---|---|
|
|
65
|
+
| `Flowrunner.Request.get(url)` | – |
|
|
66
|
+
| `Flowrunner.Request.head(url)` | – |
|
|
67
|
+
| `Flowrunner.Request.options(url)` | – |
|
|
68
|
+
| `Flowrunner.Request.post(url, body?)` | ✓ |
|
|
69
|
+
| `Flowrunner.Request.put(url, body?)` | ✓ |
|
|
70
|
+
| `Flowrunner.Request.patch(url, body?)` | ✓ |
|
|
71
|
+
| `Flowrunner.Request.delete(url, body?)` | ✓ |
|
|
72
|
+
| `new Flowrunner.Request(url, method, body?)` | ✓ — verb as a value, either case |
|
|
73
|
+
|
|
74
|
+
The optional second argument is the body, identical to `.send(body)` except that it leaves the chain open:
|
|
75
|
+
|
|
76
|
+
```js
|
|
77
|
+
await Flowrunner.Request.post(url, { name: 'Bob' }).set(headers) // body first, still chainable
|
|
78
|
+
await Flowrunner.Request.post(url).set(headers).send({ name: 'Bob' })
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Query parameters
|
|
82
|
+
|
|
83
|
+
`.query(obj)` appends to the URL's query string:
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
await Flowrunner.Request.get('https://api.vendor.com/items')
|
|
87
|
+
.query({ str: 'abc', num: 123, bool: true, list: [1, 2, 3] })
|
|
88
|
+
// → /items?str=abc&num=123&bool=true&list=1&list=2&list=3
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
- An **array repeats the key** (`list=1&list=2&list=3`); there is no bracket or comma form.
|
|
92
|
+
- `undefined` values are **dropped**; `null` is **serialized as the string `null`** (`nil=null`), which is
|
|
93
|
+
almost never what an API wants. Strip empties before calling `.query()` — on `undefined`/`null` rather than
|
|
94
|
+
on falsiness, because an empty string is a value ([16-gotchas.md](16-gotchas.md)).
|
|
95
|
+
|
|
96
|
+
> **Do not combine an inline query string with `.query()`.** The two are concatenated without normalizing the
|
|
97
|
+
> separator, so `Request.get('/p?a=1').query({ b: 2 })` puts **`/p?a=1?b=2`** on the wire — a second `?`
|
|
98
|
+
> instead of an `&`. Pass a bare path and put every parameter in `.query()`; a unit suite then reads `query`
|
|
99
|
+
> back as a parsed object ([15-unit-tests.md](15-unit-tests.md)).
|
|
100
|
+
|
|
101
|
+
## Headers
|
|
102
|
+
|
|
103
|
+
`.set()` takes either a name and a value, or an object, and may be called repeatedly:
|
|
104
|
+
|
|
105
|
+
```js
|
|
106
|
+
await Flowrunner.Request.get(url)
|
|
107
|
+
.set('X-Api-Key', apiKey)
|
|
108
|
+
.set({ Accept: 'application/json', 'X-Trace': traceId })
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`.type(contentType)` is shorthand for setting `Content-Type`. One is set for you when the body is an object
|
|
112
|
+
(`application/json`) or a form (multipart with a generated boundary), so set it by hand only to override
|
|
113
|
+
that. `.basicAuth({ token })` and `.authKey(key)` are shorthands for the two common schemes; anything else is
|
|
114
|
+
an ordinary header.
|
|
115
|
+
|
|
116
|
+
## Request body
|
|
117
|
+
|
|
118
|
+
An object body is serialized as JSON:
|
|
119
|
+
|
|
120
|
+
```js
|
|
121
|
+
await Flowrunner.Request.post(url).send({ name: 'Bob', tags: ['a', 'b'] })
|
|
122
|
+
await Flowrunner.Request.post(url).type('text/plain').send('raw text')
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Forms and file uploads
|
|
126
|
+
|
|
127
|
+
`.form(data)` sets a form-data body — this is the multipart path, and there is no `.attach()`. It takes a
|
|
128
|
+
**plain object**, the **global WHATWG `FormData`** (the Node 18+ one, same as a browser's), or a
|
|
129
|
+
`Flowrunner.Request.FormData`. The plain object is the shortest and the one to reach for:
|
|
130
|
+
|
|
131
|
+
```js
|
|
132
|
+
await request.form({
|
|
133
|
+
chat_id: String(chatId), // text part
|
|
134
|
+
photo : new File([bytes], 'shot.png', { type: 'image/png' }), // name + type in one go
|
|
135
|
+
|
|
136
|
+
// the explicit form, when the value is a Buffer or a stream
|
|
137
|
+
doc : { value: bytes, options: { filename: 'report.pdf', contentType: 'application/pdf' } },
|
|
138
|
+
}) // note: awaited, not .send()
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
An array value repeats the key, one part per element. Whichever shape you pass, this is a Node-style
|
|
142
|
+
**streaming** multipart body underneath, and these are the values a part may hold:
|
|
143
|
+
|
|
144
|
+
| Value | What is sent |
|
|
145
|
+
|---|---|
|
|
146
|
+
| string, number, boolean | a text part — numbers and booleans are coerced to strings |
|
|
147
|
+
| `Buffer`, `Uint8Array` | a binary part; give it a name via the `{ value, options }` form |
|
|
148
|
+
| `File` | a binary part, **streamed** — the shortest way to send a named file: `filename` comes from its name and `contentType` from its type, so no options are needed. `size` sets `Content-Length`, so a large file is not held in memory twice |
|
|
149
|
+
| `Blob` | the same, but it has no name — every Blob part is sent as `filename="blob"`, and a Blob with no `type` as `application/octet-stream`. Use a `File`, or the `{ value, options }` form, when the filename matters |
|
|
150
|
+
| a stream | a binary part; pass `knownLength` in the options or the length cannot be computed |
|
|
151
|
+
| `{ value, options }` | any of the above plus explicit `filename` / `contentType` / `knownLength` — **these options win** over anything derived from a Blob. **Both keys must be present**: `{ value: bytes }` alone is read as an ordinary object and refused |
|
|
152
|
+
|
|
153
|
+
Pass `contentType` explicitly for a Buffer or a stream — omitted, one is derived from `filename` and you
|
|
154
|
+
inherit whatever that lookup returns (`a.bin` → `application/octet-stream`).
|
|
155
|
+
|
|
156
|
+
Anything else — a plain object, a class instance — is refused **with the field named**, before the body
|
|
157
|
+
starts streaming:
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
The form field "photo" can not be sent, expected a Buffer, a stream, a Blob or a primitive value,
|
|
161
|
+
received an instance of ReadableStream.
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
> **A `Blob` or a `File` goes to `.form()`, never onto a `Flowrunner.Request.FormData`.** That instance
|
|
165
|
+
> takes only a Buffer, a stream or a primitive, so `form.append('file', new Blob([bytes]), 'a.png')` throws
|
|
166
|
+
> **`source.on is not a function`**. Put it in the object you hand to `.form()`, or on a global `FormData`,
|
|
167
|
+
> and it is streamed for you.
|
|
168
|
+
|
|
169
|
+
Reach for `Flowrunner.Request.FormData` when you want the encoded body in hand: it exposes `getBoundary()`,
|
|
170
|
+
`getHeaders()`, `getBuffer()` and `getLength()`, which are how a test or a scratch check inspects what would
|
|
171
|
+
go out.
|
|
172
|
+
|
|
173
|
+
> **Never follow `.form(data)` with `.send()`.** `.form()` only stages the body; `.send()` is what issues the
|
|
174
|
+
> request, and a bare `.send()` issues it with **no body at all** — no `Content-Type`, no fields,
|
|
175
|
+
> `Content-Length: 0`. The vendor then answers as though no parameters were passed, which reads like a bug in
|
|
176
|
+
> your parameter mapping rather than in the transport.
|
|
177
|
+
>
|
|
178
|
+
> ```js
|
|
179
|
+
> await request.form(form) // correct
|
|
180
|
+
> await request.send(form) // also correct — .send() accepts the form
|
|
181
|
+
> request.form(form).send() // WRONG — one empty request, silently
|
|
182
|
+
> ```
|
|
183
|
+
|
|
184
|
+
## Response handling
|
|
185
|
+
|
|
186
|
+
| Call | Effect |
|
|
187
|
+
|---|---|
|
|
188
|
+
| *(default)* | resolves to the response **body** |
|
|
189
|
+
| `.unwrapBody(false)` | resolves to `{ status, statusText, headers, body }` |
|
|
190
|
+
| `.toBuffer()` | **terminal** — sends, and resolves the body as raw bytes |
|
|
191
|
+
| `.setTimeout(ms)` | per-request client timeout |
|
|
192
|
+
|
|
193
|
+
Use `.unwrapBody(false)` when the status or a response header carries meaning — a pagination cursor in a
|
|
194
|
+
`Link` header, a `Retry-After`, a `204` that must be told apart from an empty body.
|
|
195
|
+
|
|
196
|
+
### Binary downloads
|
|
197
|
+
|
|
198
|
+
**`.toBuffer()` downloads bytes** — a PDF, an image, a video. It is terminal, so it comes last, and it
|
|
199
|
+
resolves a `Buffer` you pass straight on:
|
|
200
|
+
|
|
201
|
+
```js
|
|
202
|
+
const bytes = await Flowrunner.Request.get(fileUrl).set(headers).toBuffer()
|
|
203
|
+
|
|
204
|
+
await request.form({ file: new File([bytes], 'report.pdf', { type: 'application/pdf' }) }) // forward it
|
|
205
|
+
await files.uploadFile(bytes, { filename: 'report.pdf' }) // or store it
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
- The body is returned byte for byte, including when its content happens to be valid JSON.
|
|
209
|
+
- A response with no body — a `204`, a `Content-Length: 0` — resolves to an **empty buffer**, never `''`.
|
|
210
|
+
- A non-2xx rejects as everywhere else, with the *error* body parsed when it is JSON, so
|
|
211
|
+
`error.status` and `error.body.message` read normally.
|
|
212
|
+
- `.unwrapBody(false)` composes: the whole response resolves and `body` is the bytes.
|
|
213
|
+
|
|
214
|
+
Use it for **every** binary download; do not reach for a response encoding.
|
|
215
|
+
|
|
216
|
+
Per platform policy **no execution timeout** is imposed around service code; `.setTimeout(ms)` is a
|
|
217
|
+
per-request client timeout, which is a different thing.
|
|
218
|
+
|
|
219
|
+
## Client certificates
|
|
220
|
+
|
|
221
|
+
An API that requires mutual TLS needs a client certificate on **every** call, including the OAuth2 token
|
|
222
|
+
request, so it belongs in `apiRequest` rather than in individual actions:
|
|
223
|
+
|
|
224
|
+
```js
|
|
225
|
+
apiRequest: async ({ url, method = 'get', body, query, context }) =>
|
|
226
|
+
new Flowrunner.Request(`${ context.apiUrl }${ url }`, method, body)
|
|
227
|
+
.cert({ cert: context.clientCert, key: context.clientKey })
|
|
228
|
+
.query(query),
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`.cert()` and its failure modes are [17-client-certificates.md](17-client-certificates.md); read it when the
|
|
232
|
+
vendor requires one.
|
|
233
|
+
|
|
234
|
+
## Failures
|
|
235
|
+
|
|
236
|
+
A non-2xx **rejects** with a `ResponseError`:
|
|
237
|
+
|
|
238
|
+
| Property | Value |
|
|
239
|
+
|---|---|
|
|
240
|
+
| `status` | HTTP status |
|
|
241
|
+
| `headers` | response headers |
|
|
242
|
+
| `body` | parsed response body |
|
|
243
|
+
| `message` | the response body when there is one — **so it is not always a string** — else `Status Code <status> (<statusText>)`. A 502 is `No connection with server`. |
|
|
244
|
+
|
|
245
|
+
Because `message` is the raw body for most JSON APIs, reading it as a string used to produce an unreadable
|
|
246
|
+
`[object Object]`. The platform now renders an unhandled failure as the provider's response body — the
|
|
247
|
+
Execute tab, a Run Block result and a flow's error exit all show that body rather than `[object Object]` —
|
|
248
|
+
so a service that does nothing still fails legibly.
|
|
249
|
+
|
|
250
|
+
Normalising it yourself in `apiRequest` is still worth doing, and is still the main reason `apiRequest`
|
|
251
|
+
exists: the raw body is whatever the vendor chose to send, often wrapped in an envelope and carrying fields
|
|
252
|
+
a flow author has no use for. A one-line `Error` naming the service and the actual reason reads better than
|
|
253
|
+
a dump of it, and you write it once here rather than per action.
|
|
254
|
+
|
|
255
|
+
A transport failure — a dropped connection, DNS, a refused socket — rejects with **no `status` and no
|
|
256
|
+
`body`**. Services routinely handle one kind and not the other; both are worth a test
|
|
257
|
+
([15-unit-tests.md](15-unit-tests.md)).
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# 05 — Dictionaries
|
|
2
|
+
|
|
3
|
+
Dictionaries provide **dynamic options** for a param dropdown. `ext.dictionary(props)` returns a ref used
|
|
4
|
+
via `.dictionary(ref)` on a param (see [02-zod-types.md](02-zod-types.md)). A dictionary declares its
|
|
5
|
+
`criteria` once, and consumers auto-derive their `dependsOn` from it.
|
|
6
|
+
|
|
7
|
+
| Property | Type | Description |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `id` | string | Dictionary id — **starts with `get`, ends with `Dictionary`** (`getChatsDictionary`). |
|
|
10
|
+
| `category` | string | Optional grouping label. Defaults to `''` — unlike an action's `category`, which is required. The v1 convention was to leave dictionaries uncategorised, so set it only to match a v1 dictionary that declared one. |
|
|
11
|
+
| `label` | string | **Human-readable name** → `operationName`. Dictionaries are shown in the UI and exposed to AI tools, so **always set a label**. Falls back to `id` when omitted. |
|
|
12
|
+
| `description` | string | Description. |
|
|
13
|
+
| `criteria` | `z.object` | Optional dependency inputs (become `dependsOn` on consumers). Omit when the dictionary depends on nothing; declared ⇒ must be a `z.object` (see [03-parameters.md](03-parameters.md)). |
|
|
14
|
+
| `result` | `{ items, cursor }` \| `z.` schema | Optional sample output → `metaInfo.sampleResult` + `OBJECT` `returnType`. Omit → `sampleResult: null`, `returnType: OBJECT`. |
|
|
15
|
+
| `execute` | fn | see below. |
|
|
16
|
+
|
|
17
|
+
| `execute` arguments | Returns |
|
|
18
|
+
|---|---|
|
|
19
|
+
| `{ search, cursor, criteria, context, apiRequest, helpers }` | `{ items: [{ label, value, note? }], cursor? }` (bare array ok if no pagination) |
|
|
20
|
+
|
|
21
|
+
```js
|
|
22
|
+
const getTablesDictionary = ext.dictionary({
|
|
23
|
+
id : 'getTablesDictionary',
|
|
24
|
+
label : 'Tables',
|
|
25
|
+
description: 'Tables in the base',
|
|
26
|
+
criteria : z.object({ baseId: z.string().label('Base ID') }),
|
|
27
|
+
result : { items: [{ label: 'Base A', value: 'a' }], cursor: null },
|
|
28
|
+
execute : async ({ search, criteria, apiRequest }) => {
|
|
29
|
+
return { items: [], cursor: null }
|
|
30
|
+
},
|
|
31
|
+
})
|
|
32
|
+
|
|
33
|
+
// consumer:
|
|
34
|
+
const tableIdParam = z.string()
|
|
35
|
+
.label('Table')
|
|
36
|
+
.dictionary(getTablesDictionary) // auto dependsOn: ['baseId']
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
- The `execute` bag is the shared handler context (see [07-actions.md](07-actions.md)) plus `search`,
|
|
40
|
+
`cursor`, and the resolved `criteria`.
|
|
41
|
+
- Return `{ items, cursor }` for paginated sources, or a bare `items` array when there is no pagination.
|
|
42
|
+
- **The `id` starts with `get` and ends with `Dictionary`**, and the const holding the ref carries the same
|
|
43
|
+
name — so the declaration and every `.dictionary(ref)` read alike.
|
|
44
|
+
|
|
45
|
+
## Browse versus resolve — a dictionary does not need a listing endpoint
|
|
46
|
+
|
|
47
|
+
`execute` receives **`search`**, the text the flow author has typed. That makes two different dictionaries
|
|
48
|
+
possible, and only the first needs an endpoint that enumerates anything:
|
|
49
|
+
|
|
50
|
+
- **Browse** — the API has a listing endpoint. Ignore or filter by `search`, page with `cursor`, return the
|
|
51
|
+
set. This is the common case.
|
|
52
|
+
- **Resolve** — the API has no listing endpoint but *can* look up one entity by id, handle or URL. Call that
|
|
53
|
+
lookup with `search` and return the single hit, labelled with something human (`'Team Standup (group)'`)
|
|
54
|
+
and valued with the id. Return an empty array for empty or unmatched `search`, and use `description` to
|
|
55
|
+
tell the author what to type.
|
|
56
|
+
|
|
57
|
+
**"The API has no endpoint that lists these" is not a reason to leave a parameter as free text.** It rules
|
|
58
|
+
out *browse*, not *resolve*. A resolve dictionary still validates the value before the flow runs, still shows
|
|
59
|
+
the author the name of the thing they picked instead of a bare id, and still surfaces the parameter to AI
|
|
60
|
+
tools as a resolvable option. Reach for plain free text only when the API can neither list nor look up the
|
|
61
|
+
value — and say so in the service `README.md` when that happens.
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
// Resolve: no "list my chats" endpoint exists, but a single chat can be fetched by id or @username
|
|
65
|
+
const getChatsDictionary = ext.dictionary({
|
|
66
|
+
id : 'getChatsDictionary',
|
|
67
|
+
label : 'Chats',
|
|
68
|
+
description: 'Type a numeric chat ID or @username to resolve the chat.',
|
|
69
|
+
result : { items: [{ label: 'Team Standup (group)', value: '-1001234567890' }], cursor: null },
|
|
70
|
+
execute : async ({ search, apiRequest }) => {
|
|
71
|
+
if (!search?.trim()) {
|
|
72
|
+
return { items: [], cursor: null }
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
try {
|
|
76
|
+
const chat = await apiRequest({ url: '/getChat', query: { chat_id: search.trim() } })
|
|
77
|
+
|
|
78
|
+
return { items: [{ label: `${ chat.title ?? chat.username } (${ chat.type })`, value: String(chat.id) }] }
|
|
79
|
+
} catch (error) {
|
|
80
|
+
if (isUnresolvableInput(error)) {
|
|
81
|
+
return { items: [], cursor: null } // unresolvable input is an empty list, not an error
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
throw error // a credential or transport failure is not "no matches"
|
|
85
|
+
}
|
|
86
|
+
},
|
|
87
|
+
})
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
A resolve dictionary usually declares no `criteria` — the input is `search`, not a dependency on another
|
|
91
|
+
field.
|
|
92
|
+
|
|
93
|
+
**Validation note.** The payload is validated in two steps: the `{ search, cursor, criteria }` envelope,
|
|
94
|
+
then `criteria` on its own against the declared schema. A criteria failure is reported separately
|
|
95
|
+
(`FR_EXT_INVALID_CRITERIA`) so the UI can point at the dependent fields — which is why `criteria` should
|
|
96
|
+
list exactly the inputs `execute` needs, and mark anything genuinely optional as such. `execute` receives
|
|
97
|
+
the parsed criteria (defaults applied, unknown fields dropped).
|
|
98
|
+
|
|
99
|
+
**Model note.** A dictionary is invoked through the helper-method route with a single `payload`
|
|
100
|
+
(`{ search, cursor, criteria }`) — the runner synthesizes a `payload` OBJECT bodyParam describing
|
|
101
|
+
`search` + `cursor` (+ a nested `criteria` object when `criteria` is declared) and puts the `"Payload"`
|
|
102
|
+
label in `metaInfo.args`. You do **not** declare `search`/`cursor` yourself. See
|
|
103
|
+
[11-output-model.md](11-output-model.md).
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# 06 — OAuth2
|
|
2
|
+
|
|
3
|
+
Declare OAuth with `ext.setupOauth2(props)`. Its **presence ⇒ `requireOAuth = true`**. It is declarative
|
|
4
|
+
for the common case; any handler below overrides its step. Combined scopes = `scopes` ∪ every op's
|
|
5
|
+
`oauth2Scopes` (deduped), passed to handlers as `scopes`.
|
|
6
|
+
|
|
7
|
+
| Property | Type | Description |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `scopes` | string[] | Base scope list. |
|
|
10
|
+
| `authorizeUrl` / `tokenUrl` | string | Declarative endpoints. |
|
|
11
|
+
| `pkce` | boolean | Runtime generates verifier/challenge + threads state. |
|
|
12
|
+
| `clientAuth` | `'basic' \| 'body'` | Client credential placement. |
|
|
13
|
+
| `identityRequest` | fn | `({ apiRequest }) => raw` — fetch the account identity. |
|
|
14
|
+
| `identity` | fn | `(raw) => { name, imageUrl?, userData? }`. |
|
|
15
|
+
| `getConnectionURL` (esc) | fn | see below. |
|
|
16
|
+
| `executeCallback` (esc) | fn | see below. |
|
|
17
|
+
| `refreshToken` (esc) | fn | see below. |
|
|
18
|
+
| `serializeToken` / `deserializeToken` | fn | Composite-token (de)serialization; runtime deserializes the header token into `oauth.token` before `initContext`. |
|
|
19
|
+
|
|
20
|
+
## Escape-hatch handlers → returns
|
|
21
|
+
|
|
22
|
+
| Handler | Arguments | Returns |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `getConnectionURL` | `{ config, context, scopes }` | `string` (authorize URL) |
|
|
25
|
+
| `executeCallback` | `{ callbackObject, config, context }` | `{ token, expirationInSeconds?, refreshToken?, connectionIdentityName?, connectionIdentityImageURL?, overwrite?, userData? }` |
|
|
26
|
+
| `refreshToken` | `{ refreshToken, config, context }` | `{ token, expirationInSeconds?, refreshToken? }` |
|
|
27
|
+
|
|
28
|
+
## Using OAuth in handlers
|
|
29
|
+
|
|
30
|
+
`oauth` derives only from the `oauth-access-token` header → `oauth = { accessToken, token? }` (`token` =
|
|
31
|
+
`deserializeToken(accessToken)`). Per-op opt-in for extra scopes: set `oauth2Scopes: ['extra.scope']` on
|
|
32
|
+
any action, **polling** trigger, or dictionary.
|
|
33
|
+
|
|
34
|
+
`token` is the one slot in the handler bag left open rather than inferred: `setupOauth2` runs after
|
|
35
|
+
`createExtension` has already resolved the service shape, so a `deserializeToken` return cannot flow back
|
|
36
|
+
into every handler. Annotate it where you read it if the composite shape matters.
|
|
37
|
+
|
|
38
|
+
> Scopes declared on a **realtime** trigger are currently **not** collected into the authorize URL — the
|
|
39
|
+
> runtime unions `scopes` with the `oauth2Scopes` of actions, polling triggers and dictionaries only. Put a
|
|
40
|
+
> realtime trigger's scopes in the extension-level `scopes` instead.
|
|
41
|
+
|
|
42
|
+
Client id/secret are typically `configItems` marked `.shared()` (see [02-zod-types.md](02-zod-types.md)).
|