screentinker/server/test/billing-endpoint.test.js
ScreenTinker 977407ce99 feat(#146): usage metering + admin-gated Billable Screens report (contract system-of-record)
Implements the ByteTinker-Bold distribution-agreement billing math and surfaces it on a
standalone admin-only route. No UI (the API figure is the deliverable). Server-side only.

Contract math (lib/billing.js, config-driven; defaults ARE the agreement):
- ASD (per device/day) = min(1.0, online_seconds / (hours*3600))   # 28800 default
- BillableScreens (per month) = round-half-up( Sum ASD / days_in_month )
- Flat tier (not marginal): 1-499 $1.50 / 500-999 $1.25 / 1000+ $1.00; cost = screens*rate.
Single global rate card for now (per-tenant is a future concern; noted in code).

Data foundation:
- New durable rollup device_usage_daily(device_id, day 'YYYY-MM-DD', online_seconds),
  index on day. status_log (3d) / telemetry (24h) can't back a billing month.
- Accumulated INCREMENTALLY off the heartbeat tick from the live connection map (same
  source as devices_connected) - never reconstructed from logs. Each tick credits every
  connected device's today-row (min(86400, +elapsed)), chunked + transactional (non-blocking);
  per-tick credit capped (accrualCapSeconds) as a stall/restart guard.
- Retention ~400d, pruned via chunked-prune (pruneUsageDaily in runMaintenance).

API: GET /api/billing/usage?month=YYYY-MM (default current), requirePlatformAdmin, mounted
SEPARATELY from /api/status (billing is revenue data + a heavier aggregate; must not touch
the hot status path). Reads the rollup only. MTD figure averages over COMPLETED days only
(today shown in `daily` but excluded until it completes); is_final + billable_screens_final
appear once the month completes.

Tests (12): ASD math; billable round-half-up; flat tier/cost boundaries; accumulator
(accrues by interval, caps at 86400/day, disconnected doesn't accrue); report MTD-excludes-
today + final-month is_final; retention prune; endpoint authz (admin 200 / non-admin 403 /
anon 401) + billing absent from /api/status. Suite 301/301. First-full-month caveat +
formula in docs/billing.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-01 20:45:27 -05:00

73 lines
3.7 KiB
JavaScript

'use strict';
// #146 BILLING — endpoint authz + route isolation. Booted server + JWT + DB access.
// Asserts: admin can GET /api/billing/usage (200), non-admin 403 / anon 401, and billing
// is NOT present on the public /api/status (it lives on a SEPARATE route).
const { test, before, after } = require('node:test');
const assert = require('node:assert/strict');
const { spawn } = require('node:child_process');
const path = require('node:path');
const os = require('node:os');
const fs = require('node:fs');
const crypto = require('node:crypto');
const Database = require('better-sqlite3');
const PORT = 3999;
const BASE = `http://127.0.0.1:${PORT}`;
const DATA_DIR = path.join(os.tmpdir(), 'st-billing-ep-' + crypto.randomBytes(4).toString('hex'));
let proc, db;
before(async () => {
const logFd = fs.openSync(path.join(os.tmpdir(), 'st-billing-ep.log'), 'w');
proc = spawn('node', ['server.js'], {
cwd: path.join(__dirname, '..'),
env: { ...process.env, DATA_DIR, SELF_HOSTED: 'true', PORT: String(PORT), NODE_ENV: 'test' },
stdio: ['ignore', logFd, logFd],
});
let up = false;
for (let i = 0; i < 80; i++) { try { const r = await fetch(BASE + '/api/status'); if (r.ok) { up = true; break; } } catch { /* */ } await new Promise(r => setTimeout(r, 250)); }
if (!up) throw new Error('server did not boot');
db = new Database(path.join(DATA_DIR, 'db', 'remote_display.db'));
});
after(() => { try { db && db.close(); } catch { /* */ } try { proc.kill('SIGKILL'); } catch { /* */ } });
const reg = (o) => ({ method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(o) });
const auth = (tok) => (tok ? { headers: { Authorization: 'Bearer ' + tok } } : {});
test('admin can GET /api/billing/usage; returns a current-month report', async () => {
const email = 'bad' + crypto.randomBytes(4).toString('hex') + '@x.local';
const tok = (await (await fetch(BASE + '/api/auth/register', reg({ email, password: 'Passw0rd123' }))).json()).token;
db.prepare("UPDATE users SET role = 'platform_admin' WHERE email = ?").run(email);
const r = await fetch(BASE + '/api/billing/usage', auth(tok));
assert.equal(r.status, 200);
const b = await r.json();
assert.match(b.month, /^\d{4}-\d{2}$/, 'current month by default');
assert.equal(typeof b.billable_screens, 'number');
assert.equal(typeof b.provisioned_screens, 'number');
assert.equal(typeof b.cost_usd, 'number');
assert.ok(Array.isArray(b.daily), 'daily breakdown present');
assert.equal(b.is_final, false, 'current month is not final');
// a specific month is accepted; a bad month is 400
assert.equal((await fetch(BASE + '/api/billing/usage?month=2025-02', auth(tok))).status, 200);
assert.equal((await fetch(BASE + '/api/billing/usage?month=2025-13', auth(tok))).status, 400);
});
test('non-admin gets 403, anonymous gets 401', async () => {
const email = 'bu' + crypto.randomBytes(4).toString('hex') + '@x.local';
const tok = (await (await fetch(BASE + '/api/auth/register', reg({ email, password: 'Passw0rd123' }))).json()).token;
assert.equal((await fetch(BASE + '/api/billing/usage', auth(tok))).status, 403, 'non-admin denied');
assert.equal((await fetch(BASE + '/api/billing/usage')).status, 401, 'anon denied');
});
test('billing is NOT on public /api/status (separate route; no revenue data leaks)', async () => {
const b = await (await fetch(BASE + '/api/status')).json();
assert.equal(typeof b.devices_connected, 'number', 'devices_connected stays public');
for (const k of ['billing', 'billable_screens', 'cost_usd', 'rate_usd', 'provisioned_screens']) {
assert.equal(k in b, false, `/api/status must not expose ${k}`);
if (b.debug) assert.equal(k in b.debug, false, `/api/status.debug must not expose ${k}`);
}
});