@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,142 @@
|
|
|
1
|
+
# 11 — Service Model
|
|
2
|
+
|
|
3
|
+
Declaring a service produces the platform's service model — `SharedExtensionServiceInfo` + `methodsMap` +
|
|
4
|
+
config descriptions. This is what the console UI, the flow editor and AI tools consume, so it is the contract
|
|
5
|
+
your declarations have to satisfy.
|
|
6
|
+
|
|
7
|
+
| What you declare | Model output |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `createExtension({ id, name, … })` | `SharedExtensionServiceInfo` |
|
|
10
|
+
| `configItems` (`.shared()` → shared) | `appConfigDescriptions` / `sharedConfigDescriptions`, **plus `configSchema`** |
|
|
11
|
+
| `addAction` | `SharedExtensionMethod` `registerAs: ACTION` |
|
|
12
|
+
| `dictionary` | `SharedExtensionMethod` `registerAs: DICTIONARY` — `label`→`operationName` (else `id`); `result`→`sampleResult` (+`OBJECT` return) |
|
|
13
|
+
| `addPollingTrigger` / `addRealtimeTrigger` | `SharedExtensionMethod` `registerAs: POLLING_TRIGGER` / `REALTIME_TRIGGER` |
|
|
14
|
+
| `params` | `bodyParams` + `metaInfo.args` (widget derived from zod type — see below), **plus `paramsSchema`** |
|
|
15
|
+
| `result` (value/schema/loader) | `metaInfo.sampleResult` / `sampleResultLoader` |
|
|
16
|
+
| `scope` (realtime) | `integrationTriggersScope` |
|
|
17
|
+
| `handleTrigger*` | SYSTEM methods (runtime-generated) |
|
|
18
|
+
|
|
19
|
+
Platform-side identity fields are added downstream — you never author them.
|
|
20
|
+
|
|
21
|
+
The names change on the way out, which matters when you inspect a built model:
|
|
22
|
+
|
|
23
|
+
| Authored | Published as |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `id` | `serviceInfo.serviceClassName` |
|
|
26
|
+
| `name` | `serviceInfo.integrationName` |
|
|
27
|
+
| `logo` | `serviceInfo.integrationIcon` |
|
|
28
|
+
| `scope` (realtime) | `serviceInfo.integrationTriggersScope` |
|
|
29
|
+
| `appearanceColors` | per-method `colorStart` / `colorEnd` (every method inherits them) |
|
|
30
|
+
| `label` | per-method `operationName` |
|
|
31
|
+
|
|
32
|
+
`serviceInfo` also carries `requireOAuth`, and the definition root carries `runnerVersion` (`'v2'`). A
|
|
33
|
+
service's `description` and `appearanceColors` are not published on `serviceInfo` itself.
|
|
34
|
+
|
|
35
|
+
## The schema travels too
|
|
36
|
+
|
|
37
|
+
Alongside the projections above, the model carries the schema you actually declared:
|
|
38
|
+
|
|
39
|
+
| Field | Where | Holds |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `configSchema` | definition root | your `configItems` object |
|
|
42
|
+
| `paramsSchema` | each `ACTION` / `POLLING_TRIGGER` / `REALTIME_TRIGGER` | that method's `params` |
|
|
43
|
+
|
|
44
|
+
The console rebuilds real zod from it and validates against that, which is why a config dialog can report
|
|
45
|
+
`«Retries» must be at least 1` rather than only "this field is required".
|
|
46
|
+
|
|
47
|
+
Two things follow for you as an author:
|
|
48
|
+
|
|
49
|
+
- **Nothing is lost by declaring more.** `.min()`, `.regex()`, a format like `z.email()`, your own message —
|
|
50
|
+
all of it reaches the form. Only function-backed rules (`.refine()`, `.transform()`, `.trim()`) cannot
|
|
51
|
+
travel; see [02-zod-types.md](02-zod-types.md).
|
|
52
|
+
- **A missing `.label()` or `.describe()` is filled in when the field is DRAWN, not when your service is
|
|
53
|
+
built.** `z.email()` with neither shows "Contact Email" (from the field key) and "Expects an email address,
|
|
54
|
+
e.g. foo@bar.com". Because that happens at draw time, the wording can improve without you redeploying —
|
|
55
|
+
and anything you write yourself always wins.
|
|
56
|
+
|
|
57
|
+
`bodyParams`, `metaInfo.args` and the config descriptions are unchanged and still authoritative for
|
|
58
|
+
everything that reads them; the schema is additional, not a replacement.
|
|
59
|
+
|
|
60
|
+
## Param split: `bodyParams` vs `metaInfo.args`
|
|
61
|
+
|
|
62
|
+
All params are body params (`queryParams` is always `[]`). A param's information is split:
|
|
63
|
+
|
|
64
|
+
| `bodyParams` (structural) | `metaInfo.args` (display) |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `name`, `required`, `description`, `type`, `items`, `properties`, `defaultValue` | `label`, `dictionary`, `dependsOn`, `uiComponent` |
|
|
67
|
+
|
|
68
|
+
**Nested object properties are the exception** — they inline their display metadata (`label`, `uiComponent`,
|
|
69
|
+
`dictionary`, `dependsOn`) directly on the property.
|
|
70
|
+
|
|
71
|
+
**A platform param group is the other exception.** `z.filesUploadOptions([…])` and its siblings
|
|
72
|
+
(see [03-parameters.md](03-parameters.md)) publish their `uiComponent` token on the param *as well as* in
|
|
73
|
+
`metaInfo.args`, at every depth. That token says what the param **is**, not how one control should look, so a
|
|
74
|
+
consumer walking `bodyParams` alone can still tell the platform's own options object from an anonymous
|
|
75
|
+
`z.object` a service declared.
|
|
76
|
+
|
|
77
|
+
### Type → widget derivation
|
|
78
|
+
|
|
79
|
+
There is no `.uiComponent()`; the widget follows the zod type (after unwrapping
|
|
80
|
+
`.optional()` / `.nullable()` / `.default()`):
|
|
81
|
+
|
|
82
|
+
| zod | `type` | `uiComponent` |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| `z.string()` | `STRING` | — |
|
|
85
|
+
| `z.text()` | `STRING` | `MULTI_LINE_TEXT` |
|
|
86
|
+
| `z.number()` | `NUMBER` | `NUMERIC_STEPPER` |
|
|
87
|
+
| `z.boolean()` | `BOOLEAN` | `TOGGLE` |
|
|
88
|
+
| `z.date()` | `STRING` | `DATE_PICKER` |
|
|
89
|
+
| `z.enum([...])` | `STRING` | `DROPDOWN` — `{ value, label }` pairs when `.labels()` is declared, else the enum values |
|
|
90
|
+
| `z.object({...})` | `OBJECT` | — (recurses into `properties`) |
|
|
91
|
+
| `z.array(inner)` | `LIST` | — (`items.type` from the element) |
|
|
92
|
+
| `z.filesUploadOptions([…])` | `OBJECT` | `FILE_UPLOAD_OPTIONS` — and `FILE_LIST_OPTIONS` / `FILE_GET_OPTIONS` / `FILE_DELETE_OPTIONS` for the siblings |
|
|
93
|
+
|
|
94
|
+
### `result` → `sampleResult`
|
|
95
|
+
|
|
96
|
+
| `result` form | `sampleResult` | `returnType` | `sampleResultLoader` |
|
|
97
|
+
|---|---|---|---|
|
|
98
|
+
| literal value | the value | array → `LIST`, object → `OBJECT`, string → `STRING`, else `VOID` | `null` |
|
|
99
|
+
| zod schema | the last `.example()` on it, else `null` | `OBJECT` | `null` |
|
|
100
|
+
| loader fn | `null` | `OBJECT` | `{ methodName: '<id>_SampleResultLoader', dependsOn: [all params] }` |
|
|
101
|
+
|
|
102
|
+
### `configItems` → config descriptions
|
|
103
|
+
|
|
104
|
+
| zod | config item `type` |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `z.boolean()` | `bool` |
|
|
107
|
+
| `z.date()` | `date` |
|
|
108
|
+
| `z.enum([...])` | `choice` (+ `options`) |
|
|
109
|
+
| `z.text()` | `text` |
|
|
110
|
+
| anything else | `string` |
|
|
111
|
+
|
|
112
|
+
`.shared()` → `shared: true`, routing the field to the global config **dialog** instead of the per-app one.
|
|
113
|
+
It does not change how a handler reads the value, and a custom install has no global tier to route to.
|
|
114
|
+
|
|
115
|
+
## Helper-route & SYSTEM methods carry a wrapper-param `metaInfo.args`
|
|
116
|
+
|
|
117
|
+
Dictionaries, sample-result / dynamic-params loaders, and the trigger/polling/OAuth SYSTEM methods take a
|
|
118
|
+
**single wrapper param** (never per-field params). The model describes that wrapper so `metaInfo.args` is
|
|
119
|
+
never empty — consumers (UI, AI tools) need the label:
|
|
120
|
+
|
|
121
|
+
| Method kind | `bodyParams` | `metaInfo.args` |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| Trigger / polling / OAuth SYSTEM | `[{ invocation }]` / `[{ callbackObject }]` / `[{ refreshToken }]` | labelled from that param (e.g. `{ invocation: { label: 'invocation' } }`) |
|
|
124
|
+
| Loaders (`*_SampleResultLoader` / `*_DynamicParams`) | `[{ payload: OBJECT }]` | `{ payload: { label: 'payload' } }` |
|
|
125
|
+
| Dictionary | synthesized `payload` OBJECT with nested `search` + `cursor` (+ `criteria` when declared) | `{ payload: { label: 'Payload' } }` |
|
|
126
|
+
|
|
127
|
+
You never author these params — the runtime emits them. Dictionaries keep the extension's **service colors**
|
|
128
|
+
and default to `OBJECT` `returnType`.
|
|
129
|
+
|
|
130
|
+
## Runtime surfaces worth knowing
|
|
131
|
+
|
|
132
|
+
- **Crypto** lives on the namespace as `Flowrunner.crypto` — `hmac(algo, key, data, encoding)`,
|
|
133
|
+
`timingSafeEqual(a, b)`, `ageSeconds(timestamp)`. Not on ctx `helpers`. See
|
|
134
|
+
[09-realtime-triggers.md](09-realtime-triggers.md).
|
|
135
|
+
- **The custom type** is `z.text()` → `uiComponent: MULTI_LINE_TEXT`, `STRING`-typed — see the type table
|
|
136
|
+
above.
|
|
137
|
+
|
|
138
|
+
## Open items
|
|
139
|
+
|
|
140
|
+
- The client-side render contract for **top-level** `dynamicParams` fields. The runtime emits and serves the
|
|
141
|
+
`PARAM_SCHEMA_DEFINITION` method today, so the authoring side works; `metaInfo.dynamicParams` is marked
|
|
142
|
+
provisional in the model.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# 12 — Service README Generation
|
|
2
|
+
|
|
3
|
+
Rules for creating and maintaining the `README.md` of an individual FlowRunner service, generated from the
|
|
4
|
+
service's `src/index.js` (the single source of truth).
|
|
5
|
+
|
|
6
|
+
## Structure — exact sections, in order
|
|
7
|
+
|
|
8
|
+
1. **Title**: `{Service Name} FlowRunner Extension` — the `name` passed to `Flowrunner.createExtension`.
|
|
9
|
+
2. **Description** — brief overview of the service's purpose and main capabilities. Do NOT use the phrase "Service Description"; focus on what the service does.
|
|
10
|
+
3. **Ideal Use Cases** — bullet points of scenarios where the service is helpful (use this exact heading).
|
|
11
|
+
4. **List of Actions** — logically sorted list of action names only (no descriptions); alphabetical or logical grouping.
|
|
12
|
+
5. **List of Triggers** — logically sorted list of trigger names only (no descriptions).
|
|
13
|
+
6. **Agent Ideas** — cross-service synergies (see below), always the last section.
|
|
14
|
+
|
|
15
|
+
## Content Rules
|
|
16
|
+
|
|
17
|
+
- **Maximum 2000 characters total.** Brevity is the point — no per-action/trigger descriptions.
|
|
18
|
+
- Standard Markdown; bullet points for lists; clear, concise language; consistent structure across all services.
|
|
19
|
+
- Extraction from `src/index.js`:
|
|
20
|
+
|
|
21
|
+
| README needs | Read from |
|
|
22
|
+
|---|---|
|
|
23
|
+
| Service name | the `name` prop of `Flowrunner.createExtension({ ... })` |
|
|
24
|
+
| Actions | every `ext.addAction({ ... })` — list its **`label`** |
|
|
25
|
+
| Triggers | every `ext.addPollingTrigger({ ... })` and `ext.addRealtimeTrigger({ ... })` — list its **`label`** |
|
|
26
|
+
|
|
27
|
+
- **List `label`, never `id`.** `id` is the persisted execution key and is frozen once a service ships, so it
|
|
28
|
+
may read nothing like the current behaviour. `label` is the human text the console shows, so it is what
|
|
29
|
+
belongs in a README.
|
|
30
|
+
- **Exclude** everything that is not a user-facing action or trigger: `ext.dictionary(...)` registrations,
|
|
31
|
+
`dynamicParams`, `result` loader functions, `initContext`, `apiRequest`, `helpers`, and
|
|
32
|
+
`ext.setupOauth2` / `ext.setupRealtimeTriggers` setup calls. These are internal support declarations, and
|
|
33
|
+
the SYSTEM methods generated from them are never documented.
|
|
34
|
+
- If a `GENERATED_README.md` exists in the service directory it may be used as a source, but never modify it —
|
|
35
|
+
it is auto-generated and excluded from version control.
|
|
36
|
+
|
|
37
|
+
## Agent Ideas Section
|
|
38
|
+
|
|
39
|
+
Every README ends with an `## Agent Ideas` section highlighting multi-service workflows an AI Agent could orchestrate:
|
|
40
|
+
|
|
41
|
+
1. Scan the other service directories under `services/` and read their READMEs to understand capabilities.
|
|
42
|
+
2. Select 2–3 services that pair well with the current one.
|
|
43
|
+
3. Write 2–3 bullets; each must name the specific operations by their exact `label` (from this service AND the
|
|
44
|
+
companions), describe a realistic end-to-end workflow, and be a single concise sentence.
|
|
45
|
+
|
|
46
|
+
Example:
|
|
47
|
+
|
|
48
|
+
```markdown
|
|
49
|
+
## Agent Ideas
|
|
50
|
+
|
|
51
|
+
- When a **ShipBob** "On Order Shipped" trigger fires, use **Gmail** "Send Email" to notify the customer with tracking details and estimated delivery date
|
|
52
|
+
- Use **Airtable** "Get Records" to fetch new product listings, then call **ShipBob** "Create Product" to sync each product into ShipBob's fulfillment catalog
|
|
53
|
+
- When a **ShipBob** "On Return Completed" trigger fires, use **Google Sheets** "Append Row" to log the return details into a returns tracking spreadsheet
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
(If the project contains only one service, base the Agent Ideas on well-known FlowRunner integrations instead.)
|
|
57
|
+
|
|
58
|
+
The README of the service you are writing follows this document; what you quote from a companion service
|
|
59
|
+
follows whatever that companion declares.
|
|
60
|
+
|
|
61
|
+
## Process & Verification
|
|
62
|
+
|
|
63
|
+
- Process one service at a time; the README must reflect `src/index.js` exactly.
|
|
64
|
+
- When updating, preserve manually-added sections (extra notes, troubleshooting) that don't conflict with the required structure.
|
|
65
|
+
- After generating/updating, cross-reference against `src/index.js`: every registered action and trigger is
|
|
66
|
+
listed, nothing removed is still documented, names match the `label` values, and the character limit is
|
|
67
|
+
respected.
|
|
68
|
+
- **Refactoring a service should not change its README** unless a `label` changed. A diff there when you only
|
|
69
|
+
meant to change internals is a signal that something user-facing moved — check before accepting it.
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
# 13 — Runtime Contracts
|
|
2
|
+
|
|
3
|
+
The other documents describe what to declare. This one collects the handful of **runtime** facts that change
|
|
4
|
+
what you write and that are otherwise visible only by reading the CLI bundle.
|
|
5
|
+
|
|
6
|
+
> **Do not read the CLI bundle** (`flowrunner-cli/runtime/index.js`, its `.d.ts` tree, or the templates) to
|
|
7
|
+
> answer a question about authoring, and do not reason from what the runtime "probably" does. This document
|
|
8
|
+
> is meant to be complete: if a fact you needed is missing, that is a defect here. Report it and proceed on
|
|
9
|
+
> what *is* documented, saying which part you could not confirm — do not go and read the source, and do not
|
|
10
|
+
> fill the gap with an assumption.
|
|
11
|
+
|
|
12
|
+
## The `Flowrunner` global vs the `flowrunner-cli/runtime` module
|
|
13
|
+
|
|
14
|
+
Two different surfaces, easily confused:
|
|
15
|
+
|
|
16
|
+
| Surface | How you get it | Contains |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| **`Flowrunner` global** | always present when the platform runs your service; a harness gets it as a side effect of importing `flowrunner-cli/runtime` | `Request`, `z`, `crypto`, `createExtension`, `getExtension`, `ServerCode` |
|
|
19
|
+
| **`require('flowrunner-cli/runtime')`** | explicit import — **harness-side only** | `buildServiceDefinition`, `getServiceConfigs`, `runServiceMethod`, `detectVersion`, `resetRegistry`, `parseJsDocToServiceJson` |
|
|
20
|
+
|
|
21
|
+
A service module uses only the global, and `require`s nothing. Note that importing the module is what
|
|
22
|
+
installs the global — there is no separate namespace export to pull in.
|
|
23
|
+
|
|
24
|
+
## Verifying that a service builds
|
|
25
|
+
|
|
26
|
+
`src/index.js` is only ever loaded by the runtime, so a typo in a schema surfaces as a build failure rather
|
|
27
|
+
than a syntax error. Check it directly:
|
|
28
|
+
|
|
29
|
+
| Export | Signature | Returns |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `buildServiceDefinition` | `(serviceId, serviceEntryPointPath)` | `SharedExtensionDefinition` — `serviceInfo` + `methodsMap` (see [11-output-model.md](11-output-model.md)) |
|
|
32
|
+
| `getServiceConfigs` | `(serviceId, serviceEntryPointPath)` | `ConfigItem[]` — the published config descriptions |
|
|
33
|
+
| `runServiceMethod` | `(data: RunServiceMethodData)` | `Promise<unknown>` — invokes one method, SYSTEM methods included |
|
|
34
|
+
| `detectVersion` | `(serviceId, serviceEntryPointPath)` | `'v1' \| 'v2'` |
|
|
35
|
+
| `resetRegistry` | `()` | clears the extension registry — **not sufficient on its own**, see below |
|
|
36
|
+
|
|
37
|
+
```js
|
|
38
|
+
// throwaway check — run it, read it, delete it
|
|
39
|
+
const path = require('path')
|
|
40
|
+
const { buildServiceDefinition } = require('flowrunner-cli/runtime')
|
|
41
|
+
|
|
42
|
+
const model = buildServiceDefinition('telegram', path.resolve('services/telegram/src/index.js'))
|
|
43
|
+
console.log(Object.keys(model.methodsMap))
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Put the script in the project root.** `require('flowrunner-cli/runtime')` resolves relative to the
|
|
47
|
+
script's own location, so the same file fails with `MODULE_NOT_FOUND` from `/tmp` and works from the root.
|
|
48
|
+
If the project's `package.json` sets `"type": "module"`, name it `.cjs`.
|
|
49
|
+
|
|
50
|
+
`RunServiceMethodData` — for exercising a single method:
|
|
51
|
+
|
|
52
|
+
| Field | Req | Notes |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| `serviceId`, `serviceEntryPointPath` | ✓ | as above |
|
|
55
|
+
| `methodName` | ✓ | action/trigger `id`, or a SYSTEM method from [08](08-polling-triggers.md)/[09](09-realtime-triggers.md) |
|
|
56
|
+
| `methodData` | – | `Record<string, unknown>`|
|
|
57
|
+
| `configs` | – | your `configItems` values — ONE bag. `.shared()` names the dialog that fills a value in, not how it is passed; a host running a shared extension merges its global and per-app tiers before calling in |
|
|
58
|
+
| `executionContext` | ✓ | `{ runtimeKey, accessToken, appId, apiKey, serverURL, flowId, executionId }` |
|
|
59
|
+
| `retrieveNewS3Token` | ✓ | `(runtimeKey) => Promise<{ filesS3Token }>` |
|
|
60
|
+
| `createFiles` | – | supplies `ctx.files` — see [10-files-api.md](10-files-api.md) |
|
|
61
|
+
| `logger` | – | defaults to the runtime logger |
|
|
62
|
+
|
|
63
|
+
**This is a check, not a test suite.** A scratch script that you run and then delete is the expected end
|
|
64
|
+
state. The project's suites are a separate thing with their own harness — `sandbox/` and
|
|
65
|
+
`services/{id}/tests/`, written by `flowrunner init` — and they wrap these same exports with an HTTP mock
|
|
66
|
+
and a Files backend. See [15-unit-tests.md](15-unit-tests.md); do not build a private harness alongside it.
|
|
67
|
+
|
|
68
|
+
### Reloading the same service in one process
|
|
69
|
+
|
|
70
|
+
`buildServiceDefinition` can be called repeatedly without any reset — the second call returns the same built
|
|
71
|
+
model. You only need `resetRegistry()` when the module has *changed* on disk and you want it re-read, and
|
|
72
|
+
then it is **half the job**: the module body is what calls `createExtension`, and Node runs a module body
|
|
73
|
+
only on first `require`. Clearing the registry without clearing the require cache leaves the runtime with no
|
|
74
|
+
registered service and the next call fails on
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
Cannot read properties of null (reading 'methodsMap')
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
which reads like a broken service rather than a stale cache. Do both, or simplest of all, use one fresh
|
|
81
|
+
process per check:
|
|
82
|
+
|
|
83
|
+
```js
|
|
84
|
+
resetRegistry()
|
|
85
|
+
delete require.cache[ENTRY] // ENTRY must be the same resolved absolute path
|
|
86
|
+
buildServiceDefinition('telegram', ENTRY)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Exercising SYSTEM methods
|
|
90
|
+
|
|
91
|
+
`runServiceMethod` drives the `handleTrigger*` methods, but their payload does not sit directly in
|
|
92
|
+
`methodData` — it goes one level down, under `invocation`. Omitting the wrapper fails with
|
|
93
|
+
`missing required "invocation" in method input`.
|
|
94
|
+
|
|
95
|
+
| `methodName` | `methodData` | Returns |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| `handleTriggerUpsertWebhook` | `{ invocation: { callbackUrl, triggers, webhookData?, connectionId? } }` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
|
|
98
|
+
| `handleTriggerDeleteWebhook` | `{ invocation: { callbackUrl, webhookData, connectionId? } }` | `{ webhookData? }` |
|
|
99
|
+
| `handleTriggerSelectMatched` | `{ invocation: { eventName, eventData, triggers } }` | `{ ids, enrichedEventData }` |
|
|
100
|
+
| `handleTriggerResolveEvents` | `{ invocation: { body, rawBody?, headers?, query?, connectionId? } }` | `{ events: [{ name, data }], responseToWebhook? }` (plus the deprecated `responseToExternalService`, still forwarded) |
|
|
101
|
+
|
|
102
|
+
`handleTriggerResolveEvents` is the inbound-delivery seam. **`body` is required** — omitting it fails with
|
|
103
|
+
`body: Invalid input: expected nonoptional, received undefined`. `rawBody` and `headers` are the only fields
|
|
104
|
+
forwarded to `verifyRequest`; `query` is accepted but not forwarded, and `connectionId` is echoed back on the
|
|
105
|
+
response. Unknown fields in `invocation` are ignored rather than rejected.
|
|
106
|
+
|
|
107
|
+
It answers `{ events: [] }` for a delivery no trigger claims, and `{ handshake: true, events: [] }` for an
|
|
108
|
+
empty body — the runtime acks those automatically, with no `handshake` declared
|
|
109
|
+
([09-realtime-triggers.md](09-realtime-triggers.md)). A `verify` / `verifyRequest` that turns a delivery down
|
|
110
|
+
**resolves** with `{ events: [], responseToWebhook: { httpStatus: 401, rawBody: '' } }` — it does not reject,
|
|
111
|
+
so assert on the returned value, not on a thrown error.
|
|
112
|
+
|
|
113
|
+
### What the harness cannot reach — do not probe for it
|
|
114
|
+
|
|
115
|
+
**`subscribe` always receives `triggers: []` when driven through `runServiceMethod`.** The live trigger set
|
|
116
|
+
is resolved from persisted flow instances, which a scratch script has none of; whatever array you put in the
|
|
117
|
+
invocation is discarded, silently and without a validation error. The same is true of the `triggers` entries
|
|
118
|
+
handed to `handleTriggerSelectMatched` — varying their shape changes nothing observable.
|
|
119
|
+
|
|
120
|
+
This is a limit of the local harness, not a bug in your service, and it is **not** something to reverse-engineer
|
|
121
|
+
by calling the method with deliberately malformed input to read the validation errors back. That technique
|
|
122
|
+
tells you about the runtime's input validator, not about what your `subscribe` will receive in production,
|
|
123
|
+
and conclusions drawn that way have been wrong.
|
|
124
|
+
|
|
125
|
+
Verify the parts you own by calling them directly instead — your `subscribe` body is an ordinary function:
|
|
126
|
+
|
|
127
|
+
```js
|
|
128
|
+
require('flowrunner-cli/runtime') // installs the Flowrunner global
|
|
129
|
+
require(ENTRY) // registers the service
|
|
130
|
+
const ext = Flowrunner.getExtension('telegram') // note: on the global, not the module export
|
|
131
|
+
// → { props, actions, dictionaries, pollingTriggers, realtimeTriggers, loaders, realtime }
|
|
132
|
+
//
|
|
133
|
+
// actions / dictionaries / pollingTriggers / realtimeTriggers / loaders are each a **Map keyed by id**,
|
|
134
|
+
// not an array: `.get('sendPhoto')` and `.values()` work, `.find()` is undefined. `realtime` is the
|
|
135
|
+
// object passed to setupRealtimeTriggers.
|
|
136
|
+
|
|
137
|
+
await ext.realtime.subscribe({ // exactly the props you passed to setupRealtimeTriggers
|
|
138
|
+
callbackUrl: 'https://cb/x',
|
|
139
|
+
triggers: [{ id: 'i1', params: { chatId: '42' } }], // your set arrives intact on this path
|
|
140
|
+
webhookData: null, config, apiRequest, logger,
|
|
141
|
+
})
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Called this way the ctx bag is yours to supply, so stub `apiRequest` and assert on what `subscribe` would
|
|
145
|
+
have sent.
|
|
146
|
+
|
|
147
|
+
If a SYSTEM-method contract you needed is not in the table above, it belongs there — report the gap rather
|
|
148
|
+
than inferring it from error messages.
|
|
149
|
+
|
|
150
|
+
Driving these methods from a *suite* rather than a scratch script is the same call with the same limits —
|
|
151
|
+
[15-unit-tests.md](15-unit-tests.md) covers the invocation shapes and what to assert.
|
|
152
|
+
|
|
153
|
+
## Where `.default()` is applied
|
|
154
|
+
|
|
155
|
+
`.default(v)` is applied by the **invocation path**, not by the schema itself. Three paths differ:
|
|
156
|
+
|
|
157
|
+
| Path | `.default()` filled |
|
|
158
|
+
|---|---|
|
|
159
|
+
| Action `execute` params | ✓ |
|
|
160
|
+
| Dictionary `criteria` | ✓ |
|
|
161
|
+
| Realtime trigger `match` params — object **and** function form | ✗ |
|
|
162
|
+
|
|
163
|
+
An action's params are parsed, so `execute` sees defaults filled in. A trigger's `match` receives the
|
|
164
|
+
**persisted instance config verbatim**: no defaults.
|
|
165
|
+
|
|
166
|
+
`.labels()` needs no path at all — it is display metadata, so the value the element stored is already the
|
|
167
|
+
value the handler receives.
|
|
168
|
+
|
|
169
|
+
The consequence for `match`: normalize by hand, and treat an absent value as "no filter" rather than
|
|
170
|
+
assuming a default arrived.
|
|
171
|
+
|
|
172
|
+
```js
|
|
173
|
+
match: ({ params, providerEventData }) => {
|
|
174
|
+
const want = params.status ?? 'open' // .default('open') does NOT arrive here
|
|
175
|
+
if (!params.chatId) return true // absent → no filter
|
|
176
|
+
return providerEventData.status === want
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
The declarative object form of `match` compares with string coercion and skips params that are `null` or
|
|
181
|
+
`''` — see [09-realtime-triggers.md](09-realtime-triggers.md).
|
|
182
|
+
|
|
183
|
+
## `Flowrunner.Request`
|
|
184
|
+
|
|
185
|
+
The runtime HTTP client, and the transport under `apiRequest`. Its full surface — the sending model,
|
|
186
|
+
methods, query, headers, bodies and multipart, response handling and the `ResponseError` shape — is
|
|
187
|
+
**[04-http-requests.md](04-http-requests.md)**; client certificates are
|
|
188
|
+
[17-client-certificates.md](17-client-certificates.md).
|
|
189
|
+
|
|
190
|
+
The one fact worth repeating here, because it is the source of a silent bug: **the request instance is
|
|
191
|
+
thenable, so `await` on a chain is what issues the request.** `.send()` and `.toBuffer()` are the exceptions
|
|
192
|
+
— both are terminal, firing immediately and returning a `Promise` rather than the request. `.form()` only
|
|
193
|
+
stages a body, so `request.form(data).send()` issues one request with no body at all.
|