@intelmesh/sdk 0.1.0

package/docs/superpowers/specs/2026-04-10-release-pipeline-design.md

@@ -0,0 +1,309 @@
+# Release Pipeline Design — `@intelmesh/sdk`
+
+**Date:** 2026-04-10
+**Status:** Draft (pending user review)
+**Scope:** GitHub Actions workflow to publish `@intelmesh/sdk` to the public npm registry and create a GitHub Release on every signed semver tag.
+
+---
+
+## 1. Goals
+
+Create a single, auditable GitHub Actions workflow that:
+
+1. Triggers on semver tag push (`v*.*.*` and `v*.*.*-*`).
+2. Refuses to publish unless **both** the commit the tag points to **and** the tag object itself are cryptographically signed and verified by GitHub.
+3. Runs the full quality gate (lint, typecheck, tests, build) on a Node version matrix (20, 22, 24) before any publish action.
+4. Publishes to the public npm registry with Sigstore provenance.
+5. Automatically derives the npm `dist-tag` from the tag suffix (stable → `latest`, prerelease → `beta`/`rc`/`alpha`/etc).
+6. Creates a GitHub Release with the built tarball attached and auto-generated changelog, marked as `prerelease` when appropriate.
+7. Fails hard at the earliest failing step — no partial state (no published version without a release, no release without a successful publish).
+
+## 2. Non-goals
+
+- PR CI workflow (only release-on-tag is in scope).
+- `workflow_dispatch` with `dry_run` flag (deferred, YAGNI).
+- Integration tests hitting a live API (no such tests exist today).
+- Publishing to GitHub Packages or any registry other than public npm.
+- Automatic version bumping, changelog generation outside `gh release --generate-notes`, or release-please style automation.
+- Unpublish / rollback automation (stays manual).
+
+## 3. Trigger
+
+```yaml
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+-*'
+```
+
+Two explicit glob patterns. GitHub filters these *before* scheduling runners, so malformed tags like `v-test` or `release-1` never spend CI minutes. The first pattern matches stable releases (`v1.2.3`); the second matches prereleases (`v1.2.3-beta.1`, `v1.2.3-rc.2`, `v2.0.0-alpha.0`, etc).
+
+## 4. Workflow-level permissions and concurrency
+
+```yaml
+permissions:
+  contents: write    # github-release job creates releases
+  id-token: write    # publish-npm job generates OIDC token for --provenance
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+```
+
+**Permissions** are declared at the workflow level (not per job) because both are needed and `contents: read` alone is insufficient for the release step. No other permissions granted — principle of least privilege.
+
+**Concurrency** groups runs by tag ref with `cancel-in-progress: false`. Same tag cannot run twice in parallel (defense against accidental double-push), but distinct tags run independently. `cancel-in-progress` is explicitly `false` because a publish-in-flight must never be cancelled mid-flight (would leave npm and GitHub in inconsistent states).
+
+## 5. Job graph
+
+Four jobs, chained strictly via `needs:`. Any failure aborts the entire chain.
+
+```
+verify-signature → test (matrix 20/22/24) → publish-npm → github-release
+```
+
+### 5.1 Job: `verify-signature`
+
+**Runs-on:** `ubuntu-24.04`
+**Responsibility:** Refuse to proceed unless both the commit and the annotated tag object are verified.
+
+**Algorithm:**
+
+1. **Commit check**
+   - `GET /repos/{owner}/{repo}/commits/{github.sha}`
+   - Read `.commit.verification.verified`
+   - If not `true`: log `.commit.verification.reason` (examples: `unsigned`, `unknown_key`, `bad_email`, `unverified_email`, `not_signing_key`, `expired_key`) and `exit 1`.
+
+2. **Resolve tag object**
+   - `GET /repos/{owner}/{repo}/git/refs/tags/{github.ref_name}`
+   - Read `.object.type`
+   - If `"commit"`: the tag is a lightweight tag (no signature). Emit error telling the user to use `git tag -s` and `exit 1`.
+   - If `"tag"`: read `.object.sha` (the SHA of the tag object itself).
+
+3. **Tag signature check**
+   - `GET /repos/{owner}/{repo}/git/tags/{tag_object_sha}`
+   - Read `.verification.verified`
+   - If not `true`: log `.verification.reason` and `exit 1`.
+
+**Implementation tool:** `gh api` (pre-installed on GitHub-hosted runners, authenticated via `GH_TOKEN=${{ github.token }}`). JSON parsing via `--jq`.
+
+**Error output:** uses `::error::` workflow command so failures surface as annotations on the tag's commit in the Actions UI.
+
+**Why both checks?**
+- Commit-only: misses a lightweight tag created on top of a verified commit — you'd publish without ever signing the release itself.
+- Tag-only: misses the case where the tag is signed but the underlying commit came from an unverified push.
+- Both: guarantees a complete cryptographic chain from commit → tag → release.
+
+### 5.2 Job: `test`
+
+**Runs-on:** `ubuntu-24.04`
+**Needs:** `verify-signature`
+**Strategy:** Matrix on `node-version: [20, 22, 24]`, `fail-fast: true`.
+
+**Steps:**
+
+1. `actions/checkout@v5`
+2. `actions/setup-node@v5` with `node-version: ${{ matrix.node-version }}` and `cache: 'npm'`
+3. `npm ci`
+4. `npm run lint`
+5. `npm run typecheck`
+6. `npm run test` (vitest)
+7. `npm run build`
+
+All three matrix cells must succeed for `needs: test` downstream to unblock.
+
+**Rationale for matrix:** `package.json` declares `engines.node: ">=20"`. The release must prove the SDK works on every LTS-or-current supported runtime before going to npm. Runtime is cheap (three parallel jobs) and it catches runtime-specific regressions that only manifest on newer Node versions (e.g., changes to `fetch`, `URL`, or `AbortController` semantics).
+
+### 5.3 Job: `publish-npm`
+
+**Runs-on:** `ubuntu-24.04`
+**Needs:** `test`
+**Outputs:** `is_prerelease`, `disttag`, `version` (consumed by `github-release`).
+
+**Steps:**
+
+1. `actions/checkout@v5`
+2. `actions/setup-node@v5` with `node-version: 22`, `registry-url: 'https://registry.npmjs.org'`, `cache: 'npm'`
+3. `npm ci`
+4. `npm run build`
+5. **Compute dist-tag and version (step id: `disttag`)**
+
+   ```bash
+   set -euo pipefail
+   tag="${GITHUB_REF_NAME}"           # e.g. "v1.2.3-beta.1"
+   version="${tag#v}"                 # strip leading v → "1.2.3-beta.1"
+   if [[ "$version" == *-* ]]; then
+     suffix="${version#*-}"           # "beta.1"
+     disttag="${suffix%%.*}"          # "beta"
+     is_prerelease=true
+   else
+     disttag="latest"
+     is_prerelease=false
+   fi
+   echo "version=$version"         >> "$GITHUB_OUTPUT"
+   echo "disttag=$disttag"         >> "$GITHUB_OUTPUT"
+   echo "is_prerelease=$is_prerelease" >> "$GITHUB_OUTPUT"
+   ```
+
+6. **Version mismatch guard**
+
+   ```bash
+   pkg_version=$(node -p "require('./package.json').version")
+   if [ "$pkg_version" != "${{ steps.disttag.outputs.version }}" ]; then
+     echo "::error::package.json version ($pkg_version) does not match git tag (${{ steps.disttag.outputs.version }})"
+     exit 1
+   fi
+   ```
+
+7. **Publish**
+
+   ```bash
+   npm publish --provenance --access public --tag "${{ steps.disttag.outputs.disttag }}"
+   ```
+
+   With `env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`.
+
+**Tag-to-dist-tag mapping (reference):**
+
+| Tag pushed            | `version`         | `disttag` | `is_prerelease` |
+|-----------------------|-------------------|-----------|-----------------|
+| `v1.2.3`              | `1.2.3`           | `latest`  | `false`         |
+| `v1.2.3-beta.1`       | `1.2.3-beta.1`    | `beta`    | `true`          |
+| `v1.2.3-beta.4`       | `1.2.3-beta.4`    | `beta`    | `true`          |
+| `v1.2.3-rc.1`         | `1.2.3-rc.1`      | `rc`      | `true`          |
+| `v2.0.0-alpha.7`      | `2.0.0-alpha.7`   | `alpha`   | `true`          |
+| `v2.0.0-next.0`       | `2.0.0-next.0`    | `next`    | `true`          |
+
+**Why `--access public`?** `@intelmesh/sdk` is a scoped package; npm defaults scoped packages to private. The flag makes it explicit and prevents accidental private publishes.
+
+**Why `--provenance`?** Generates a Sigstore attestation linking the published tarball to the GitHub Actions run that built it. Consumers see a "provenance" badge on `npmjs.com/package/@intelmesh/sdk`. Requires `id-token: write` permission (already declared) and the npm account to have the package linked to this repo (via `package.json` `repository` field — must be verified present during implementation).
+
+**Why use the tag as the source of truth, not `package.json`?** If the developer tags `v1.2.3-beta.1` but forgets to bump `package.json` from `1.2.3`, we want a loud failure, not silent guessing. The version mismatch guard enforces this.
+
+### 5.4 Job: `github-release`
+
+**Runs-on:** `ubuntu-24.04`
+**Needs:** `publish-npm`
+
+**Steps:**
+
+1. `actions/checkout@v5` with `fetch-depth: 0` (needed for `gh release --generate-notes` to compute since-last-tag)
+2. `actions/setup-node@v5` with `node-version: 22`, `cache: 'npm'`
+3. `npm ci`
+4. `npm run build`
+5. `npm pack` (produces `intelmesh-sdk-<version>.tgz`)
+6. **Create release** — split into two steps, gated by `if:` on the `is_prerelease` output, to keep each command readable:
+
+   ```yaml
+   - name: Create GitHub Release (stable)
+     if: needs.publish-npm.outputs.is_prerelease == 'false'
+     env:
+       GH_TOKEN: ${{ github.token }}
+     run: |
+       gh release create "$GITHUB_REF_NAME" \
+         ./intelmesh-sdk-*.tgz \
+         --title "$GITHUB_REF_NAME" \
+         --generate-notes
+
+   - name: Create GitHub Release (prerelease)
+     if: needs.publish-npm.outputs.is_prerelease == 'true'
+     env:
+       GH_TOKEN: ${{ github.token }}
+     run: |
+       gh release create "$GITHUB_REF_NAME" \
+         ./intelmesh-sdk-*.tgz \
+         --title "$GITHUB_REF_NAME" \
+         --generate-notes \
+         --prerelease
+   ```
+
+   Two mutually exclusive steps are clearer than one step with a dynamic flag inlined via GHA expression syntax.
+
+**Why rebuild here instead of reusing `publish-npm` artifacts?** GitHub Actions jobs have isolated file systems. The alternatives are (a) `actions/upload-artifact` + `actions/download-artifact` between jobs, or (b) rebuild. Rebuild is simpler, deterministic, and the build is fast (<30s for this SDK). If build time grows, switch to upload/download. YAGNI for now.
+
+**Why `--generate-notes`?** GitHub auto-generates release notes from commits and PRs since the previous tag. No need to maintain a manual CHANGELOG for the MVP — the git log and PR titles are the source of truth. Manual CHANGELOG can be added later if needed.
+
+**Why create release *after* npm publish (not before)?** If npm publish fails, we don't want a dangling GitHub release pointing at a version that isn't in the registry. Publish first, release second.
+
+## 6. Secrets
+
+| Secret         | Source                          | Used in                         | Required |
+|----------------|---------------------------------|---------------------------------|----------|
+| `NPM_TOKEN`    | Repo Settings → Secrets → Actions | `publish-npm`                   | Yes      |
+| `GITHUB_TOKEN` | Automatic (injected)            | `verify-signature`, `github-release` | Auto     |
+
+**`NPM_TOKEN` provisioning (one-time, manual):**
+
+1. On `npmjs.com`, log in with the owner account for `@intelmesh`.
+2. Settings → Access Tokens → Generate New Token → Granular Access Token.
+3. Scope: `Read and write` on packages under `@intelmesh`.
+4. Expiration: 1 year (document renewal in team runbook).
+5. Copy the token.
+6. In the GitHub repo: Settings → Secrets and variables → Actions → New repository secret, name `NPM_TOKEN`.
+
+**Provenance prerequisite check:** During implementation, verify `package.json` has a `repository` field pointing to `github.com/intelmesh/intelmesh-sdk-ts`. If missing, add it — `npm publish --provenance` uses it to link the package to the source repo.
+
+## 7. Failure modes
+
+| Scenario                                | Failing job       | User-visible message                                                                 |
+|-----------------------------------------|-------------------|---------------------------------------------------------------------------------------|
+| Push of lightweight tag                 | `verify-signature` | `Tag vX.Y.Z is a lightweight tag. Use 'git tag -s' to create a signed annotated tag.` |
+| Commit not signed                       | `verify-signature` | `Commit <sha> is NOT verified. Reason: unsigned`                                      |
+| Signing key not registered on GitHub    | `verify-signature` | `Reason: unknown_key`                                                                 |
+| Expired signing key                     | `verify-signature` | `Reason: expired_key`                                                                 |
+| Signer email not verified on GitHub     | `verify-signature` | `Reason: unverified_email`                                                            |
+| Lint / typecheck / test / build failure | `test`            | ESLint / tsc / vitest annotations on the run                                          |
+| `package.json` version ≠ tag            | `publish-npm`     | `package.json version (X) does not match git tag (Y)`                                 |
+| Version already published               | `publish-npm`     | npm 403; step fails; no release created                                               |
+| `NPM_TOKEN` missing/expired             | `publish-npm`     | npm 401                                                                               |
+| Provenance OIDC fails                   | `publish-npm`     | npm publish error mentioning `id-token`                                               |
+
+All failures propagate via `needs:` so no downstream job runs. There is no partial state: a failed pipeline leaves the npm registry and GitHub Releases untouched by downstream jobs.
+
+## 8. Re-running a failed release
+
+**Supported:** GitHub Actions "Re-run failed jobs" works because the trigger is `push: tags` and the tag continues to point to the same commit. Use this for flaky failures (npm registry 502, runner network blip, etc).
+
+**Not supported by the workflow (manual process):**
+
+- Unpublishing a broken release from npm: `npm unpublish @intelmesh/sdk@X.Y.Z` within the 72-hour window, or contact npm support after.
+- Removing a release from GitHub: `gh release delete vX.Y.Z`.
+- Deleting/moving a tag: `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z && git tag -s vX.Y.Z <new-sha> && git push origin vX.Y.Z`.
+
+These stay manual because they are operational rollbacks, not part of a normal release flow, and automating them would be footgun territory.
+
+## 9. Testing the workflow itself
+
+Before the first real release, validate the pipeline end-to-end on a throwaway version:
+
+1. Create a branch with a signed commit.
+2. Bump `package.json` to a harmless prerelease version like `0.1.0-alpha.0`.
+3. Sign-tag: `git tag -s v0.1.0-alpha.0 -m "pipeline smoke test"`.
+4. Push tag: `git push origin v0.1.0-alpha.0`.
+5. Watch the Actions run:
+   - `verify-signature` must pass (if not: fix GPG/SSH setup first).
+   - `test` must pass on all three Node versions.
+   - `publish-npm` will actually publish to npm under dist-tag `alpha`. This is fine — `alpha` dist-tag doesn't affect default installs.
+   - `github-release` creates a prerelease on GitHub.
+6. After success: `npm dist-tag rm @intelmesh/sdk alpha` (cleanup, optional) and delete the GitHub release if desired.
+
+Alternatively, if contaminating the npm registry with a test version is undesirable, a future `workflow_dispatch` with `dry_run` input can be added (explicitly deferred — see Non-goals).
+
+## 10. File layout
+
+```
+.github/
+  workflows/
+    release.yml       ← this design's output
+```
+
+Single file. All four jobs live in one workflow so the full release pipeline is visible in one place.
+
+## 11. Open implementation questions
+
+None at spec time. Items to verify during implementation:
+
+- `package.json` `repository` field is present and points to the correct GitHub URL (required for `--provenance`).
+- The npm account owning `@intelmesh` exists and `NPM_TOKEN` has been provisioned before merging the workflow (otherwise the first tag push will fail at `publish-npm`).
+- GitHub org `intelmesh` has `Actions` enabled with `write` permissions for workflow tokens (Settings → Actions → Workflow permissions).

