@arnaudjnn/billing-tools 2.19.0 → 3.0.0

package/dist/usage-counters.js

@@ -1,214 +0,0 @@
-// Counting usage as COUNTERS rather than as events — the scale-correct store, and
-// the one that works without SQL.
-//
-// ── Why counters, when `postgresUsageLedger` already works ──────────────────
-//
-// Because of what the seam is actually asked. Every read in this library is the
-// same shape — `sum(cost) where org, [start, end), callerKind?, callerId?` — and
-// every window is FIXED and UTC-aligned (`rateWindowFor`, `cycleWindowFor`). An
-// append-only event log answers that by aggregating a range on the hot path of
-// every metered call, over a table that grows by one row per call forever. At the
-// volumes a plan actually declares (an Enterprise window of 200 000 credits a
-// week) that is millions of rows a month whose only purpose is to be summed back
-// into a handful of integers, plus the retention and partitioning work that
-// follows.
-//
-// Counters answer it with a point read. One row per (org, scope, hour), so a
-// caller making a thousand calls in an hour writes ONE row instead of a thousand,
-// and the row count is bounded by time rather than by traffic.
-//
-// ── Why HOURLY buckets rather than one counter per declared window ──────────
-//
-// A counter keyed by the plan's own windows would be smaller still, but `record`
-// would have to know which windows exist — and a window it failed to bump is
-// usage counted by nothing, which reads as 0% and refuses no one. That failure
-// looks like generosity, which is the exact class of defect this file is written
-// to avoid. Bucketing by a fixed grain instead means `record` needs no plan
-// knowledge at all: it bumps the bucket the event falls in, and `total` sums the
-// buckets its window covers. Any window is answerable, including one added to the
-// config later.
-//
-// An hour is the grain because `every: "hour"` is the tightest window the plan
-// model can express, so it is the finest anything can ask for. A month is then at
-// most 744 keys in ONE batched read.
-//
-// ── What this gives up ──────────────────────────────────────────────────────
-//
-// The audit trail. A counter cannot say WHICH actions made up a total, or when
-// inside the hour. `postgresUsageLedger` keeps that and stays the right choice for
-// a consumer who wants per-action history; the two satisfy the same seam, so a
-// deployment can even write to both.
-/** Milliseconds in the bucket grain. The tightest window a plan can declare. */
-export const BUCKET_MS = 3_600_000;
-/** The bucket an instant falls in: hours since the epoch, UTC-aligned. */
-export const bucketOf = (atMs) => Math.floor(atMs / BUCKET_MS);
-/**
- * WHOSE counter. Derived identically on the write and read paths, which is the
- * whole contract — a `total` that computed a different scope string from the same
- * caller would read a counter nobody writes, and report 0 forever.
- *
- * `org` is every call in the workspace. A caller kind with no id is every caller
- * of that kind (how a shared API seat is measured); with an id it is one member.
- */
-export function scopeOf(filter) {
-    if (filter?.callerId)
-        return `u:${filter.callerId}`;
-    if (filter?.callerKind)
-        return `k:${filter.callerKind}`;
-    return "org";
-}
-/** Every scope a single event counts toward. An event is counted once per scope,
- *  so an org-wide read and a per-member read both see it. */
-export function scopesFor(event) {
-    const scopes = ["org"];
-    if (event.caller?.kind)
-        scopes.push(`k:${event.caller.kind}`);
-    if (event.caller?.id)
-        scopes.push(`u:${event.caller.id}`);
-    return scopes;
-}
-/** `org|scope|bucket` — derivable from either side, so no index is needed to find
- *  a counter and a KV store works as well as a table. */
-export const counterKey = (orgId, scope, bucket) => `${orgId}|${scope}|${bucket}`;
-/**
- * A `UsageLedger` backed by counters. Counts EVERYTHING — included and
- * wallet-funded, org-wide and per member — which is what `covers` declares.
- */
-export function counterUsageLedger(store, opts = {}) {
-    const retentionMs = opts.retentionMs ?? 400 * 86_400_000;
-    const maxKeys = Math.max(1, opts.maxKeysPerRead ?? 8_784);
-    return {
-        covers: { orgIncluded: true, callerIncluded: true },
-        async record(event) {
-            if (!event.cost)
-                return; // a free call moves no counter
-            const at = event.at ?? Date.now();
-            const bucket = bucketOf(at);
-            const keys = scopesFor(event).map((s) => counterKey(event.orgId, s, bucket));
-            // One call for every scope: a store can pipeline them, and a table can do it
-            // in a single multi-row upsert.
-            await store.add(keys, event.cost, at + retentionMs);
-        },
-        async total(query) {
-            // [start, end): the half-open window this library defines everywhere. The
-            // END bucket is inclusive when the window ends mid-bucket, because an event
-            // in that hour may fall inside the window — a counter cannot say where in
-            // the hour it happened, so it is counted. The overshoot is bounded by one
-            // bucket and only ever at the CURRENT edge, where the alternative is to
-            // ignore the usage that just happened.
-            const from = bucketOf(query.start);
-            const to = bucketOf((query.end ?? Date.now()) - 1);
-            if (to < from)
-                return 0;
-            const scope = scopeOf(query.filter);
-            const keys = [];
-            // Newest-first when clamped, so a window wider than the cap keeps the slice
-            // that decides whether the NEXT call is allowed.
-            const first = Math.max(from, to - maxKeys + 1);
-            for (let b = first; b <= to; b++)
-                keys.push(counterKey(query.orgId, scope, b));
-            return store.sum(keys);
-        },
-    };
-}
-// ── Backends ────────────────────────────────────────────────────────────────
-/** The table + the one index its read uses. Idempotent, so it is safe to run from
- *  a migration on every deploy. Bounded by (orgs × scopes × hours kept), not by
- *  traffic — the reason to prefer it over `usage_events` at volume. */
-export const USAGE_COUNTERS = `
-CREATE TABLE IF NOT EXISTS usage_counters (
-  key   text PRIMARY KEY,
-  used  bigint NOT NULL,
-  -- Kept for bulk expiry; the read never filters on it.
-  stale timestamptz
-);
-CREATE INDEX IF NOT EXISTS usage_counters_stale_idx ON usage_counters (stale);
-`;
-/** @deprecated Renamed to `USAGE_COUNTERS`, alongside `USAGE_EVENTS`. */
-export const USAGE_COUNTERS_DDL = USAGE_COUNTERS;
-export async function ensureUsageCountersTable(client) {
-    await client.query(USAGE_COUNTERS);
-}
-/**
- * Counters in Postgres: one upsert per scope on write, one `SUM` over a primary-key
- * lookup on read.
- *
- * `used = usage_counters.used + excluded.used` is the atomic increment — the row
- * lock is held for the statement, so concurrent calls serialise instead of losing
- * one another's writes.
- */
-export function sqlUsageCounters(client) {
-    return {
-        async add(keys, amount, expiresAtMs) {
-            if (!keys.length)
-                return;
-            // One statement for every scope: unnest the keys rather than issuing N
-            // round trips on the hot path.
-            await client.query(`INSERT INTO usage_counters (key, used, stale)
-         SELECT k, $2::bigint, $3::timestamptz FROM unnest($1::text[]) AS k
-         ON CONFLICT (key) DO UPDATE
-           SET used = usage_counters.used + excluded.used,
-               stale = GREATEST(usage_counters.stale, excluded.stale)`, [keys, amount, expiresAtMs == null ? null : new Date(expiresAtMs).toISOString()]);
-        },
-        async sum(keys) {
-            if (!keys.length)
-                return 0;
-            const r = await client.query(`SELECT COALESCE(SUM(used), 0) AS total
-           FROM usage_counters WHERE key = ANY($1::text[])`, [keys]);
-            // bigint comes back as a string from `pg`; Number is exact to 2^53, far
-            // beyond any credit total.
-            return Number(r.rows[0]?.total ?? 0) || 0;
-        },
-    };
-}
-/** Delete expired buckets. Call it from a cron; nothing depends on it running —
- *  a stale bucket is simply never read once its window has passed. */
-export async function pruneUsageCounters(client, now = Date.now()) {
-    await client.query(`DELETE FROM usage_counters WHERE stale IS NOT NULL AND stale < $1`, [
-        new Date(now).toISOString(),
-    ]);
-}
-/**
- * Counters in Redis: `INCRBY` per scope, one `MGET` per read.
- *
- * The expiry is set on every write rather than only on create. `PEXPIREAT` is
- * idempotent and one round trip, whereas checking first is two and races — and a
- * bucket that lost its expiry is a leak that only shows up as memory months later.
- */
-export function redisUsageCounters(client) {
-    return {
-        async add(keys, amount, expiresAtMs) {
-            await Promise.all(keys.map(async (key) => {
-                await client.incrby(key, amount);
-                if (expiresAtMs != null && client.pexpireat)
-                    await client.pexpireat(key, expiresAtMs);
-            }));
-        },
-        async sum(keys) {
-            if (!keys.length)
-                return 0;
-            const values = await client.mget(keys);
-            return values.reduce((acc, v) => acc + (v == null ? 0 : Number(v) || 0), 0);
-        },
-    };
-}
-/** In-memory counters, for tests and single-process development. Not for a
- *  deployment with more than one instance: each would count its own share, and the
- *  gate would allow the sum of every instance's window. */
-export function memoryUsageCounters() {
-    const map = new Map();
-    return {
-        map,
-        async add(keys, amount) {
-            for (const key of keys)
-                map.set(key, (map.get(key) ?? 0) + amount);
-        },
-        async sum(keys) {
-            let total = 0;
-            for (const key of keys)
-                total += map.get(key) ?? 0;
-            return total;
-        },
-    };
-}
-//# sourceMappingURL=usage-counters.js.map

package/dist/usage-counters.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"usage-counters.js","sourceRoot":"","sources":["../src/usage-counters.ts"],"names":[],"mappings":"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"}