sparta_worlds 0.6.0

package/server/dist/admin/routes.js

@@ -0,0 +1,469 @@
+import { z } from "zod";
+import { WorldNotFoundError, WorldRefusedError } from "../core/manager.js";
+import { summarizeMoney } from "../core/money.js";
+import { PROTOCOL_VERSION } from "../core/protocol.js";
+import { parseSeed, SeedValidationError, seedHash } from "../core/seed.js";
+import { exportSeed } from "../core/seedExport.js";
+import { parseDuration } from "../core/time.js";
+import { RESOURCE_NAMES } from "../core/world.js";
+import { parseScenario } from "../scenario/engine.js";
+import { processRenewals, RenewalFailed } from "../twin/resources/subscriptions.js";
+import { ApplyScenarioBody, ClockAdvanceBody, CreateWorldBody, MarkBody, SeedValidateBody, WebhookEndpointBody, } from "./schemas.js";
+function badRequest(reply, message, details) {
+    void reply.status(400).send({ error: { message, ...(details !== undefined ? { details } : {}) } });
+}
+const STRIPE_NAMESPACES = new Set([
+    "apple_pay",
+    "apps",
+    "billing",
+    "billing_portal",
+    "checkout",
+    "climate",
+    "entitlements",
+    "financial_connections",
+    "forwarding",
+    "identity",
+    "issuing",
+    "radar",
+    "reporting",
+    "sigma",
+    "tax",
+    "terminal",
+    "test_helpers",
+    "treasury",
+]);
+export function coverageRoute(method, path) {
+    const segments = path.split("/").filter(Boolean);
+    let resource = segments[0] === "v2" ? 2 : 1;
+    while (resource < segments.length - 1 && STRIPE_NAMESPACES.has(segments[resource]))
+        resource++;
+    const collapsed = segments.map((segment, i) => {
+        const idPosition = i > resource && (i - resource) % 2 === 1;
+        const loose = /[_0-9A-Z]/.test(segment);
+        const strict = segment.includes("_") && /[0-9A-Z]/.test(segment);
+        return (idPosition && loose) || strict ? "{id}" : segment;
+    });
+    return `${method} /${collapsed.join("/")}`;
+}
+function notFound(reply, message) {
+    void reply.status(404).send({ error: { message } });
+}
+function conflict(reply, message) {
+    void reply.status(409).send({ error: { message } });
+}
+export function registerAdminApi(app, deps) {
+    const { manager, dispatcher, scenarios } = deps;
+    const getWorld = (id, reply) => {
+        try {
+            return manager.get(id);
+        }
+        catch (err) {
+            if (err instanceof WorldNotFoundError) {
+                notFound(reply, err.message);
+                return undefined;
+            }
+            if (err instanceof WorldRefusedError) {
+                conflict(reply, err.message);
+                return undefined;
+            }
+            throw err;
+        }
+    };
+    app.get("/admin/health", async () => ({
+        ok: true,
+        worlds: manager.count(),
+        auth: deps.auth().mode,
+        protocol: PROTOCOL_VERSION,
+        resources: RESOURCE_NAMES,
+    }));
+    app.get("/admin/seeds", async () => ({
+        seeds: manager.seedLibrary.list().map((s) => ({
+            name: s.name,
+            version: s.seed.version,
+            seed_hash: s.hash,
+            epoch: s.seed.epoch,
+            clock_mode: s.seed.clock_mode,
+            counts: {
+                customers: s.seed.data.customers.length,
+                products: s.seed.data.products.length,
+                prices: s.seed.data.prices.length,
+                invoices: s.seed.data.invoices.length,
+                subscriptions: s.seed.data.subscriptions.length,
+                tickets: s.seed.data.tickets.length,
+            },
+        })),
+    }));
+    app.get("/admin/seeds/:name", async (req, reply) => {
+        const { name } = req.params;
+        const found = manager.seedLibrary.get(name);
+        if (!found)
+            return notFound(reply, `No such seed: ${name}`);
+        return { name, seed_hash: found.hash, seed_doc: found.seed };
+    });
+    app.post("/admin/seeds/validate", async (req, reply) => {
+        const body = SeedValidateBody.safeParse(req.body ?? {});
+        if (!body.success)
+            return badRequest(reply, "invalid body", body.error.issues);
+        try {
+            const seed = parseSeed(body.data.seed_doc);
+            return { valid: true, name: seed.name, seed_hash: seedHash(seed) };
+        }
+        catch (err) {
+            if (err instanceof SeedValidationError) {
+                return { valid: false, issues: err.issues };
+            }
+            throw err;
+        }
+    });
+    app.get("/admin/scenarios", async () => ({
+        scenarios: scenarios
+            .list()
+            .map((s) => ({ name: s.name, description: s.scenario.description ?? null, rules: s.scenario.rules.length })),
+    }));
+    app.post("/admin/worlds", async (req, reply) => {
+        const body = CreateWorldBody.safeParse(req.body ?? {});
+        if (!body.success)
+            return badRequest(reply, "invalid body", body.error.issues);
+        try {
+            const { world, apiKey, adminToken } = manager.createWorld(body.data);
+            void reply.status(201);
+            return {
+                world_id: world.id,
+                base_url: deps.publicUrl(req),
+                api_key: apiKey,
+                admin_token: adminToken,
+                seed_name: world.seedName,
+                seed_hash: world.seedHash,
+                clock: world.clock,
+                clock_mode: world.clockMode,
+            };
+        }
+        catch (err) {
+            if (err instanceof SeedValidationError)
+                return badRequest(reply, err.message, err.issues);
+            return badRequest(reply, err instanceof Error ? err.message : String(err));
+        }
+    });
+    app.get("/admin/worlds", async () => manager.scan());
+    app.get("/admin/worlds/:id", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        return {
+            ...manager.info(world.id),
+            api_keys: world.listApiKeys(),
+            admin_tokens: world.countAdminTokens(),
+            webhook_endpoint: world.webhookConfig() ?? null,
+            scenario: world.getScenario() ?? null,
+            marks: world.listMarks(),
+        };
+    });
+    app.post("/admin/worlds/:id/reset", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        await manager.exclusive(world.id, () => manager.reset(world.id));
+        return manager.info(world.id);
+    });
+    app.delete("/admin/worlds/:id", async (req, reply) => {
+        if (!manager.has(req.params.id))
+            return notFound(reply, `No such world: '${req.params.id}'`);
+        try {
+            await manager.exclusive(req.params.id, () => manager.destroy(req.params.id));
+        }
+        catch (err) {
+            if (err instanceof WorldNotFoundError)
+                return notFound(reply, err.message);
+            throw err;
+        }
+        return { destroyed: true, world_id: req.params.id };
+    });
+    app.post("/admin/worlds/:id/keys", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        return { api_key: manager.mintKey(world.id) };
+    });
+    app.post("/admin/worlds/:id/admin-tokens", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const token = manager.mintAdminToken(world.id);
+        return { admin_token: token, active: world.countAdminTokens() };
+    });
+    app.delete("/admin/worlds/:id/admin-tokens/:token", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        if (!world.revokeAdminToken(req.params.token))
+            return notFound(reply, `No such admin token on world '${world.id}'`);
+        return { revoked: true, active: world.countAdminTokens() };
+    });
+    app.get("/admin/worlds/:id/state/:resource", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const resource = req.params.resource;
+        if (!RESOURCE_NAMES.includes(resource)) {
+            return badRequest(reply, `unknown resource '${resource}'. Known: ${RESOURCE_NAMES.join(", ")}`);
+        }
+        const query = { ...req.query };
+        const limit = query.limit ? Number(query.limit) : undefined;
+        delete query.limit;
+        let items = world.listObjects(resource).map((o) => o.data);
+        for (const [field, value] of Object.entries(query)) {
+            items = items.filter((obj) => {
+                const actual = obj[field];
+                if (typeof actual === "number")
+                    return actual === Number(value);
+                if (typeof actual === "boolean")
+                    return String(actual) === value;
+                return actual === value;
+            });
+        }
+        if (limit !== undefined)
+            items = items.slice(0, limit);
+        return { resource, count: items.length, data: items };
+    });
+    app.get("/admin/worlds/:id/events", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const { type, after_seq } = req.query;
+        let afterSeq;
+        if (after_seq !== undefined) {
+            if (!/^\d+$/.test(after_seq))
+                return badRequest(reply, "after_seq must be a non-negative integer (a mark's seq)");
+            afterSeq = Number(after_seq);
+        }
+        let events = world.listEvents({ afterSeq });
+        if (type)
+            events = events.filter((e) => e.type === type);
+        return { count: events.length, data: events.map((e) => e.data) };
+    });
+    app.get("/admin/worlds/:id/requests", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const { unmatched } = req.query;
+        const data = world.listRequests({ unmatchedOnly: unmatched === "true" });
+        if (unmatched === "true") {
+            const byRoute = new Map();
+            for (const r of data) {
+                const route = coverageRoute(r.method, r.path);
+                const key = r.unsupported ? `${route} — refused ${r.unsupported}` : route;
+                byRoute.set(key, (byRoute.get(key) ?? 0) + 1);
+            }
+            return {
+                count: data.length,
+                gaps: [...byRoute.entries()].map(([route, hits]) => ({ route, hits })).sort((a, b) => b.hits - a.hits),
+                data,
+            };
+        }
+        return { count: data.length, data };
+    });
+    app.post("/admin/worlds/:id/marks", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const body = MarkBody.safeParse(req.body ?? {});
+        if (!body.success)
+            return badRequest(reply, "invalid body", body.error.issues);
+        return world.setMark(body.data.name);
+    });
+    app.get("/admin/worlds/:id/marks", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        return { marks: world.listMarks() };
+    });
+    app.get("/admin/worlds/:id/diff", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const { from } = req.query;
+        if (!from)
+            return badRequest(reply, "query param 'from' (mark name) is required");
+        const mark = world.getMark(from);
+        if (!mark)
+            return notFound(reply, `No such mark: '${from}'`);
+        const groups = world.diff(mark.seq);
+        return { from: mark, ...groups, money: summarizeMoney(groups) };
+    });
+    app.get("/admin/worlds/:id/clock", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        return { clock: world.clock, clock_mode: world.clockMode, iso: new Date(world.clock * 1000).toISOString() };
+    });
+    app.post("/admin/worlds/:id/clock/advance", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const body = ClockAdvanceBody.safeParse(req.body ?? {});
+        if (!body.success)
+            return badRequest(reply, "invalid body", body.error.issues);
+        let seconds;
+        try {
+            seconds = parseDuration(body.data.duration);
+        }
+        catch (err) {
+            return badRequest(reply, err instanceof Error ? err.message : String(err));
+        }
+        let result;
+        try {
+            result = await manager.withLock(world.id, () => {
+                const from = world.clock;
+                const renewals = world.db.transaction(() => {
+                    world.advanceClock(seconds);
+                    return processRenewals(world);
+                });
+                return { from, to: world.clock, renewals };
+            });
+        }
+        catch (err) {
+            if (err instanceof RenewalFailed)
+                return conflict(reply, err.message);
+            throw err;
+        }
+        dispatcher.drainSoon(world);
+        return {
+            clock: result.to,
+            advanced_from: result.from,
+            advanced_by: seconds,
+            renewals_billed: result.renewals.billed,
+            renewals_pending: result.renewals.pending,
+            iso: new Date(result.to * 1000).toISOString(),
+        };
+    });
+    app.post("/admin/worlds/:id/scenario", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const body = ApplyScenarioBody.safeParse(req.body ?? {});
+        if (!body.success)
+            return badRequest(reply, "invalid scenario", body.error.issues);
+        let doc;
+        if (body.data.name !== undefined) {
+            const found = scenarios.get(body.data.name);
+            if (!found) {
+                const known = scenarios
+                    .list()
+                    .map((s) => s.name)
+                    .join(", ") || "(none)";
+                return notFound(reply, `No such scenario: '${body.data.name}'. Available: ${known}`);
+            }
+            doc = found;
+        }
+        else if (body.data.scenario_doc !== undefined) {
+            doc = body.data.scenario_doc;
+        }
+        else {
+            return badRequest(reply, "either 'name' or 'scenario_doc' is required");
+        }
+        let parsed;
+        try {
+            parsed = parseScenario(doc);
+        }
+        catch (err) {
+            if (err instanceof z.ZodError)
+                return badRequest(reply, "invalid scenario", err.issues);
+            throw err;
+        }
+        world.setScenario(parsed);
+        return { applied: parsed.name, rules: parsed.rules.length };
+    });
+    app.get("/admin/worlds/:id/scenario", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        return { scenario: world.getScenario() ?? null };
+    });
+    app.delete("/admin/worlds/:id/scenario", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        world.setScenario(null);
+        return { cleared: true };
+    });
+    app.post("/admin/worlds/:id/webhook-endpoint", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const body = WebhookEndpointBody.safeParse(req.body ?? {});
+        if (!body.success)
+            return badRequest(reply, "invalid body", body.error.issues);
+        const config = world.setWebhookConfig(body.data.url, body.data.max_retries, body.data.auto_deliver, body.data.signature_time);
+        return {
+            url: config.url,
+            signing_secret: config.secret,
+            max_retries: config.max_retries,
+            auto_deliver: config.auto_deliver === 1,
+            signature_time: config.signature_time,
+        };
+    });
+    app.delete("/admin/worlds/:id/webhook-endpoint", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        world.clearWebhookConfig();
+        return { cleared: true };
+    });
+    app.get("/admin/worlds/:id/webhook-deliveries", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        return { deliveries: world.listDeliveries() };
+    });
+    app.post("/admin/worlds/:id/webhooks/flush", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        let results;
+        try {
+            results = await dispatcher.flush(world);
+        }
+        catch (err) {
+            if (!manager.has(world.id))
+                return notFound(reply, `No such world: '${world.id}'`);
+            throw err;
+        }
+        if (!manager.has(world.id))
+            return notFound(reply, `No such world: '${world.id}'`);
+        const pending = world.listDeliveries().filter((d) => d.status === "pending").length;
+        return { results, remaining_pending: pending };
+    });
+    app.get("/admin/worlds/:id/export-seed", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        const { name } = req.query;
+        const seedName = name ?? `${world.seedName}-export`;
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(seedName)) {
+            return badRequest(reply, `invalid seed name '${seedName}' (kebab-case required: lowercase letters, digits, hyphens)`);
+        }
+        const result = exportSeed(world, seedName);
+        return {
+            name: seedName,
+            epoch: result.seed.epoch,
+            seed_hash: seedHash(result.seed),
+            counts: {
+                customers: result.seed.data.customers.length,
+                products: result.seed.data.products.length,
+                prices: result.seed.data.prices.length,
+                invoices: result.seed.data.invoices.length,
+                charges_attached: result.seed.data.invoices.reduce((n, inv) => n + inv.charges.length, 0),
+                subscriptions: result.seed.data.subscriptions.length,
+            },
+            lossy: result.lossy,
+            seed_doc: result.seedDoc,
+        };
+    });
+    app.get("/admin/worlds/:id/dump", async (req, reply) => {
+        const world = getWorld(req.params.id, reply);
+        if (!world)
+            return;
+        void reply.header("content-type", "application/json");
+        return world.dump();
+    });
+}