package/eslint.config.mjs

@@ -0,0 +1,38 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import security from 'eslint-plugin-security';
+import jsdoc from 'eslint-plugin-jsdoc';
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  security.configs.recommended,
+  jsdoc.configs['flat/recommended-typescript'],
+  {
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.eslint.json',
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/explicit-function-return-type': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_' },
+      ],
+      'complexity': ['error', 10],
+      'max-lines-per-function': ['error', { max: 50, skipBlankLines: true, skipComments: true }],
+      'jsdoc/require-jsdoc': [
+        'error',
+        { publicOnly: true },
+      ],
+      'jsdoc/require-description': 'error',
+      'no-console': 'error',
+    },
+  },
+  {
+    ignores: ['dist/', 'node_modules/', 'coverage/', '*.config.*', '*.cjs'],
+  },
+);

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@intelmesh/sdk",
+  "version": "0.1.0",
+  "description": "Official Node.js client for the IntelMesh Risk Intelligence Engine API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "intelmesh": {
+    "apiVersion": "v1",
+    "minServerVersion": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/ tests/",
+    "lint:fix": "eslint src/ tests/ --fix",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
+    "generate": "openapi-typescript ../docs/swagger.json -o src/generated/types.ts && prettier --write src/generated/types.ts",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "keywords": [
+    "intelmesh",
+    "risk",
+    "fraud",
+    "rules-engine",
+    "cel"
+  ],
+  "author": "IntelMesh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intelmesh/intelmesh-sdk-ts.git"
+  },
+  "homepage": "https://github.com/intelmesh/intelmesh-sdk-ts#readme",
+  "bugs": {
+    "url": "https://github.com/intelmesh/intelmesh-sdk-ts/issues"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.5.2",
+    "eslint": "^10.2.0",
+    "eslint-plugin-jsdoc": "^62.9.0",
+    "eslint-plugin-security": "^4.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "openapi-typescript": "^7.13.0",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
+    "vitest": "^4.1.3"
+  }
+}

