immortal-js 1.0.0

package/examples/invoice-service/src/server.ts

@@ -0,0 +1,527 @@
+/**
+ * @file src/server.ts
+ * @description Invoice Service Pro v3 — Ultra Pro Fastify Server
+ *
+ * Frontend-is-Backend Pattern:
+ *   Fastify serves static SPA from public/ (dark/light theme, Lucide icons)
+ *   AND a full REST API at /api/*
+ *
+ * Resilience (Immortal.js):
+ *   CircuitBreaker  — external email/storage calls
+ *   BulkheadPool    — PDF rendering + API concurrency
+ *   FallbackCache   — dashboard stats (15s TTL), invoice list (30s TTL)
+ *   withRetry       — transient storage errors
+ *   withTimeout     — email + external ops
+ *   GracefulShutdown — SIGTERM/SIGINT → drain → close
+ *   MemoryLeakGuard  — restart at 1500 MB
+ *   HealthMonitor    — event loop + memory tracking
+ *
+ * Routes:
+ *   GET  /api/            — API welcome + endpoint map
+ *   GET  /api/health      — full system health
+ *   GET  /api/metrics     — Prometheus text
+ *   GET  /api/dashboard   — real SQLite stats (KPI, monthly, top clients)
+ *   GET  /api/invoices    — paginated invoice list (SQLite, filtered, sorted)
+ *   POST /api/invoices    — create invoice
+ *   GET  /api/invoices/:id         — get invoice
+ *   PATCH /api/invoices/:id        — update invoice (status, notes, etc.)
+ *   DELETE /api/invoices/:id       — delete invoice
+ *   GET  /api/invoices/:id/pdf     — print-ready PDF HTML
+ *   GET  /api/invoices/:id/activity — audit log
+ *   GET  /api/clients     — list clients
+ *   POST /api/clients     — create client
+ *   GET  /api/clients/:id — get client
+ *   PATCH /api/clients/:id — update client
+ *   DELETE /api/clients/:id — delete client
+ *   GET  /api/stats       — quick stats for sidebar KPIs
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { FastifyRequest, FastifyReply } from "fastify";
+import Fastify from "fastify";
+import fastifyStatic from "@fastify/static";
+
+import {
+  CircuitBreaker, BulkheadPool, FallbackCache, GracefulShutdown,
+  MetricsCollector, HealthMonitor, MemoryLeakGuard, ErrorTrap,
+  withRetry, withTimeout, getEventBus, mergeWithDefaults,
+} from "@immortal/core";
+
+import { InvoiceStore, ClientStore, newId, newItemId, nextNumber, now, today, addDays } from "./db.js";
+import { generatePdfHtml, calculateTotals } from "./pdf.js";
+import type { Invoice, CreateInvoiceDto, UpdateInvoiceDto, CreateClientDto, InvoiceListQuery, InvoiceCurrency } from "./types.js";
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PUBLIC_DIR = path.resolve(__dirname, "..", "public");
+
+// ─── Error helper ─────────────────────────────────────────────────────────────
+
+function sendError(reply: FastifyReply, status: number, message: string, code = "ERROR"): FastifyReply {
+  return reply.status(status).send({ error: message, code, timestamp: now() });
+}
+
+// ─── Immortal.js Runtime ──────────────────────────────────────────────────────
+
+const config = mergeWithDefaults({});
+const bus    = getEventBus();
+
+new ErrorTrap(bus).install();
+
+const metrics       = new MetricsCollector();
+const healthMonitor = new HealthMonitor(config.healthMonitor, bus, metrics);
+const memoryGuard   = new MemoryLeakGuard({ checkIntervalMs: 30_000, restartThresholdMb: 1_500 }, bus);
+
+// Circuit breakers
+const emailCircuit   = new CircuitBreaker("email-service",   { threshold: 3, cooldownMs: 30_000, slidingWindowSize: 10 });
+const storageCircuit = new CircuitBreaker("storage-service", { threshold: 5, cooldownMs: 15_000, slidingWindowSize: 20 });
+
+// Bulkhead pools
+const pdfBulkhead = new BulkheadPool("pdf-rendering",  { maxConcurrent: 5,  maxQueueSize: 20,  queueTimeoutMs: 30_000 });
+const apiBulkhead = new BulkheadPool("api-requests",   { maxConcurrent: 50, maxQueueSize: 200, queueTimeoutMs: 10_000 });
+
+// Fallback caches (JSON-serialized values)
+const dashboardCache = new FallbackCache<string>({ maxSize: 10,  defaultTtlMs: 15_000 });
+const listCache      = new FallbackCache<string>({ maxSize: 100, defaultTtlMs: 30_000 });
+const statsCache     = new FallbackCache<string>({ maxSize: 5,   defaultTtlMs: 10_000 });
+
+function bustCaches(): void {
+  dashboardCache.invalidate("dashboard");
+  statsCache.invalidate("stats");
+  for (const k of ["all","draft","sent","paid","overdue","cancelled","refunded"]) {
+    listCache.invalidate(`list:${k}`);
+  }
+}
+
+// Graceful shutdown
+const shutdown = new GracefulShutdown({
+  timeoutMs: 20_000,
+  signals: ["SIGTERM", "SIGINT"],
+  onShutdown: [
+    async () => { pdfBulkhead.drain(); },
+    async () => { healthMonitor.stop(); memoryGuard.stop(); },
+    async () => { await fastify.close(); },
+  ],
+}, bus);
+void shutdown;
+
+// ─── Fastify ──────────────────────────────────────────────────────────────────
+
+const fastify = Fastify({ logger: false, bodyLimit: 2 * 1024 * 1024 });
+
+await fastify.register(fastifyStatic, { root: PUBLIC_DIR, prefix: "/" });
+
+// CORS
+fastify.addHook("onRequest", async (_req: FastifyRequest, reply: FastifyReply) => {
+  reply.header("Access-Control-Allow-Origin",  "*");
+  reply.header("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
+  reply.header("Access-Control-Allow-Headers", "Content-Type,Authorization");
+  reply.header("X-Powered-By", "Immortal.js Invoice Service Pro v3");
+});
+fastify.options("/*", async (_req, reply) => reply.status(204).send());
+
+// ─── /api/ ────────────────────────────────────────────────────────────────────
+
+fastify.get("/api/", async (_req: FastifyRequest, reply: FastifyReply) => {
+  return reply.send({
+    service: "Immortal.js Invoice Service Pro",
+    version: "3.0.0",
+    status: "running",
+    timestamp: now(),
+    database: "SQLite (better-sqlite3 WAL mode)",
+    endpoints: {
+      "GET  /api/":                         "API welcome",
+      "GET  /api/health":                   "System health",
+      "GET  /api/metrics":                  "Prometheus metrics",
+      "GET  /api/dashboard":                "Dashboard KPIs from SQLite",
+      "GET  /api/stats":                    "Quick sidebar stats",
+      "GET  /api/invoices":                 "List invoices (paginated, filtered, sorted)",
+      "POST /api/invoices":                 "Create invoice",
+      "GET  /api/invoices/:id":             "Get invoice by ID",
+      "PATCH /api/invoices/:id":            "Update invoice",
+      "DELETE /api/invoices/:id":           "Delete invoice",
+      "GET  /api/invoices/:id/pdf":         "Render PDF-ready HTML",
+      "GET  /api/invoices/:id/activity":    "Audit log",
+      "GET  /api/clients":                  "List clients",
+      "POST /api/clients":                  "Create client",
+      "GET  /api/clients/:id":              "Get client",
+      "PATCH /api/clients/:id":             "Update client",
+      "DELETE /api/clients/:id":            "Delete client",
+    },
+  });
+});
+
+// ─── /api/health ──────────────────────────────────────────────────────────────
+
+fastify.get("/api/health", async (_req: FastifyRequest, reply: FastifyReply) => {
+  const snap  = metrics.getSnapshot();
+  const pdfBk = pdfBulkhead.getStatus();
+  const apiBk = apiBulkhead.getStatus();
+  return reply.send({
+    status: "healthy",
+    uptime:    Math.round(process.uptime()),
+    version:   "3.0.0",
+    memoryMb: {
+      heapUsed:  Math.round(process.memoryUsage().heapUsed  / 1024 / 1024),
+      heapTotal: Math.round(process.memoryUsage().heapTotal / 1024 / 1024),
+      rss:       Math.round(process.memoryUsage().rss       / 1024 / 1024),
+    },
+    eventLoop: snap.eventLoopLag,
+    invoiceCount: InvoiceStore.count(),
+    clientCount:  ClientStore.count(),
+    circuits: {
+      "email-service":   emailCircuit.getStatus(),
+      "storage-service": storageCircuit.getStatus(),
+    },
+    bulkheads: {
+      "pdf-rendering": { active: pdfBk.active, queued: pdfBk.queued, max: 5  },
+      "api-requests":  { active: apiBk.active, queued: apiBk.queued, max: 50 },
+    },
+  });
+});
+
+// ─── /api/metrics ─────────────────────────────────────────────────────────────
+
+fastify.get("/api/metrics", async (_req: FastifyRequest, reply: FastifyReply) => {
+  const snap   = metrics.getSnapshot();
+  const emailS = emailCircuit.getStatus();
+  const strgS  = storageCircuit.getStatus();
+  const pdfBk  = pdfBulkhead.getStatus();
+  const apiBk  = apiBulkhead.getStatus();
+  const stateNum = (s: string): number => s === "CLOSED" ? 1 : s === "HALF_OPEN" ? 2 : 3;
+  return reply.header("Content-Type", "text/plain; version=0.0.4").send([
+    `immortal_circuit_state{name="email-service"}   ${stateNum(emailS.state)}`,
+    `immortal_circuit_state{name="storage-service"} ${stateNum(strgS.state)}`,
+    `immortal_bulkhead_active{pool="pdf-rendering"} ${pdfBk.active}`,
+    `immortal_bulkhead_active{pool="api-requests"}  ${apiBk.active}`,
+    `immortal_heap_used_mb ${Math.round(process.memoryUsage().heapUsed / 1024 / 1024)}`,
+    `immortal_eventloop_lag_p99_ms ${snap.eventLoopLag.p99.toFixed(2)}`,
+    `invoice_service_total ${InvoiceStore.count()}`,
+    `invoice_client_total  ${ClientStore.count()}`,
+  ].join("\n"));
+});
+
+// ─── /api/dashboard ───────────────────────────────────────────────────────────
+
+fastify.get("/api/dashboard", async (_req: FastifyRequest, reply: FastifyReply) => {
+  return apiBulkhead.run(async () => {
+    const cached = dashboardCache.get("dashboard");
+    if (cached) {
+      return reply.header("X-Cache", "HIT").header("Content-Type", "application/json").send(cached);
+    }
+    const stats = InvoiceStore.dashboard();
+    const payload = JSON.stringify(stats);
+    dashboardCache.set("dashboard", payload);
+    return reply.header("X-Cache", "MISS").send(stats);
+  }, "medium");
+});
+
+// ─── /api/stats ───────────────────────────────────────────────────────────────
+
+fastify.get("/api/stats", async (_req: FastifyRequest, reply: FastifyReply) => {
+  const cached = statsCache.get("stats");
+  if (cached) return reply.header("X-Cache", "HIT").header("Content-Type", "application/json").send(cached);
+  const stats = InvoiceStore.dashboard();
+  const quick = {
+    total:       stats.totalInvoices,
+    revenue:     stats.totalRevenueCents,
+    outstanding: stats.outstandingCents,
+    overdue:     stats.overdueCents,
+    drafts:      stats.draftCount,
+    clients:     stats.totalClients,
+    paid:        stats.paidCount,
+    sent:        stats.sentCount,
+  };
+  statsCache.set("stats", JSON.stringify(quick));
+  return reply.send(quick);
+});
+
+// ─── /api/invoices (GET — list) ───────────────────────────────────────────────
+
+fastify.get(
+  "/api/invoices",
+  async (
+    request: FastifyRequest<{ Querystring: Record<string, string> }>,
+    reply: FastifyReply
+  ) => {
+    return apiBulkhead.run(async () => {
+      const q = request.query;
+      // Build query object without undefined optional fields (exactOptionalPropertyTypes)
+      const query: InvoiceListQuery = {};
+      query.page    = q["page"]  ? parseInt(q["page"],  10) : 1;
+      query.limit   = q["limit"] ? parseInt(q["limit"], 10) : 25;
+      query.sortDir = q["sortDir"] === "asc" ? "asc" : "desc";
+      if (q["status"])   query.status   = q["status"]   as NonNullable<InvoiceListQuery["status"]>;
+      if (q["currency"]) query.currency = q["currency"] as NonNullable<InvoiceListQuery["currency"]>;
+      if (q["search"])   query.search   = q["search"];
+      if (q["sortBy"])   query.sortBy   = q["sortBy"]   as NonNullable<InvoiceListQuery["sortBy"]>;
+      if (q["dateFrom"]) query.dateFrom = q["dateFrom"];
+      if (q["dateTo"])   query.dateTo   = q["dateTo"];
+
+      const cacheKey = `list:${JSON.stringify(query)}`;
+      const cached = listCache.get(cacheKey);
+      if (cached) {
+        return reply.header("X-Cache", "HIT").header("Content-Type", "application/json").send(cached);
+      }
+
+      const result = await storageCircuit.execute(
+        async () => {
+          await simulateStorageLatency();
+          return InvoiceStore.list(query);
+        },
+        () => InvoiceStore.list(query)
+      );
+
+      listCache.set(cacheKey, JSON.stringify(result));
+      return reply.header("X-Cache", "MISS").send(result);
+    }, "medium");
+  }
+);
+
+// ─── /api/invoices (POST — create) ────────────────────────────────────────────
+
+fastify.post(
+  "/api/invoices",
+  async (request: FastifyRequest, reply: FastifyReply) => {
+    return apiBulkhead.run(async () => {
+      const dto = request.body as CreateInvoiceDto;
+
+      if (!dto?.from?.name || !dto?.to?.name || !dto?.to?.email) {
+        return sendError(reply, 400, "from.name, to.name, to.email are required", "VALIDATION_ERROR");
+      }
+      if (!dto.lineItems?.length) {
+        return sendError(reply, 400, "At least one line item is required", "VALIDATION_ERROR");
+      }
+
+      const invoice = await withRetry(async () => {
+        await simulateStorageLatency();
+        const n = now();
+        const newInv: Invoice = {
+          id:       newId(),
+          number:   nextNumber(),
+          status:   "draft",
+          currency: (dto.currency ?? "USD") as InvoiceCurrency,
+          issuedAt: dto.issuedAt ?? today(),
+          dueAt:    dto.dueAt    ?? addDays(30),
+          from:     dto.from,
+          to:       dto.to,
+          lineItems: dto.lineItems.map(li => ({ ...li, id: newItemId() })),
+          createdAt: n,
+          updatedAt: n,
+          ...(dto.notes     !== undefined && { notes:     dto.notes     }),
+          ...(dto.terms     !== undefined && { terms:     dto.terms     }),
+          ...(dto.discount  !== undefined && { discount:  dto.discount  }),
+          ...(dto.reference !== undefined && { reference: dto.reference }),
+          ...(dto.tags?.length            && { tags:      dto.tags      }),
+        };
+        return InvoiceStore.create(newInv);
+      }, { maxAttempts: 2, baseDelayMs: 100 });
+
+      bustCaches();
+
+      // Non-blocking email
+      void emailCircuit.execute(
+        () => withTimeout(
+          () => simulateEmailSend(invoice.to.email, invoice.number),
+          5_000, "email"
+        ),
+        () => undefined
+      ).catch(() => undefined);
+
+      return reply.status(201).send(invoice);
+    }, "high");
+  }
+);
+
+// ─── /api/invoices/:id (GET) ──────────────────────────────────────────────────
+
+fastify.get(
+  "/api/invoices/:id",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    const { id } = request.params;
+    const invoice = InvoiceStore.get(id);
+    if (!invoice) return sendError(reply, 404, `Invoice '${id}' not found`, "NOT_FOUND");
+    return reply.send(invoice);
+  }
+);
+
+// ─── /api/invoices/:id (PATCH) ────────────────────────────────────────────────
+
+fastify.patch(
+  "/api/invoices/:id",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    const { id } = request.params;
+    const dto = request.body as UpdateInvoiceDto;
+
+    if (dto.status) {
+      const valid = ["draft", "sent", "paid", "overdue", "cancelled", "refunded"];
+      if (!valid.includes(dto.status)) {
+        return sendError(reply, 400, `Invalid status. Valid: ${valid.join(", ")}`, "VALIDATION_ERROR");
+      }
+      if (dto.status === "paid" && !dto.paidAt) {
+        dto.paidAt = today();
+      }
+    }
+
+    const updated = InvoiceStore.update(id, dto);
+    if (!updated) return sendError(reply, 404, `Invoice '${id}' not found`, "NOT_FOUND");
+    bustCaches();
+    return reply.send(updated);
+  }
+);
+
+// ─── /api/invoices/:id (DELETE) ───────────────────────────────────────────────
+
+fastify.delete(
+  "/api/invoices/:id",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    const { id } = request.params;
+    if (!InvoiceStore.get(id)) return sendError(reply, 404, `Invoice '${id}' not found`, "NOT_FOUND");
+    InvoiceStore.delete(id);
+    bustCaches();
+    return reply.status(204).send();
+  }
+);
+
+// ─── /api/invoices/:id/pdf ────────────────────────────────────────────────────
+
+fastify.get(
+  "/api/invoices/:id/pdf",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    const { id } = request.params;
+    return pdfBulkhead.run(async () => {
+      const invoice = InvoiceStore.get(id);
+      if (!invoice) return sendError(reply, 404, `Invoice '${id}' not found`, "NOT_FOUND");
+
+      await sleep(20 + Math.random() * 50);
+      const html   = generatePdfHtml(invoice);
+      const totals = calculateTotals(invoice);
+
+      InvoiceStore.addActivity(id, "viewed", "PDF rendered");
+
+      return reply
+        .header("Content-Type", "text/html; charset=utf-8")
+        .header("X-Invoice-Total",  totals.total)
+        .header("X-Invoice-Number", invoice.number)
+        .send(html);
+    }, "high");
+  }
+);
+
+// ─── /api/invoices/:id/activity ───────────────────────────────────────────────
+
+fastify.get(
+  "/api/invoices/:id/activity",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    const { id } = request.params;
+    if (!InvoiceStore.get(id)) return sendError(reply, 404, `Invoice '${id}' not found`, "NOT_FOUND");
+    return reply.send(InvoiceStore.getActivity(id));
+  }
+);
+
+// ─── /api/clients ─────────────────────────────────────────────────────────────
+
+fastify.get("/api/clients", async (_req: FastifyRequest, reply: FastifyReply) => {
+  return reply.send(ClientStore.list());
+});
+
+fastify.post("/api/clients", async (request: FastifyRequest, reply: FastifyReply) => {
+  const dto = request.body as CreateClientDto;
+  if (!dto?.name || !dto?.email) {
+    return sendError(reply, 400, "name and email are required", "VALIDATION_ERROR");
+  }
+  const client = ClientStore.create(dto);
+  bustCaches();
+  return reply.status(201).send(client);
+});
+
+fastify.get("/api/clients/:id",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    const client = ClientStore.get(request.params.id);
+    if (!client) return sendError(reply, 404, "Client not found", "NOT_FOUND");
+    return reply.send(client);
+  }
+);
+
+fastify.patch("/api/clients/:id",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    const updated = ClientStore.update(request.params.id, request.body as Partial<{ name: string; email: string; phone: string; address: string; city: string; country: string; taxId: string; website: string; notes: string }>);
+    if (!updated) return sendError(reply, 404, "Client not found", "NOT_FOUND");
+    return reply.send(updated);
+  }
+);
+
+fastify.delete("/api/clients/:id",
+  async (request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) => {
+    if (!ClientStore.delete(request.params.id)) return sendError(reply, 404, "Client not found", "NOT_FOUND");
+    return reply.status(204).send();
+  }
+);
+
+// ─── SPA Fallback ─────────────────────────────────────────────────────────────
+
+fastify.setNotFoundHandler(async (request: FastifyRequest, reply: FastifyReply) => {
+  if (request.url.startsWith("/api")) {
+    return reply.status(404).send({ error: `Route not found: ${request.method} ${request.url}`, code: "NOT_FOUND", timestamp: now() });
+  }
+  return reply.sendFile("index.html");
+});
+
+// ─── Global Error Handler ─────────────────────────────────────────────────────
+
+fastify.setErrorHandler(async (error, _req: FastifyRequest, reply: FastifyReply) => {
+  const status = (error as { statusCode?: number }).statusCode ?? 500;
+  console.error(`[ERROR] ${error.name}: ${error.message}`);
+  return reply.status(status).send({
+    error:     status >= 500 ? "Internal Server Error" : error.message,
+    code:      error.name,
+    timestamp: now(),
+  });
+});
+
+// ─── Simulators ───────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> { return new Promise(r => setTimeout(r, ms)); }
+
+async function simulateStorageLatency(): Promise<void> {
+  await sleep(2 + Math.random() * 8);
+  if (Math.random() < 0.01) throw new Error("Storage transient error");
+}
+
+async function simulateEmailSend(email: string, num: string): Promise<void> {
+  await sleep(60 + Math.random() * 100);
+  if (Math.random() < 0.04) throw new Error("Email service unavailable");
+  console.log(`  [email] Confirmation → ${email} [${num}]`);
+}
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+healthMonitor.start();
+memoryGuard.start();
+
+const PORT = parseInt(process.env["PORT"] ?? "3000", 10);
+
+try {
+  await fastify.listen({ port: PORT, host: "0.0.0.0" });
+  console.log(`
++----------------------------------------------------------------------+
+|       Immortal.js  Invoice Service Pro v3   (Ultra Edition)          |
++----------------------------------------------------------------------+
+|  Frontend      -->  http://localhost:${PORT}/                          |
+|  API           -->  http://localhost:${PORT}/api/                      |
+|  Dashboard     -->  http://localhost:${PORT}/api/dashboard             |
+|  Health        -->  http://localhost:${PORT}/api/health                |
+|  Metrics       -->  http://localhost:${PORT}/api/metrics               |
++----------------------------------------------------------------------+
+|  DB: SQLite WAL  |  Invoices: ${InvoiceStore.count()}  |  Clients: ${ClientStore.count()}           |
+|  Circuits: email-service, storage-service                            |
+|  Bulkheads: pdf-rendering(5), api-requests(50)                       |
+|  Caches: dashboard(15s), list(30s), stats(10s)                       |
++----------------------------------------------------------------------+
+`);
+} catch (err) {
+  console.error("Startup failed:", err);
+  process.exit(1);
+}

package/examples/invoice-service/src/store.ts

@@ -0,0 +1,159 @@
+/**
+ * @file src/store.ts
+ * @description In-memory invoice store with atomic operations.
+ *              In production, replace with PostgreSQL / MongoDB.
+ */
+
+import type { Invoice, InvoiceStatus, InvoiceCurrency } from "./types.js";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function newId(): string {
+  return `inv_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+}
+
+function newItemId(): string {
+  return `li_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}
+
+let invoiceCounter = 1;
+function nextNumber(): string {
+  const n = String(invoiceCounter++).padStart(4, "0");
+  return `INV-${new Date().getFullYear()}-${n}`;
+}
+
+// ─── Seed data ────────────────────────────────────────────────────────────────
+
+function seedInvoices(): Map<string, Invoice> {
+  const now = new Date();
+  const due = new Date(now);
+  due.setDate(due.getDate() + 30);
+
+  const mkInvoice = (
+    status: InvoiceStatus,
+    currency: InvoiceCurrency,
+    clientName: string,
+    items: { desc: string; qty: number; unit: number; tax: number }[]
+  ): Invoice => {
+    const id = newId();
+    return {
+      id,
+      number: nextNumber(),
+      status,
+      currency,
+      issuedAt: now.toISOString().split("T")[0] ?? now.toISOString(),
+      dueAt: due.toISOString().split("T")[0] ?? due.toISOString(),
+      from: {
+        name: "Immortal Corp",
+        email: "billing@immortal.dev",
+        address: "1 Resilience Boulevard",
+        city: "San Francisco, CA 94102",
+        country: "US",
+        taxId: "US-TAX-99887766",
+      },
+      to: {
+        name: clientName,
+        email: `accounts@${clientName.toLowerCase().replace(/\s/g, "")}.com`,
+        address: "100 Client Street",
+        city: "New York, NY 10001",
+        country: "US",
+      },
+      lineItems: items.map((i) => ({
+        id: newItemId(),
+        description: i.desc,
+        quantity: i.qty,
+        unitPrice: i.unit,
+        taxRate: i.tax,
+      })),
+      notes: "Thank you for your business.",
+      terms: "Payment due within 30 days of invoice date.",
+      createdAt: now.toISOString(),
+      updatedAt: now.toISOString(),
+    };
+  };
+
+  const store = new Map<string, Invoice>();
+  const invoices = [
+    mkInvoice("paid", "USD", "Acme Technologies", [
+      { desc: "Enterprise License — Immortal.js Pro", qty: 1, unit: 299900, tax: 0.08 },
+      { desc: "Onboarding & Setup (4h)", qty: 4, unit: 20000, tax: 0.08 },
+    ]),
+    mkInvoice("sent", "EUR", "Munich Innovations GmbH", [
+      { desc: "Monthly SaaS Subscription", qty: 3, unit: 49900, tax: 0.19 },
+      { desc: "Priority Support (yearly)", qty: 1, unit: 120000, tax: 0.19 },
+    ]),
+    mkInvoice("overdue", "GBP", "London Fintech Ltd", [
+      { desc: "API Integration Consulting (8h)", qty: 8, unit: 25000, tax: 0.20 },
+    ]),
+    mkInvoice("draft", "AED", "Dubai Digital Solutions", [
+      { desc: "Cloud Infrastructure Setup", qty: 1, unit: 550000, tax: 0.05 },
+      { desc: "Custom Dashboard Development", qty: 1, unit: 180000, tax: 0.05 },
+      { desc: "Training Sessions (6h)", qty: 6, unit: 18000, tax: 0.05 },
+    ]),
+    mkInvoice("paid", "USD", "Startup Valley Inc", [
+      { desc: "Immortal.js Starter License", qty: 1, unit: 9900, tax: 0.08 },
+    ]),
+  ];
+
+  for (const inv of invoices) {
+    store.set(inv.id, inv);
+  }
+  return store;
+}
+
+// ─── Store ────────────────────────────────────────────────────────────────────
+
+export class InvoiceStore {
+  private readonly invoices: Map<string, Invoice> = seedInvoices();
+
+  list(): Invoice[] {
+    return [...this.invoices.values()].sort(
+      (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+    );
+  }
+
+  get(id: string): Invoice | undefined {
+    return this.invoices.get(id);
+  }
+
+  create(invoice: Invoice): Invoice {
+    this.invoices.set(invoice.id, invoice);
+    return invoice;
+  }
+
+  update(id: string, patch: Partial<Invoice>): Invoice | undefined {
+    const existing = this.invoices.get(id);
+    if (!existing) return undefined;
+    const updated: Invoice = {
+      ...existing,
+      ...patch,
+      id,             // never overwrite id
+      updatedAt: new Date().toISOString(),
+    };
+    this.invoices.set(id, updated);
+    return updated;
+  }
+
+  delete(id: string): boolean {
+    return this.invoices.delete(id);
+  }
+
+  count(): number {
+    return this.invoices.size;
+  }
+
+  newId(): string {
+    return newId();
+  }
+
+  newItemId(): string {
+    return newItemId();
+  }
+
+  nextNumber(): string {
+    return nextNumber();
+  }
+}
+
+// Singleton store
+export const store = new InvoiceStore();