specproof 0.1.0 → 0.2.0

package/.github/workflows/release.yml

@@ -3,7 +3,6 @@ name: 🚀 Release
 on:
   push:
     branches: main
-  workflow_dispatch:
 
 permissions:
   contents: read

package/.github/workflows/test-unit.yml

@@ -1,20 +1,58 @@
-name: 🧾 Proof Contract Tests
+name: CI
 
 on:
-  push:
-    branches: main
   pull_request:
     branches: main
+  merge_group:
+  push:
+    branches: main
   workflow_dispatch:
 
 jobs:
-  test-unit:
-    name: 🧾 Run proof contract tests
+  build:
+    name: Build
     runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v5
 
+      - name: 🍞 Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: 🧰 Install dependencies
+        run: bun install
+
+      - name: 🏗️ Build
+        run: bun run build
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v5
+
+      - name: 🍞 Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: 🧰 Install dependencies
+        run: bun install
+
+      - name: 🧹 ESLint
+        run: bun run lint:es
+
+      - name: 🔎 Typecheck
+        run: bun run lint:ts
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
     env:
       NODE_ENV: test
-
     steps:
       - name: 📥 Checkout code
         uses: actions/checkout@v5
@@ -27,10 +65,5 @@ jobs:
       - name: 🧰 Install dependencies
         run: bun install
 
-      # The contract tests self-skip when no audited repo is configured.
-      # To guard a specific target in CI, check it out here and set
-      # SPECPROOF_REPO (and optionally SPECPROOF_SPEC) on the test step.
-      - name: 🧾 Run contract tests
+      - name: 🧾 Run unit & contract tests
         run: bun run test:unit
-        env:
-          NODE_ENV: test

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-07-14
+
+### Added
+- Bundled `example/` demo target: the fictional TaskFlow API (7 operations) plus fixture test files, audited automatically when no `SPECPROOF_REPO` is set — the app now renders a meaningful proof out of the box, demonstrating every verdict state.
+- Unit test suite for the coverage analyzer (`lib/api-test-coverage.test.ts`, 30 tests): path-param normalization, snippet extraction, test-file parsing, spec discovery, evidence merging, and report assembly with independently computed expectations.
+- CI workflow with separate `Build`, `Lint`, and `Test` jobs, running on pull requests and in the merge queue.
+- Merge queue ruleset on `main`: PRs required, all CI checks must pass, no direct pushes.
+- Marketing showcase page (`marketing/`) and brand assets (`public/`), with a banner in the README.
+
+### Changed
+- Releases now publish only after a PR merges to `main` through the merge queue; the manual release trigger was removed.
+- `buildCoverageReport()` accepts an optional target repo root, and the analyzer's parsing internals are exported for testing.
+- Larger SpecProof masthead in the coverage view.
+
 ## [0.1.0] - 2026-07-13
 
 ### Added

package/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 SpecProof: a standalone Next.js app that renders an audit view of any repo's API test coverage: every OpenAPI operation and response status, cross-examined against the target repo's test assertions. Clicking a stamped verdict shows the actual test snippet that proves (or fails to prove) coverage.
 
-This repo does not contain an API or its tests — it audits a target repo from the outside, the way OpenAPI tooling works when installed into a repo. Nothing repo-specific is baked in.
+This repo does not contain a real API or its tests — it audits a target repo from the outside, the way OpenAPI tooling works when installed into a repo. Nothing repo-specific is baked in. It does carry a hand-written demo target in `example/` (see "Example fixture" below), which is what gets audited when no `SPECPROOF_REPO` is set.
 
 ## Architecture: generate → checked-in artifact → contract-test
 
