grant/recap-relay
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add self-serve billing: tiers, credits, BTCPay and Zaprite

Browse Source
This commit is contained in:
Keysat
2026-06-13 13:36:05 -05:00
parent 84d56c94c9
commit 0aa648706e
17 changed files with 3781 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/credits.js
+487 -59
View File
@@ -1,21 +1,40 @@
// Credit ledger keyed by install-id. JSON-file backed (single file at
// /data/credits.json). Write throughput is low — at most one mutation
// per relay request — so a plain JSON file with mutex-style serial
// writes is plenty. Swap to SQLite if a single relay starts seeing
// dozens of req/sec sustained.
// Credit ledger. JSON-file backed (single file at /data/credits.json).
// Write throughput is low — at most one mutation per relay request —
// so a plain JSON file with mutex-style serial writes is plenty. Swap
// to SQLite if a single relay starts seeing dozens of req/sec sustained.
//
// Per-install row shape:
// {
// install_id: "uuid",
// tier_snapshot: "core" | "pro" | "max", // last-seen tier
// lifetime_consumed: number, // total Core credits ever used
// lifetime_gemini_consumed: number, // Core credits served by Gemini
// last_renewal_at: ISO-8601 string, // start of current billing period
// monthly_consumed: number, // total this period (paid tiers)
// monthly_gemini_consumed: number, // Gemini-only this period
// last_active_at: ISO-8601 string,
// }
// ── Key model ────────────────────────────────────────────────────────
// Free-tier (Core) rows are keyed by install_id. Paid-tier (Pro / Max)
// rows are keyed by a stable fingerprint of the license key — so a
// single Pro license activated on two installs (e.g. cloud account
// AND self-hosted instance) drains the SAME monthly pool instead of
// getting two independent budgets.
//
// `getCreditKey({ installId, license })` resolves to:
// - `lic:<fingerprint>` when license.tier is "pro" or "max"
// - `inst:<installId>` otherwise (anonymous, invalid, or Core)
//
// Rows still carry `install_id` (last-seen install that touched them)
// for diagnostics, but the LEDGER KEY is what determines pool identity.
//
// ── Migration / backwards compatibility ──────────────────────────────
// Existing pre-refactor rows are keyed by bare install_id. We leave
// them in place — they continue to serve correctly for Core users
// (whose key is now `inst:<installId>`, which still matches the legacy
// bare-installId row because getOrCreateRow looks up by the resolved
// key first and falls back to the legacy installId only when no
// `inst:<...>` row exists yet — see lookupRow() below).
//
// Existing Pro/Max installs keep using their legacy installId-keyed
// row until they next interact with the relay AFTER the new build is
// live. The first such interaction will create a fresh `lic:<fp>`
// row; the old installId row continues to exist as orphaned ledger
// state. Self-heals within one billing cycle for licensed users.
// NO retroactive migration — operator policy is "tolerate the value
// leak for one month rather than risk a buggy bulk-migration on real
// customer balances".
//
// ── Billing-period anchor ────────────────────────────────────────────
// Billing periods are CALENDAR-ANNIVERSARY, not calendar-month. A user
// whose first paid request lands on the 17th of October renews on the
// 17th of every subsequent month — not the 1st. This matches how typical
@@ -27,12 +46,52 @@
import fs from "fs/promises";
import path from "path";
import crypto from "crypto";
let dataDir = "/data";
let ledgerPath = "/data/credits.json";
let ledger = { rows: {} };
let writing = null; // serializes concurrent writes
// ── License fingerprint helpers ─────────────────────────────────────
// Centralized hash so every caller (credits.js, job-credits.js,
// audit-log entries) derives the SAME identifier from the SAME license.
// 16 hex chars = 64 bits — plenty against collision and short enough
// to stay readable in log lines and admin-dashboard tables.
//
// The "raw key" we hash is the licenseUuid resolved by keysat-client
// when available, otherwise a stable stringified form of the resolved
// license object. licenseUuid is the field set by the offline verifier
// and is stable across reactivations and across machines — exactly
// what we want for a per-user pool identifier.
export function licenseFingerprint(license) {
if (!license) return null;
const seed = license.licenseUuid || license.license_uuid || null;
if (!seed) return null;
return crypto
.createHash("sha256")
.update(String(seed))
.digest("hex")
.slice(0, 16);
}
// Resolve the ledger-key for a given (install, license) pair. Paid
// tiers route to `lic:<fp>` so a single license activated on multiple
// installs shares ONE monthly pool. Anonymous / invalid / Core (and
// any paid case missing a fingerprint, e.g. licenseUuid couldn't be
// extracted) fall back to the install-scoped key `inst:<installId>`.
export function getCreditKey({ installId, license }) {
const tier = license?.tier || "core";
if (tier === "pro" || tier === "max") {
const fp = licenseFingerprint(license);
if (fp) return `lic:${fp}`;
}
if (!installId) {
throw new Error("getCreditKey: installId required (no license fingerprint either)");
}
return `inst:${installId}`;
}
export async function initCredits({ dataDir: dd }) {
if (dd) dataDir = dd;
ledgerPath = path.join(dataDir, "credits.json");
@@ -149,10 +208,17 @@ function ensureRenewalRollover(row) {
return rolled;
}
function blankRow(installId) {
function blankRow({ installId, license }) {
const now = new Date();
const fp = licenseFingerprint(license);
return {
install_id: installId,
// install_id captures the LAST install that touched this row.
// For `lic:<fp>` rows that's whichever install most recently
// committed against the license; for `inst:<installId>` rows it
// matches the key. Kept on the row for diagnostics / dashboard
// display — not used for ledger lookup.
install_id: installId || null,
license_fingerprint: fp,
tier_snapshot: "core",
lifetime_consumed: 0,
lifetime_gemini_consumed: 0,
@@ -161,9 +227,38 @@ function blankRow(installId) {
monthly_consumed: 0,
monthly_gemini_consumed: 0,
last_active_at: now.toISOString(),
// Top-up credits the user bought via BTCPay. Never expire (per
// operator policy). Consumed AFTER the tier allotment so the
// user always gets their monthly/lifetime allowance first.
purchased_balance: 0,
purchased_total_ever: 0,
};
}
// Look up a row by its resolved credit-key, with one back-compat fallback:
// when the key is `inst:<installId>` and no such row exists, check for
// a legacy row stored under bare `<installId>` (pre-refactor format).
// Returns { row, key } where `key` is the actual key under which the
// row lives in ledger.rows. Returns { row: null } when nothing was found.
//
// The fallback is one-directional only: we DO NOT promote a legacy
// install-keyed row to a `lic:<fp>` key just because the caller now
// has a license. That's intentional — see the migration note at the
// top of the file. A previously-Pro install that re-presents its
// license will silently start a fresh license-keyed pool; its old
// install-keyed row stays put with whatever monthly_consumed it had,
// usable again next time it falls back to Core.
function lookupRow(key) {
if (ledger.rows[key]) return { row: ledger.rows[key], key };
if (key.startsWith("inst:")) {
const bareInstall = key.slice("inst:".length);
if (ledger.rows[bareInstall]) {
return { row: ledger.rows[bareInstall], key: bareInstall };
}
}
return { row: null, key };
}
async function persist() {
// Coalesce concurrent writes — multiple in-flight mutations resolve
// against the same persisted snapshot in fifo order.
@@ -180,16 +275,94 @@ async function persist() {
}
}
// Returns the row for an install, creating + persisting a blank one
// if this is the first time we've seen it.
export async function getOrCreateRow(installId) {
if (!installId) throw new Error("getOrCreateRow: installId required");
let row = ledger.rows[installId];
// Returns the row for an (install, license) pair, creating + persisting
// a blank one if this is the first time we've seen its resolved
// credit-key. The credit-key is `lic:<fingerprint>` for paid tiers and
// `inst:<installId>` otherwise — so a single Pro license activated on
// two installs shares one row.
//
// When the credit-key is `inst:<installId>` and no row exists under
// that key, we fall back to a legacy bare-installId row (pre-refactor
// format) before creating a new one — keeps existing Core users on
// their existing balances without any retroactive migration. See the
// "Migration / backwards compatibility" comment at the top of the file.
//
// `creditKey` is an optional explicit override. It bypasses
// getCreditKey() and looks up directly under the supplied key. Used by
// job-credits.refundJob to route a refund to the SAME row a charge
// landed on even when the original license object isn't in scope
// anymore (e.g. after a relay restart, refund time only knows the
// stored fingerprint, not the raw licenseUuid).
export async function getOrCreateRow({
installId,
license,
creditKey = null,
} = {}) {
if (!installId && !license && !creditKey) {
throw new Error("getOrCreateRow: installId, license, or creditKey required");
}
const key = creditKey || getCreditKey({ installId, license });
let { row } = lookupRow(key);
let dirty = false;
if (!row) {
row = blankRow(installId);
ledger.rows[installId] = row;
row = blankRow({ installId, license });
// For explicit-creditKey rows whose license object isn't available
// (refund-after-restart), stamp the fingerprint extracted from the
// key itself onto the row so the dashboard surfaces it.
if (creditKey && key.startsWith("lic:") && !row.license_fingerprint) {
row.license_fingerprint = key.slice("lic:".length);
}
// When creating a fresh `lic:<fp>` row but an install row already
// exists for this installId, seed the new row's lifetime_consumed
// from the install row. Why: applyTierPromotion below treats this
// moment as a Core → Paid upgrade and transfers `coreQuota.lifetime
// - lifetime_consumed` as leftover bonus credits. If we left
// lifetime_consumed at 0, the user would get the FULL Core lifetime
// cap as bonus on top of their Pro monthly allotment — effectively
// double-credited (they already burned some of those Core credits
// on the install row before upgrading). Carrying over
// lifetime_consumed lines the math up so the leftover transfer
// reflects the REAL unused-Core balance at the moment of upgrade.
//
// Special case: when the install row's tier_snapshot is ALREADY
// paid (Pro/Max), this is a legacy-Pro user landing on a fresh
// license row post-refactor. They already received any Core-leftover
// transfer on the install row when they first upgraded; doing it
// again here would double-issue. We flag the new row by pre-flipping
// its tier_snapshot to the install row's snapshot — applyTierPromotion
// bails out when tier_snapshot is already non-Core, so the transfer
// skips. Purchased balance carries forward so any top-up credits
// the user had stay accessible on the new license-keyed row.
if (key.startsWith("lic:") && installId) {
const { row: installRow } = lookupRow(`inst:${installId}`);
if (installRow) {
const installAlreadyPaid =
installRow.tier_snapshot === "pro" ||
installRow.tier_snapshot === "max";
row.lifetime_consumed = installRow.lifetime_consumed || 0;
row.lifetime_gemini_consumed = installRow.lifetime_gemini_consumed || 0;
if (installAlreadyPaid) {
row.tier_snapshot = installRow.tier_snapshot;
row.purchased_balance = installRow.purchased_balance || 0;
row.purchased_total_ever = installRow.purchased_total_ever || 0;
}
}
}
ledger.rows[key] = row;
dirty = true;
} else {
// Keep the most recently seen install/fingerprint stamped on the
// row so the admin dashboard can show "which device of this user
// last touched this license pool" without trawling audit logs.
if (installId && row.install_id !== installId) {
row.install_id = installId;
dirty = true;
}
const fp = licenseFingerprint(license);
if (fp && row.license_fingerprint !== fp) {
row.license_fingerprint = fp;
dirty = true;
}
}
if (ensureRenewalRollover(row)) dirty = true;
if (dirty) await persist();
@@ -198,16 +371,26 @@ export async function getOrCreateRow(installId) {
// Compute the remaining balance for a row against its tier's quota.
// Returns:
// { remaining: number | null, capped: "lifetime" | "monthly" | "none", gemini_remaining: number | null }
// `null` for remaining means "unlimited" (Max tier total).
// `null` for gemini_remaining means "no Gemini cap on this tier" — the
// router can always pick Gemini.
// {
// remaining: number | null, // tier portion only; null = unlimited
// capped: "lifetime" | "monthly" | "none",
// gemini_remaining: number | null, // null = no Gemini cap on this tier
// purchased: number, // top-up credits the user bought via BTCPay
// total: number | null, // remaining + purchased; null = unlimited
// }
//
// Spend order is implemented by callers: tier portion is debited
// first (commitCredit increments lifetime_consumed / monthly_consumed);
// only when that hits zero do we touch purchased_balance. This keeps
// the user's purchased credits as a true durable top-up rather than
// crowding out the monthly allotment they're already entitled to.
export function computeRemaining(row, quota) {
const tier = row.tier_snapshot;
const tierQuota = quota[tier] || quota.core;
const purchased = Math.max(0, row.purchased_balance || 0);
if (tierQuota.lifetime != null) {
const remaining = Math.max(0, tierQuota.lifetime - (row.lifetime_consumed || 0));
const tierRemaining = Math.max(0, tierQuota.lifetime - (row.lifetime_consumed || 0));
// Core tier may carve out a portion of the lifetime budget for
// Gemini specifically (geminiCapLifetime). When set, remaining
// Gemini credits = cap - lifetime_gemini_consumed; the rest of
@@ -222,17 +405,19 @@ export function computeRemaining(row, quota) {
tierQuota.geminiCapLifetime - (row.lifetime_gemini_consumed || 0)
);
return {
remaining,
remaining: tierRemaining,
capped: "lifetime",
gemini_remaining: geminiRemaining,
purchased,
total: tierRemaining + purchased,
};
}
let remaining;
let tierRemaining;
if (tierQuota.monthly == null) {
remaining = null; // unlimited
tierRemaining = null; // unlimited
} else {
remaining = Math.max(0, tierQuota.monthly - (row.monthly_consumed || 0));
tierRemaining = Math.max(0, tierQuota.monthly - (row.monthly_consumed || 0));
}
const geminiRemaining =
tierQuota.geminiCapMonthly == null
@@ -240,9 +425,11 @@ export function computeRemaining(row, quota) {
: Math.max(0, tierQuota.geminiCapMonthly - (row.monthly_gemini_consumed || 0));
return {
remaining,
remaining: tierRemaining,
capped: "monthly",
gemini_remaining: geminiRemaining,
purchased,
total: tierRemaining == null ? null : tierRemaining + purchased,
};
}
@@ -270,13 +457,22 @@ export function computeRemaining(row, quota) {
export function planBackend(row, quota, { hasHardware, preference = "gemini_first" }) {
const balance = computeRemaining(row, quota);
// Out of credits entirely?
if (balance.remaining === 0) {
// Out of credits entirely? Tier allotment exhausted AND no purchased
// top-up remaining. (balance.total === null means unlimited.)
if (balance.total === 0) {
return { allowed: false, backend: null, reason: "out_of_credits" };
}
// Gemini availability has two paths: either the tier's Gemini-cap
// portion has headroom (gemini_remaining > 0 or null) OR the user
// has purchased top-up credits. Purchased credits bypass the per-
// tier Gemini cap because the operator has already been paid for
// those calls — the cap exists to bound free/comped Gemini spend,
// not paid-for spend.
const geminiAvailable =
balance.gemini_remaining === null || balance.gemini_remaining > 0;
balance.gemini_remaining === null ||
balance.gemini_remaining > 0 ||
balance.purchased > 0;
switch (preference) {
case "hardware_only":
@@ -339,34 +535,266 @@ export function planBackend(row, quota, { hasHardware, preference = "gemini_firs
// upgrades on the 17th gets renewals on the 17th going forward, not
// at some earlier date that happens to be when their install_id was
// first seen.
export async function commitCredit(installId, { backend, tier }) {
const row = await getOrCreateRow(installId);
const wasCorePromotion =
tier !== "core" && row.tier_snapshot === "core";
row.tier_snapshot = tier;
if (wasCorePromotion) {
const now = new Date();
row.last_renewal_at = now.toISOString();
row.anniversary_day = now.getUTCDate();
row.monthly_consumed = 0;
row.monthly_gemini_consumed = 0;
}
// Inverse of commitCredit — returns one charged credit back to the
// install's ledger when the work that consumed it ended up failing.
// Mirrors commitCredit field-by-field so the same row that was
// incremented gets decremented; floors at 0 so we never accidentally
// hand a user negative consumption from a buggy refund sequence.
//
// Called from the route handlers via job-credits.refundJob when a
// backend call fails after the credit was already charged (typical
// case: transcribe succeeded + committed, analyze failed, so the
// job's credit needs to be returned because the summary didn't
// actually complete).
export async function refundCredit({
installId,
license,
creditKey = null,
backend,
tier,
}) {
const row = await getOrCreateRow({ installId, license, creditKey });
// Mirror commitCredit's spend order: tier bucket gets refunded
// first (which is where the credit was charged); only if the tier
// counter is already at zero do we credit back to purchased_balance
// (which means the original commit came out of the top-up bucket).
if (tier === "core") {
row.lifetime_consumed = (row.lifetime_consumed || 0) + 1;
if (backend === "gemini") {
row.lifetime_gemini_consumed = (row.lifetime_gemini_consumed || 0) + 1;
if ((row.lifetime_consumed || 0) > 0) {
row.lifetime_consumed -= 1;
if (backend === "gemini" && (row.lifetime_gemini_consumed || 0) > 0) {
row.lifetime_gemini_consumed -= 1;
}
} else {
row.purchased_balance = (row.purchased_balance || 0) + 1;
}
} else {
row.monthly_consumed = (row.monthly_consumed || 0) + 1;
if (backend === "gemini") {
row.monthly_gemini_consumed = (row.monthly_gemini_consumed || 0) + 1;
if ((row.monthly_consumed || 0) > 0) {
row.monthly_consumed -= 1;
if (backend === "gemini" && (row.monthly_gemini_consumed || 0) > 0) {
row.monthly_gemini_consumed -= 1;
}
} else {
row.purchased_balance = (row.purchased_balance || 0) + 1;
}
}
row.last_active_at = new Date().toISOString();
await persist();
}
// For the admin dashboard.
export function snapshotAll() {
return Object.values(ledger.rows).map((r) => ({ ...r }));
// Loads the quota for the install's tier so we can decide whether
// to debit the tier portion or the purchased top-up portion. Imported
// lazily to avoid a circular dep with config.js → credits.js.
async function getCommitQuota(tier) {
const { getTierQuotas } = await import("./config.js");
const all = await getTierQuotas();
return all[tier] || all.core;
}
// Apply the Core → paid-tier promotion bookkeeping in a single place.
// Idempotent: only fires the FIRST time we see a paid tier on a row
// whose tier_snapshot is still "core". On promotion we:
// - Anchor the user's billing-anniversary to right now so monthly
// renewals line up with the upgrade moment (not their install
// creation date).
// - Zero out monthly counters so the user gets their full first
// month, even if they made it past the Core lifetime cap by
// burning some monthly counter earlier.
// - Transfer any UNUSED Core lifetime credits into purchased_balance.
// This way the 6 leftover credits a Core user had don't vanish on
// upgrade — they stack on top of the paid tier's monthly allotment
// as durable bonus credit. Total after upgrade = monthly cap +
// leftover Core credits + any prior top-up purchases.
// - Flip tier_snapshot to the new tier last so the spend-order check
// below routes the next debit to the right bucket.
//
// Mutates `row` in place AND persists the ledger when a promotion
// fires — so the leftover transfer survives a relay restart even if
// the calling route doesn't otherwise persist (the /relay/balance
// route, for example, mutates tier_snapshot in memory without a
// follow-up persist).
//
// Returns true if a promotion was applied, false otherwise.
export async function applyTierPromotion(row, newTier) {
if (newTier === "core") return false;
if (row.tier_snapshot !== "core") return false;
// Compute leftover Core credits BEFORE we flip tier_snapshot. If
// Core's lifetime cap isn't set (unlimited), there's nothing to
// transfer — the user already had unlimited.
const coreQuota = await getCommitQuota("core");
let transferred = 0;
if (typeof coreQuota.lifetime === "number" && coreQuota.lifetime > 0) {
transferred = Math.max(
0,
coreQuota.lifetime - (row.lifetime_consumed || 0)
);
if (transferred > 0) {
row.purchased_balance = (row.purchased_balance || 0) + transferred;
row.purchased_total_ever =
(row.purchased_total_ever || 0) + transferred;
}
}
const now = new Date();
row.last_renewal_at = now.toISOString();
row.anniversary_day = now.getUTCDate();
row.monthly_consumed = 0;
row.monthly_gemini_consumed = 0;
row.tier_snapshot = newTier;
row.last_active_at = now.toISOString();
await persist();
if (transferred > 0) {
console.log(
`[credits] tier promotion core → ${newTier} for ${row.install_id || row.license_fingerprint || "(unknown)"}: ` +
`transferred ${transferred} leftover Core credit(s) to purchased_balance ` +
`(now ${row.purchased_balance})`
);
}
return true;
}
export async function commitCredit({ installId, license, creditKey = null, backend, tier }) {
const row = await getOrCreateRow({ installId, license, creditKey });
const promoted = await applyTierPromotion(row, tier);
// If no promotion fired, applyTierPromotion left tier_snapshot
// untouched (it only flips on Core → paid). Still want to keep the
// snapshot current for paid → paid moves (Pro → Max, etc.) so the
// ledger reflects the most recent license tier seen.
if (!promoted) {
row.tier_snapshot = tier;
}
// Spend order: tier allotment first, purchased top-up second.
// Figure out whether THIS credit comes out of the tier bucket or
// the purchased bucket by checking remaining tier headroom against
// the current quota.
const tierQuota = await getCommitQuota(tier);
let tierHasRoom = false;
if (tier === "core") {
tierHasRoom =
tierQuota.lifetime == null ||
(row.lifetime_consumed || 0) < tierQuota.lifetime;
} else {
tierHasRoom =
tierQuota.monthly == null ||
(row.monthly_consumed || 0) < tierQuota.monthly;
}
if (tierHasRoom) {
if (tier === "core") {
row.lifetime_consumed = (row.lifetime_consumed || 0) + 1;
if (backend === "gemini") {
row.lifetime_gemini_consumed = (row.lifetime_gemini_consumed || 0) + 1;
}
} else {
row.monthly_consumed = (row.monthly_consumed || 0) + 1;
if (backend === "gemini") {
row.monthly_gemini_consumed = (row.monthly_gemini_consumed || 0) + 1;
}
}
} else {
// Tier allotment exhausted — debit the purchased top-up. Capped
// at zero so a refundCredit miss can't bring this negative.
row.purchased_balance = Math.max(0, (row.purchased_balance || 0) - 1);
}
row.last_active_at = new Date().toISOString();
await persist();
}
// Add purchased credits to the install's top-up bucket. Used by the
// BTCPay webhook after a successful invoice settlement. Idempotent
// at the webhook layer via processed-invoice tracking (the webhook
// handler dedupes by invoice_id before calling this).
// Purchased credits land on whichever row backs the buying install at
// the time of purchase. The caller passes (installId, license, creditKey),
// in priority order: an explicit creditKey wins, otherwise the resolved
// (installId, license) decides.
//
// Why creditKey is accepted as an explicit override: the BTCPay webhook
// re-enters this path AFTER a restart, with only invoice metadata in
// hand (install_id + license_fingerprint stashed at buy time, no live
// license object). The webhook constructs `lic:<fp>` from the stored
// fingerprint and passes it as creditKey so the credit lands on the
// SAME pool the buyer was looking at when they minted the invoice.
//
// Anonymous / Core buyers (no fingerprint stashed) fall through to the
// install-keyed row — the credit follows the install. Once they
// upgrade to Pro/Max later, applyTierPromotion transfers any leftover
// Core tier credits to purchased_balance — see commitCredit's path.
export async function addPurchasedCredits({
installId,
license = null,
creditKey = null,
amount,
}) {
if (!Number.isFinite(amount) || amount <= 0) return null;
const row = await getOrCreateRow({ installId, license, creditKey });
row.purchased_balance = (row.purchased_balance || 0) + amount;
row.purchased_total_ever = (row.purchased_total_ever || 0) + amount;
row.last_active_at = new Date().toISOString();
await persist();
return row.purchased_balance;
}
// ── Cloud user tier (core-decoupling) ───────────────────────────────
// The relay is the source of truth for a cloud user's Pro/Max tier,
// stored on the user's credit row (keyed `user:<id>`). Set by the
// operator (today) and the self-serve purchase flow (later slice).
// Operator-set a cloud user's tier. Resets the monthly counters and
// anchors the renewal to now (so the monthly cycle starts on the grant
// date), mirroring applyTierPromotion. `expiresAt` is stored for
// reporting / future self-serve billing but NOT auto-enforced in this
// slice — to revoke, set tier back to "core".
export async function setUserTier({ userId, tier, expiresAt = null }) {
if (!userId) throw new Error("setUserTier: userId required");
const t = tier === "pro" || tier === "max" ? tier : "core";
const row = await getOrCreateRow({ creditKey: `user:${userId}` });
const now = new Date();
row.tier_snapshot = t;
row.monthly_consumed = 0;
row.monthly_gemini_consumed = 0;
row.last_renewal_at = now.toISOString();
row.anniversary_day = now.getUTCDate();
row.subscription_expires_at = expiresAt || null;
row.last_active_at = now.toISOString();
await persist();
return row;
}
// Buy / extend a PREPAID PERIOD of `tier` (self-serve subscriptions). The
// new expiry extends from whichever is later — now, or the user's current
// (still-active) expiry — so paying early ADDS time rather than resetting
// it. `periodDays` defaults to 30. Both payment rails (BTCPay + Zaprite)
// land here on a settled payment. Returns the updated row.
export async function extendUserTier({ userId, tier, periodDays = 30 }) {
if (!userId) throw new Error("extendUserTier: userId required");
const t = tier === "pro" || tier === "max" ? tier : "core";
const now = Date.now();
const row = await getOrCreateRow({ creditKey: `user:${userId}` });
const curExp = row.subscription_expires_at
? new Date(row.subscription_expires_at).getTime()
: 0;
const base = Math.max(now, Number.isFinite(curExp) ? curExp : 0);
const expiresAt = new Date(
base + periodDays * 24 * 60 * 60 * 1000,
).toISOString();
return setUserTier({ userId, tier: t, expiresAt });
}
// Read a cloud user's credit row (creates a blank Core row if none yet).
export async function getUserCreditRow(userId) {
if (!userId) throw new Error("getUserCreditRow: userId required");
return getOrCreateRow({ creditKey: `user:${userId}` });
}
// For the admin dashboard. Includes the ledger-key (`credit_key`) so
// the dashboard can render "license pool" vs "install pool" rows
// distinctly — license-keyed rows aggregate spend across every install
// that uses the same license, install-keyed rows aggregate one install.
export function snapshotAll() {
return Object.entries(ledger.rows).map(([credit_key, r]) => ({
credit_key,
...r,
}));
}