@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/skill/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: testrail-cli
+description: Use the `testrail` CLI to query and write TestRail projects, suites, cases, runs, results, milestones, and users from the shell. Trigger when the user asks to look up, list, fetch, count, inspect, create, update, or publish TestRail entities, or when TESTRAIL_BASE_URL / TESTRAIL_EMAIL / TESTRAIL_API_KEY are set in the environment.
+version: 2.1.0
+license: MIT
+homepage: https://github.com/dichovsky/testrail-api-client
+---
+
+# `testrail` CLI
+
+A zero-dependency Node CLI for the TestRail REST API. Covers query (`get`,
+`list`) and write (`add`, `update`, `add-bulk`, `close`) operations across
+projects, suites, cases, runs, results, milestones, and users.
+
+This skill is designed for **coding agents** running shell commands. It is
+not a TestRail user manual. For the browser UI, see TestRail's own docs.
+
+## When to use this skill
+
+- The user mentions TestRail by name, or asks about test cases, test runs,
+  test results, or test plans in a TestRail context.
+- `TESTRAIL_BASE_URL` / `TESTRAIL_EMAIL` / `TESTRAIL_API_KEY` are set in the
+  environment.
+- The user wants to: look up, list, fetch, count, inspect, create, update,
+  or publish TestRail entities from the shell or from CI.
+
+## Install / verify
+
+The CLI ships with the npm package `@dichovsky/testrail-api-client` and
+exposes the `testrail` binary. Verify it is available:
+
+```bash
+npx testrail --version
+```
+
+If you installed the package locally, `npx testrail` runs the local copy
+without a global install.
+
+## Authentication
+
+The CLI requires three credentials. Provide them either as environment
+variables (preferred — keeps secrets out of argv and shell history) or as
+flags:
+
+| Purpose       | Env var             | Flag               |
+| ------------- | ------------------- | ------------------ |
+| TestRail URL  | `TESTRAIL_BASE_URL` | `--base-url <url>` |
+| Account email | `TESTRAIL_EMAIL`    | `--email <email>`  |
+| API key       | `TESTRAIL_API_KEY`  | `--api-key <key>`  |
+
+If credentials are missing, the CLI exits 1 with `Error: Missing auth...`
+on stderr. Never echo or log the API key.
+
+## Command surface
+
+<!-- GENERATED:command-table -->
+| Resource | Action | Path args | Body | Description |
+| --- | --- | --- | --- | --- |
+| project | get | `<project_id>` | — | Fetch a single project by ID |
+| project | list | — | — | List all projects (paginated) |
+| suite | get | `<suite_id>` | — | Fetch a single suite by ID |
+| suite | list | — | — | List suites in a project |
+| case | get | `<case_id>` | — | Fetch a single test case by ID |
+| case | list | — | — | List cases in a project (optionally filtered by suite) |
+| run | get | `<run_id>` | — | Fetch a single run by ID |
+| run | list | — | — | List runs in a project (paginated) |
+| result | list | — | — | List results for a run (paginated) |
+| milestone | get | `<milestone_id>` | — | Fetch a single milestone by ID |
+| milestone | list | — | — | List milestones in a project (paginated) |
+| user | get | `<user_id>` | — | Fetch a single user by ID |
+| user | list | — | — | List users (paginated) |
+| case | add | `<section_id>` | `AddCasePayloadSchema` | Create a new test case under a section |
+| case | update | `<case_id>` | `UpdateCasePayloadSchema` | Update an existing test case (partial fields) |
+| run | add | `<project_id>` | `AddRunPayloadSchema` | Create a new test run in a project |
+| run | close | `<run_id>` | — (no body) | Close a test run (no body) |
+| result | add | `<run_id>` `<case_id>` | `AddResultPayloadSchema` | Record a single result for a case in a run |
+| result | add-bulk | `<run_id>` | `AddResultsForCasesPayloadSchema` | Record multiple results for cases in one API call |
+<!-- /GENERATED:command-table -->
+
+## Body input for write actions
+
+For body-bearing write actions (all except `run close`), provide the JSON
+payload via **exactly one** of:
+
+```bash
+# (a) inline string — best for short payloads, agent-generated
+testrail case add 5 --data '{"title":"New case"}'
+
+# (b) file — best for large/repeated payloads, reviewable in git
+testrail case add 5 --data-file payload.json
+
+# (c) piped stdin — best for shell composition with jq / curl / etc.
+echo '{"title":"New case"}' | testrail case add 5
+```
+
+The CLI exits 1 if zero or more than one body source is provided.
+
+### `--dry-run`
+
+Add `--dry-run` to validate the payload against the Zod schema and print
+what _would_ be sent, without making an API call. Useful for verifying
+payload shape before consuming TestRail rate limit.
+
+```bash
+testrail case add 5 --data '{"title":"x"}' --dry-run
+```
+
+## Payload schemas
+
+Each write action validates its body against a Zod schema with
+`.passthrough()` — required fields must match types exactly (no
+coercion; `"5"` is rejected where `5` is expected), and TestRail
+`custom_*` fields pass through untouched.
+
+<!-- GENERATED:payload-schemas -->
+### `AddCasePayloadSchema` (used by `case add`)
+
+```jsonc
+{
+    "title": "string (required)",
+    "template_id": "number?",
+    "type_id": "number?",
+    "priority_id": "number?",
+    "estimate": "string?",
+    "milestone_id": "number?",
+    "refs": "string?",
+    "custom_fields": "Record<string, unknown>?"
+}
+```
+
+### `UpdateCasePayloadSchema` (used by `case update`)
+
+```jsonc
+{
+    "title": "string?",
+    "template_id": "number?",
+    "type_id": "number?",
+    "priority_id": "number?",
+    "estimate": "string?",
+    "milestone_id": "number?",
+    "refs": "string?",
+    "custom_fields": "Record<string, unknown>?"
+}
+```
+
+### `AddRunPayloadSchema` (used by `run add`)
+
+```jsonc
+{
+    "name": "string (required)",
+    "suite_id": "number?",
+    "description": "string?",
+    "milestone_id": "number?",
+    "assignedto_id": "number?",
+    "include_all": "boolean?",
+    "case_ids": "number[]?",
+    "refs": "string?"
+}
+```
+
+### `AddResultPayloadSchema` (used by `result add`)
+
+```jsonc
+{
+    "status_id": "number (required)",
+    "comment": "string?",
+    "version": "string?",
+    "elapsed": "string?",
+    "defects": "string?",
+    "assignedto_id": "number?",
+    "custom_fields": "Record<string, unknown>?"
+}
+```
+
+### `AddResultsForCasesPayloadSchema` (used by `result add-bulk`)
+
+```jsonc
+{
+    "results": "object[] (required)"
+}
+```
+<!-- /GENERATED:payload-schemas -->
+
+For the authoritative type definitions, see `src/schemas.ts` in the
+package source.
+
+## Output
+
+By default, `testrail` emits pretty-printed JSON to stdout. Use `--format
+table` for column-aligned human-readable output. Use `--quiet` to
+suppress stdout entirely (rely on exit code).
+
+```bash
+testrail project get 1                  # JSON (default)
+testrail project list --format table    # Table
+testrail run get 5 --quiet              # Exit code 0/1 only
+```
+
+### Filtering output (preserve context budget)
+
+The CLI emits the full JSON object for each entity. For list endpoints
+with hundreds of items, that can blow the agent's context window. Filter
+at the shell when possible:
+
+**Preferred:** `jq` (if available — most dev/CI environments have it):
+
+```bash
+testrail run get 5 | jq '.passed_count'
+testrail case list --project-id 1 | jq '.[] | {id, title}'
+```
+
+**Fallback:** Node one-liner (always available since the package itself
+is a Node CLI):
+
+```bash
+testrail run get 5 | node -e 'const d=JSON.parse(require("fs").readFileSync(0));console.log(d.passed_count)'
+```
+
+## Recipes
+
+### 1. Smoke-test auth & connectivity
+
+```bash
+testrail user list --limit 1 --quiet && echo "auth OK" || echo "auth FAILED"
+```
+
+Exit code 0 = creds resolve and TestRail responds; 1 = anything broken.
+
+### 2. Fetch a project
+
+```bash
+testrail project get 5
+```
+
+### 3. List projects with pagination
+
+```bash
+testrail project list --limit 25 --offset 0
+```
+
+### 4. List suites under a project
+
+```bash
+testrail suite list --project-id 5
+```
+
+### 5. List cases in a specific suite
+
+```bash
+testrail case list --project-id 5 --suite-id 12
+```
+
+### 6. Extract just the IDs from any list (generic pattern)
+
+```bash
+testrail case list --project-id 5 | jq '.[].id'
+```
+
+### 7. Count pass/fail for a run
+
+```bash
+testrail run get 42 | jq '{passed: .passed_count, failed: .failed_count}'
+```
+
+### 8. Page through a large result list
+
+```bash
+offset=0
+while true; do
+    page=$(testrail result list --run-id 100 --limit 100 --offset $offset)
+    count=$(echo "$page" | jq 'length')
+    [ "$count" -eq 0 ] && break
+    echo "$page" | jq -c '.[]'
+    offset=$((offset + count))
+done
+```
+
+### 9. Author a new test case
+
+```bash
+testrail case add 12 --data '{
+    "title": "Login page accepts SSO redirect",
+    "type_id": 1,
+    "priority_id": 3,
+    "refs": "JIRA-1234"
+}'
+```
+
+### 10. Update a test case (partial fields)
+
+```bash
+testrail case update 87 --data '{"title": "Renamed", "priority_id": 4}'
+```
+
+### 11. Create a CI test run
+
+```bash
+RUN=$(testrail run add 5 --data '{
+    "name": "CI build #'"$CI_BUILD_NUMBER"'",
+    "include_all": false,
+    "case_ids": [42, 43, 44]
+}')
+RUN_ID=$(echo "$RUN" | jq '.id')
+```
+
+### 12. Publish bulk results from a CI run
+
+```bash
+testrail result add-bulk "$RUN_ID" --data-file /tmp/results.json
+```
+
+Where `/tmp/results.json` has shape:
+
+```json
+{
+    "results": [
+        { "case_id": 42, "status_id": 1, "comment": "passed" },
+        { "case_id": 43, "status_id": 5, "comment": "failed: timeout" }
+    ]
+}
+```
+
+### 13. Close a run when CI finishes
+
+```bash
+testrail run close "$RUN_ID"
+```
+
+### 14. Validate a payload before sending (`--dry-run`)
+
+```bash
+testrail result add 100 42 --data '{"status_id":1,"comment":"sanity check"}' --dry-run
+```
+
+Prints the parsed payload + a `"dryRun": true` marker; no API call made.
+
+## Errors & exit codes
+
+| Exit | Meaning                                                                            |
+| ---- | ---------------------------------------------------------------------------------- |
+| `0`  | Success                                                                            |
+| `1`  | Any failure: bad auth, invalid args, validation, 4xx/5xx HTTP, rate limit, timeout |
+
+Errors are written to stderr in the form `Error: <message>`. Common
+causes:
+
+- `Missing auth.` → env vars / flags not set.
+- `<param> must be a positive integer` → bad path arg (e.g. `project get abc`).
+- `Unknown resource '<x>'. Use: project, suite, case, run, result, milestone, user`
+- `Unknown action '<a>' for <r>. Use: get, list, …`
+- `Body required.` → write action invoked with no `--data` / `--data-file` / stdin.
+- `Invalid JSON: …` → malformed body.
+- `Payload validation failed: …` → body shape doesn't match the Zod schema.
+- `TestRail API error: 404 Not Found …` → 4xx/5xx response from TestRail.
+
+## Limits & gotchas
+
+- **Rate limit:** 100 requests / 60s by default (configurable on the
+  programmatic client; the CLI uses defaults). The CLI throws an error
+  rather than queueing on overflow.
+- **GET cache:** GET responses are cached in-process for ~5 minutes by
+  default. POSTs invalidate the entire cache. Stale reads are possible
+  if the same `testrail` invocation re-fetches the same endpoint within
+  the TTL.
+- **Retry:** 5xx responses, 429s, and network errors are retried with
+  exponential backoff (max 3 attempts). 4xx and timeout errors are not
+  retried.
+- **No coercion on write payloads:** `"5"` is **not** silently converted
+  to `5`. This is intentional — catches agent template-substitution
+  bugs at the CLI boundary rather than the API call site.
+- **`custom_*` fields:** Pass through `.passthrough()` schemas unchanged.
+  Field naming follows TestRail's `custom_<field-system-name>` convention.
+
+## When NOT to use this skill
+
+- **Writing TypeScript/JavaScript code that imports the package.**
+  This skill documents the CLI surface only. For programmatic use,
+  read `README.md` and `CODEMAP.md` in the package — the programmatic
+  API exposes 101 methods, far beyond what the CLI covers.
+- **Project / suite / section / milestone / user CRUD** beyond the 6
+  write actions listed above. Use the TestRail web UI for structural
+  setup (or the programmatic API).
+- **Deletes** of any kind. The CLI deliberately does not expose `delete`
+  actions to keep agents away from irrecoverable operations.
+- **Attachments** (upload/download). Not in the CLI surface; use the
+  programmatic API.
+- **Browser/UI workflows.** This is a non-interactive CLI.
+
+## See also
+
+- `README.md` — package install, programmatic API overview, configuration
+- `CODEMAP.md` — every public method, type, error class, and constant
+- `src/schemas.ts` — Zod payload schemas (source of truth)
+- `BACKLOG.md` — deferred CLI/skill features tracked for future releases
+- TestRail API docs: <https://support.testrail.com/hc/en-us/articles/7077083596436-Introduction-to-the-TestRail-API>