@@ -16,7 +16,15 @@ This repo does not contain an API or its tests — it audits a target repo from
 2. **Analyzer** (`lib/api-test-coverage.ts`): joins the two sources into a `CoverageReport` (tags → operations → statuses, each status with assertion counts and extracted `it()` snippets). Operations are joined on the describe title's method + path; `{param}`, `[param]`, and `:param` segments are treated as equivalent. When several test files describe the same operation, the one with the most `it()` blocks wins.
 3. **Generator** (`scripts/generate-proof.ts`): calls the analyzer, writes the result to `app/proof.generated.json`. This is checked in, deterministic, and regenerated automatically before `dev`/`build`. When no target spec is found it leaves the existing artifact untouched (exit 0), so the app always builds.
 4. **Consumer** (`app/page.tsx` → `components/CoverageProof.tsx`): renders the checked-in artifact only. No target checkout is needed to build or deploy the app itself. An empty proof renders an empty-state hint.
-5. **Drift guard** (`app/proof-contract.test.ts`): fails when the artifact is stale relative to the spec/tests, when the proof's audited operations don't exactly match the spec's operations, or when a quoted snippet no longer points at a real `it()`/`test()` line. This suite self-skips (via `describe.skipIf`) when no target spec is resolvable.
+5. **Drift guard** (`app/proof-contract.test.ts`): fails when the artifact is stale relative to the spec/tests, when the proof's audited operations don't exactly match the spec's operations, or when a quoted snippet no longer points at a real `it()`/`test()` line. This suite self-skips (via `describe.skipIf`) when no target spec is resolvable — in this repo one always is (the example fixture), so `bun run test:unit` always exercises the full analyzer here.
+
+## Example fixture (`example/`)
+
+`example/` is a hand-written demo target: `example/api/openapi.json` (the fictional "TaskFlow" API, 7 operations) plus `example/tests/*.test.ts` written in exactly the `describe("METHOD /path")` / `.status).toBe(NNN)` shape the parser expects. Because spec auto-discovery finds the shallowest `openapi*.json` under the target root (cwd by default), running `dev` / `generate:proof` / `test:unit` from this repo audits the example automatically — no `SPECPROOF_REPO` needed. When the package is installed into another repo, the example sits under `node_modules/`, which the scanner excludes, so it never pollutes a real audit.
+
+- The example files are **fixture data parsed as text**, never executed or compiled: they are excluded from vitest (`vitest.config.ts`), tsc (`tsconfig.json`), and eslint (`eslint.config.mjs`). They only need to look like a prettier-formatted test suite.
+- The spec and tests are **deliberately out of step** so the demo shows every verdict state: fully proven operations (`POST /auth/login`, `GET /tasks`, `GET /tasks/{taskId}`), partial coverage (`POST /tasks`, `PATCH /tasks/{taskId}`), untested operations (`DELETE /tasks/{taskId}`, `GET /projects`), and one status the tests assert but the spec omits (422 on `POST /tasks`). Preserve that mix when editing.
+- Editing anything in `example/` makes the checked-in proof stale and fails the contract tests: run `bun run generate:proof` and commit the regenerated `app/proof.generated.json`.
 
 Because of this split, most day-to-day work happens in exactly one of two places:
 - Changing what's audited/how coverage is computed → `lib/api-test-coverage.ts` (+ regenerate the proof).
@@ -32,16 +40,16 @@ bun run dev              # generate:proof + next dev (port 3001)
 bun run build            # generate:proof + next build
 bun run start            # serve the production build (port 3001)
 bun run generate:proof   # regenerate app/proof.generated.json only
-bun run test:unit        # contract tests (vitest run; self-skips without a configured target)
+bun run test:unit        # contract tests (vitest run; audits example/ unless SPECPROOF_REPO is set)
 bun run test:unit:watch  # vitest watch mode
 bun run lint             # eslint + tsc --noEmit
 bun run lint:es          # eslint only
 bun run lint:ts          # tsc --noEmit only
 ```
 
-To run a single test file: `bunx vitest run app/proof-contract.test.ts` (there is currently only the one test file).
+To run a single test file: `bunx vitest run app/proof-contract.test.ts` (contract tests) or `bunx vitest run lib/api-test-coverage.test.ts` (analyzer unit tests). The unit tests' inline fixtures deliberately use operations that don't exist in the example spec (`/widgets`, `/gadgets`) — the analyzer parses this repo's own `*.test.ts` files as raw text when auditing `example/`, and colliding paths would pollute the generated proof.
 
-The generator/contract tests need a target repo:
+To audit a real repo instead of the bundled example:
 
 ```bash
 SPECPROOF_REPO=/path/to/target-repo bun run generate:proof
