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

+21
View File
@@ -0,0 +1,21 @@
CREATE TABLE `cost_item_versions` (
`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
`item_id` integer NOT NULL,
`name` text NOT NULL,
`amount` real NOT NULL,
`currency` text NOT NULL,
`period` text NOT NULL,
`category` text NOT NULL,
`valid_from` text NOT NULL,
`valid_to` text
);
--> statement-breakpoint
CREATE INDEX `cost_item_versions_item_idx` ON `cost_item_versions` (`item_id`);--> statement-breakpoint
CREATE TABLE `cost_snapshots` (
`day` text NOT NULL,
`key` text NOT NULL,
`name` text NOT NULL,
`currency` text NOT NULL,
`monthly` real NOT NULL,
PRIMARY KEY(`day`, `key`)
);
File diff suppressed because it is too large. Load diff
+7
View File
@@ -596,6 +596,13 @@
"when": 1793830559784,
"tag": "0084_soft_ezekiel",
"breakpoints": true
},
{
"idx": 85,
"version": "6",
"when": 1793832143749,
"tag": "0085_broad_skrulls",
"breakpoints": true
}
]
}
+33
View File
@@ -1299,6 +1299,39 @@ export const costItems = sqliteTable("cost_items", {
updatedAt: text("updated_at").notNull(), // ISO
});
// What an item on the Costs page was at each time: one row for each stretch in which its name, amount, currency, period and kind were what they are, opened when it is added or changed and closed (validTo)
// when it is changed again or removed. It is what lets the Costs page say what the homelab cost in a past month, and what changed. `itemId` is a soft reference: the row stays when the item is removed.
// Kept in step with cost_items by services/costHistory.ts, which also fills it in for items that were there before it existed (from the day each was added).
export const costItemVersions = sqliteTable(
"cost_item_versions",
{
id: integer("id").primaryKey({ autoIncrement: true }),
itemId: integer("item_id").notNull(),
name: text("name").notNull(),
amount: real("amount").notNull(), // per period, including VAT
currency: text("currency").notNull(),
period: text("period").notNull(), // month | year
category: text("category").notNull(),
validFrom: text("valid_from").notNull(), // ISO
validTo: text("valid_to"), // ISO; null: still in force
},
(t) => [index("cost_item_versions_item_idx").on(t.itemId)],
);
// What can be read rather than typed (a Hetzner project's monthly estimate) as it was on each day, one row for each day and source, written once a day: the estimate moves with the servers, and the
// estimate of a past month cannot be worked out afterwards. `key` is the source ("hetzner:3"). Read by services/costHistory.ts.
export const costSnapshots = sqliteTable(
"cost_snapshots",
{
day: text("day").notNull(), // YYYY-MM-DD (UTC)
key: text("key").notNull(),
name: text("name").notNull(),
currency: text("currency").notNull(),
monthly: real("monthly").notNull(), // per month, including VAT, at list prices
},
(t) => [primaryKey({ columns: [t.day, t.key] })],
);
// ─── Speedtest Tracker ──────────────────────────────────────────────────────
// The speed tests a Speedtest Tracker (an integration of type "speedtest") has made, one row for each, kept for 90 days: when, how fast down and up (bits per second) and the ping (ms).
+2
View File
@@ -46,6 +46,7 @@ import { initAdguardSync } from "./services/adguardSync.js";
import { initTechnitiumSync } from "./services/technitiumSync.js";
import { initDownloadsSync } from "./services/downloadsSync.js";
import { initHetznerRobotSync } from "./services/hetznerRobotSync.js";
import { initCostHistory } from "./services/costHistory.js";
import { initGrafanaSync } from "./services/grafanaSync.js";
import { initVersionCheck } from "./services/appVersions.js";
import { backfillMetricRollups } from "./services/serverMetrics.js";
@@ -115,6 +116,7 @@ initAdguardSync();
initTechnitiumSync();
initDownloadsSync();
initHetznerRobotSync();
initCostHistory();
initGrafanaSync();
initVersionCheck();
// The hourly and daily figures are built from what is already kept, once, the first time after they were added (in the background: nothing waits for it).
+20
View File
@@ -6,6 +6,7 @@ import { costItems } from "../db/schema.js";
import { requireAuth, requireRole } from "../auth/middleware.js";
import { recordAudit } from "../services/audit.js";
import { automaticCosts, costTotals, DEFAULT_CATEGORIES, isYmd, listCostItems, monthlyOf, nextRenewal, PERIODS, type CostRow } from "../services/costs.js";
import { buildHistory, reconcileVersions } from "../services/costHistory.js";
import { localDate } from "../services/agenda.js";
import { getSettings } from "../services/settingsStore.js";
import { asyncHandler } from "../utils/asyncHandler.js";
@@ -54,12 +55,29 @@ costsRouter.get("/", asyncHandler(async (_req, res) => {
});
}));
/** What it cost, month by month, for each currency (from the first month there is anything to say about, at most `months` back), and what changed: items added, changed and removed, and an estimate that moved. Everyone signed in can see it. */
costsRouter.get("/history", asyncHandler(async (req, res) => {
const asked = Number(req.query.months);
const months = Number.isInteger(asked) && asked >= 1 && asked <= 36 ? asked : 12;
res.json(await buildHistory(Date.now(), months));
}));
/** The history keeps in step with the items; a failure there never stops an item being saved. */
async function keepHistory() {
try {
await reconcileVersions();
} catch (err) {
console.error("[costs] couldn't update the cost history:", err);
}
}
costsRouter.post("/", requireRole("admin"), asyncHandler(async (req, res) => {
const parsed = body.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: "invalid_body", message: "Give it a name, an amount above zero, a three-letter currency (EUR, SEK …) and say whether it is per month or per year." });
const now = new Date().toISOString();
const [created] = await db.insert(costItems).values({ ...parsed.data, renewsOn: parsed.data.renewsOn ?? null, note: parsed.data.note ?? null, createdAt: now, updatedAt: now }).returning();
await recordAudit({ actor: req.currentUser!, category: "cost", action: "create", targetType: "cost", targetId: created.id, detail: { name: created.name, amount: created.amount, currency: created.currency, period: created.period } });
await keepHistory();
res.status(201).json({ id: created.id });
}));
@@ -71,6 +89,7 @@ costsRouter.put("/:id", requireRole("admin"), asyncHandler(async (req, res) => {
const [updated] = await db.update(costItems).set({ ...parsed.data, renewsOn: parsed.data.renewsOn ?? null, note: parsed.data.note ?? null, updatedAt: new Date().toISOString() }).where(eq(costItems.id, id)).returning();
if (!updated) return res.status(404).json({ error: "not_found" });
await recordAudit({ actor: req.currentUser!, category: "cost", action: "update", targetType: "cost", targetId: id, detail: { name: updated.name, amount: updated.amount, currency: updated.currency, period: updated.period } });
await keepHistory();
res.json({ id });
}));
@@ -80,5 +99,6 @@ costsRouter.delete("/:id", requireRole("admin"), asyncHandler(async (req, res) =
const [removed] = await db.delete(costItems).where(eq(costItems.id, id)).returning();
if (!removed) return res.status(404).json({ error: "not_found" });
await recordAudit({ actor: req.currentUser!, category: "cost", action: "delete", targetType: "cost", targetId: id, detail: { name: removed.name } });
await keepHistory();
res.status(204).end();
}));
+204
View File
@@ -0,0 +1,204 @@
/**
* What the homelab cost in the past, and what changed. The Costs page only ever knew what is paid *now*; this keeps what was, in two ways:
*
* - **Items typed in.** Each item's name, amount, currency, period and kind are kept as a series of versions (`cost_item_versions`): one is opened when the item is added, closed and a new one opened when
* any of those change, and closed when the item is removed. A month's figure is then worked out afterwards from what was in force at the month's end (today, for the month that is not over) — so an
* item that was dearer last spring, or that has since been removed, is in the figures of the months it was there. Items that were there before this existed are given a version from the day each was
* added, at the amount it has now: whatever it was before that is not known.
* - **Estimates that are read.** A Hetzner project's estimate moves with its servers and cannot be worked out afterwards, so it is written down once a day (`cost_snapshots`); a month's figure is the last
* day written in it. It starts when the first one was written.
*
* Nothing is converted between currencies, as everywhere on the Costs page: each currency has its own series. Yearly items count one twelfth a month, as the page's own totals do.
*/
import { isNull, eq } from "drizzle-orm";
import { db } from "../db/client.js";
import { costItems, costItemVersions, costSnapshots } from "../db/schema.js";
import { automaticCosts, monthlyOf } from "./costs.js";
import { getInternalFlag, setInternalFlag } from "./settingsStore.js";
export type VersionRow = typeof costItemVersions.$inferSelect;
export type SnapshotRow = typeof costSnapshots.$inferSelect;
const START_FLAG = "costHistoryStartedAt";
const round2 = (n: number) => Math.round(n * 100) / 100;
// ─── Keeping the versions and the snapshots ─────────────────────────────────
type Fields = Pick<VersionRow, "name" | "amount" | "currency" | "period" | "category">;
const same = (a: Fields, b: Fields) => a.name === b.name && a.amount === b.amount && a.currency === b.currency && a.period === b.period && a.category === b.category;
async function reconcile(now: Date): Promise<void> {
const at = now.toISOString();
const items = await db.select().from(costItems);
const open = await db.select().from(costItemVersions).where(isNull(costItemVersions.validTo));
const openByItem = new Map(open.map((v) => [v.itemId, v]));
const alive = new Set(items.map((i) => i.id));
for (const v of open) if (!alive.has(v.itemId)) await db.update(costItemVersions).set({ validTo: at }).where(eq(costItemVersions.id, v.id));
for (const i of items) {
const v = openByItem.get(i.id);
if (v && same(v, i)) continue;
if (v) await db.update(costItemVersions).set({ validTo: at }).where(eq(costItemVersions.id, v.id));
// The first version of an item is from the day it was added; a later one from now.
await db.insert(costItemVersions).values({ itemId: i.id, name: i.name, amount: i.amount, currency: i.currency, period: i.period, category: i.category, validFrom: v ? at : i.createdAt, validTo: null });
}
}
let chain: Promise<void> = Promise.resolve();
/** Brings the versions in step with the items (an item added, changed or removed). One at a time, so two callers cannot both open the same version. */
export function reconcileVersions(now: Date = new Date()): Promise<void> {
chain = chain.catch(() => undefined).then(() => reconcile(now));
return chain;
}
/** Writes down today's estimate of everything that is read rather than typed (once a day for each: a second time the same day replaces the first). */
export async function snapshotAutomatic(now: Date = new Date()): Promise<number> {
const day = now.toISOString().slice(0, 10);
const list = await automaticCosts(now.getTime());
for (const a of list) {
await db.insert(costSnapshots).values({ day, key: a.key, name: a.name, currency: a.currency, monthly: a.monthly }).onConflictDoUpdate({ target: [costSnapshots.day, costSnapshots.key], set: { name: a.name, currency: a.currency, monthly: a.monthly } });
}
return list.length;
}
// ─── Working out the months and the changes ─────────────────────────────────
export interface MonthPoint {
month: string; // YYYY-MM
/** The month's figure per month, in this currency: the items typed in plus the estimates read. */
monthly: number;
manual: number;
automatic: number;
}
export interface CurrencySeries {
currency: string;
points: MonthPoint[];
}
const monthOf = (ms: number) => new Date(ms).toISOString().slice(0, 7);
const monthStart = (month: string) => Date.UTC(Number(month.slice(0, 4)), Number(month.slice(5, 7)) - 1, 1);
const nextMonth = (month: string) => monthOf(Date.UTC(Number(month.slice(0, 4)), Number(month.slice(5, 7)), 1));
/** Pure: the months from `first` to `last`, both included. */
export function monthsBetween(first: string, last: string): string[] {
const out: string[] = [];
for (let m = first; m <= last && out.length < 600; m = nextMonth(m)) out.push(m);
return out;
}
/**
* Pure: the figure for each month, per currency — from the first month there is anything to say about (at most `maxMonths` back from the month `nowMs` is in). An item counts in a month if it was in
* force at the month's end (at `nowMs` for the month that is not over); an estimate counts as of the last day written in the month.
*/
export function monthlySeries(versions: VersionRow[], snapshots: SnapshotRow[], nowMs: number, maxMonths = 12): { months: string[]; series: CurrencySeries[] } {
const earliest = Math.min(...versions.map((v) => Date.parse(v.validFrom)), ...snapshots.map((s) => Date.parse(`${s.day}T00:00:00Z`)));
if (!Number.isFinite(earliest)) return { months: [], series: [] };
const current = monthOf(nowMs);
const oldestAllowed = monthsBetween(monthOf(Date.UTC(new Date(nowMs).getUTCFullYear(), new Date(nowMs).getUTCMonth() - (maxMonths - 1), 1)), current)[0];
const months = monthsBetween(monthOf(earliest) > oldestAllowed ? monthOf(earliest) : oldestAllowed, current);
const manual = new Map<string, Map<string, number>>(); // currency → month → figure
const automatic = new Map<string, Map<string, number>>();
const bump = (into: Map<string, Map<string, number>>, currency: string, month: string, n: number) => {
const byMonth = into.get(currency) ?? new Map<string, number>();
byMonth.set(month, (byMonth.get(month) ?? 0) + n);
into.set(currency, byMonth);
};
for (const month of months) {
const at = Math.min(monthStart(nextMonth(month)) - 1, nowMs);
for (const v of versions) {
if (Date.parse(v.validFrom) <= at && (v.validTo === null || Date.parse(v.validTo) > at)) bump(manual, v.currency, month, monthlyOf(v.amount, v.period));
}
const day = new Date(at).toISOString().slice(0, 10);
const latest = new Map<string, SnapshotRow>();
for (const s of snapshots) {
if (!s.day.startsWith(month) || s.day > day) continue;
const kept = latest.get(s.key);
if (!kept || s.day > kept.day) latest.set(s.key, s);
}
for (const s of latest.values()) bump(automatic, s.currency, month, s.monthly);
}
const currencies = new Set([...manual.keys(), ...automatic.keys()]);
const series = [...currencies].map((currency) => ({
currency,
points: months.map((month) => {
const m = manual.get(currency)?.get(month) ?? 0;
const a = automatic.get(currency)?.get(month) ?? 0;
return { month, monthly: round2(m + a), manual: round2(m), automatic: round2(a) };
}),
}));
series.sort((a, b) => b.points[b.points.length - 1].monthly - a.points[a.points.length - 1].monthly || a.currency.localeCompare(b.currency));
return { months, series };
}
export interface CostEvent {
/** ISO. */
at: string;
/** added and removed are items typed in; changed is one of them edited (what was and what is are both given); estimate is a read estimate that moved. */
kind: "added" | "changed" | "removed" | "estimate";
name: string;
amount: number;
currency: string;
period: string;
category: string;
/** For changed (and estimate): what it was before. */
from: Fields | null;
}
/** Pure: what happened, newest first — items added, changed and removed, and a read estimate moving by a cent or more from one day to the next. */
export function costEvents(versions: VersionRow[], snapshots: SnapshotRow[], limit = 50): CostEvent[] {
const out: CostEvent[] = [];
const byItem = new Map<number, VersionRow[]>();
for (const v of versions) byItem.set(v.itemId, [...(byItem.get(v.itemId) ?? []), v]);
for (const list of byItem.values()) {
list.sort((a, b) => Date.parse(a.validFrom) - Date.parse(b.validFrom) || a.id - b.id);
list.forEach((v, k) => {
const fields = { name: v.name, amount: v.amount, currency: v.currency, period: v.period, category: v.category };
if (k === 0) out.push({ at: v.validFrom, kind: "added", ...fields, from: null });
else {
const p = list[k - 1];
out.push({ at: v.validFrom, kind: "changed", ...fields, from: { name: p.name, amount: p.amount, currency: p.currency, period: p.period, category: p.category } });
}
// A version closed with none after it is an item that was removed.
if (k === list.length - 1 && v.validTo !== null) out.push({ at: v.validTo, kind: "removed", ...fields, from: null });
});
}
const byKey = new Map<string, SnapshotRow[]>();
for (const s of snapshots) byKey.set(s.key, [...(byKey.get(s.key) ?? []), s]);
for (const list of byKey.values()) {
list.sort((a, b) => a.day.localeCompare(b.day));
for (let k = 1; k < list.length; k++) {
const p = list[k - 1];
const s = list[k];
if (p.currency !== s.currency || Math.abs(round2(s.monthly) - round2(p.monthly)) < 0.01) continue;
out.push({ at: `${s.day}T12:00:00.000Z`, kind: "estimate", name: s.name, amount: round2(s.monthly), currency: s.currency, period: "month", category: "Hosting", from: { name: p.name, amount: round2(p.monthly), currency: p.currency, period: "month", category: "Hosting" } });
}
}
return out.sort((a, b) => Date.parse(b.at) - Date.parse(a.at)).slice(0, limit);
}
export async function buildHistory(nowMs: number = Date.now(), maxMonths = 12) {
await reconcileVersions(new Date(nowMs));
const [versions, snapshots, startedAt] = await Promise.all([db.select().from(costItemVersions), db.select().from(costSnapshots), getInternalFlag(START_FLAG)]);
return { ...monthlySeries(versions, snapshots, nowMs, maxMonths), events: costEvents(versions, snapshots), startedAt };
}
// ─── Keeping it going ───────────────────────────────────────────────────────
let timer: ReturnType<typeof setInterval> | null = null;
export function initCostHistory(): void {
if (timer) return;
const pass = async () => {
try {
if (!(await getInternalFlag(START_FLAG))) await setInternalFlag(START_FLAG, new Date().toISOString());
await reconcileVersions();
await snapshotAutomatic();
} catch (err) {
console.error("[costs] couldn't keep the history:", err);
}
};
// Every six hours is enough: the estimate is written once a day (a later pass the same day replaces the first), and the versions are also brought up to date whenever an item is saved.
timer = setInterval(() => void pass(), 6 * 60 * 60_000);
setTimeout(() => void pass(), 50_000);
console.log("[costs] keeping the cost history");
}
+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));
});
});