@crvouga/mockingbird-service-plane

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator 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 emulator; 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

In a test, the application's Plane SDK (@makeplane/plane-node-sdk) takes the emulator's URL as its baseUrl:

import { PlaneClient } from "@makeplane/plane-node-sdk"
import { createServer } from "@crvouga/mockingbird-service-plane/server"

// Test setup: a local Plane.
const server = await createServer()

// Application code: Plane's SDK. Only its base URL changes.
const plane = new PlaneClient({ baseUrl: server.url, apiKey: "plane_api_test" })
const projectId = "33333333-3333-4333-8333-333333333333"
const item = await plane.workItems.create("acme", projectId, { name: "Checkout fails on Safari" })

// Test control: resolve it the way a teammate would; the resolution watcher then sees group
// "completed".
await fetch(`${server.url}/__admin/work-items/${item.id}/state`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ state: "Done" }),
})

await server.close()

Routes

All under /api/v1/workspaces/{slug}/projects/{project_id}/, with X-API-Key. {slug} is your workspace's slug (acme in the examples).

Seed types through POST /__admin/work-item-types, then send type_id on work-item create or patch. GET returns both type_id and type, as Plane's work-item serializer does. Unknown IDs fail with a DRF type_id error before any field or sequence number changes. Creation inherits a seeded default type; an explicit patch type_id: null clears it.

Cycle dates use UTC project days and the emulator clock, following Plane's cycle endpoint and date converter: future/past starts are 00:00:01, today's start is the creation time, and ends are 23:59:00. The current filter includes both endpoints. Cycle counts follow work-item state changes.

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 /__admin/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), cycle editing/deletion and non-UTC project timezones, modules, pages, intake, attachments, members, estimates, worklogs, and expand=.
• Deleting work items, comments, links or labels; archiving.
• Vendor work-item type administration, custom type schemas, epics and cross-project type sharing. Seed types with the admin control for this list/assignment surface.
• Rich-text processing: description_stripped / comment_stripped are tag-stripped text.

API

Part of mockingbird.