package/src/builders/event.ts

@@ -0,0 +1,72 @@
+// ---------------------------------------------------------------------------
+// Fluent EventBuilder
+// ---------------------------------------------------------------------------
+
+import type { IngestRequest } from '../types.js';
+
+/**
+ * Fluent builder for constructing IngestRequest payloads.
+ */
+export class EventBuilder {
+  private eventType = '';
+  private idempotencyKey: string | undefined;
+  private payload: Record<string, unknown> = {};
+
+  /**
+   * Sets the event type.
+   * @param type - The event type string (e.g. "transaction.pix").
+   * @returns This builder for chaining.
+   */
+  type(type: string): this {
+    this.eventType = type;
+    return this;
+  }
+
+  /**
+   * Sets the idempotency key for deduplication.
+   * @param key - The idempotency key.
+   * @returns This builder for chaining.
+   */
+  idempotency(key: string): this {
+    this.idempotencyKey = key;
+    return this;
+  }
+
+  /**
+   * Sets a single payload field.
+   * @param key - The field name.
+   * @param value - The field value.
+   * @returns This builder for chaining.
+   */
+  set(key: string, value: unknown): this {
+    Object.assign(this.payload, { [key]: value });
+    return this;
+  }
+
+  /**
+   * Merges multiple fields into the payload.
+   * @param data - Record of fields to merge.
+   * @returns This builder for chaining.
+   */
+  data(data: Record<string, unknown>): this {
+    Object.assign(this.payload, data);
+    return this;
+  }
+
+  /**
+   * Builds and returns the IngestRequest.
+   * @returns The constructed IngestRequest.
+   * @throws {Error} If event type is not set.
+   */
+  build(): IngestRequest {
+    if (!this.eventType) {
+      throw new Error('EventBuilder: event type is required');
+    }
+
+    return {
+      event_type: this.eventType,
+      payload: { ...this.payload },
+      ...(this.idempotencyKey !== undefined && { idempotency_key: this.idempotencyKey }),
+    };
+  }
+}

