feat(api): public REST API with API-key auth and OpenAPI docs

.husky/pre-push

@@ -0,0 +1,10 @@
+# Keep the committed OpenAPI spec in sync with the API router: regenerate it
+# and abort the push when the regenerated file would change, so the spec can
+# never go stale. Compare against both the working tree and the index so the
+# check passes only after the file is actually committed.
+pnpm gen:openapi
+if [ -n "$(git status --porcelain -- src/server/api/openapi.generated.json)" ]; then
+  echo "✖ src/server/api/openapi.generated.json is out of date."
+  echo "  Run: pnpm gen:openapi && git add src/server/api/openapi.generated.json && git commit"
+  exit 1
+fi

docs/api.md

@@ -0,0 +1,94 @@
+# SplitPro Public REST API
+
+SplitPro exposes a small, versioned REST API for integrations (e.g. syncing
+expenses to a budgeting tool). The API is served at `/api/v1` and documented
+interactively at **`/api/docs`** (Scalar), backed by the machine-readable
+OpenAPI 3.1 spec at **`/api/openapi.json`**.
+
+## Authentication
+
+1. In the app, open **Account → API keys** and create a key. Optionally set an
+   expiry date. The plaintext key (`spro_…`) is shown exactly once; only a
+   SHA-256 hash is stored server-side.
+2. Send the key with every request:
+
+   ```
+   Authorization: Bearer spro_…
+   ```
+
+   The `X-API-Key: spro_…` header is also accepted. Requests without a valid,
+   unexpired key receive `401`.
+
+API keys act with your user's permissions: every endpoint only returns data
+you are part of, and writes run the same permission checks as the app.
+
+## Endpoints
+
+| Endpoint                        | Method | Description                                     |
+| ------------------------------- | ------ | ----------------------------------------------- |
+| `user.me`                       | GET    | Authenticated user profile                      |
+| `user.getFriends`               | GET    | Friends with balances                           |
+| `user.getOwnExpenses`           | GET    | Expenses paid by you **(paginated)**            |
+| `user.getBalancesWithFriend`    | GET    | Per-group balances with a friend                |
+| `user.getFriend`                | GET    | Friend profile + default split                  |
+| `group.getAllGroups`            | GET    | All groups you belong to                        |
+| `group.getGroupDetails`         | GET    | Single group with members and balances          |
+| `expense.getBalances`           | GET    | Per-friend balances across all groups           |
+| `expense.getAllExpenses`        | GET    | All expenses you participate in **(paginated)** |
+| `expense.getExpensesWithFriend` | GET    | Expense history with a friend **(paginated)**   |
+| `expense.getGroupExpenses`      | GET    | All expenses in a group **(paginated)**         |
+| `expense.getExpenseDetails`     | GET    | Full expense detail                             |
+| `expense.addOrEditExpense`      | POST   | Create or update expenses (array body)          |
+
+All requests go to `https://<your-host>/api/v1/<endpoint>`, e.g.
+`GET /api/v1/user.me`.
+
+### Input formats
+
+GET endpoints accept individual query params (`?groupId=150&limit=20`), a
+plain JSON object (`?input={"groupId":150}`), or a native superjson envelope.
+POST bodies are plain JSON; a superjson envelope also works when calling from
+a tRPC client.
+
+Because JSON has no BigInt or Date type, monetary amounts accept numbers or
+numeric strings (strings keep full precision beyond `Number.MAX_SAFE_INTEGER`)
+and are returned as numbers; timestamps are ISO 8601 strings.
+
+### Pagination
+
+List endpoints use offset pagination:
+
+- Input: `?limit=20&offset=0` (defaults `limit=20`, `offset=0`, max `limit=100`)
+- Response: `{ items: […], pagination: { total, limit, offset, hasMore } }`
+
+### Example
+
+```bash
+curl -H "Authorization: Bearer spro_…" \
+  'https://splitpro.example.com/api/v1/expense.getGroupExpenses?groupId=16&limit=10'
+```
+
+```bash
+curl -X POST -H "Authorization: Bearer spro_…" -H "Content-Type: application/json" \
+  -d '[{"name":"Lunch","currency":"EUR","groupId":null,"amount":4200,"paidBy":1,
+        "category":"general","splitType":"EQUAL",
+        "participants":[{"userId":1,"amount":2100},{"userId":2,"amount":-2100}],
+        "expenseDate":"2026-10-25T12:00:00Z"}]' \
+  'https://splitpro.example.com/api/v1/expense.addOrEditExpense'
+```
+
+Note the participant amounts follow the app's stored sign convention: the
+payer's entry is `amount − their share` (positive), every other participant's
+entry is their negated share. The example above is a `4200` expense split
+equally between user 1 (payer) and user 2, so each share is `2100`.
+
+## Maintenance (for developers)
+
+- The API router is `src/server/api/apiRouter.ts` — a curated subset of the
+  app procedures, shared via the exported method records in the router files.
+- Regenerate the OpenAPI spec after changing any procedure with
+  `pnpm gen:openapi`. The pre-push hook fails if the committed
+  `src/server/api/openapi.generated.json` is out of date, and `pnpm build`
+  regenerates it.
+- `/api/docs` loads the Scalar bundle pinned to an exact version with a
+  subresource-integrity hash (see `src/pages/api/docs.ts` for upgrade steps).

