{"_id":"@businessagil/workflow-schema","_rev":"3-5dfaee80d435836411946124c6b715f0","name":"@businessagil/workflow-schema","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@businessagil/workflow-schema","version":"1.0.0","keywords":["businessagil","n8n","workflow","manifest","schema"],"license":"UNLICENSED","_id":"@businessagil/workflow-schema@1.0.0","maintainers":[{"name":"davidpuziol","email":"davidpuziol@gmail.com"}],"homepage":"https://gitlab.com/businessagil/packages/workflow-schema#readme","bugs":{"url":"https://gitlab.com/businessagil/packages/workflow-schema/issues"},"dist":{"shasum":"45ef2c15e8f8eecb7fbc8299197ab97bda964dbd","tarball":"https://registry.npmjs.org/@businessagil/workflow-schema/-/workflow-schema-1.0.0.tgz","fileCount":6,"integrity":"sha512-7Rovh/JXD+mQkhCrpQiF96Wcdp2TxLYoOsHHD19D1bgk3tsZFu0rXLVb5raHZ+t/pw2lvPdgbz1dDgyDMm1LeQ==","signatures":[{"sig":"MEUCIAdcSZr6xaD/F0w/rsHy8gGasIJ3bdWwS3yqup1fnyAIAiEA457jahfR7iZ0nvdpgckzjROx97yhnYNCWaM948Av4k8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19894},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./manifest.v1":{"types":"./dist/manifest.v1.d.ts"},"./manifest.v1.json":"./dist/manifest.v1.json"},"gitHead":"20133dc66e19c7096457caceed0e539163af7ef4","private":false,"scripts":{"build":"node scripts/build.mjs","generate:kinds":"node scripts/generate-kinds-enum.mjs","prepublishOnly":"npm run generate:kinds && npm run build && npm run validate:examples","validate:examples":"node scripts/validate-examples.mjs"},"_npmUser":{"name":"davidpuziol","email":"davidpuziol@gmail.com"},"repository":{"url":"git+https://gitlab.com/businessagil/packages/workflow-schema.git","type":"git"},"_npmVersion":"10.9.7","description":"Schema and TypeScript types for BusinessAgil n8n workflow manifests.","directories":{},"_nodeVersion":"22.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.17.0","js-yaml":"^4.1.0","ajv-formats":"^3.0.1","json-schema-to-typescript":"^15.0.0"},"_npmOperationalInternal":{"tmp":"tmp/workflow-schema_1.0.0_1777896620508_0.7134555771619229","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@businessagil/workflow-schema","version":"1.0.1","keywords":["businessagil","n8n","workflow","manifest","schema"],"license":"UNLICENSED","_id":"@businessagil/workflow-schema@1.0.1","maintainers":[{"name":"davidpuziol","email":"davidpuziol@gmail.com"}],"homepage":"https://gitlab.com/businessagil/packages/workflow-schema#readme","bugs":{"url":"https://gitlab.com/businessagil/packages/workflow-schema/issues"},"dist":{"shasum":"cb9bcb4eed4c60fad064afe43acbfb584b0d8764","tarball":"https://registry.npmjs.org/@businessagil/workflow-schema/-/workflow-schema-1.0.1.tgz","fileCount":6,"integrity":"sha512-9TYOu9ZeVrw72As4VvGsdcEVClopnoTqTA3AIkxhAeO4Iptse8zokGyl1SfIjTTBnMLhLbEmRniR1CCjv0hQcA==","signatures":[{"sig":"MEUCIQDiqYFZqVTlbwJ4UOwMC1nPxzRSounFajAcuWD9cJ43ewIgE+CJtQDm9Ufx+GptzVtcYb+2Sun9uiznzCiK+Oq7B8s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19904},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./manifest.v1":{"types":"./dist/manifest.v1.d.ts"},"./manifest.v1.json":"./dist/manifest.v1.json"},"gitHead":"e0e1104ed3ebb4a42999257f012cecc7d2a113f7","private":false,"scripts":{"build":"node scripts/build.mjs","generate:kinds":"node scripts/generate-kinds-enum.mjs","prepublishOnly":"npm run generate:kinds && npm run build && npm run validate:examples","validate:examples":"node scripts/validate-examples.mjs"},"_npmUser":{"name":"davidpuziol","email":"davidpuziol@gmail.com"},"repository":{"url":"git+https://gitlab.com/businessagil/packages/workflow-schema.git","type":"git"},"_npmVersion":"10.9.7","description":"Schema and TypeScript types for BusinessAgil n8n workflow manifests.","directories":{},"_nodeVersion":"22.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.17.0","js-yaml":"^4.1.0","ajv-formats":"^3.0.1","json-schema-to-typescript":"^15.0.0"},"_npmOperationalInternal":{"tmp":"tmp/workflow-schema_1.0.1_1777896969112_0.7256985735314423","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@businessagil/workflow-schema","version":"1.0.2","description":"Schema and TypeScript types for BusinessAgil n8n workflow manifests.","license":"UNLICENSED","private":false,"type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./manifest.v1.json":"./dist/manifest.v1.json","./manifest.v1":{"types":"./dist/manifest.v1.d.ts"}},"scripts":{"generate:kinds":"node scripts/generate-kinds-enum.mjs","build":"node scripts/build.mjs","validate:examples":"node scripts/validate-examples.mjs","prepublishOnly":"npm run generate:kinds && npm run build && npm run validate:examples"},"devDependencies":{"ajv":"^8.17.0","ajv-formats":"^3.0.1","js-yaml":"^4.1.0","json-schema-to-typescript":"^15.0.0"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://gitlab.com/businessagil/packages/workflow-schema.git"},"keywords":["businessagil","n8n","workflow","manifest","schema"],"_id":"@businessagil/workflow-schema@1.0.2","gitHead":"a97e05b77d054415141c2f211623dd5c81e66f8c","bugs":{"url":"https://gitlab.com/businessagil/packages/workflow-schema/issues"},"homepage":"https://gitlab.com/businessagil/packages/workflow-schema#readme","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-UFbQAMo257lUyF5kN6Y4Pk/I9EK+s9dzdEs3iTdVEMEh8su2LB1GTEevXh0NOidanqfO8iYR2cu5/KgttxIlsQ==","shasum":"52e6aff51d8d373609a2916b36f9984c6da6744c","tarball":"https://registry.npmjs.org/@businessagil/workflow-schema/-/workflow-schema-1.0.2.tgz","fileCount":6,"unpackedSize":19929,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDSNHTC7HPhYdEmv+9okLGeECGGOga6w0TAtcrO9Ney9AiEArxOUG1UAL8o4Gfr8q/OJAEgY7qAdvtP/dfGFlCkIEnw="}]},"_npmUser":{"name":"davidpuziol","email":"davidpuziol@gmail.com"},"directories":{},"maintainers":[{"name":"davidpuziol","email":"davidpuziol@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/workflow-schema_1.0.2_1778551910184_0.09880752712831131"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-04T12:10:20.423Z","modified":"2026-05-12T02:11:50.483Z","1.0.0":"2026-05-04T12:10:20.654Z","1.0.1":"2026-05-04T12:16:09.250Z","1.0.2":"2026-05-12T02:11:50.329Z"},"bugs":{"url":"https://gitlab.com/businessagil/packages/workflow-schema/issues"},"license":"UNLICENSED","homepage":"https://gitlab.com/businessagil/packages/workflow-schema#readme","keywords":["businessagil","n8n","workflow","manifest","schema"],"repository":{"type":"git","url":"git+https://gitlab.com/businessagil/packages/workflow-schema.git"},"description":"Schema and TypeScript types for BusinessAgil n8n workflow manifests.","maintainers":[{"name":"davidpuziol","email":"davidpuziol@gmail.com"}],"readme":"# @businessagil/workflow-schema\n\nSchema and TypeScript types for BusinessAgil n8n workflow manifests.\n\nA workflow manifest (`manifest.yaml` at the root of every workflow module\nunder `workflows/*`) is the contract between the workflow author and the\nBusinessAgil platform. It tells the platform:\n\n1. How to display the workflow in the client-facing catalog.\n2. What credentials the client must connect before activation.\n3. What configuration the client provides on the activation form.\n\nThis package distributes the formal schema for that file plus generated\nTypeScript types, so app code, runner code, and IDE tooling can all\nconsume the same source of truth.\n\n## Install (consumer)\n\n```sh\nnpm install @businessagil/workflow-schema\n```\n\n```ts\nimport type { Manifest } from '@businessagil/workflow-schema';\nimport schema from '@businessagil/workflow-schema/manifest.v1.json' assert { type: 'json' };\n```\n\n## $schema directive (workflow modules)\n\nEvery `manifest.yaml` in `workflows/*` should start with:\n\n```yaml\n# yaml-language-server: $schema=https://cdn.jsdelivr.net/npm/@businessagil/workflow-schema@1/dist/manifest.v1.json\n```\n\nThis enables autocomplete, validation, and field documentation in\nVSCode/Neovim/JetBrains via the YAML language server, with no extra\ninstall.\n\n## Repository layout\n\n```text\nworkflow-schema/\n├── src/\n│   ├── manifest.v1.yaml          # Hand-edited JSON Schema (YAML format)\n│   └── _kinds.generated.yaml     # Generated from integrations/*.yaml\n├── credentials/                  # Registry — one file per credential kind\n│   ├── _README.md                # How to add a credential\n│   └── *.yaml\n├── scripts/\n│   ├── generate-kinds-enum.mjs   # integrations/ → _kinds.generated.yaml\n│   └── build.mjs                 # YAML → JSON + TS types\n├── examples/\n│   └── *.manifest.yaml           # Reference manifests, validated in CI\n├── dist/                         # Build output (npm publish artifact)\n└── package.json\n```\n\n## Adding a new credential\n\nSee [`credentials/_README.md`](./credentials/_README.md). Short version:\n\n1. Create `credentials/<kind>.yaml` with the credential metadata.\n2. Run `npm run generate:kinds` — updates `src/_kinds.generated.yaml`.\n3. Commit both files in the same PR.\n4. CI validates the schema is consistent and that all examples still\n   pass against the new schema.\n\n## Releasing\n\nReleases are **manually decided, automatically published**. Humans\nchoose the version bump; CI publishes once the tag arrives. There is\nno automation that decides bumps from commit messages.\n\n### Versioning policy\n\nVersioning follows semver under each major version of the schema:\n\n- **Patch (`1.0.0` → `1.0.1`)** — additive: new optional field, new\n  enum value (e.g. registering a new credential kind).\n- **Minor (`1.0.0` → `1.1.0`)** — additive structural: new optional\n  block.\n- **Major (`1.x.x` → `2.0.0`)** — breaking: removed field, type\n  change, made-required field. Cuts a new schema file\n  (`src/manifest.v2.yaml`) so v1 manifests keep validating against the\n  pinned URL.\n\n### Procedure\n\nWhat you do locally:\n\n```sh\n# 1. Decide the bump (patch | minor | major) based on what changed.\n#    `npm version` updates package.json, creates a commit, and creates\n#    the matching git tag — atomically.\nnpm version patch          # 1.0.0 → 1.0.1\n# npm version minor        # 1.0.0 → 1.1.0\n# npm version major        # 1.0.0 → 2.0.0\n\n# 2. Push the commit AND the tag to GitLab.\ngit push --follow-tags\n```\n\nWhat CI does automatically:\n\n1. Sees the new tag arrive (matching `^v\\d+\\.\\d+\\.\\d+$`).\n2. Runs the `release` job defined in [`cicd/release.yaml`](./cicd/release.yaml).\n3. `npm run build` regenerates `dist/` from source.\n4. `npm run validate:examples` confirms every fixture still validates.\n5. Authenticates to npm via `NPM_TOKEN` (CI variable, never committed).\n6. `npm publish --access public` ships the version that's now in\n   `package.json`.\n\nThe `release` job runs **only** on tags matching the SemVer regex.\nPushing to branches (or tags in another format) does not trigger a\npublish.\n\n### Monitoring\n\nAfter `git push --follow-tags`, monitor the pipeline at\n**GitLab → Pipelines**. Look for the pipeline tagged with `v1.0.0`\n(or whatever you cut). The `release` job should reach\n`Status: passed` in ~1–2 minutes. Confirm the new version appears at\n[npmjs.com/package/@businessagil/workflow-schema](https://www.npmjs.com/package/@businessagil/workflow-schema).\n\n### What if the CI publish fails\n\n| Symptom | Likely cause |\n| --- | --- |\n| `release` job not triggered | Tag doesn't match `^v\\d+\\.\\d+\\.\\d+$`. Confirm exact tag name |\n| 401/403 on `npm publish` | `NPM_TOKEN` invalid, expired, or lacks Read+Write on `@businessagil/*` |\n| 402 / 404 from npm | Org `@businessagil` doesn't exist on npmjs.com, or the access tier doesn't allow public publish |\n| `NPM_TOKEN` is empty in logs | Variable is set but not Protected, OR the tag isn't on a Protected pattern |\n\nThe version on `package.json` is already bumped from `npm version`\nlocally, even if CI fails — re-running the pipeline (after fixing the\nunderlying cause) re-attempts publish without re-bumping.\n\n### Rollback\n\nThere is no clean rollback once a version hits npm. The right pattern\nis **forward**:\n\n1. Fix the issue.\n2. Cut a new patch (`npm version patch` if it's a bug fix).\n3. The bad version stays on npm but consumers using `^1.0.0` skip past\n   it on the next install.\n\nUse `npm deprecate @businessagil/workflow-schema@1.0.5 \"use 1.0.6\"`\nto tag a known-bad version with a warning; consumers see it on\ninstall. `npm unpublish` is **only** allowed in the first 72 hours\nand breaks anyone who already installed.\n\n## Design rationale\n\nThe \"why\" of each schema decision lives in the handbook:\n[`handbook/conventions/workflow-manifest.md`](https://gitlab.com/businessagil/handbook/-/blob/main/conventions/workflow-manifest.md).\nThis package is the formal contract; the handbook explains the\nreasoning behind it.\n","readmeFilename":"README.md"}