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

v0.2.6 calendar-anniversary billing

Browse Source
This commit is contained in:
local
2026-05-11 23:02:57 -05:00
parent 45c8462fa2
commit cd377683fb
5 changed files with 153 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/credits.js
+129 -18
View File
@@ -10,11 +10,20 @@
// 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
// month: "YYYY-MM", // calendar-month key
// monthly_consumed: number, // total this month (paid tiers)
// monthly_gemini_consumed: number, // Gemini-only this month
// 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,
// }
//
// 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
// subscription billing works (Stripe et al.) so the relay's monthly-cap
// resets line up with the actual renewal date the user is being charged
// on. Edge cases (Jan 31 → Feb 28/29) clamp to the last day of the
// target month, then resume the original day-of-month the next time
// it's available, same as standard subscription convention.
import fs from "fs/promises";
import path from "path";
@@ -38,37 +47,120 @@ export async function initCredits({ dataDir: dd }) {
}
ledger = { rows: {} };
}
// Migrate any rows that still carry the old { month: "YYYY-MM" }
// shape from pre-anniversary ledger versions. Conservative: anchor
// their last_renewal_at at the first of that month so they don't
// get a surprise re-issue.
let migrated = 0;
for (const row of Object.values(ledger.rows)) {
if (row.last_renewal_at) continue;
if (typeof row.month === "string" && /^\d{4}-\d{2}$/.test(row.month)) {
const [y, m] = row.month.split("-").map(Number);
row.last_renewal_at = new Date(Date.UTC(y, m - 1, 1, 0, 0, 0)).toISOString();
delete row.month;
migrated += 1;
} else {
// No prior period info — anchor to now so the next renewal
// happens one calendar month from this point.
row.last_renewal_at = new Date().toISOString();
if ("month" in row) delete row.month;
migrated += 1;
}
}
if (migrated > 0) {
console.log(`[credits] migrated ${migrated} row(s) from calendar-month to anniversary-renewal shape`);
await persist();
}
console.log(`[credits] loaded ${Object.keys(ledger.rows).length} install rows from ${ledgerPath}`);
}
function currentMonthKey() {
const d = new Date();
return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}`;
// Add one calendar month to the given Date, clamping the day to the
// last valid day of the target month. Examples (all UTC):
// Jan 31 → Feb 28 (or Feb 29 in leap years)
// Feb 28 → Mar 28 (note: NOT Mar 31 — we use the original day)
// Mar 31 → Apr 30
// May 31 → Jun 30 → Jul 31 (clamping is per-step, not absorbed)
//
// Note the third example. We anchor to the ORIGINAL anniversary day
// each step, so a user who started on the 31st keeps getting renewals
// on the 31st in months that have one, and on the last day for months
// that don't. This is the standard subscription-billing rule.
export function nextRenewalAfter(d, originalDay) {
// originalDay is the anniversary day-of-month. If not supplied, use
// d's own date — useful for the first hop from a freshly-set
// last_renewal_at.
const anchor = originalDay ?? d.getUTCDate();
const targetMonth = d.getUTCMonth() + 1;
const overflow = targetMonth > 11 ? 1 : 0;
const targetYear = d.getUTCFullYear() + overflow;
const actualMonth = targetMonth % 12;
// Last day of the target month (e.g. for Feb non-leap, this is 28).
const lastDayOfTarget = new Date(Date.UTC(targetYear, actualMonth + 1, 0)).getUTCDate();
const day = Math.min(anchor, lastDayOfTarget);
return new Date(
Date.UTC(
targetYear,
actualMonth,
day,
d.getUTCHours(),
d.getUTCMinutes(),
d.getUTCSeconds()
)
);
}
// Lazily rolls over the per-install monthly counters when the calendar
// month changes. Lifetime counter is left untouched (Core lifetime
// credits never reset).
function ensureCurrentMonth(row) {
const m = currentMonthKey();
if (row.month !== m) {
row.month = m;
// Determine the install's anniversary day-of-month, which stays stable
// even if a clamp pushed last_renewal_at to a shorter month. Stored
// explicitly as `anniversary_day` once the row is created at a non-
// month-end date; for legacy rows without it we infer from
// last_renewal_at as a one-time best-effort.
function anniversaryDay(row) {
if (typeof row.anniversary_day === "number" && row.anniversary_day >= 1 && row.anniversary_day <= 31) {
return row.anniversary_day;
}
const d = new Date(row.last_renewal_at);
return Number.isFinite(d.getTime()) ? d.getUTCDate() : 1;
}
// Step the renewal forward until next_renewal > now. Handles rows
// that have been dormant for several months and need multiple rollovers
// in one shot. Mutates `row` in place; caller is responsible for
// persisting when something changed.
function ensureRenewalRollover(row) {
if (!row.last_renewal_at) {
row.last_renewal_at = new Date().toISOString();
return false;
}
const now = Date.now();
const anchorDay = anniversaryDay(row);
let last = new Date(row.last_renewal_at);
let next = nextRenewalAfter(last, anchorDay);
let rolled = false;
while (next.getTime() <= now) {
last = next;
next = nextRenewalAfter(last, anchorDay);
rolled = true;
}
if (rolled) {
row.last_renewal_at = last.toISOString();
row.monthly_consumed = 0;
row.monthly_gemini_consumed = 0;
}
return row;
return rolled;
}
function blankRow(installId) {
const now = new Date();
return {
install_id: installId,
tier_snapshot: "core",
lifetime_consumed: 0,
lifetime_gemini_consumed: 0,
month: currentMonthKey(),
last_renewal_at: now.toISOString(),
anniversary_day: now.getUTCDate(),
monthly_consumed: 0,
monthly_gemini_consumed: 0,
last_active_at: new Date().toISOString(),
last_active_at: now.toISOString(),
};
}
@@ -93,12 +185,15 @@ async function persist() {
export async function getOrCreateRow(installId) {
if (!installId) throw new Error("getOrCreateRow: installId required");
let row = ledger.rows[installId];
let dirty = false;
if (!row) {
row = blankRow(installId);
ledger.rows[installId] = row;
await persist();
dirty = true;
}
return ensureCurrentMonth(row);
if (ensureRenewalRollover(row)) dirty = true;
if (dirty) await persist();
return row;
}
// Compute the remaining balance for a row against its tier's quota.
@@ -178,9 +273,25 @@ export function planBackend(row, quota, { hasHardware }) {
// Tracks Gemini-vs-hardware separately for Core (lifetime_gemini_consumed)
// and paid tiers (monthly_gemini_consumed) so the planner can enforce
// the per-tier Gemini cap.
//
// When a previously-Core install presents a paid license for the first
// time, we treat THIS moment as the start of their billing period and
// anchor last_renewal_at + anniversary_day to now. That way a user who
// 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;
}
if (tier === "core") {
row.lifetime_consumed = (row.lifetime_consumed || 0) + 1;
if (backend === "gemini") {