Plane

Stateful mock of the Plane REST API (v1) for test suites, covering what our bug-report dedup and resolution jobs call on one project: work items (Plane's cursor-paginated list, get, create, patch), comments, links, states and labels, with Plane's rate limit and error shapes. Projects are provisioned on first use with Plane's default workflow (Backlog, Todo, In Progress, Done, Cancelled), so no setup is needed.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from Plane's API reference and the consumer's zod schemas (plane-response.ts).

#Install

npm install -D @crvouga/mockingbird-service-plane

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-plane serve, createServer from ./server (Node), or createRuntime with any Fetch server.

#Usage

The backend hardcodes https://api.plane.so (plane-http-client.ts, seam G-Y1: make it env-driven). Point it at the mock; PLANE_ACCESS_TOKEN, PLANE_WORKSPACE_SLUG and PLANE_BUGS_PROJECT_ID can be any values (the project id must be a UUID, as our config validates).

npx mockingbird-plane serve --port 8821 --rate-limit 60

import { createRuntime } from "@crvouga/mockingbird-service-plane"

const plane = createRuntime()
const base = "http://plane.test/api/v1/workspaces/geviti/projects/33333333-3333-4333-8333-333333333333"
const headers = { "x-api-key": "plane_api_test", "content-type": "application/json" }

const created = await plane.fetch(
  new Request(`${base}/work-items/`, {
    method: "POST",
    headers,
    body: JSON.stringify({ name: "Checkout fails on Safari" }),
  }),
)
const item = (await created.json()) as { id: string }
// Resolve it the way a teammate would; the resolution watcher then sees group "completed".
await plane.fetch(
  new Request(`http://plane.test/__admin/work-items/${item.id}/state`, {
    method: "POST",
    headers,
    body: JSON.stringify({ state: "Done" }),
  }),
)

#Routes

All under /api/v1/workspaces/{slug}/projects/{project_id}/, with X-API-Key.

Errors: no key 401 {"detail": "Authentication credentials were not provided."}, a key outside apiKeys 401 {"detail": "Given API token is not valid"}, unknown item/project 404 {"error": "The requested resource does not exist."}, throttled 429 {"detail": "Request was throttled. Expected available in N seconds."} with x-ratelimit-* headers.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): rate_limited (429), server_error (500), bad_gateway (502 HTML), unauthorized (401), invalid_json (200 non-JSON on reads), network_drop, slow (15 s, past our 10 s timeout), pagination_missing_cursor, pagination_repeated_cursor. Our client retries GETs at 0, 2 and 8 s, so count: 2 recovers on the third attempt and count: 3 exhausts the budget; writes are never retried.

#Namespaces

x-mockingbird-namespace, a /ns/<name> prefix on the base URL, or by API key: PUT /__admin/credentials {"credentials": {"<PLANE_ACCESS_TOKEN>": "<namespace>"}}.

#Deliberately not modelled

• Plane webhooks (our app polls), cycles, modules, pages, intake, attachments, members, estimates, worklogs, and expand=.
• Deleting work items, comments, links or labels; archiving.
• Rich-text processing: description_stripped / comment_stripped are tag-stripped text.

#API

Part of mockingbird.