package.json

@@ -4,8 +4,9 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "next build",
+    "build": "pnpm gen:openapi && next build",
     "just-build": "next build",
+    "gen:openapi": "cross-env SKIP_ENV_VALIDATION=true tsx scripts/generate-openapi.ts",
     "db:push": "prisma db push && prisma generate",
     "db:studio": "prisma studio",
     "db:dev": "prisma migrate dev && prisma generate",
@@ -46,6 +47,7 @@
     "@tanstack/react-query": "^5.79.2",
     "@trpc/client": "^11.2.0",
     "@trpc/next": "^11.2.0",
+    "@trpc/openapi": "11.18.0-alpha",
     "@trpc/react-query": "^11.2.0",
     "@trpc/server": "^11.2.0",
     "boring-avatars": "^1.10.1",
@@ -102,6 +104,7 @@
     "@types/react-dom": "19.3.0",
     "@types/web-push": "^3.6.3",
     "babel-plugin-react-compiler": "^1.0.0",
+    "cross-env": "^10.1.0",
     "esbuild": "^0.25.12",
     "husky": "^9.1.7",
     "jest": "30.5.2",

prisma/migrations/20260715120000_add_api_key/migration.sql

@@ -0,0 +1,22 @@
+-- CreateTable
+CREATE TABLE "ApiKey" (
+    "id" TEXT NOT NULL,
+    "userId" INTEGER NOT NULL,
+    "name" TEXT NOT NULL,
+    "hashedKey" TEXT NOT NULL,
+    "partialKey" TEXT NOT NULL,
+    "lastUsedAt" TIMESTAMP(3),
+    "expiresAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ApiKey_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ApiKey_hashedKey_key" ON "ApiKey"("hashedKey");
+
+-- CreateIndex
+CREATE INDEX "ApiKey_userId_idx" ON "ApiKey"("userId");
+
+-- AddForeignKey
+ALTER TABLE "ApiKey" ADD CONSTRAINT "ApiKey_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/schema.prisma

@@ -63,11 +63,27 @@ model User {
   friendDefaultSplitsA FriendDefaultSplit[] @relation("FriendDefaultSplitUserA")
   friendDefaultSplitsB FriendDefaultSplit[] @relation("FriendDefaultSplitUserB")
   sessions             Session[]
+  apiKeys              ApiKey[]
   hiddenFriendIds      Int[]                @default([])
 
   @@schema("public")
 }
 
+model ApiKey {
+  id         String    @id @default(cuid())
+  userId     Int
+  name       String
+  hashedKey  String    @unique
+  partialKey String
+  lastUsedAt DateTime?
+  expiresAt  DateTime?
+  createdAt  DateTime  @default(now())
+  user       User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+  @@schema("public")
+}
+
 model VerificationToken {
   identifier String
   token      String   @unique

public/locales/en/common.json

@@ -30,6 +30,27 @@
       "title": "Edit details"
     },
     "follow_on_x": "Follow us on X",
+    "api_keys": {
+      "title": "API keys",
+      "description": "Use API keys to access the SplitPro API. Send the key as",
+      "docs_prefix": "Documentation is at",
+      "copy_now_notice": "Copy your key now — it won't be shown again.",
+      "name_label": "New key name",
+      "name_placeholder": "e.g. Actual Budget",
+      "expires_label": "Expires (optional)",
+      "create": "Create",
+      "last_used": "used {date}",
+      "never_used": "never used",
+      "expires_on": "expires {date}",
+      "empty": "No API keys yet.",
+      "messages": {
+        "name_required": "Please enter a name for the key",
+        "create_failed": "Failed to create API key",
+        "revoke_failed": "Failed to revoke API key",
+        "copied": "Copied to clipboard",
+        "copy_failed": "Failed to copy"
+      }
+    },
     "import_from_splitwise": "Import from Splitwise",
     "import_from_splitwise_details": {
       "choose_file": "Choose file",