Add cost history to the Costs page: what it cost each month, and what changed

Each cost item's name, amount, currency, period and kind are kept as versions (cost_item_versions), and Hetzner's estimate is written down once a day (cost_snapshots), so a past month's figure and the changes between can be worked out. History card with monthly bars per currency, month-by-month figures and a list of added, changed and removed items.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-11-04 23:57:59 +01:00
1 parent b29c0b7d04
commit 9f366c37de
15 files changed
+9716 -3

No files matched your search

+252
View File
@@ -0,0 +1,252 @@
/**
* Cost history: what the homelab cost in each past month (from what each item was at the month's end, and the estimates written down day by day), what changed, how the versions are kept in step
* with the items, and the route.
*
* Run with: npm test --workspace server
*/
import { test, describe, before, after } from "node:test";
import assert from "node:assert/strict";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { AddressInfo } from "node:net";
import type { Server } from "node:http";
const dir = mkdtempSync(join(tmpdir(), "hm-costhistory-"));
process.env.DATABASE_PATH = join(dir, "test.sqlite");
process.env.SESSION_DIR = join(dir, "sessions");
process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32);
process.env.HEALTH_STARTUP_GRACE_MS = "0";
const express = (await import("express")).default;
const { db } = await import("../src/db/client.js");
const { users, integrations, costItems, costItemVersions, costSnapshots } = await import("../src/db/schema.js");
const { runMigrations } = await import("../src/db/migrate.js");
const hist = await import("../src/services/costHistory.js");
const hz = await import("../src/services/hetznerSync.js");
const { costsRouter } = await import("../src/routes/costs.js");
const { eventText } = await import("../../web/src/utils/costText.js");
const { eq } = await import("drizzle-orm");
await runMigrations();
type V = import("../src/services/costHistory.js").VersionRow;
type S = import("../src/services/costHistory.js").SnapshotRow;
let nextId = 1;
const version = (itemId: number, extra: Partial<V> = {}): V => ({ id: nextId++, itemId, name: "VPN", amount: 5, currency: "EUR", period: "month", category: "Subscriptions", validFrom: "2026-01-10T10:00:00.000Z", validTo: null, ...extra });
const snap = (day: string, monthly: number, extra: Partial<S> = {}): S => ({ day, key: "hetzner:1", name: "Prod", currency: "EUR", monthly, ...extra });
const NOW = Date.parse("2026-06-15T12:00:00Z");
describe("the months", () => {
test("months between two, both included, across a year's end", () => {
assert.deepEqual(hist.monthsBetween("2025-11", "2026-02"), ["2025-11", "2025-12", "2026-01", "2026-02"]);
assert.deepEqual(hist.monthsBetween("2026-06", "2026-06"), ["2026-06"]);
});
test("an item counts in every month from the one it was added in; a yearly one is a twelfth; the month that is not over is as of now", () => {
const { months, series } = hist.monthlySeries([version(1), version(2, { name: "Domain", amount: 24, period: "year", category: "Domains", validFrom: "2026-03-20T00:00:00.000Z" })], [], NOW);
assert.deepEqual(months, ["2026-01", "2026-02", "2026-03", "2026-04", "2026-05", "2026-06"]);
assert.deepEqual(series[0].points.map((p) => p.monthly), [5, 5, 7, 7, 7, 7]);
assert.deepEqual(series.map((s) => s.currency), ["EUR"]);
});
test("a price that changed is the old one before the change and the new one after, by the month's end", () => {
const list = [version(1, { amount: 5, validFrom: "2026-01-01T00:00:00.000Z", validTo: "2026-04-10T09:00:00.000Z" }), version(1, { amount: 8, validFrom: "2026-04-10T09:00:00.000Z" })];
const { series } = hist.monthlySeries(list, [], NOW);
assert.deepEqual(series[0].points.map((p) => [p.month, p.monthly]), [["2026-01", 5], ["2026-02", 5], ["2026-03", 5], ["2026-04", 8], ["2026-05", 8], ["2026-06", 8]]);
});
test("an item that was removed is counted in the months it was there, not after; one removed within a month is not counted in it", () => {
const list = [version(1, { validFrom: "2026-01-01T00:00:00.000Z", validTo: "2026-03-31T23:59:59.999Z" }), version(2, { name: "Short", amount: 3, validFrom: "2026-02-05T00:00:00.000Z", validTo: "2026-02-20T00:00:00.000Z" })];
const { series } = hist.monthlySeries(list, [], NOW);
assert.deepEqual(series[0].points.map((p) => [p.month, p.monthly]), [["2026-01", 5], ["2026-02", 5], ["2026-03", 0], ["2026-04", 0], ["2026-05", 0], ["2026-06", 0]]);
});
test("only the last months asked for are given; nothing at all gives nothing", () => {
const { months } = hist.monthlySeries([version(1, { validFrom: "2024-01-01T00:00:00.000Z" })], [], NOW, 4);
assert.deepEqual(months, ["2026-03", "2026-04", "2026-05", "2026-06"]);
assert.deepEqual(hist.monthlySeries([], [], NOW), { months: [], series: [] });
});
test("each currency is its own series, the largest now first, and none is converted", () => {
const { series } = hist.monthlySeries([version(1), version(2, { currency: "SEK", amount: 100 })], [], NOW);
assert.deepEqual(series.map((s) => [s.currency, s.points[s.points.length - 1].monthly]), [["SEK", 100], ["EUR", 5]]);
});
test("an estimate that is read counts as of the last day written in the month, apart from what was typed in", () => {
const snaps = [snap("2026-04-03", 8), snap("2026-04-28", 10), snap("2026-05-30", 12), snap("2026-06-10", 14)];
const { months, series } = hist.monthlySeries([version(1, { validFrom: "2026-04-01T00:00:00.000Z" })], snaps, NOW);
assert.deepEqual(months, ["2026-04", "2026-05", "2026-06"]);
assert.deepEqual(series[0].points, [
{ month: "2026-04", monthly: 15, manual: 5, automatic: 10 },
{ month: "2026-05", monthly: 17, manual: 5, automatic: 12 },
{ month: "2026-06", monthly: 19, manual: 5, automatic: 14 },
]);
// Estimates alone start the history too, and two projects add up.
const two = hist.monthlySeries([], [snap("2026-06-01", 4), snap("2026-06-01", 6, { key: "hetzner:2", name: "Test" })], NOW);
assert.deepEqual(two.series[0].points, [{ month: "2026-06", monthly: 10, manual: 0, automatic: 10 }]);
});
});
describe("what changed", () => {
test("added, changed (what it was and what it is) and removed — newest first", () => {
const list = [
version(1, { amount: 5, validFrom: "2026-01-10T00:00:00.000Z", validTo: "2026-04-01T00:00:00.000Z" }),
version(1, { amount: 8, name: "VPN Plus", validFrom: "2026-04-01T00:00:00.000Z", validTo: "2026-05-01T00:00:00.000Z" }),
version(2, { name: "Domain", amount: 12, period: "year", validFrom: "2026-02-01T00:00:00.000Z" }),
];
const e = hist.costEvents(list, []);
assert.deepEqual(e.map((x) => [x.kind, x.name, x.at.slice(0, 10)]), [["removed", "VPN Plus", "2026-05-01"], ["changed", "VPN Plus", "2026-04-01"], ["added", "Domain", "2026-02-01"], ["added", "VPN", "2026-01-10"]]);
const changed = e.find((x) => x.kind === "changed")!;
assert.deepEqual([changed.from?.amount, changed.from?.name, changed.amount, changed.name], [5, "VPN", 8, "VPN Plus"]);
});
test("a version closed to make way for another is a change, not a removal", () => {
const list = [version(1, { validTo: "2026-04-01T00:00:00.000Z" }), version(1, { amount: 6, validFrom: "2026-04-01T00:00:00.000Z" })];
assert.deepEqual(hist.costEvents(list, []).map((x) => x.kind), ["changed", "added"]);
});
test("an estimate that moved by a cent or more from one day to the next is an event; one that held, or changed currency, is not", () => {
const e = hist.costEvents([], [snap("2026-06-01", 10), snap("2026-06-02", 10.004), snap("2026-06-03", 12.5), snap("2026-06-04", 12.5, { currency: "SEK" })]);
assert.deepEqual(e.map((x) => [x.kind, x.from?.amount, x.amount]), [["estimate", 10, 12.5]]);
});
test("only as many as asked for, the newest", () => {
const list = Array.from({ length: 5 }, (_, i) => version(10 + i, { name: `I${i}`, validFrom: `2026-0${i + 1}-01T00:00:00.000Z` }));
assert.deepEqual(hist.costEvents(list, [], 2).map((x) => x.name), ["I4", "I3"]);
});
test("in words", () => {
const base = { at: "2026-04-01T00:00:00.000Z", name: "VPN", amount: 8, currency: "EUR", period: "month", category: "Subscriptions" };
assert.match(eventText({ ...base, kind: "added", from: null }), /^Added VPN — .*8.* a month$/);
assert.match(eventText({ ...base, kind: "removed", from: null }), /^Removed VPN \(it was .*8.* a month\)$/);
const changed = eventText({ ...base, kind: "changed", from: { name: "VPN", amount: 5, currency: "EUR", period: "month", category: "Subscriptions" } });
assert.match(changed, /^Changed VPN — .*5.* a month → .*8.* a month$/);
assert.match(eventText({ ...base, kind: "changed", name: "VPN+", category: "Hosting", from: { name: "VPN", amount: 8, currency: "EUR", period: "month", category: "Subscriptions" } }), /renamed from VPN; kind Subscriptions → Hosting/);
assert.match(eventText({ ...base, kind: "estimate", name: "Prod", from: { name: "Prod", amount: 10, currency: "EUR", period: "month", category: "Hosting" } }), /^Prod: the estimate went from .*10.* to .*8.* a month$/);
});
});
describe("keeping the versions in step with the items", () => {
const versionsOf = async (itemId: number) => (await db.select().from(costItemVersions).where(eq(costItemVersions.itemId, itemId))).sort((a, b) => a.id - b.id);
const addItem = async (name: string, amount: number, createdAt = "2026-02-01T10:00:00.000Z") =>
(await db.insert(costItems).values({ name, amount, currency: "EUR", period: "month", category: "Subscriptions", createdAt, updatedAt: createdAt }).returning({ id: costItems.id }))[0].id;
test("an item that was there before is given a version from the day it was added", async () => {
const id = await addItem("Old VPN", 5, "2025-11-03T08:00:00.000Z");
await hist.reconcileVersions(new Date("2026-06-01T00:00:00Z"));
const v = await versionsOf(id);
assert.deepEqual(v.map((x) => [x.amount, x.validFrom, x.validTo]), [[5, "2025-11-03T08:00:00.000Z", null]]);
});
test("nothing changed, or only a note or the day it is billed, makes nothing new; a new amount closes the old version and opens another from now", async () => {
const id = await addItem("Plex", 4);
await hist.reconcileVersions(new Date("2026-06-01T00:00:00Z"));
await db.update(costItems).set({ note: "annual pass", renewsOn: "2026-09-01" }).where(eq(costItems.id, id));
await hist.reconcileVersions(new Date("2026-06-02T00:00:00Z"));
assert.equal((await versionsOf(id)).length, 1);
await db.update(costItems).set({ amount: 6 }).where(eq(costItems.id, id));
await hist.reconcileVersions(new Date("2026-06-03T00:00:00Z"));
const v = await versionsOf(id);
assert.deepEqual(v.map((x) => [x.amount, x.validFrom.slice(0, 10), x.validTo?.slice(0, 10) ?? null]), [[4, "2026-02-01", "2026-06-03"], [6, "2026-06-03", null]]);
});
test("a removed item's open version is closed, and is kept", async () => {
const id = await addItem("Short-lived", 2);
await hist.reconcileVersions(new Date("2026-06-01T00:00:00Z"));
await db.delete(costItems).where(eq(costItems.id, id));
await hist.reconcileVersions(new Date("2026-06-04T00:00:00Z"));
const v = await versionsOf(id);
assert.deepEqual(v.map((x) => [x.amount, x.validTo?.slice(0, 10)]), [[2, "2026-06-04"]]);
});
test("two at once do not open the same version twice", async () => {
const id = await addItem("Raced", 3);
await Promise.all([hist.reconcileVersions(), hist.reconcileVersions(), hist.reconcileVersions()]);
assert.equal((await versionsOf(id)).length, 1);
});
});
describe("writing the estimate down", () => {
let hid = 0;
before(async () => {
hid = (await db.insert(integrations).values({ type: "hetzner", name: "Prod", baseUrl: "https://api.hetzner.cloud", config: "{}" }).returning({ id: integrations.id }))[0].id;
const server = { id: 1, name: "web", status: "running", created: null, type: "cx22", cores: 2, memoryGb: 4, diskGb: 40, location: "fsn1", city: null, os: null, ipv4: null, ipv6: null, privateIps: [], locked: false, rescueEnabled: false, backupWindow: null, includedTraffic: null, outgoingTraffic: null, ingoingTraffic: null, monthlyPrice: 10 };
await hz.storeRead(hid, { servers: [server], volumes: [], images: [], primaryIps: [], prices: { currency: "EUR", imagePerGb: 0.01, volumePerGb: 0.05, backupPercent: 20, primaryIps: [] } }, new Date());
});
after(async () => {
await db.delete(integrations).where(eq(integrations.id, hid));
});
test("today's estimate is written once a day: a second time the same day replaces the first, another day adds a row", async () => {
assert.equal(await hist.snapshotAutomatic(new Date("2026-06-10T08:00:00Z")), 1);
await hist.snapshotAutomatic(new Date("2026-06-10T20:00:00Z"));
await hist.snapshotAutomatic(new Date("2026-06-11T08:00:00Z"));
const rows = (await db.select().from(costSnapshots).where(eq(costSnapshots.key, `hetzner:${hid}`))).sort((a, b) => a.day.localeCompare(b.day));
assert.deepEqual(rows.map((r) => [r.day, r.name, r.currency, r.monthly]), [["2026-06-10", "Prod", "EUR", 10], ["2026-06-11", "Prod", "EUR", 10]]);
});
});
describe("the route", () => {
let app: Server;
let base = "";
let who = "admin";
const call = async (method: string, path: string, body?: unknown) => {
const res = await fetch(`${base}${path}`, { method, headers: { "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
return { status: res.status, body: res.status === 204 ? null : await res.json() };
};
before(async () => {
await db.insert(users).values([
{ oidcSub: "admin", name: "Ada", role: "admin" },
{ oidcSub: "viewer", name: "Vic", role: "viewer" },
]);
const a = express();
a.use(express.json());
a.use((req, _res, next) => {
(req as unknown as { session: unknown }).session = { user: { sub: who } };
next();
});
a.use("/api/costs", costsRouter);
app = await new Promise<Server>((resolve) => {
const s = a.listen(0, "127.0.0.1", () => resolve(s));
});
base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/costs`;
});
after(() => {
app.close();
try {
rmSync(dir, { recursive: true, force: true });
} catch {
// Windows keeps the database file locked until the process exits.
}
});
test("adding, changing and removing an item through the page is in the history at once, and everyone signed in can see it", async () => {
const created = await call("POST", "", { name: "Backup service", amount: 7, currency: "SEK", period: "month", category: "Hosting" });
assert.equal(created.status, 201);
const id = created.body.id as number;
assert.equal((await call("PUT", `/${id}`, { name: "Backup service", amount: 9, currency: "SEK", period: "month", category: "Hosting" })).status, 200);
who = "viewer";
let h = (await call("GET", "/history")).body;
assert.equal((await call("GET", "/history")).status, 200);
assert.deepEqual(h.events.filter((e: { name: string }) => e.name === "Backup service").map((e: { kind: string; amount: number; from: { amount: number } | null }) => [e.kind, e.amount, e.from?.amount ?? null]), [["changed", 9, 7], ["added", 7, null]]);
const sek = h.series.find((s: { currency: string }) => s.currency === "SEK");
assert.equal(sek.points[sek.points.length - 1].monthly, 9);
who = "admin";
assert.equal((await call("DELETE", `/${id}`)).status, 204);
h = (await call("GET", "/history")).body;
assert.deepEqual(h.events.filter((e: { name: string }) => e.name === "Backup service").map((e: { kind: string }) => e.kind), ["removed", "changed", "added"]);
// Added and removed within the same month it was never there at a month's end, so the currency has no series at all.
const after = h.series.find((s: { currency: string }) => s.currency === "SEK");
assert.equal(after?.points[after.points.length - 1].monthly ?? 0, 0, "gone from this month's figure");
});
test("how many months back can be asked for, within reason", async () => {
const one = (await call("GET", "/history?months=1")).body;
assert.equal(one.months.length, 1);
const silly = (await call("GET", "/history?months=9999")).body;
assert.ok(silly.months.length <= 12, "an absurd number falls back to the default");
assert.ok(Array.isArray(silly.events));
});
});