package/src/cli/auth.ts

@@ -0,0 +1,37 @@
+import type { TestRailConfig } from '../types.js';
+
+export interface AuthFlags {
+    baseUrl: string | undefined;
+    email: string | undefined;
+    apiKey: string | undefined;
+}
+
+export interface AuthEnv {
+    TESTRAIL_BASE_URL?: string;
+    TESTRAIL_EMAIL?: string;
+    TESTRAIL_API_KEY?: string;
+}
+
+export type AuthResolution = { ok: true; config: TestRailConfig } | { ok: false; error: string };
+
+export const MISSING_AUTH_MESSAGE =
+    'Missing auth. Set TESTRAIL_BASE_URL, TESTRAIL_EMAIL, TESTRAIL_API_KEY or use --base-url, --email, --api-key flags.';
+
+export function resolveAuth(flags: AuthFlags, env: AuthEnv): AuthResolution {
+    const baseUrl = flags.baseUrl ?? env.TESTRAIL_BASE_URL;
+    const email = flags.email ?? env.TESTRAIL_EMAIL;
+    const apiKey = flags.apiKey ?? env.TESTRAIL_API_KEY;
+
+    if (
+        baseUrl === undefined ||
+        baseUrl === '' ||
+        email === undefined ||
+        email === '' ||
+        apiKey === undefined ||
+        apiKey === ''
+    ) {
+        return { ok: false, error: MISSING_AUTH_MESSAGE };
+    }
+
+    return { ok: true, config: { baseUrl, email, apiKey } };
+}

