immortal-js 1.0.0

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

@@ -0,0 +1,608 @@
+/**
+ * @file src/db.ts
+ * @description Invoice Service Pro v3 — SQLite Database Layer (better-sqlite3)
+ *
+ * Schema:
+ *   clients    — reusable client records
+ *   invoices   — invoice headers
+ *   line_items — line items per invoice
+ *   activity   — audit log
+ *
+ * All monetary values stored in CENTS (INTEGER).
+ * JSON columns: tags, party JSON (from/to stored as JSON blob).
+ */
+
+import Database from "better-sqlite3";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  Invoice, InvoiceStatus, InvoiceCurrency, InvoiceLineItem,
+  InvoiceParty, InvoiceActivity, Client,
+  DashboardStats, InvoiceListQuery, PaginatedResponse,
+} from "./types.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DB_PATH = process.env["DB_PATH"] ?? path.join(__dirname, "..", "data", "invoices.db");
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+function newId(): string {
+  return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function newItemId(): string {
+  return `li_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}
+let counter = 1;
+function nextNumber(): string {
+  const n = String(counter++).padStart(4, "0");
+  return `INV-${new Date().getFullYear()}-${n}`;
+}
+function now(): string { return new Date().toISOString(); }
+function today(): string { return now().split("T")[0] ?? now(); }
+function addDays(d: number): string {
+  const dt = new Date(); dt.setDate(dt.getDate() + d);
+  return dt.toISOString().split("T")[0] ?? dt.toISOString();
+}
+
+// ─── DB Init ───────────────────────────────────────────────────────────────────
+
+import { mkdirSync } from "node:fs";
+mkdirSync(path.dirname(DB_PATH), { recursive: true });
+
+const db = new Database(DB_PATH);
+db.pragma("journal_mode = WAL");
+db.pragma("foreign_keys = ON");
+
+db.exec(`
+  CREATE TABLE IF NOT EXISTS clients (
+    id          TEXT PRIMARY KEY,
+    name        TEXT NOT NULL,
+    email       TEXT NOT NULL,
+    phone       TEXT,
+    address     TEXT NOT NULL DEFAULT '',
+    city        TEXT NOT NULL DEFAULT '',
+    country     TEXT NOT NULL DEFAULT '',
+    tax_id      TEXT,
+    website     TEXT,
+    notes       TEXT,
+    created_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS invoices (
+    id          TEXT PRIMARY KEY,
+    number      TEXT NOT NULL UNIQUE,
+    status      TEXT NOT NULL DEFAULT 'draft',
+    currency    TEXT NOT NULL DEFAULT 'USD',
+    issued_at   TEXT NOT NULL,
+    due_at      TEXT NOT NULL,
+    paid_at     TEXT,
+    from_json   TEXT NOT NULL,
+    to_json     TEXT NOT NULL,
+    notes       TEXT,
+    terms       TEXT,
+    discount    REAL DEFAULT 0,
+    reference   TEXT,
+    tags_json   TEXT DEFAULT '[]',
+    created_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS line_items (
+    id          TEXT PRIMARY KEY,
+    invoice_id  TEXT NOT NULL REFERENCES invoices(id) ON DELETE CASCADE,
+    description TEXT NOT NULL,
+    quantity    REAL NOT NULL DEFAULT 1,
+    unit_price  INTEGER NOT NULL DEFAULT 0,
+    tax_rate    REAL NOT NULL DEFAULT 0,
+    discount    REAL DEFAULT 0,
+    unit        TEXT,
+    sort_order  INTEGER DEFAULT 0
+  );
+
+  CREATE TABLE IF NOT EXISTS activity (
+    id          TEXT PRIMARY KEY,
+    invoice_id  TEXT NOT NULL REFERENCES invoices(id) ON DELETE CASCADE,
+    action      TEXT NOT NULL,
+    note        TEXT,
+    performed_at TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_invoices_status   ON invoices(status);
+  CREATE INDEX IF NOT EXISTS idx_invoices_currency ON invoices(currency);
+  CREATE INDEX IF NOT EXISTS idx_invoices_issued   ON invoices(issued_at);
+  CREATE INDEX IF NOT EXISTS idx_line_items_inv    ON line_items(invoice_id);
+  CREATE INDEX IF NOT EXISTS idx_activity_inv      ON activity(invoice_id);
+`);
+
+// ─── Row → Domain ──────────────────────────────────────────────────────────────
+
+interface InvoiceRow {
+  id: string; number: string; status: string; currency: string;
+  issued_at: string; due_at: string; paid_at?: string | null;
+  from_json: string; to_json: string; notes?: string | null;
+  terms?: string | null; discount?: number | null; reference?: string | null;
+  tags_json?: string | null; created_at: string; updated_at: string;
+}
+
+interface LineItemRow {
+  id: string; invoice_id: string; description: string;
+  quantity: number; unit_price: number; tax_rate: number;
+  discount?: number | null; unit?: string | null; sort_order: number;
+}
+
+interface ActivityRow {
+  id: string; invoice_id: string; action: string; note?: string | null; performed_at: string;
+}
+
+interface ClientRow {
+  id: string; name: string; email: string; phone?: string | null;
+  address: string; city: string; country: string; tax_id?: string | null;
+  website?: string | null; notes?: string | null; created_at: string; updated_at: string;
+}
+
+function rowToInvoice(row: InvoiceRow, items: InvoiceLineItem[]): Invoice {
+  const inv: Invoice = {
+    id:       row.id,
+    number:   row.number,
+    status:   row.status as InvoiceStatus,
+    currency: row.currency as InvoiceCurrency,
+    issuedAt: row.issued_at,
+    dueAt:    row.due_at,
+    from:     JSON.parse(row.from_json) as InvoiceParty,
+    to:       JSON.parse(row.to_json)   as InvoiceParty,
+    lineItems: items,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+  if (row.paid_at)   inv.paidAt    = row.paid_at;
+  if (row.notes)     inv.notes     = row.notes;
+  if (row.terms)     inv.terms     = row.terms;
+  if (row.discount)  inv.discount  = row.discount;
+  if (row.reference) inv.reference = row.reference;
+  const tags = row.tags_json ? JSON.parse(row.tags_json) as string[] : [];
+  if (tags.length)   inv.tags = tags;
+  return inv;
+}
+
+function rowToLineItem(row: LineItemRow): InvoiceLineItem {
+  const li: InvoiceLineItem = {
+    id: row.id, description: row.description,
+    quantity: row.quantity, unitPrice: row.unit_price, taxRate: row.tax_rate,
+  };
+  if (row.discount) li.discount = row.discount;
+  if (row.unit)     li.unit     = row.unit;
+  return li;
+}
+
+function rowToClient(row: ClientRow): Client {
+  const c: Client = {
+    id: row.id, name: row.name, email: row.email,
+    address: row.address, city: row.city, country: row.country,
+    createdAt: row.created_at, updatedAt: row.updated_at,
+  };
+  if (row.phone)   c.phone   = row.phone;
+  if (row.tax_id)  c.taxId   = row.tax_id;
+  if (row.website) c.website = row.website;
+  if (row.notes)   c.notes   = row.notes;
+  return c;
+}
+
+function rowToActivity(row: ActivityRow): InvoiceActivity {
+  const a: InvoiceActivity = {
+    id: row.id, invoiceId: row.invoice_id,
+    action: row.action as InvoiceActivity["action"],
+    performedAt: row.performed_at,
+  };
+  if (row.note) a.note = row.note;
+  return a;
+}
+
+// ─── Prepared Statements ───────────────────────────────────────────────────────
+
+const stmts = {
+  getInvoice:    db.prepare<[string], InvoiceRow>("SELECT * FROM invoices WHERE id=?"),
+  getItems:      db.prepare<[string], LineItemRow>("SELECT * FROM line_items WHERE invoice_id=? ORDER BY sort_order"),
+  listActivity:  db.prepare<[string], ActivityRow>("SELECT * FROM activity WHERE invoice_id=? ORDER BY performed_at DESC"),
+  insertInvoice: db.prepare(`INSERT INTO invoices
+    (id,number,status,currency,issued_at,due_at,from_json,to_json,notes,terms,discount,reference,tags_json,created_at,updated_at)
+    VALUES (@id,@number,@status,@currency,@issued_at,@due_at,@from_json,@to_json,@notes,@terms,@discount,@reference,@tags_json,@created_at,@updated_at)`),
+  insertItem: db.prepare(`INSERT INTO line_items
+    (id,invoice_id,description,quantity,unit_price,tax_rate,discount,unit,sort_order)
+    VALUES (@id,@invoice_id,@description,@quantity,@unit_price,@tax_rate,@discount,@unit,@sort_order)`),
+  insertActivity: db.prepare(`INSERT INTO activity (id,invoice_id,action,note,performed_at)
+    VALUES (@id,@invoice_id,@action,@note,@performed_at)`),
+  updateInvoice: db.prepare(`UPDATE invoices SET
+    status=@status, notes=@notes, terms=@terms, reference=@reference,
+    paid_at=@paid_at, tags_json=@tags_json, updated_at=@updated_at
+    WHERE id=@id`),
+  deleteInvoice: db.prepare("DELETE FROM invoices WHERE id=?"),
+  // Clients
+  getClient:    db.prepare<[string], ClientRow>("SELECT * FROM clients WHERE id=?"),
+  listClients:  db.prepare<[], ClientRow>("SELECT * FROM clients ORDER BY name"),
+  insertClient: db.prepare(`INSERT INTO clients
+    (id,name,email,phone,address,city,country,tax_id,website,notes,created_at,updated_at)
+    VALUES (@id,@name,@email,@phone,@address,@city,@country,@tax_id,@website,@notes,@created_at,@updated_at)`),
+  updateClient: db.prepare(`UPDATE clients SET
+    name=@name, email=@email, phone=@phone, address=@address, city=@city,
+    country=@country, tax_id=@tax_id, website=@website, notes=@notes, updated_at=@updated_at
+    WHERE id=@id`),
+  deleteClient: db.prepare("DELETE FROM clients WHERE id=?"),
+};
+
+// ─── Invoice Store ─────────────────────────────────────────────────────────────
+
+export const InvoiceStore = {
+
+  get(id: string): Invoice | undefined {
+    const row = stmts.getInvoice.get(id);
+    if (!row) return undefined;
+    const items = stmts.getItems.all(id).map(rowToLineItem);
+    return rowToInvoice(row, items);
+  },
+
+  list(query: InvoiceListQuery = {}): PaginatedResponse<Invoice> {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (query.status)   { conditions.push("status=?");          params.push(query.status); }
+    if (query.currency) { conditions.push("currency=?");        params.push(query.currency); }
+    if (query.dateFrom) { conditions.push("issued_at>=?");      params.push(query.dateFrom); }
+    if (query.dateTo)   { conditions.push("issued_at<=?");      params.push(query.dateTo); }
+    if (query.search || query.clientName) {
+      const term = `%${query.search ?? query.clientName ?? ""}%`;
+      conditions.push("(number LIKE ? OR json_extract(to_json,'$.name') LIKE ? OR notes LIKE ?)");
+      params.push(term, term, term);
+    }
+
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const sortCol: Record<string, string> = {
+      number: "number", issuedAt: "issued_at", dueAt: "due_at", status: "status", total: "issued_at",
+    };
+    const col = sortCol[query.sortBy ?? "issuedAt"] ?? "issued_at";
+    const dir = query.sortDir === "asc" ? "ASC" : "DESC";
+
+    const page  = Math.max(1, query.page  ?? 1);
+    const limit = Math.min(100, Math.max(1, query.limit ?? 25));
+    const offset = (page - 1) * limit;
+
+    const countSql = `SELECT COUNT(*) as n FROM invoices ${where}`;
+    const dataSql  = `SELECT * FROM invoices ${where} ORDER BY ${col} ${dir} LIMIT ${limit} OFFSET ${offset}`;
+
+    const total = (db.prepare(countSql).get(...params) as { n: number }).n;
+    const rows  = db.prepare(dataSql).all(...params) as InvoiceRow[];
+
+    const data = rows.map(row => {
+      const items = stmts.getItems.all(row.id).map(rowToLineItem);
+      return rowToInvoice(row, items);
+    });
+
+    return { data, total, page, limit, totalPages: Math.ceil(total / limit) };
+  },
+
+  create(inv: Invoice): Invoice {
+    const tx = db.transaction(() => {
+      stmts.insertInvoice.run({
+        id: inv.id, number: inv.number, status: inv.status, currency: inv.currency,
+        issued_at: inv.issuedAt, due_at: inv.dueAt,
+        from_json: JSON.stringify(inv.from), to_json: JSON.stringify(inv.to),
+        notes: inv.notes ?? null, terms: inv.terms ?? null,
+        discount: inv.discount ?? null, reference: inv.reference ?? null,
+        tags_json: JSON.stringify(inv.tags ?? []),
+        created_at: inv.createdAt, updated_at: inv.updatedAt,
+      });
+      inv.lineItems.forEach((li, i) => {
+        stmts.insertItem.run({
+          id: li.id, invoice_id: inv.id, description: li.description,
+          quantity: li.quantity, unit_price: li.unitPrice, tax_rate: li.taxRate,
+          discount: li.discount ?? null, unit: li.unit ?? null, sort_order: i,
+        });
+      });
+      stmts.insertActivity.run({
+        id: newId(), invoice_id: inv.id, action: "created",
+        note: `Invoice ${inv.number} created`, performed_at: now(),
+      });
+    });
+    tx();
+    return inv;
+  },
+
+  update(id: string, patch: Partial<Invoice> & { status?: InvoiceStatus }): Invoice | undefined {
+    const existing = this.get(id);
+    if (!existing) return undefined;
+
+    const updated: Invoice = { ...existing, ...patch, id, updatedAt: now() };
+    stmts.updateInvoice.run({
+      id,
+      status: updated.status,
+      notes:  updated.notes     ?? null,
+      terms:  updated.terms     ?? null,
+      reference: updated.reference ?? null,
+      paid_at:   updated.paidAt    ?? null,
+      tags_json: JSON.stringify(updated.tags ?? []),
+      updated_at: updated.updatedAt,
+    });
+    if (patch.status && patch.status !== existing.status) {
+      stmts.insertActivity.run({
+        id: newId(), invoice_id: id,
+        action: "status_changed",
+        note: `Status changed from ${existing.status} to ${patch.status}`,
+        performed_at: now(),
+      });
+    }
+    return this.get(id);
+  },
+
+  delete(id: string): boolean {
+    const res = stmts.deleteInvoice.run(id);
+    return res.changes > 0;
+  },
+
+  getActivity(id: string): InvoiceActivity[] {
+    return stmts.listActivity.all(id).map(rowToActivity);
+  },
+
+  addActivity(invoiceId: string, action: InvoiceActivity["action"], note?: string): void {
+    stmts.insertActivity.run({ id: newId(), invoice_id: invoiceId, action, note: note ?? null, performed_at: now() });
+  },
+
+  count(): number {
+    return (db.prepare("SELECT COUNT(*) as n FROM invoices").get() as { n: number }).n;
+  },
+
+  dashboard(): DashboardStats {
+    const countByStatus = db.prepare(
+      "SELECT status, COUNT(*) as n FROM invoices GROUP BY status"
+    ).all() as { status: string; n: number }[];
+
+    const byStatus: Record<string, number> = {};
+    for (const r of countByStatus) byStatus[r.status] = r.n;
+
+    // Revenue from paid invoices (sum unit_price * quantity + tax - discount)
+    const revenueRow = db.prepare(`
+      SELECT COALESCE(SUM(
+        CAST(li.quantity * li.unit_price AS REAL) * (1 + li.tax_rate) * (1 - COALESCE(li.discount,0))
+        * (1 - COALESCE(i.discount,0))
+      ),0) as total
+      FROM line_items li
+      JOIN invoices i ON i.id = li.invoice_id
+      WHERE i.status = 'paid'
+    `).get() as { total: number };
+
+    const outstandingRow = db.prepare(`
+      SELECT COALESCE(SUM(
+        CAST(li.quantity * li.unit_price AS REAL) * (1 + li.tax_rate) * (1 - COALESCE(li.discount,0))
+        * (1 - COALESCE(i.discount,0))
+      ),0) as total
+      FROM line_items li
+      JOIN invoices i ON i.id = li.invoice_id
+      WHERE i.status = 'sent'
+    `).get() as { total: number };
+
+    const overdueRow = db.prepare(`
+      SELECT COALESCE(SUM(
+        CAST(li.quantity * li.unit_price AS REAL) * (1 + li.tax_rate) * (1 - COALESCE(li.discount,0))
+        * (1 - COALESCE(i.discount,0))
+      ),0) as total
+      FROM line_items li
+      JOIN invoices i ON i.id = li.invoice_id
+      WHERE i.status = 'overdue'
+    `).get() as { total: number };
+
+    const totalCount = (db.prepare("SELECT COUNT(*) as n FROM invoices").get() as { n: number }).n;
+    const clientCount = (db.prepare("SELECT COUNT(*) as n FROM clients").get() as { n: number }).n;
+
+    const avgRow = db.prepare(`
+      SELECT COALESCE(AVG(sub.total), 0) as avg FROM (
+        SELECT i.id, SUM(li.quantity * li.unit_price * (1 + li.tax_rate)) as total
+        FROM invoices i JOIN line_items li ON li.invoice_id = i.id
+        GROUP BY i.id
+      ) sub
+    `).get() as { avg: number };
+
+    // Monthly revenue (last 12 months)
+    const monthlyRows = db.prepare(`
+      SELECT strftime('%Y-%m', i.issued_at) as month,
+             COALESCE(SUM(li.quantity * li.unit_price * (1 + li.tax_rate)),0) as cents
+      FROM invoices i JOIN line_items li ON li.invoice_id = i.id
+      WHERE i.status = 'paid' AND i.issued_at >= date('now','-12 months')
+      GROUP BY month ORDER BY month
+    `).all() as { month: string; cents: number }[];
+
+    // Top clients
+    const topClientsRows = db.prepare(`
+      SELECT json_extract(i.to_json, '$.name') as name,
+             COUNT(*) as invoice_count,
+             COALESCE(SUM(li.quantity * li.unit_price * (1 + li.tax_rate)),0) as total_cents
+      FROM invoices i JOIN line_items li ON li.invoice_id = i.id
+      WHERE i.status IN ('paid','sent')
+      GROUP BY name ORDER BY total_cents DESC LIMIT 5
+    `).all() as { name: string; invoice_count: number; total_cents: number }[];
+
+    // This month vs last month
+    const thisMonthRow = db.prepare(`
+      SELECT COALESCE(SUM(li.quantity * li.unit_price * (1 + li.tax_rate)),0) as cents
+      FROM invoices i JOIN line_items li ON li.invoice_id = i.id
+      WHERE i.status = 'paid' AND strftime('%Y-%m', i.issued_at) = strftime('%Y-%m','now')
+    `).get() as { cents: number };
+
+    const lastMonthRow = db.prepare(`
+      SELECT COALESCE(SUM(li.quantity * li.unit_price * (1 + li.tax_rate)),0) as cents
+      FROM invoices i JOIN line_items li ON li.invoice_id = i.id
+      WHERE i.status = 'paid' AND strftime('%Y-%m', i.issued_at) = strftime('%Y-%m','now','-1 month')
+    `).get() as { cents: number };
+
+    const recentActivity = (db.prepare(
+      "SELECT * FROM activity ORDER BY performed_at DESC LIMIT 15"
+    ).all() as ActivityRow[]).map(rowToActivity);
+
+    return {
+      totalInvoices: totalCount,
+      totalRevenueCents: Math.round(revenueRow.total),
+      outstandingCents:  Math.round(outstandingRow.total),
+      overdueCents:      Math.round(overdueRow.total),
+      draftCount:        byStatus["draft"]     ?? 0,
+      sentCount:         byStatus["sent"]      ?? 0,
+      paidCount:         byStatus["paid"]      ?? 0,
+      overdueCount:      byStatus["overdue"]   ?? 0,
+      cancelledCount:    byStatus["cancelled"] ?? 0,
+      totalClients:      clientCount,
+      avgInvoiceCents:   Math.round(avgRow.avg),
+      revenueThisMonth:  Math.round(thisMonthRow.cents),
+      revenueLastMonth:  Math.round(lastMonthRow.cents),
+      invoicesByStatus:  byStatus as Record<InvoiceStatus, number>,
+      recentActivity,
+      topClients: topClientsRows.map(r => ({ name: r.name ?? "—", totalCents: Math.round(r.total_cents), invoiceCount: r.invoice_count })),
+      monthlyRevenue: monthlyRows.map(r => ({ month: r.month, cents: Math.round(r.cents) })),
+    };
+  },
+};
+
+// ─── Client Store ──────────────────────────────────────────────────────────────
+
+export const ClientStore = {
+  get(id: string): Client | undefined {
+    const r = stmts.getClient.get(id);
+    return r ? rowToClient(r) : undefined;
+  },
+
+  list(): Client[] {
+    return stmts.listClients.all().map(rowToClient);
+  },
+
+  create(dto: Omit<Client, "id" | "createdAt" | "updatedAt">): Client {
+    const n = now();
+    const client: Client = { ...dto, id: newId(), createdAt: n, updatedAt: n };
+    stmts.insertClient.run({
+      id: client.id, name: client.name, email: client.email,
+      phone: client.phone ?? null, address: client.address, city: client.city,
+      country: client.country, tax_id: client.taxId ?? null,
+      website: client.website ?? null, notes: client.notes ?? null,
+      created_at: client.createdAt, updated_at: client.updatedAt,
+    });
+    return client;
+  },
+
+  update(id: string, patch: Partial<Client>): Client | undefined {
+    const existing = this.get(id);
+    if (!existing) return undefined;
+    const updated = { ...existing, ...patch, id, updatedAt: now() };
+    stmts.updateClient.run({
+      id, name: updated.name, email: updated.email,
+      phone: updated.phone ?? null, address: updated.address, city: updated.city,
+      country: updated.country, tax_id: updated.taxId ?? null,
+      website: updated.website ?? null, notes: updated.notes ?? null,
+      updated_at: updated.updatedAt,
+    });
+    return this.get(id);
+  },
+
+  delete(id: string): boolean {
+    const res = stmts.deleteClient.run(id);
+    return res.changes > 0;
+  },
+
+  count(): number {
+    return (db.prepare("SELECT COUNT(*) as n FROM clients").get() as { n: number }).n;
+  },
+};
+
+// ─── ID / Number helpers ───────────────────────────────────────────────────────
+
+export { newId, newItemId, nextNumber, now, today, addDays };
+
+// ─── Seed data (runs once if DB is empty) ─────────────────────────────────────
+
+function seedIfEmpty(): void {
+  const count = InvoiceStore.count();
+  if (count > 0) return;
+
+  // Reset counter to match DB
+  counter = 1;
+
+  // Seed clients
+  const clients = [
+    ClientStore.create({ name: "Acme Technologies", email: "accounts@acme.com", phone: "+1 415 555 0100", address: "100 Innovation Drive", city: "San Francisco, CA 94105", country: "US", taxId: "US-TAX-88776655" }),
+    ClientStore.create({ name: "Munich Innovations GmbH", email: "billing@munich-innovations.de", phone: "+49 89 12345678", address: "Maximilianstrasse 12", city: "Munich 80539", country: "DE", taxId: "DE-TAX-99887766" }),
+    ClientStore.create({ name: "London Fintech Ltd", email: "accounts@londonfintech.co.uk", phone: "+44 20 7946 0958", address: "1 Canary Wharf", city: "London E14 5AB", country: "GB", taxId: "GB-TAX-112233" }),
+    ClientStore.create({ name: "Dubai Digital Solutions", email: "finance@dubaidigital.ae", phone: "+971 4 555 0234", address: "DIFC Gate Building", city: "Dubai", country: "AE" }),
+    ClientStore.create({ name: "Startup Valley Inc", email: "pay@startupvalley.io", phone: "+1 650 555 0199", address: "500 University Ave", city: "Palo Alto, CA 94301", country: "US" }),
+  ];
+
+  const sender: { name: string; email: string; address: string; city: string; country: string; taxId: string } = {
+    name: "Immortal Corp", email: "billing@immortal.dev",
+    address: "1 Resilience Boulevard", city: "San Francisco, CA 94102",
+    country: "US", taxId: "US-TAX-99887766",
+  };
+
+  const mkInv = (status: string, currency: string, client: Client, items: { desc: string; qty: number; unit: number; tax: number; unit_label?: string }[], notesText?: string): Invoice => {
+    const issuedDt = new Date();
+    issuedDt.setDate(issuedDt.getDate() - Math.floor(Math.random() * 60));
+    const dueDt = new Date(issuedDt);
+    dueDt.setDate(dueDt.getDate() + 30);
+
+    const id = newId();
+    const inv: Invoice = {
+      id, number: nextNumber(),
+      status: status as InvoiceStatus,
+      currency: currency as InvoiceCurrency,
+      issuedAt: issuedDt.toISOString().split("T")[0] ?? today(),
+      dueAt: dueDt.toISOString().split("T")[0] ?? addDays(30),
+      from: { ...sender },
+      to: { name: client.name, email: client.email, address: client.address, city: client.city, country: client.country, ...(client.taxId && { taxId: client.taxId }), ...(client.phone && { phone: client.phone }) },
+      lineItems: items.map(i => ({ id: newItemId(), description: i.desc, quantity: i.qty, unitPrice: i.unit, taxRate: i.tax, ...(i.unit_label && { unit: i.unit_label }) })),
+      notes: notesText ?? "Thank you for your business. We appreciate the opportunity to work with you.",
+      terms: "Payment due within 30 days of invoice date. Late payments subject to 1.5% monthly interest.",
+      createdAt: now(), updatedAt: now(),
+    };
+    if (status === "paid") {
+      const paidDt = new Date(issuedDt);
+      paidDt.setDate(paidDt.getDate() + Math.floor(Math.random() * 25) + 5);
+      inv.paidAt = paidDt.toISOString().split("T")[0] ?? today();
+    }
+    return inv;
+  };
+
+  const [acme, munich, london, dubai, startup] = clients as [Client, Client, Client, Client, Client];
+
+  const invoices = [
+    mkInv("paid", "USD", acme, [
+      { desc: "Enterprise License — Immortal.js Pro (Annual)", qty: 1, unit: 299900, tax: 0.08, unit_label: "yr" },
+      { desc: "Onboarding & Architecture Review (Senior Engineer)", qty: 8, unit: 25000, tax: 0.08, unit_label: "hrs" },
+      { desc: "24/7 Priority Support Package", qty: 1, unit: 120000, tax: 0.08, unit_label: "yr" },
+    ]),
+    mkInv("sent", "EUR", munich, [
+      { desc: "SaaS Monthly Subscription — Team Plan", qty: 3, unit: 49900, tax: 0.19, unit_label: "mo" },
+      { desc: "Custom Plugin Development", qty: 40, unit: 15000, tax: 0.19, unit_label: "hrs" },
+    ]),
+    mkInv("overdue", "GBP", london, [
+      { desc: "API Integration Consulting", qty: 16, unit: 22500, tax: 0.20, unit_label: "hrs" },
+      { desc: "Security Audit & Penetration Testing", qty: 1, unit: 350000, tax: 0.20, unit_label: "proj" },
+    ]),
+    mkInv("draft", "AED", dubai, [
+      { desc: "Cloud Infrastructure Architecture Design", qty: 1, unit: 550000, tax: 0.05, unit_label: "proj" },
+      { desc: "Custom Dashboard Development (React + Node.js)", qty: 1, unit: 280000, tax: 0.05, unit_label: "proj" },
+      { desc: "Technical Training Sessions", qty: 8, unit: 18000, tax: 0.05, unit_label: "hrs" },
+    ]),
+    mkInv("paid", "USD", startup, [
+      { desc: "Immortal.js Starter License", qty: 1, unit: 9900, tax: 0.08, unit_label: "yr" },
+      { desc: "Quick-Start Implementation Pack", qty: 2, unit: 15000, tax: 0.08, unit_label: "hrs" },
+    ]),
+    mkInv("cancelled", "CAD", acme, [
+      { desc: "Custom Analytics Module (Cancelled)", qty: 1, unit: 180000, tax: 0.13, unit_label: "proj" },
+    ], "Project cancelled due to scope change."),
+    mkInv("paid", "USD", munich, [
+      { desc: "Performance Optimization Engagement", qty: 20, unit: 20000, tax: 0.08, unit_label: "hrs" },
+      { desc: "Load Testing & Benchmarking", qty: 1, unit: 45000, tax: 0.08, unit_label: "proj" },
+    ]),
+    mkInv("sent", "GBP", london, [
+      { desc: "Resilience Framework Consultation", qty: 12, unit: 22500, tax: 0.20, unit_label: "hrs" },
+    ]),
+  ];
+
+  for (const inv of invoices) {
+    InvoiceStore.create(inv);
+  }
+}
+
+seedIfEmpty();