Built: SQLite (node:sqlite) via server/db.js with checksummed migrations, injectable clock, persistent event scheduler with catch-up, tiny REST router (error envelope, idempotency keys, rate limits, bearer tokens with scrypt passwords), lazy-resource economy in public/js/rules.js + data.js, build/cancel/rename commands, seeded map + spawn ring, generated docs/openapi.json. NETWALL net.js/static.js reused. Tested: manual smoke run only (signup, town view, build, map). No unit tests or e2e yet. NOT done: military, expansion, social, client, push, deploy docs, bots/admin. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
1.9 KiB
1.9 KiB
API
REST JSON under /api/v1/. The machine-readable contract is docs/openapi.json, generated from the route table
(npm run openapi); this file covers conventions and per-resource notes.
Conventions
- Auth:
Authorization: Bearer <token>(opaque, one per device;POST /auth/loginor/auth/signupissues one,POST /auth/logoutandDELETE /auth/tokens/:idrevoke). No cookies. - Every response is an object with
serverTime(integer ms since epoch, server clock). Clients compute countdowns from the offset. - Errors:
{ serverTime, error: { code, message, details } }. Clients switch oncode. All codes:x-error-codesin openapi.json. - Mutating POSTs accept
Idempotency-Key(8-64 charsA-Za-z0-9_.:-); a replay returns the stored response withIdempotent-Replay: true; the same key with a different request isidempotency_key_reuse. - Lists are cursor-paginated:
?after=<id>&limit=<n>, responsenextis the cursor ornull. - Rate limits: per IP, per token, stricter on login/signup.
429 rate_limitedwithRetry-After. - The client never sends computed amounts, only intents. The server recomputes everything with
public/js/rules.js.
Resources (stage 0-2)
| Route | Purpose |
|---|---|
POST /auth/signup, POST /auth/login |
account + token (signup also founds the capital POP) |
GET /me |
user, operators (per world), POPs |
GET /towns/:id |
full POP state: resources {amount, rate, cap} at serverTime, power, buildings with the server's build plan, queue |
POST /towns/:id/build {key} |
build/upgrade one level of a field (f1..f18) or an infrastructure building |
DELETE /towns/:id/queue/:eventId |
cancel a running build, 80% refund |
GET /map?x&y&r |
rural areas, incumbent sites, POPs in the viewport |
GET /notifications?after&limit |
durable notification feed (build done, ...) |
Later stages append their routes here and to the route table.