Flow SDK

Packs

Bundle artifacts, modules, workflow templates, and connector configs into distributable packs — install from the marketplace or publish your own.

A pack is a versioned bundle of related SDK artifacts, modules, workflow templates, and connector configuration that solves a complete use case. You can install packs from the FlowOS Marketplace (Plugin Management) or create custom internal packs for your organization.

What a Pack Can Include

•Artifacts — custom nodes, scripts, webhook handlers, scheduled jobs, transforms
•Modules — shared TypeScript libraries
•Workflow Templates — pre-built workflows that users can deploy with one click
•Connector Definitions — credential schema for connectors the pack communicates with
•Notification Templates — email/Slack/Teams message templates
•Catalog Item Templates — service catalog items pre-filled for common requests
•SLA Policy Templates — default SLA configurations

pack.json

Every pack has a pack.json manifest at its root:

pack.json

{
  "id": "com.acme.github-itsm",
  "name": "GitHub → ITSM Integration",
  "version": "2.1.0",
  "minFlowOsVersion": "4.0.0",
  "description": "Automatically create incidents from GitHub Actions failures and link PRs to change requests.",
  "author": { "name": "Acme IT", "email": "platform@acme.com" },
  "license": "MIT",
  "tags": ["github", "itsm", "incident", "change"],
  "icon": "Github",

  "artifacts": [
    { "key": "github-push-handler",      "file": "artifacts/push-handler.ts" },
    { "key": "github-action-failed",     "file": "artifacts/action-failed.ts" },
    { "key": "link-pr-to-change",        "file": "artifacts/link-pr-change.ts" }
  ],
  "modules": [
    { "key": "github-helpers",           "file": "modules/helpers.ts" }
  ],
  "workflows": [
    { "name": "GitHub Actions Failure → Incident", "file": "workflows/action-failure-incident.yaml" }
  ],
  "connectors": [
    { "key": "github", "authType": "oauth2", "configSchema": "connectors/github.json" }
  ],
  "notificationTemplates": [
    { "slug": "github-incident-created", "file": "templates/incident-created.hbs" }
  ],

  "requiredSecrets": ["GITHUB_WEBHOOK_SECRET"],
  "requiredConnectors": ["github"],

  "configSchema": {
    "type": "object",
    "properties": {
      "targetTeam":    { "type": "string", "description": "Team slug to assign GitHub-sourced incidents to." },
      "defaultSeverity": { "type": "string", "enum": ["P1","P2","P3","P4"], "default": "P2" }
    },
    "required": ["targetTeam"]
  }
}

Installing a Pack

From the Marketplace (UI)

Navigate to Plugins → Marketplace, find the pack, click Install. You'll be prompted to fill in configSchema values and provide required secrets and connector credentials before installation completes.

From a File or Registry (CLI)

bash

# Install from npm-style registry
flowos pack install com.acme.github-itsm@2.1.0

# Install from a local .flowpack file
flowos pack install ./github-itsm-2.1.0.flowpack

# Install with config values
flowos pack install com.acme.github-itsm --config targetTeam=platform-eng

Creating a Pack

Scaffolding a new pack with the CLI:

bash

flowos pack new my-pack --template blank
# or use a starter:
flowos pack new my-pack --template itsm-integration

This creates the following structure:

bash

my-pack/
  pack.json
  artifacts/
    example-node.ts
  modules/
    helpers.ts
  workflows/
    example-workflow.yaml
  tests/
    example-node.test.ts
  README.md

Building & Publishing

bash

# Validate pack.json and TypeScript
flowos pack validate

# Build a distributable .flowpack bundle
flowos pack build

# Publish to your workspace registry (internal packs only)
flowos pack publish --registry workspace

# Publish to FlowOS Marketplace (requires developer account)
flowos pack publish --registry marketplace

Pack Versioning

Packs use semantic versioning (MAJOR.MINOR.PATCH). FlowOS enforces the following:

•PATCH — Bug fixes. Auto-applied when workspace has auto-update enabled.
•MINOR — New artifacts or templates added. Backward compatible. Prompted in UI.
•MAJOR — Breaking changes (removed artifacts, changed schemas). Requires manual review and re-configuration.

Post-Install Configuration

After install, pack configuration can be updated at SDK → Packs → [pack name] → Configuration without reinstalling. Changes take effect on the next execution.

All pack artifacts are namespaced by the pack ID to avoid key collisions. A custom node from pack com.acme.github-itsm with slug link-pr-to-change is addressable as com.acme.github-itsm/link-pr-to-change in the workflow node palette.