package/src/builders/rule.ts

@@ -0,0 +1,143 @@
+// ---------------------------------------------------------------------------
+// Fluent RuleBuilder
+// ---------------------------------------------------------------------------
+
+import type { Actions, CreateRuleRequest, Decision, Flow, Severity } from '../types.js';
+
+/**
+ * Fluent builder for constructing CreateRuleRequest payloads.
+ */
+export class RuleBuilder {
+  private ruleName = '';
+  private ruleExpression = '';
+  private ruleApplicableWhen = '';
+  private rulePhaseId = '';
+  private rulePriority = 0;
+  private ruleEnabled = true;
+  private ruleDryRun = false;
+  private ruleActions: Actions = {};
+
+  /**
+   * Sets the rule name.
+   * @param n - The rule name.
+   * @returns This builder for chaining.
+   */
+  name(n: string): this {
+    this.ruleName = n;
+    return this;
+  }
+
+  /**
+   * Sets the CEL expression for the rule.
+   * @param expr - The CEL expression.
+   * @returns This builder for chaining.
+   */
+  expression(expr: string): this {
+    this.ruleExpression = expr;
+    return this;
+  }
+
+  /**
+   * Sets the condition under which this rule applies.
+   * @param condition - The applicable-when CEL expression.
+   * @returns This builder for chaining.
+   */
+  applicableWhen(condition: string): this {
+    this.ruleApplicableWhen = condition;
+    return this;
+  }
+
+  /**
+   * Sets the phase this rule belongs to.
+   * @param id - The phase ID.
+   * @returns This builder for chaining.
+   */
+  phase(id: string): this {
+    this.rulePhaseId = id;
+    return this;
+  }
+
+  /**
+   * Sets the rule priority (lower number = higher priority).
+   * @param p - The priority value.
+   * @returns This builder for chaining.
+   */
+  priority(p: number): this {
+    this.rulePriority = p;
+    return this;
+  }
+
+  /**
+   * Sets whether the rule is enabled.
+   * @param value - True to enable, false to disable.
+   * @returns This builder for chaining.
+   */
+  enabled(value: boolean): this {
+    this.ruleEnabled = value;
+    return this;
+  }
+
+  /**
+   * Sets whether the rule runs in dry-run mode.
+   * @param value - True for dry-run.
+   * @returns This builder for chaining.
+   */
+  dryRun(value: boolean): this {
+    this.ruleDryRun = value;
+    return this;
+  }
+
+  /**
+   * Sets the decision action when the rule matches.
+   * @param action - The action string.
+   * @param severity - The severity level.
+   * @returns This builder for chaining.
+   */
+  decide(action: string, severity: Severity): this {
+    const decision: Decision = { action, severity };
+    this.ruleActions = { ...this.ruleActions, decision };
+    return this;
+  }
+
+  /**
+   * Sets the flow control when the rule matches.
+   * @param flow - The flow control value.
+   * @returns This builder for chaining.
+   */
+  flow(flow: Flow): this {
+    this.ruleActions = { ...this.ruleActions, flow };
+    return this;
+  }
+
+  /**
+   * Sets the score delta when the rule matches.
+   * @param delta - The score points to add.
+   * @returns This builder for chaining.
+   */
+  scoreDelta(delta: number): this {
+    this.ruleActions = { ...this.ruleActions, score: { add: delta } };
+    return this;
+  }
+
+  /**
+   * Builds and returns the CreateRuleRequest.
+   * @returns The constructed CreateRuleRequest.
+   * @throws {Error} If required fields are missing.
+   */
+  build(): CreateRuleRequest {
+    if (!this.ruleName) throw new Error('RuleBuilder: name is required');
+    if (!this.ruleExpression) throw new Error('RuleBuilder: expression is required');
+    if (!this.rulePhaseId) throw new Error('RuleBuilder: phase is required');
+
+    return {
+      name: this.ruleName,
+      expression: this.ruleExpression,
+      applicable_when: this.ruleApplicableWhen,
+      phase_id: this.rulePhaseId,
+      priority: this.rulePriority,
+      enabled: this.ruleEnabled,
+      dry_run: this.ruleDryRun,
+      actions: this.ruleActions,
+    };
+  }
+}