package/src/cli/body.ts

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs';
+import type { z } from 'zod';
+import type { BodyInput } from './handler-context.js';
+
+/**
+ * Source of a parsed body. Reported alongside the resolution result so
+ * handlers (or callers writing recipes) can log which input mechanism the
+ * agent actually used.
+ */
+export type BodySource = 'data' | 'file' | 'stdin';
+
+export type BodyResolution<T> = { ok: true; payload: T; source: BodySource } | { ok: false; error: string };
+
+/**
+ * Resolve a write-action body from one of three mutually-exclusive sources:
+ *
+ * - `--data <json-string>` (provided via `BodyInput.dataFlag`)
+ * - `--data-file <path>` (provided via `BodyInput.dataFileFlag`; read via
+ *   readFileSync so failures surface as a structured `ok: false` rather than
+ *   crashing the CLI)
+ * - stdin (provided via `BodyInput.readStdin` thunk; the caller is
+ *   responsible for non-TTY detection — only set the thunk when stdin is
+ *   piped. The resolver invokes the thunk *only* when stdin is the
+ *   selected source, so read actions and no-body writes never drain it.)
+ *
+ * After source resolution: JSON-parse the raw string, then validate against
+ * the supplied Zod schema. No coercion is applied (Q8 lock from
+ * SKILL-PLAN.md) — wrong types are rejected immediately so agent payload
+ * bugs surface at the CLI boundary rather than the API call site.
+ *
+ * Typed via `S extends z.ZodTypeAny` so the inferred payload type carries
+ * through to the caller — `resolveBody(input, AddCasePayloadSchema)` returns
+ * `BodyResolution<AddCasePayload>`, not `BodyResolution<unknown>`.
+ *
+ * @param input  raw inputs from the CLI argv + stdin reader
+ * @param schema Zod schema for the expected payload shape
+ */
+export function resolveBody<S extends z.ZodTypeAny>(input: BodyInput, schema: S): BodyResolution<z.infer<S>> {
+    const sources = [
+        input.dataFlag !== undefined ? 'data' : null,
+        input.dataFileFlag !== undefined ? 'file' : null,
+        input.readStdin !== undefined ? 'stdin' : null,
+    ].filter((s): s is BodySource => s !== null);
+
+    if (sources.length === 0) {
+        return {
+            ok: false,
+            error: 'Body required. Pass a JSON payload via --data <json>, --data-file <path>, or stdin pipe.',
+        };
+    }
+    if (sources.length > 1) {
+        return {
+            ok: false,
+            error: `Multiple body sources provided (${sources.join(', ')}). Use exactly one of --data, --data-file, or stdin.`,
+        };
+    }
+
+    let raw: string;
+    let source: BodySource;
+    if (input.dataFlag !== undefined) {
+        raw = input.dataFlag;
+        source = 'data';
+    } else if (input.dataFileFlag !== undefined) {
+        try {
+            raw = readFileSync(input.dataFileFlag, 'utf-8');
+        } catch (e) {
+            return {
+                ok: false,
+                error: `Cannot read --data-file '${input.dataFileFlag}': ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+        source = 'file';
+    } else {
+        // stdin is the only remaining source. Invoke the thunk now (and only
+        // now) so the underlying readFileSync(0) call happens lazily.
+        try {
+            raw = (input.readStdin as () => string)();
+        } catch (e) {
+            return {
+                ok: false,
+                error: `Cannot read stdin: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+        source = 'stdin';
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (e) {
+        return { ok: false, error: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        return { ok: false, error: `Payload validation failed: ${result.error.message}` };
+    }
+
+    return { ok: true, payload: result.data, source };
+}

package/src/cli/dispatch.ts

@@ -0,0 +1,91 @@
+import type { Handler } from './handler-context.js';
+import { handleProjectGet, handleProjectList } from './handlers/project.js';
+import { handleSuiteGet, handleSuiteList } from './handlers/suite.js';
+import { handleCaseGet, handleCaseList } from './handlers/case.js';
+import { handleCaseAdd, handleCaseUpdate } from './handlers/case-write.js';
+import { handleRunGet, handleRunList } from './handlers/run.js';
+import { handleRunAdd, handleRunClose } from './handlers/run-write.js';
+import { handleResultList } from './handlers/result.js';
+import { handleResultAdd, handleResultAddBulk } from './handlers/result-write.js';
+import { handleMilestoneGet, handleMilestoneList } from './handlers/milestone.js';
+import { handleUserGet, handleUserList } from './handlers/user.js';
+
+/**
+ * Single source of truth: every supported resource:action mapped to its handler.
+ * Adding an action is a one-line change here — no parallel registry to keep in
+ * sync. `dispatch()` derives both the known-resources list and the
+ * known-actions-per-resource list from this map's keys, so error wording stays
+ * accurate even as the map evolves.
+ *
+ * Keys are inserted in the canonical display order (`get` before `list`, etc.);
+ * JavaScript object iteration order is insertion-order-preserving for string
+ * keys, which keeps error messages stable.
+ */
+const HANDLERS: Record<string, Handler> = {
+    'project:get': handleProjectGet,
+    'project:list': handleProjectList,
+    'suite:get': handleSuiteGet,
+    'suite:list': handleSuiteList,
+    'case:get': handleCaseGet,
+    'case:list': handleCaseList,
+    'case:add': handleCaseAdd,
+    'case:update': handleCaseUpdate,
+    'run:get': handleRunGet,
+    'run:list': handleRunList,
+    'run:add': handleRunAdd,
+    'run:close': handleRunClose,
+    'result:list': handleResultList,
+    'result:add': handleResultAdd,
+    'result:add-bulk': handleResultAddBulk,
+    'milestone:get': handleMilestoneGet,
+    'milestone:list': handleMilestoneList,
+    'user:get': handleUserGet,
+    'user:list': handleUserList,
+};
+
+const RESOURCES: Record<string, readonly string[]> = (() => {
+    const grouped: Record<string, string[]> = {};
+    for (const key of Object.keys(HANDLERS)) {
+        const [resource, action] = key.split(':');
+        if (resource === undefined || action === undefined) continue;
+        const existing = grouped[resource];
+        if (existing === undefined) {
+            grouped[resource] = [action];
+        } else {
+            existing.push(action);
+        }
+    }
+    return grouped;
+})();
+
+export type DispatchResult = { ok: true; handler: Handler } | { ok: false; error: string };
+
+/**
+ * Returns every registered `resource:action` key. Used by the
+ * metadata↔dispatch consistency tests to catch handlers added without a
+ * matching metadata entry — the inverse of the metadata-first check.
+ */
+export function getRegisteredActions(): readonly string[] {
+    return Object.keys(HANDLERS);
+}
+
+export function dispatch(resource: string, action: string): DispatchResult {
+    const actions = RESOURCES[resource];
+    if (actions === undefined) {
+        return {
+            ok: false,
+            error: `Unknown resource '${resource}'. Use: ${Object.keys(RESOURCES).join(', ')}`,
+        };
+    }
+    if (!actions.includes(action)) {
+        return {
+            ok: false,
+            error: `Unknown action '${action}' for ${resource}. Use: ${actions.join(', ')}`,
+        };
+    }
+    const handler = HANDLERS[`${resource}:${action}`];
+    if (handler === undefined) {
+        return { ok: false, error: `No handler registered for ${resource}:${action}` };
+    }
+    return { ok: true, handler };
+}

package/src/cli/handler-context.ts

@@ -0,0 +1,46 @@
+import type { TestRailClient } from '../client.js';
+
+/**
+ * Parsed CLI argument bundle passed to every handler.
+ *
+ * `pathParams` is the slice of positional args after `[resource, action]` —
+ * read handlers consume `pathParams[0]` (the single id), write handlers may
+ * consume multiple (e.g., `result add <run_id> <case_id>` uses [0] and [1]).
+ */
+export interface HandlerArgs {
+    pathParams: readonly string[];
+    projectId?: string;
+    suiteId?: string;
+    runId?: string;
+    caseId?: string;
+    limit?: string;
+    offset?: string;
+}
+
+/**
+ * Raw inputs for the body-source resolver. The handler decides whether to
+ * consume any of these (write handlers do; read handlers ignore). When all
+ * three are absent for a write action, the resolver emits a "body required"
+ * error.
+ *
+ * `readStdin` is a thunk rather than pre-read contents so stdin is *only*
+ * drained when the resolver actually selects it as the body source. Read
+ * actions and no-body writes (`run close`) never invoke it — avoiding the
+ * "tail -f | testrail run close" hang and the cost of slurping a large
+ * redirected stdin that the handler will throw away.
+ */
+export interface BodyInput {
+    dataFlag?: string;
+    dataFileFlag?: string;
+    readStdin?: () => string;
+}
+
+export interface HandlerContext {
+    client: TestRailClient;
+    args: HandlerArgs;
+    bodyInput: BodyInput;
+    dryRun: boolean;
+    out: (data: unknown) => void;
+}
+
+export type Handler = (ctx: HandlerContext) => Promise<void>;

package/src/cli/handlers/case-write.ts

@@ -0,0 +1,26 @@
+import type { HandlerContext } from '../handler-context.js';
+import { parseId } from '../ids.js';
+import { resolveBody } from '../body.js';
+import { AddCasePayloadSchema, UpdateCasePayloadSchema } from '../../schemas.js';
+
+export async function handleCaseAdd(ctx: HandlerContext): Promise<void> {
+    const sectionId = parseId(ctx.args.pathParams[0], 'section_id');
+    const body = resolveBody(ctx.bodyInput, AddCasePayloadSchema);
+    if (!body.ok) throw new Error(body.error);
+    if (ctx.dryRun) {
+        ctx.out({ dryRun: true, action: 'case add', sectionId, payload: body.payload, source: body.source });
+        return;
+    }
+    ctx.out(await ctx.client.addCase(sectionId, body.payload));
+}
+
+export async function handleCaseUpdate(ctx: HandlerContext): Promise<void> {
+    const caseId = parseId(ctx.args.pathParams[0], 'case_id');
+    const body = resolveBody(ctx.bodyInput, UpdateCasePayloadSchema);
+    if (!body.ok) throw new Error(body.error);
+    if (ctx.dryRun) {
+        ctx.out({ dryRun: true, action: 'case update', caseId, payload: body.payload, source: body.source });
+        return;
+    }
+    ctx.out(await ctx.client.updateCase(caseId, body.payload));
+}