@@ -58,9 +66,11 @@ SPECPROOF_REPO=/path/to/target-repo bun run generate:proof
 git add app/proof.generated.json && git commit
 ```
 
-## Releasing
+## CI & Releasing
+
+`main` is protected by a repo ruleset (PR required, merge queue, no direct pushes). The flow: open a PR → the CI workflow (`.github/workflows/test-unit.yml`, jobs `Build` / `Lint` / `Test`) runs on the PR and again in the merge queue → all three checks must pass → clicking merge queues the PR and GitHub merges it (squash).
 
-Merges to `main` trigger `.github/workflows/release.yml`, which publishes to npm when `package.json`'s version isn't already on the registry (needs the `NPM_TOKEN` repo secret). To release: bump `version` in `package.json` and merge.
+Every merge to `main` then triggers `.github/workflows/release.yml`, which publishes to npm when `package.json`'s version isn't already on the registry (needs the `NPM_TOKEN` repo secret). To release: bump `version` in `package.json`, open a PR, and merge. There is no manual release trigger.
 
 ## Notes on the parsing approach
 

package/README.md

@@ -1,3 +1,5 @@
+<img src="public/banner.png" alt="SpecProof" />
+
 # SpecProof
 
 A standalone Next.js app that renders an audit view of any repo's API test coverage: every OpenAPI operation and response status, cross-examined against the repo's test assertions. Click a stamped verdict to read the test itself.

package/app/proof.generated.json

@@ -1,7 +1,288 @@
 {
-  "tags": [],
-  "operationCount": 0,
-  "coveredCount": 0,
-  "totalCount": 0,
-  "untestedOperations": 0
+  "tags": [
+    {
+      "tag": "Auth",
+      "description": "Session and token management",
+      "operations": [
+        {
+          "method": "post",
+          "specPath": "/auth/login",
+          "summary": "Exchange credentials for a session token",
+          "testFile": "example/tests/auth.test.ts",
+          "testCount": 2,
+          "statuses": [
+            {
+              "code": "200",
+              "description": "Session token issued",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "returns a session token for valid credentials",
+                  "source": "it(\"returns a session token for valid credentials\", async () => {\n  const res = await api.post(\"/auth/login\", {\n    email: \"ada@example.com\",\n    password: \"correct horse battery staple\",\n  });\n\n  expect(res.status).toBe(200);\n  expect(res.body.token).toMatch(/^tk_/);\n});",
+                  "startLine": 6
+                }
+              ]
+            },
+            {
+              "code": "401",
+              "description": "Invalid credentials",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "rejects invalid credentials",
+                  "source": "it(\"rejects invalid credentials\", async () => {\n  const res = await api.post(\"/auth/login\", {\n    email: \"ada@example.com\",\n    password: \"not-the-password\",\n  });\n\n  expect(res.status).toBe(401);\n  expect(res.body.token).toBeUndefined();\n});",
+                  "startLine": 16
+                }
+              ]
+            }
+          ],
+          "coveredCount": 2,
+          "gapCount": 0
+        }
+      ],
+      "coveredCount": 2,
+      "totalCount": 2
+    },
+    {
+      "tag": "Tasks",
+      "description": "Create and manage tasks",
+      "operations": [
+        {
+          "method": "get",
+          "specPath": "/tasks",
+          "summary": "List tasks for the authenticated user",
+          "testFile": "example/tests/tasks.test.ts",
+          "testCount": 2,
+          "statuses": [
+            {
+              "code": "200",
+              "description": "Task list",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "lists tasks for the authenticated user",
+                  "source": "it(\"lists tasks for the authenticated user\", async () => {\n  const res = await api.get(\"/tasks\");\n\n  expect(res.status).toBe(200);\n  expect(Array.isArray(res.body.tasks)).toBe(true);\n});",
+                  "startLine": 14
+                }
+              ]
+            },
+            {
+              "code": "401",
+              "description": "Missing or invalid bearer token",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "rejects requests without a bearer token",
+                  "source": "it(\"rejects requests without a bearer token\", async () => {\n  const res = await api.get(\"/tasks\", { auth: false });\n\n  expect(res.status).toBe(401);\n});",
+                  "startLine": 21
+                }
+              ]
+            }
+          ],
+          "coveredCount": 2,
+          "gapCount": 0
+        },
+        {
+          "method": "post",
+          "specPath": "/tasks",
+          "summary": "Create a task",
+          "testFile": "example/tests/tasks.test.ts",
+          "testCount": 3,
+          "statuses": [
+            {
+              "code": "201",
+              "description": "Task created",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "creates a task and returns it",
+                  "source": "it(\"creates a task and returns it\", async () => {\n  const res = await api.post(\"/tasks\", {\n    title: \"Ship the Q3 roadmap\",\n    projectId: \"proj_1\",\n  });\n\n  expect(res.status).toBe(201);\n  expect(res.body.id).toBeDefined();\n  expect(res.body.title).toBe(\"Ship the Q3 roadmap\");\n});",
+                  "startLine": 29
+                }
+              ]
+            },
+            {
+              "code": "400",
+              "description": "Malformed request body",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "rejects a task without a title",
+                  "source": "it(\"rejects a task without a title\", async () => {\n  const res = await api.post(\"/tasks\", { projectId: \"proj_1\" });\n\n  expect(res.status).toBe(400);\n  expect(res.body.error).toBe(\"title is required\");\n});",
+                  "startLine": 40
+                }
+              ]
+            },
+            {
+              "code": "401",
+              "description": "Missing or invalid bearer token",
+              "documented": true,
+              "assertions": 0,
+              "snippets": []
+            },
+            {
+              "code": "422",
+              "description": "",
+              "documented": false,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "rejects a due date in the past",
+                  "source": "it(\"rejects a due date in the past\", async () => {\n  const res = await api.post(\"/tasks\", {\n    title: \"Time travel\",\n    dueDate: \"1999-12-31\",\n  });\n\n  expect(res.status).toBe(422);\n});",
+                  "startLine": 47
+                }
+              ]
+            }
+          ],
+          "coveredCount": 2,
+          "gapCount": 1
+        },
+        {
+          "method": "get",
+          "specPath": "/tasks/{taskId}",
+          "summary": "Fetch a single task",
+          "testFile": "example/tests/tasks.test.ts",
+          "testCount": 2,
+          "statuses": [
+            {
+              "code": "200",
+              "description": "The task",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "returns a task by id",
+                  "source": "it(\"returns a task by id\", async () => {\n  const created = await api.post(\"/tasks\", { title: \"Write release notes\" });\n  const res = await api.get(`/tasks/${created.body.id}`);\n\n  expect(res.status).toBe(200);\n  expect(res.body.id).toBe(created.body.id);\n});",
+                  "startLine": 58
+                }
+              ]
+            },
+            {
+              "code": "404",
+              "description": "No task with this id",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "returns 404 for an unknown task id",
+                  "source": "it(\"returns 404 for an unknown task id\", async () => {\n  const res = await api.get(\"/tasks/task_does_not_exist\");\n\n  expect(res.status).toBe(404);\n});",
+                  "startLine": 66
+                }
+              ]
+            }
+          ],
+          "coveredCount": 2,
+          "gapCount": 0
+        },
+        {
+          "method": "patch",
+          "specPath": "/tasks/{taskId}",
+          "summary": "Update a task's fields",
+          "testFile": "example/tests/tasks.test.ts",
+          "testCount": 1,
+          "statuses": [
+            {
+              "code": "200",
+              "description": "Updated task",
+              "documented": true,
+              "assertions": 1,
+              "snippets": [
+                {
+                  "title": "updates the fields of a task",
+                  "source": "it(\"updates the fields of a task\", async () => {\n  const created = await api.post(\"/tasks\", { title: \"Refine the backlog\" });\n  const res = await api.patch(`/tasks/${created.body.id}`, {\n    title: \"Refine and prioritize the backlog\",\n  });\n\n  expect(res.status).toBe(200);\n  expect(res.body.title).toBe(\"Refine and prioritize the backlog\");\n});",
+                  "startLine": 74
+                }
+              ]
+            },
+            {
+              "code": "404",
+              "description": "No task with this id",
+              "documented": true,
+              "assertions": 0,
+              "snippets": []
+            },
+            {
+              "code": "409",
+              "description": "Task was modified concurrently",
+              "documented": true,
+              "assertions": 0,
+              "snippets": []
+            }
+          ],
+          "coveredCount": 1,
+          "gapCount": 2
+        },
+        {
+          "method": "delete",
+          "specPath": "/tasks/{taskId}",
+          "summary": "Delete a task",
+          "testFile": null,
+          "testCount": 0,
+          "statuses": [
+            {
+              "code": "204",
+              "description": "Task deleted",
+              "documented": true,
+              "assertions": 0,
+              "snippets": []
+            },
+            {
+              "code": "404",
+              "description": "No task with this id",
+              "documented": true,
+              "assertions": 0,
+              "snippets": []
+            }
+          ],
+          "coveredCount": 0,
+          "gapCount": 2
+        }
+      ],
+      "coveredCount": 7,
+      "totalCount": 12
+    },
+    {
+      "tag": "Projects",
+      "description": "Group tasks into projects",
+      "operations": [
+        {
+          "method": "get",
+          "specPath": "/projects",
+          "summary": "List projects",
+          "testFile": null,
+          "testCount": 0,
+          "statuses": [
+            {
+              "code": "200",
+              "description": "Project list",
+              "documented": true,
+              "assertions": 0,
+              "snippets": []
+            },
+            {
+              "code": "401",
+              "description": "Missing or invalid bearer token",
+              "documented": true,
+              "assertions": 0,
+              "snippets": []
+            }
+          ],
+          "coveredCount": 0,
+          "gapCount": 2
+        }
+      ],
+      "coveredCount": 0,
+      "totalCount": 2
+    }
+  ],
+  "operationCount": 7,
+  "coveredCount": 9,
+  "totalCount": 16,
+  "untestedOperations": 2
 }

package/components/CoverageProof.tsx

@@ -315,7 +315,7 @@ export function CoverageProof({
         {/* masthead */}
         <header className="sp-rise" style={{ '--sp-stagger': 0 } as React.CSSProperties}>
           <div className="flex flex-wrap items-end justify-between gap-6">
-            <h1 className="text-2xl font-semibold tracking-tight">SpecProof</h1>
+            <h1 className="text-5xl font-semibold tracking-tight">SpecProof</h1>
             <div className="text-right">
               <div className="text-5xl font-semibold tabular-nums leading-none">
                 {Math.round((report.coveredCount / Math.max(report.totalCount, 1)) * 100)}

package/eslint.config.mjs

@@ -6,7 +6,7 @@ import pluginReactHooks from "eslint-plugin-react-hooks";
 
 export default [
   {
-    ignores: ["**/.next/**", "**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**"],
+    ignores: ["**/.next/**", "**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**", "example/**"],
   },
   {
     files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],

package/example/api/openapi.json

@@ -0,0 +1,88 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "TaskFlow API",
+    "version": "1.0.0",
+    "description": "Example API used to demo SpecProof and validate its analyzer. The spec and the tests in example/tests are deliberately out of step in places, so the audit shows every verdict state: proven coverage, gaps, untested operations, and an undocumented status."
+  },
+  "tags": [
+    { "name": "Auth", "description": "Session and token management" },
+    { "name": "Tasks", "description": "Create and manage tasks" },
+    { "name": "Projects", "description": "Group tasks into projects" }
+  ],
+  "paths": {
+    "/auth/login": {
+      "post": {
+        "operationId": "login",
+        "summary": "Exchange credentials for a session token",
+        "tags": ["Auth"],
+        "responses": {
+          "200": { "description": "Session token issued" },
+          "401": { "description": "Invalid credentials" }
+        }
+      }
+    },
+    "/tasks": {
+      "get": {
+        "operationId": "listTasks",
+        "summary": "List tasks for the authenticated user",
+        "tags": ["Tasks"],
+        "responses": {
+          "200": { "description": "Task list" },
+          "401": { "description": "Missing or invalid bearer token" }
+        }
+      },
+      "post": {
+        "operationId": "createTask",
+        "summary": "Create a task",
+        "tags": ["Tasks"],
+        "responses": {
+          "201": { "description": "Task created" },
+          "400": { "description": "Malformed request body" },
+          "401": { "description": "Missing or invalid bearer token" }
+        }
+      }
+    },
+    "/tasks/{taskId}": {
+      "get": {
+        "operationId": "getTask",
+        "summary": "Fetch a single task",
+        "tags": ["Tasks"],
+        "responses": {
+          "200": { "description": "The task" },
+          "404": { "description": "No task with this id" }
+        }
+      },
+      "patch": {
+        "operationId": "updateTask",
+        "summary": "Update a task's fields",
+        "tags": ["Tasks"],
+        "responses": {
+          "200": { "description": "Updated task" },
+          "404": { "description": "No task with this id" },
+          "409": { "description": "Task was modified concurrently" }
+        }
+      },
+      "delete": {
+        "operationId": "deleteTask",
+        "summary": "Delete a task",
+        "tags": ["Tasks"],
+        "responses": {
+          "204": { "description": "Task deleted" },
+          "404": { "description": "No task with this id" }
+        }
+      }
+    },
+    "/projects": {
+      "get": {
+        "operationId": "listProjects",
+        "summary": "List projects",
+        "tags": ["Projects"],
+        "responses": {
+          "200": { "description": "Project list" },
+          "401": { "description": "Missing or invalid bearer token" }
+        }
+      }
+    }
+  }
+}

package/example/tests/auth.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+
+import { api } from "./client";
+
+describe("POST /auth/login", () => {
+  it("returns a session token for valid credentials", async () => {
+    const res = await api.post("/auth/login", {
+      email: "ada@example.com",
+      password: "correct horse battery staple",
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.body.token).toMatch(/^tk_/);
+  });
+
+  it("rejects invalid credentials", async () => {
+    const res = await api.post("/auth/login", {
+      email: "ada@example.com",
+      password: "not-the-password",
+    });
+
+    expect(res.status).toBe(401);
+    expect(res.body.token).toBeUndefined();
+  });
+});

package/example/tests/client.ts

@@ -0,0 +1,53 @@
+// Minimal HTTP client the example tests are written against.
+//
+// The example suite is fixture data for SpecProof's analyzer — it is excluded
+// from this repo's typecheck, lint, and vitest runs and never executes here.
+// It exists so the tests read like a real integration suite.
+
+const BASE_URL = process.env.API_URL ?? "http://localhost:4010";
+
+export interface ApiResponse {
+  status: number;
+  body: Record<string, unknown> & { id?: string; token?: string };
+}
+
+interface RequestOptions {
+  /** Set to false to send the request without a bearer token */
+  auth?: boolean;
+}
+
+let sessionToken: string | null = null;
+
+export function authenticate(token: string | null) {
+  sessionToken = token;
+}
+
+async function request(
+  method: string,
+  path: string,
+  payload?: unknown,
+  options: RequestOptions = {},
+): Promise<ApiResponse> {
+  const withAuth = options.auth !== false && sessionToken !== null;
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      ...(withAuth ? { authorization: `Bearer ${sessionToken}` } : {}),
+    },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  return { status: res.status, body: text ? JSON.parse(text) : {} };
+}
+
+export const api = {
+  get: (path: string, options?: RequestOptions) =>
+    request("GET", path, undefined, options),
+  post: (path: string, payload?: unknown, options?: RequestOptions) =>
+    request("POST", path, payload, options),
+  patch: (path: string, payload?: unknown, options?: RequestOptions) =>
+    request("PATCH", path, payload, options),
+  delete: (path: string, options?: RequestOptions) =>
+    request("DELETE", path, undefined, options),
+};