fest-gateway 0.1.0

package/dist/server/store/write.js

@@ -0,0 +1,330 @@
+/**
+ * The metering write path.
+ *
+ * Called from the flush side of the usage queue, never from a proxied request
+ * (see the constraint comment in db.ts — `DatabaseSync` blocks the event loop).
+ * One batch is one transaction, and inside it each record writes both its raw
+ * `requests` row and its `usage_hourly` rollups, so the rollups can never
+ * disagree with the rows they summarise.
+ *
+ * Two principles run through this file:
+ *
+ *  1. METERING MUST DEGRADE, NEVER TAKE DOWN THE PROXY. A malformed record is
+ *     logged and skipped; it never fails its batch and never escapes as an
+ *     exception into the caller. Losing one row of observability is a nuisance;
+ *     killing the gateway that developers are actively coding against is an
+ *     outage.
+ *  2. COST IS REPORTED HONESTLY. `costUsd === null` means "no dollar figure
+ *     applies", not zero, and the rollup keeps three separate facts so that
+ *     distinction survives aggregation.
+ */
+import { isErrorStatus } from "../../shared/types.js";
+import { log } from "../log.js";
+const HOUR_MS = 3_600_000;
+/** Epoch ms truncated to the start of its UTC hour. */
+export function hourStart(epochMs) {
+    return Math.floor(epochMs / HOUR_MS) * HOUR_MS;
+}
+/**
+ * Fixed latency histogram buckets: <1s, <3s, <10s, <30s, <60s, >=60s.
+ *
+ * Buckets rather than percentiles because bucket counts ADD across rollup rows
+ * and percentiles do not: p95-of-p95s is not a number that means anything.
+ */
+export function latencyBucket(durationMs) {
+    if (durationMs < 1_000)
+        return 0;
+    if (durationMs < 3_000)
+        return 1;
+    if (durationMs < 10_000)
+        return 2;
+    if (durationMs < 30_000)
+        return 3;
+    if (durationMs < 60_000)
+        return 4;
+    return 5;
+}
+/** '' is the "all" bucket sentinel for a rollup dimension (see 001-init.sql). */
+const ALL = "";
+const INSERT_REQUEST = `
+INSERT INTO requests (
+  id, org_id, user_id, token_id,
+  started_at, ended_at,
+  posture, identity_carrier, caller_fingerprint, credential_fingerprint, credential_origin,
+  session_id,
+  requested_model, served_model, upstream,
+  stream, status, http_status, error_type, error_message, partial,
+  input_tokens, cache_read_tokens, cache_write_5m_tokens, cache_write_1h_tokens,
+  output_tokens, web_searches, service_tier,
+  cost_usd, cost_basis, notional_cost_usd,
+  ttfb_ms, duration_ms, bytes_in, bytes_out,
+  upstream_request_id,
+  rl_status, rl_5h_utilization, rl_5h_status, rl_5h_reset_at,
+  rl_7d_utilization, rl_7d_status, rl_7d_reset_at,
+  rl_claim, rl_overage_status, rl_overage_reason,
+  client_version,
+  pipeline, route_id, credentials_considered
+) VALUES (
+  :id, :org_id, :user_id, :token_id,
+  :started_at, :ended_at,
+  :posture, :identity_carrier, :caller_fingerprint, :credential_fingerprint, :credential_origin,
+  :session_id,
+  :requested_model, :served_model, :upstream,
+  :stream, :status, :http_status, :error_type, :error_message, :partial,
+  :input_tokens, :cache_read_tokens, :cache_write_5m_tokens, :cache_write_1h_tokens,
+  :output_tokens, :web_searches, :service_tier,
+  :cost_usd, :cost_basis, :notional_cost_usd,
+  :ttfb_ms, :duration_ms, :bytes_in, :bytes_out,
+  :upstream_request_id,
+  :rl_status, :rl_5h_utilization, :rl_5h_status, :rl_5h_reset_at,
+  :rl_7d_utilization, :rl_7d_status, :rl_7d_reset_at,
+  :rl_claim, :rl_overage_status, :rl_overage_reason,
+  :client_version,
+  :pipeline, :route_id, :credentials_considered
+)`;
+const ADDITIVE_COLUMNS = [
+    "requests",
+    "errors",
+    "input_tokens",
+    "cache_read_tokens",
+    "cache_write_5m_tokens",
+    "cache_write_1h_tokens",
+    "output_tokens",
+    "web_searches",
+    "cost_usd",
+    "unpriced_requests",
+    "subscription_requests",
+    "notional_cost_usd",
+    "notional_unpriced_requests",
+    "duration_ms_sum",
+    "ttfb_ms_sum",
+    "ttfb_count",
+    "lat_b0",
+    "lat_b1",
+    "lat_b2",
+    "lat_b3",
+    "lat_b4",
+    "lat_b5",
+];
+const KEY_COLUMNS = [
+    "org_id",
+    "hour_start",
+    "user_id",
+    "served_model",
+    "credential_origin",
+    "cost_basis",
+];
+const ROLLUP_COLUMNS = [...KEY_COLUMNS, ...ADDITIVE_COLUMNS, "duration_ms_max"];
+const UPSERT_ROLLUP = `
+INSERT INTO usage_hourly (${ROLLUP_COLUMNS.join(", ")})
+VALUES (${ROLLUP_COLUMNS.map((c) => ":" + c).join(", ")})
+ON CONFLICT(${KEY_COLUMNS.join(", ")}) DO UPDATE SET
+  ${ADDITIVE_COLUMNS.map((c) => `${c} = ${c} + excluded.${c}`).join(",\n  ")},
+  duration_ms_max = MAX(duration_ms_max, excluded.duration_ms_max)`;
+/** Booleans are stored as INTEGER 0/1 per the schema's convention. */
+function bit(value) {
+    return value ? 1 : 0;
+}
+/** `undefined` and missing values collapse to SQL NULL; 0 and '' are preserved. */
+function nullable(value) {
+    return value === undefined ? null : value;
+}
+function requestParams(orgId, record) {
+    const usage = record.usage;
+    const rl = record.rateLimit;
+    const attributed = record;
+    // Read every field eagerly so a malformed record (missing `usage`, say)
+    // throws HERE, before any statement has run, and the skip is clean.
+    return {
+        id: record.id,
+        org_id: orgId,
+        user_id: nullable(attributed.userId),
+        token_id: nullable(attributed.tokenId),
+        started_at: record.startedAt,
+        ended_at: record.endedAt,
+        posture: record.posture,
+        identity_carrier: record.identityCarrier,
+        caller_fingerprint: nullable(record.callerFingerprint),
+        credential_fingerprint: nullable(record.credentialFingerprint),
+        credential_origin: record.credentialOrigin,
+        session_id: nullable(record.sessionId),
+        requested_model: nullable(record.requestedModel),
+        served_model: nullable(record.servedModel),
+        upstream: record.upstream,
+        stream: bit(record.stream),
+        status: record.status,
+        http_status: nullable(record.httpStatus),
+        error_type: nullable(record.errorType),
+        error_message: nullable(record.errorMessage),
+        partial: bit(record.partial),
+        input_tokens: usage.inputTokens,
+        cache_read_tokens: usage.cacheReadTokens,
+        cache_write_5m_tokens: usage.cacheWrite5mTokens,
+        cache_write_1h_tokens: usage.cacheWrite1hTokens,
+        output_tokens: usage.outputTokens,
+        web_searches: usage.webSearches,
+        service_tier: nullable(usage.serviceTier),
+        cost_usd: nullable(record.costUsd),
+        cost_basis: record.costBasis,
+        notional_cost_usd: nullable(record.notionalCostUsd),
+        ttfb_ms: nullable(record.ttfbMs),
+        duration_ms: record.durationMs,
+        bytes_in: record.bytesIn,
+        bytes_out: record.bytesOut,
+        upstream_request_id: nullable(record.upstreamRequestId),
+        rl_status: nullable(rl?.status),
+        rl_5h_utilization: nullable(rl?.fiveHourUtilization),
+        rl_5h_status: nullable(rl?.fiveHourStatus),
+        rl_5h_reset_at: nullable(rl?.fiveHourResetAt),
+        rl_7d_utilization: nullable(rl?.sevenDayUtilization),
+        rl_7d_status: nullable(rl?.sevenDayStatus),
+        rl_7d_reset_at: nullable(rl?.sevenDayResetAt),
+        rl_claim: nullable(rl?.representativeClaim),
+        rl_overage_status: nullable(rl?.overageStatus),
+        rl_overage_reason: nullable(rl?.overageDisabledReason),
+        client_version: nullable(record.clientVersion),
+        pipeline: record.pipeline,
+        route_id: nullable(record.routeId),
+        // Serialised here rather than in the request path: the array is small, but
+        // pricing and persistence both belong in the flush, and this is both.
+        credentials_considered: JSON.stringify(record.credentialsConsidered ?? []),
+    };
+}
+function rollupParams(orgId, record) {
+    const usage = record.usage;
+    const attributed = record;
+    const userId = attributed.userId ?? ALL;
+    // served_model is NOT NULL in the rollup, so an unresolved model lands in the
+    // same '' bucket as "all models". That is a deliberate collapse, and it is
+    // why the four keys below are de-duplicated before writing.
+    const servedModel = record.servedModel ?? ALL;
+    // ── Cost honesty ──────────────────────────────────────────────────────────
+    // Three mutually exclusive facts, because one number cannot carry them:
+    //   cost_usd              dollars the org actually owes, priced rows only
+    //   subscription_requests real usage the developer's own plan absorbed
+    //   unpriced_requests     usage we could not price (unknown model)
+    // Collapsing either counter into cost_usd as 0 would make a dashboard read
+    // "$0.00" for a month of heavy subscription traffic, which is a lie of the
+    // most convincing kind. SUM() over a nullable cost column skips NULLs
+    // silently — that is exactly the understatement this split prevents.
+    const priced = typeof record.costUsd === "number" && Number.isFinite(record.costUsd);
+    const isSubscription = record.costBasis === "subscription";
+    const costUsd = priced ? record.costUsd : 0;
+    const subscriptionRequests = isSubscription ? 1 : 0;
+    // Keyed off `!priced` rather than `costUsd === null` so a non-finite cost
+    // (NaN/Infinity from a bad rate table) is still counted as unpriced. With the
+    // narrower `=== null` test such a record would be excluded from the dollar
+    // sum AND from the n/a count — vanishing from the books entirely, which is
+    // precisely the silent understatement this split exists to prevent.
+    const unpricedRequests = !priced && !isSubscription ? 1 : 0;
+    // Notional value runs on its own books, and the asymmetry is the whole point:
+    // subscription rows are EXCLUDED from cost_usd and INCLUDED here. A model
+    // with no published rate is unknown on both, so it gets the same
+    // lower-bound counter treatment, keyed off `!notionalPriced` for the same
+    // NaN reason as above.
+    const notionalPriced = typeof record.notionalCostUsd === "number" && Number.isFinite(record.notionalCostUsd);
+    const notionalCostUsd = notionalPriced ? (record.notionalCostUsd ?? 0) : 0;
+    const notionalUnpricedRequests = notionalPriced ? 0 : 1;
+    const bucket = latencyBucket(record.durationMs);
+    // ttfb is only summed when it exists, so `ttfb_ms_sum / ttfb_count` is an
+    // average over requests that actually produced a first byte rather than one
+    // diluted by aborts and non-streaming calls.
+    const hasTtfb = typeof record.ttfbMs === "number";
+    const shared = {
+        org_id: orgId,
+        hour_start: hourStart(record.startedAt),
+        credential_origin: record.credentialOrigin,
+        cost_basis: record.costBasis,
+        requests: 1,
+        // Shared with the raw-range predicate in `queries.ts`; see NON_ERROR_STATUSES.
+        errors: isErrorStatus(record.status) ? 1 : 0,
+        input_tokens: usage.inputTokens,
+        cache_read_tokens: usage.cacheReadTokens,
+        cache_write_5m_tokens: usage.cacheWrite5mTokens,
+        cache_write_1h_tokens: usage.cacheWrite1hTokens,
+        output_tokens: usage.outputTokens,
+        web_searches: usage.webSearches,
+        cost_usd: costUsd ?? 0,
+        unpriced_requests: unpricedRequests,
+        subscription_requests: subscriptionRequests,
+        notional_cost_usd: notionalCostUsd,
+        notional_unpriced_requests: notionalUnpricedRequests,
+        duration_ms_sum: record.durationMs,
+        duration_ms_max: record.durationMs,
+        ttfb_ms_sum: hasTtfb ? (record.ttfbMs ?? 0) : 0,
+        ttfb_count: hasTtfb ? 1 : 0,
+        lat_b0: bucket === 0 ? 1 : 0,
+        lat_b1: bucket === 1 ? 1 : 0,
+        lat_b2: bucket === 2 ? 1 : 0,
+        lat_b3: bucket === 3 ? 1 : 0,
+        lat_b4: bucket === 4 ? 1 : 0,
+        lat_b5: bucket === 5 ? 1 : 0,
+    };
+    // Four buckets per record, so every dashboard query is a point lookup or a
+    // narrow range scan instead of a GROUP BY over the raw hot table:
+    //   (user, model)  the specific cell
+    //   (user, '')     one developer, all models
+    //   ('', model)    all developers, one model
+    //   ('', '')       org totals
+    const keys = [
+        [userId, servedModel],
+        [userId, ALL],
+        [ALL, servedModel],
+        [ALL, ALL],
+    ];
+    // De-duplicate: when the record is unattributed (userId '') or its model is
+    // unknown (servedModel ''), two or more of the four keys are the SAME primary
+    // key, and writing both would double-count that record via the upsert's
+    // `col = col + excluded.col`. Do not remove this.
+    const seen = new Set();
+    const rows = [];
+    for (const [u, m] of keys) {
+        const key = `${u}\u0000${m}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        rows.push({ ...shared, user_id: u, served_model: m });
+    }
+    return rows;
+}
+export function createRequestWriter(store) {
+    // Prepared ONCE and reused for the process lifetime. Re-preparing per row is
+    // the difference between roughly 1ms and 50ms for a 200-row batch: parsing
+    // and planning a 46-column INSERT dominates actually executing it.
+    const insertRequest = store.db.prepare(INSERT_REQUEST);
+    const upsertRollup = store.db.prepare(UPSERT_ROLLUP);
+    insertRequest.setAllowBareNamedParameters(true);
+    upsertRollup.setAllowBareNamedParameters(true);
+    return {
+        writeBatch(orgId, records) {
+            if (records.length === 0)
+                return 0;
+            let written = 0;
+            store.transaction(() => {
+                for (const record of records) {
+                    try {
+                        // Build all parameters for this record BEFORE executing anything.
+                        // A malformed record then fails with nothing written, which keeps
+                        // the row/rollup invariant without needing a SAVEPOINT per row.
+                        const reqParams = requestParams(orgId, record);
+                        const rollups = rollupParams(orgId, record);
+                        insertRequest.run(reqParams);
+                        for (const rollup of rollups)
+                            upsertRollup.run(rollup);
+                        written += 1;
+                    }
+                    catch (err) {
+                        // Per-record, inside the transaction: one bad record must not cost
+                        // us the other 199. The batch still commits.
+                        log.warn("usage record skipped", {
+                            id: typeof record?.id === "string" ? record.id : "<unknown>",
+                            err: String(err),
+                        });
+                    }
+                }
+            });
+            return written;
+        },
+    };
+}
+//# sourceMappingURL=write.js.map

package/dist/server/store/write.js.map

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

package/dist/server/usage/accumulator.js

@@ -0,0 +1,209 @@
+/**
+ * Folds Anthropic SSE events into a single UsagePayload.
+ *
+ * The whole point of this module is one rule, so it is stated up front:
+ *
+ *   USAGE FIELDS ARE LAST-WINS. THEY ARE NEVER SUMMED.
+ *
+ * `message_delta.usage.output_tokens` is the FINAL CUMULATIVE count for the
+ * message, re-sent (and revised upward) on each delta. Adding deltas together
+ * over-counts output by roughly the number of deltas — the classic 10x
+ * over-billing bug. If you are here because totals look low, the fix is
+ * somewhere else; do not turn these assignments into `+=`.
+ *
+ * Secondly, this code runs on a proxied request that has already been answered.
+ * `apply()` must never throw, whatever the upstream sends: malformed JSON, a
+ * JSON `null`, a string where a number belongs, NaN, Infinity, negatives.
+ * Anything unusable is treated as *absent*, which leaves the previous value in
+ * place.
+ */
+import { EMPTY_USAGE } from "../../shared/types.js";
+/**
+ * Accept only a real, finite, non-negative number.
+ *
+ * Numeric strings are rejected rather than coerced on purpose: a `"1234"` from
+ * Anthropic would mean the wire format changed, and silently accepting it would
+ * hide that. `Number("")` is 0 and `Number("abc")` is NaN, so string coercion
+ * also turns junk into plausible-looking zeroes.
+ */
+function num(value) {
+    if (typeof value !== "number")
+        return undefined;
+    if (!Number.isFinite(value))
+        return undefined; // NaN, Infinity, -Infinity
+    if (value < 0)
+        return undefined;
+    return value;
+}
+function asRecord(value) {
+    // typeof null === "object", and arrays are objects too. Neither is a usage
+    // block, and treating them as one yields undefined lookups rather than throws.
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return value;
+}
+/**
+ * Merge one `usage` object into a draft, last-wins per field.
+ * Returns true if at least one field was usable — that, not the mere presence
+ * of a `usage` key, is what "we observed usage" means.
+ */
+function mergeUsage(draft, usage) {
+    let seen = false;
+    const input = num(usage["input_tokens"]);
+    if (input !== undefined) {
+        // Never add cache reads in here. The buckets are disjoint billing buckets;
+        // see the UsagePayload doc comment in shared/types.ts.
+        draft.inputTokens = input;
+        seen = true;
+    }
+    const cacheRead = num(usage["cache_read_input_tokens"]);
+    if (cacheRead !== undefined) {
+        draft.cacheReadTokens = cacheRead;
+        seen = true;
+    }
+    // Cache writes: prefer the per-TTL breakdown when Anthropic sends it.
+    const creation = asRecord(usage["cache_creation"]);
+    const fiveM = creation ? num(creation["ephemeral_5m_input_tokens"]) : undefined;
+    const oneH = creation ? num(creation["ephemeral_1h_input_tokens"]) : undefined;
+    if (fiveM !== undefined || oneH !== undefined) {
+        if (fiveM !== undefined)
+            draft.cacheWrite5mTokens = fiveM;
+        if (oneH !== undefined)
+            draft.cacheWrite1hTokens = oneH;
+        draft.cacheBreakdownKnown = true;
+        seen = true;
+    }
+    else {
+        const flat = num(usage["cache_creation_input_tokens"]);
+        if (flat !== undefined && draft.cacheBreakdownKnown) {
+            // We already have the real per-TTL split from an earlier event; the flat
+            // total is the same tokens, just less precisely reported. Count it as
+            // observed but do not overwrite.
+            seen = true;
+        }
+        else if (flat !== undefined) {
+            // APPROXIMATION, and only when the breakdown is absent: the flat total is
+            // attributed entirely to the 5m bucket because 5m is the default TTL and
+            // the overwhelmingly common case. If `cache_creation` is present it always
+            // wins, so this never overrides real per-TTL data. 1h is left untouched
+            // rather than zeroed, to stay last-wins-per-field.
+            draft.cacheWrite5mTokens = flat;
+            seen = true;
+        }
+    }
+    const output = num(usage["output_tokens"]);
+    if (output !== undefined) {
+        // Assignment, not accumulation. See the module header.
+        draft.outputTokens = output;
+        seen = true;
+    }
+    const tier = usage["service_tier"];
+    if (typeof tier === "string" && tier.length > 0) {
+        draft.serviceTier = tier;
+        seen = true;
+    }
+    const toolUse = asRecord(usage["server_tool_use"]);
+    if (toolUse) {
+        const searches = num(toolUse["web_search_requests"]);
+        if (searches !== undefined) {
+            draft.webSearches = searches;
+            seen = true;
+        }
+    }
+    return seen;
+}
+function parse(data) {
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        // Truncated or hostile payload. Metering loses one event; the request is
+        // already served.
+        return undefined;
+    }
+}
+export function createUsageAccumulator() {
+    const draft = { ...EMPTY_USAGE, serviceTier: undefined, cacheBreakdownKnown: false };
+    let observed = false;
+    let error = null;
+    return {
+        apply(event) {
+            const parsed = parse(event.data);
+            const root = asRecord(parsed);
+            if (!root)
+                return;
+            if (event.type === "message_start") {
+                // Usage lives one level deeper here, under the partial message.
+                const message = asRecord(root["message"]);
+                const usage = message ? asRecord(message["usage"]) : undefined;
+                if (usage && mergeUsage(draft, usage))
+                    observed = true;
+                return;
+            }
+            if (event.type === "message_delta") {
+                // Older API versions send only output_tokens; newer ones re-echo the
+                // input and cache fields. Both go through the same last-wins merge, so
+                // a re-echo is a no-op rather than a double count.
+                const usage = asRecord(root["usage"]);
+                if (usage && mergeUsage(draft, usage))
+                    observed = true;
+                return;
+            }
+            if (event.type === "error") {
+                const err = asRecord(root["error"]);
+                if (err) {
+                    const type = typeof err["type"] === "string" ? err["type"] : "unknown";
+                    const message = typeof err["message"] === "string" ? err["message"] : "";
+                    error = { type, message };
+                }
+                return;
+            }
+            // Any other event type carries no usage. Nothing to do.
+        },
+        snapshot() {
+            return {
+                inputTokens: draft.inputTokens,
+                cacheReadTokens: draft.cacheReadTokens,
+                cacheWrite5mTokens: draft.cacheWrite5mTokens,
+                cacheWrite1hTokens: draft.cacheWrite1hTokens,
+                outputTokens: draft.outputTokens,
+                webSearches: draft.webSearches,
+                serviceTier: draft.serviceTier,
+            };
+        },
+        sawUsage() {
+            return observed;
+        },
+        streamError() {
+            return error;
+        },
+    };
+}
+/**
+ * Parse usage out of a non-streaming JSON response body.
+ *
+ * Returns null when there is nothing usable, so a caller can tell "no usage
+ * reported" from "usage reported as zero" — the same distinction `sawUsage()`
+ * draws on the streaming path.
+ */
+export function usageFromJson(body) {
+    const root = asRecord(body);
+    if (!root)
+        return null;
+    const usage = asRecord(root["usage"]);
+    if (!usage)
+        return null;
+    const draft = { ...EMPTY_USAGE, serviceTier: undefined, cacheBreakdownKnown: false };
+    if (!mergeUsage(draft, usage))
+        return null;
+    return {
+        inputTokens: draft.inputTokens,
+        cacheReadTokens: draft.cacheReadTokens,
+        cacheWrite5mTokens: draft.cacheWrite5mTokens,
+        cacheWrite1hTokens: draft.cacheWrite1hTokens,
+        outputTokens: draft.outputTokens,
+        webSearches: draft.webSearches,
+        serviceTier: draft.serviceTier,
+    };
+}
+//# sourceMappingURL=accumulator.js.map

package/dist/server/usage/accumulator.js.map

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

package/dist/server/usage/cost.js

@@ -0,0 +1,57 @@
+/**
+ * Nullable cost algebra.
+ *
+ * `null` means "no dollar figure applies or is available". It does NOT mean
+ * zero, and the distinction is load-bearing in two different ways:
+ *
+ *  - A model with no rate in our table is *unpriced*, not free. Reporting it as
+ *    $0 understates spend, which is the failure mode this module exists to
+ *    prevent.
+ *  - A request served by a developer's own subscription has no marginal dollar
+ *    cost to the org at all. Its notional list price is not spend and must
+ *    never be added to a spend total.
+ *
+ * So addition propagates null: any unpriceable component poisons the total, and
+ * the UI is expected to render "$X (+N n/a)" rather than a confidently wrong
+ * number. Callers that want a partial sum must count the unpriced rows
+ * separately — see `sumCosts`.
+ *
+ * Adapted from the cost accounting in fw-ai/fireconnect
+ * (packages/setup-cli/lib/harnesses/claude/usage/cost.mjs), which arrived at
+ * the same null-propagating rule the hard way.
+ */
+/** Add two costs. Null propagates: an unknown component makes the sum unknown. */
+export function addCost(a, b) {
+    if (a === null || b === null)
+        return null;
+    return a + b;
+}
+/**
+ * Sum a list of costs, keeping the unpriced count so a dashboard can be honest
+ * ("$12.3456 (+3 n/a)") instead of silently dropping rows the way SQL `SUM`
+ * does with NULLs.
+ */
+export function sumCosts(costs) {
+    let priced = 0;
+    let unpricedCount = 0;
+    for (const c of costs) {
+        if (c === null)
+            unpricedCount += 1;
+        else
+            priced += c;
+    }
+    return { priced, unpricedCount, total: unpricedCount > 0 ? null : priced };
+}
+/** Four decimals: a single cheap call can be worth well under a cent. */
+export function formatCost(cost) {
+    if (cost === null)
+        return "n/a";
+    return `$${cost.toFixed(4)}`;
+}
+/** Render a sum honestly, flagging that it is a lower bound when it is one. */
+export function formatCostSum(sum) {
+    if (sum.unpricedCount === 0)
+        return formatCost(sum.priced);
+    return `≥ $${sum.priced.toFixed(4)} (+${sum.unpricedCount} n/a)`;
+}
+//# sourceMappingURL=cost.js.map

package/dist/server/usage/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../../server/usage/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,kFAAkF;AAClF,MAAM,UAAU,OAAO,CAAC,CAAO,EAAE,CAAO;IACtC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAWD;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAsB;IAC7C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,IAAI;YAAE,aAAa,IAAI,CAAC,CAAC;;YAC9B,MAAM,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;AAC7E,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,IAAU;IACnC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,GAAG,CAAC,aAAa,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3D,OAAO,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,aAAa,OAAO,CAAC;AACnE,CAAC"}