Skip to content

Open source CapCut alternative.

TypeScript

feat(site): analytics billing reads Stripe and refreshes on its webhooks

David Lef8f15226e7a3
diff --git a/site/scripts/stripe-webhook-events.ts b/site/scripts/stripe-webhook-events.ts
new file mode 100644
index 00000000..8e3c4bb7
--- /dev/null
+++ b/site/scripts/stripe-webhook-events.ts
@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * Points the Stripe webhook endpoint for donkeycut.com at the events the
+ * handler and the analytics refresh listen for, so the endpoint in Stripe
+ * matches the code. Idempotent: run it after changing the event lists.
+ *
+ * Run from site/ with the production Stripe key in the environment:
+ * bun run scripts/stripe-webhook-events.ts
+ */
+
+import type Stripe from "stripe";
+
+import { getStripe } from "../src/lib/billing/stripe";
+import { ANALYTICS_BILLING_EVENTS } from "../src/lib/billing/webhook-events";
+
+const WEBHOOK_URL = "https://donkeycut.com/api/billing/webhook";
+
+const enabledEvents = [...ANALYTICS_BILLING_EVENTS].sort() as Stripe.WebhookEndpointUpdateParams.EnabledEvent[];
+
+const stripe = getStripe();
+const endpoints = await stripe.webhookEndpoints.list({ limit: 100 });
+const endpoint = endpoints.data.find((e) => e.url === WEBHOOK_URL);
+if (!endpoint) {
+ console.error(`No webhook endpoint for ${WEBHOOK_URL}; create it in Stripe first.`);
+ process.exit(1);
+}
+
+const current = [...endpoint.enabled_events].sort();
+if (current.join() === enabledEvents.join()) {
+ console.log(`${endpoint.id} already listens for ${enabledEvents.length} events.`);
+} else {
+ await stripe.webhookEndpoints.update(endpoint.id, { enabled_events: enabledEvents });
+ const added = enabledEvents.filter((e) => !current.includes(e));
+ const removed = current.filter((e) => !enabledEvents.includes(e as (typeof enabledEvents)[number]));
+ console.log(`${endpoint.id} updated: +${added.join(", ") || "none"}; -${removed.join(", ") || "none"}`);
+}
diff --git a/site/src/app/api/billing/webhook/route.ts b/site/src/app/api/billing/webhook/route.ts
index bd7ae195..7118ab97 100644
--- a/site/src/app/api/billing/webhook/route.ts
+++ b/site/src/app/api/billing/webhook/route.ts
@@ -13,6 +13,15 @@ import {
} from "@/lib/billing/pro-subscription";
import { getStripe, stripeId } from "@/lib/billing/stripe";
import { notFoundResponse } from "@/lib/donkey-api-auth";
+import { ANALYTICS_BILLING_EVENTS } from "@/lib/billing/webhook-events";
+import { enqueueJob } from "@/lib/jobs/queue";
+import { prisma } from "@/lib/prisma";
+
+const analyticsBillingEvents = new Set<string>(ANALYTICS_BILLING_EVENTS);
+
+// Without a queue configured (local dev) a queued job runs inline before the
+// response; give it room.
+export const maxDuration = 300;
// Pro is the only subscription product; ignore any other Stripe subscription
// that reaches these webhook events.
@@ -98,5 +107,15 @@ export async function POST(request: Request) {
break;
}
+ // One checkout fans out into several of these within a second; a refresh
+ // already waiting in the queue will read the state they all produced.
+ if (analyticsBillingEvents.has(event.type)) {
+ const waiting = await prisma.asyncJob.findFirst({
+ select: { id: true },
+ where: { kind: "billing-refresh", state: "queued" },
+ });
+ if (!waiting) await enqueueJob("billing-refresh", {}, "stripe-webhook");
+ }
+
return NextResponse.json({ received: true });
}
diff --git a/site/src/lib/analytics/billing.test.ts b/site/src/lib/analytics/billing.test.ts
new file mode 100644
index 00000000..68795ef4
--- /dev/null
+++ b/site/src/lib/analytics/billing.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import type Stripe from "stripe";
+
+import { subscriptionCancelScheduled } from "../billing/pro-subscription";
+import { buildBilling } from "./pipeline";
+import type { AnalyticsStripeSnapshot } from "./schema";
+
+const days = ["2026-09-01", "2026-09-02", "2026-09-03"];
+
+const snapshot: AnalyticsStripeSnapshot = {
+ abandonedCheckouts: [
+ { customerId: "cus_a", day: "2026-09-02", email: "[email protected]", id: "cs_1", kind: "pro" },
+ { customerId: "cus_b", day: "2026-08-01", email: "[email protected]", id: "cs_2", kind: "pro" },
+ ],
+ charges: [
+ // Paid inside the window: one Pro, one top-up.
+ { amountMicros: "20000000", customerId: "cus_p", day: "2026-09-01", email: "[email protected]", failure: null, id: "ch_1", kind: "pro", paymentIntentId: "pi_1", status: "paid", userId: "u_p" },
+ { amountMicros: "5000000", customerId: "cus_t", day: "2026-09-03", email: "[email protected]", failure: null, id: "ch_2", kind: "topup", paymentIntentId: "pi_2", status: "paid", userId: "u_t" },
+ // Paid before the window: funds all-time only.
+ { amountMicros: "5000000", customerId: "cus_t", day: "2026-08-01", email: "[email protected]", failure: null, id: "ch_3", kind: "topup", paymentIntentId: "pi_3", status: "paid", userId: "u_t" },
+ // Declined inside the window.
+ { amountMicros: "20000000", customerId: "cus_d", day: "2026-09-02", email: "[email protected]", failure: "Your card has insufficient funds.", id: "ch_4", kind: "pro", paymentIntentId: "pi_4", status: "declined", userId: "u_d" },
+ ],
+ dashboardUrl: "https://dashboard.stripe.com",
+ refunds: [{ amountMicros: "5000000", chargeId: "ch_2", day: "2026-09-03", id: "re_1" }],
+ subscriptions: [
+ // Live, and scheduled to end through the portal's cancel_at.
+ { cancelAt: "2026-09-08T00:00:00.000Z", cancelScheduled: true, canceledAt: "2026-09-02T10:00:00.000Z", comment: "Export broke.", createdAt: "2026-08-09T00:00:00.000Z", customerId: "cus_p", email: "[email protected]", feedback: "switched_service", id: "sub_1", status: "active", userId: "u_p" },
+ // Live, staying.
+ { cancelAt: null, cancelScheduled: false, canceledAt: null, comment: null, createdAt: "2026-09-01T00:00:00.000Z", customerId: "cus_q", email: "[email protected]", feedback: null, id: "sub_2", status: "active", userId: "u_q" },
+ // Ended before the window.
+ { cancelAt: null, cancelScheduled: false, canceledAt: "2026-07-01T00:00:00.000Z", comment: null, createdAt: "2026-06-01T00:00:00.000Z", customerId: "cus_r", email: "[email protected]", feedback: null, id: "sub_3", status: "canceled", userId: "u_r" },
+ ],
+};
+
+describe("buildBilling", () => {
+ const billing = buildBilling(snapshot, days);
+
+ test("counts a portal-scheduled cancel as canceling", () => {
+ expect(billing.days).toEqual(days);
+ expect(billing.subscribers).toBe(2);
+ expect(billing.canceling).toEqual([
+ {
+ comment: "Export broke.",
+ customerId: "cus_p",
+ email: "[email protected]",
+ endsAt: "2026-09-08T00:00:00.000Z",
+ feedback: "switched_service",
+ requestedAt: "2026-09-02T10:00:00.000Z",
+ subscriptionId: "sub_1",
+ },
+ ]);
+ expect(billing.churned).toBe(1);
+ });
+
+ test("nets paid against refunds and keeps declines outside", () => {
+ expect(billing.window).toEqual({
+ abandonedCheckouts: 1,
+ cancels: 1,
+ declinedCustomers: 1,
+ declinedMicros: "20000000",
+ netMicros: "20000000",
+ paidMicros: "25000000",
+ refundedMicros: "5000000",
+ });
+ expect(billing.revenue).toEqual([
+ { cancels: 0, declinedMicros: "0", otherMicros: "0", proMicros: "20000000", refundedMicros: "0", topupMicros: "0" },
+ { cancels: 1, declinedMicros: "20000000", otherMicros: "0", proMicros: "0", refundedMicros: "0", topupMicros: "0" },
+ { cancels: 0, declinedMicros: "0", otherMicros: "0", proMicros: "0", refundedMicros: "5000000", topupMicros: "5000000" },
+ ]);
+ });
+
+ test("funds all time and lists the window's events newest first", () => {
+ expect(billing.funded).toBe(2);
+ expect(billing.fundedMicros).toBe("30000000");
+ expect(billing.events.map((e) => [e.day, e.kind, e.objectId, e.detail])).toEqual([
+ ["2026-09-02", "canceled", "sub_1", "switched_service · Export broke."],
+ ["2026-09-02", "declined", "pi_4", "Your card has insufficient funds."],
+ ]);
+ });
+});
+
+describe("subscriptionCancelScheduled", () => {
+ const sub = (fields: Partial<Stripe.Subscription>) =>
+ ({ cancel_at: null, cancel_at_period_end: false, ...fields }) as Stripe.Subscription;
+
+ test("reads either spelling of a scheduled end", () => {
+ expect(subscriptionCancelScheduled(sub({}))).toBe(false);
+ expect(subscriptionCancelScheduled(sub({ cancel_at_period_end: true }))).toBe(true);
+ expect(subscriptionCancelScheduled(sub({ cancel_at: 1788966820 }))).toBe(true);
+ });
+});
diff --git a/site/src/lib/analytics/pipeline.ts b/site/src/lib/analytics/pipeline.ts
index 7fa69df5..ca5913ef 100644
--- a/site/src/lib/analytics/pipeline.ts
+++ b/site/src/lib/analytics/pipeline.ts
@@ -10,6 +10,7 @@ import type { z } from "zod";
import type { Prisma } from "@/generated/prisma/client";
import { getObject, listObjectsWithDates, putObject } from "@/cut/server/cloud/r2";
import { fetchActiveDistinctIds, isPosthogQueryConfigured } from "@/lib/analytics/posthog";
+import { pullStripeSnapshot } from "@/lib/analytics/stripe";
import {
addUtcDays,
ANALYTICS_DB_SOURCES,
@@ -17,10 +18,13 @@ import {
ANALYTICS_SOURCES,
analyticsDbDayFileSchema,
analyticsPosthogDayFileSchema,
+ analyticsRollupSchema,
+ analyticsSnapshotFileSchema,
type AnalyticsDbDayFile,
type AnalyticsPosthogDayFile,
type AnalyticsRollup,
type AnalyticsSnapshotFile,
+ type AnalyticsStripeSnapshot,
utcDayOf,
} from "@/lib/analytics/schema";
import { cutLimitsForTier } from "@/cut/server/cloud/limits";
@@ -40,9 +44,23 @@ const WINDOW_DAYS = 60;
const MAX_EXTRACT_DAYS_PER_RUN = 5;
const SNAPSHOT_PAGE_SIZE = 1000;
-// Credit grant sources that correspond to a Stripe charge; the grant amount
-// equals the dollars paid, so these rows double as the revenue record.
-const PAID_GRANT_SOURCES = ["pro_subscription", "stripe_autoreload", "stripe_topup"];
+// The rollup's day window: yesterday and the days before it, oldest first.
+// Activity is extracted once a UTC day has closed, so today is never in it.
+function windowDays(): string[] {
+ return daysEnding(addUtcDays(utcDayOf(new Date()), -1));
+}
+
+// The billing window ends today: Stripe reports money and cancels as they
+// happen, and the webhook refresh exists to show them the same day.
+function billingDays(): string[] {
+ return daysEnding(utcDayOf(new Date()));
+}
+
+function daysEnding(last: string): string[] {
+ const days: string[] = [];
+ for (let i = WINDOW_DAYS - 1; i >= 0; i--) days.push(addUtcDays(last, -i));
+ return days;
+}
export class InvalidDayError extends Error {}
@@ -248,44 +266,13 @@ async function writeSnapshot(): Promise<AnalyticsSnapshotFile> {
cursor = page[page.length - 1].userId;
}
- const subscriptions = (
- await fetchAllPages((cursorArgs) =>
- prisma.proSubscription.findMany({
- orderBy: { id: "asc" },
- select: { cancelAtPeriodEnd: true, id: true, status: true, userId: true },
- take: SNAPSHOT_PAGE_SIZE,
- ...cursorArgs,
- }),
- )
- ).map((sub) => ({
- cancelAtPeriodEnd: sub.cancelAtPeriodEnd,
- status: sub.status,
- userId: sub.userId,
- }));
-
- const payments = (
- await fetchAllPages((cursorArgs) =>
- prisma.userCreditGrant.findMany({
- orderBy: { id: "asc" },
- select: { createdAt: true, id: true, originalAmountMicros: true, source: true, userId: true },
- take: SNAPSHOT_PAGE_SIZE,
- where: { source: { in: PAID_GRANT_SOURCES } },
- ...cursorArgs,
- }),
- )
- ).map((grant) => ({
- amountMicros: grant.originalAmountMicros.toString(),
- day: utcDayOf(grant.createdAt),
- source: grant.source,
- userId: grant.userId,
- }));
+ const stripe = await pullStripeSnapshot(billingDays()[0]);
const snapshot: AnalyticsSnapshotFile = {
balances,
generatedAt: new Date().toISOString(),
- payments,
storage,
- subscriptions,
+ stripe,
users,
version: 1,
};
@@ -297,9 +284,8 @@ async function consolidate(
snapshot: AnalyticsSnapshotFile,
posthogConfigured: boolean,
): Promise<AnalyticsRollup> {
- const yesterday = addUtcDays(utcDayOf(new Date()), -1);
- const days: string[] = [];
- for (let i = WINDOW_DAYS - 1; i >= 0; i--) days.push(addUtcDays(yesterday, -i));
+ const days = windowDays();
+ const yesterday = days[days.length - 1];
const masks = new Map<string, number[]>();
for (const user of snapshot.users) masks.set(user.id, days.map(() => 0));
@@ -343,16 +329,12 @@ async function consolidate(
}
const balanceByUser = new Map(snapshot.balances.map((b) => [b.userId, b.balanceMicros]));
- const fundedByUser = new Map<string, bigint>();
- for (const payment of snapshot.payments) {
- fundedByUser.set(
- payment.userId,
- (fundedByUser.get(payment.userId) ?? BigInt(0)) + BigInt(payment.amountMicros),
- );
- }
+ const fundedByUser = fundedMicrosByUser(snapshot.stripe);
const storageByUser = new Map((snapshot.storage ?? []).map((s) => [s.userId, s.bytes]));
const proUsers = new Set(
- snapshot.subscriptions.filter((sub) => isActiveProStatus(sub.status)).map((sub) => sub.userId),
+ (snapshot.stripe?.subscriptions ?? [])
+ .filter((sub) => isActiveProStatus(sub.status))
+ .map((sub) => sub.userId),
);
const users = snapshot.users
.map((u) => {
@@ -374,7 +356,7 @@ async function consolidate(
.sort((a, b) => (a.registeredAt < b.registeredAt ? 1 : -1));
const rollup: AnalyticsRollup = {
- billing: buildBilling(snapshot, days),
+ ...(snapshot.stripe ? { billing: buildBilling(snapshot.stripe, billingDays()) } : {}),
days,
generatedAt: new Date().toISOString(),
missing,
@@ -387,48 +369,178 @@ async function consolidate(
return rollup;
}
-// Current subscription state plus the paid-grant revenue record, folded into
-// the counts and per-day sums the dashboard shows. Abandoned checkouts
-// (incomplete statuses) never subscribed, so they count nowhere; past_due and
-// paused sit outside both buckets until Stripe resolves them.
-function buildBilling(
- snapshot: AnalyticsSnapshotFile,
+// All-time paid charges per user, for the user list's funded column.
+function fundedMicrosByUser(stripe: AnalyticsStripeSnapshot | undefined): Map<string, bigint> {
+ const funded = new Map<string, bigint>();
+ for (const charge of stripe?.charges ?? []) {
+ if (charge.status !== "paid" || !charge.userId) continue;
+ funded.set(
+ charge.userId,
+ (funded.get(charge.userId) ?? BigInt(0)) + BigInt(charge.amountMicros),
+ );
+ }
+ return funded;
+}
+
+// The Stripe record folded into what the dashboard shows: subscription state
+// now, per-day money, and the window's declines and cancel requests with the
+// ids that link into Stripe. Abandoned checkouts never subscribed, so they
+// count nowhere in churn; past_due and paused sit outside both buckets until
+// Stripe resolves them.
+export function buildBilling(
+ stripe: AnalyticsStripeSnapshot,
days: string[],
): NonNullable<AnalyticsRollup["billing"]> {
+ type Billing = NonNullable<AnalyticsRollup["billing"]>;
+ const dayIndex = new Map(days.map((day, i) => [day, i]));
+ const inWindow = (iso: string | null) => iso !== null && dayIndex.has(utcDayOf(new Date(iso)));
+
let subscribers = 0;
- let canceling = 0;
let churned = 0;
- for (const sub of snapshot.subscriptions) {
+ const canceling: Billing["canceling"] = [];
+ const events: Billing["events"] = [];
+ const revenue = days.map(() => ({
+ cancels: 0,
+ declinedMicros: BigInt(0),
+ otherMicros: BigInt(0),
+ proMicros: BigInt(0),
+ refundedMicros: BigInt(0),
+ topupMicros: BigInt(0),
+ }));
+
+ for (const sub of stripe.subscriptions) {
if (isActiveProStatus(sub.status)) {
subscribers++;
- if (sub.cancelAtPeriodEnd) canceling++;
+ if (sub.cancelScheduled) {
+ canceling.push({
+ comment: sub.comment,
+ customerId: sub.customerId,
+ email: sub.email,
+ endsAt: sub.cancelAt,
+ feedback: sub.feedback,
+ requestedAt: sub.canceledAt,
+ subscriptionId: sub.id,
+ });
+ }
} else if (sub.status === "canceled" || sub.status === "unpaid") {
churned++;
}
+ // A cancel request lands on the day it was made, whether the
+ // subscription is still running out its period or already ended.
+ if (sub.canceledAt !== null && inWindow(sub.canceledAt)) {
+ const day = utcDayOf(new Date(sub.canceledAt));
+ revenue[dayIndex.get(day)!].cancels++;
+ events.push({
+ amountMicros: null,
+ customerId: sub.customerId,
+ day,
+ detail: [sub.feedback, sub.comment].filter(Boolean).join(" · ") || null,
+ email: sub.email,
+ kind: "canceled",
+ objectId: sub.id,
+ });
+ }
}
+ canceling.sort((a, b) => (a.endsAt ?? "").localeCompare(b.endsAt ?? ""));
- const dayIndex = new Map(days.map((day, i) => [day, i]));
- const revenue = days.map(() => ({ proMicros: BigInt(0), topupMicros: BigInt(0) }));
+ const fundedCustomers = new Set<string>();
let fundedMicros = BigInt(0);
- for (const payment of snapshot.payments) {
- const amount = BigInt(payment.amountMicros);
- fundedMicros += amount;
- const i = dayIndex.get(payment.day);
+ let paidMicros = BigInt(0);
+ let declinedMicros = BigInt(0);
+ const declinedCustomers = new Set<string>();
+ for (const charge of stripe.charges) {
+ const amount = BigInt(charge.amountMicros);
+ const i = dayIndex.get(charge.day);
+ if (charge.status === "paid") {
+ fundedMicros += amount;
+ fundedCustomers.add(charge.customerId ?? charge.id);
+ if (i === undefined) continue;
+ paidMicros += amount;
+ if (charge.kind === "pro") revenue[i].proMicros += amount;
+ else if (charge.kind === "topup") revenue[i].topupMicros += amount;
+ else revenue[i].otherMicros += amount;
+ } else if (i !== undefined) {
+ declinedMicros += amount;
+ declinedCustomers.add(charge.customerId ?? charge.id);
+ revenue[i].declinedMicros += amount;
+ events.push({
+ amountMicros: charge.amountMicros,
+ customerId: charge.customerId,
+ day: charge.day,
+ detail: charge.failure,
+ email: charge.email,
+ kind: "declined",
+ objectId: charge.paymentIntentId,
+ });
+ }
+ }
+
+ let refundedMicros = BigInt(0);
+ for (const refund of stripe.refunds) {
+ const i = dayIndex.get(refund.day);
if (i === undefined) continue;
- if (payment.source === "pro_subscription") revenue[i].proMicros += amount;
- else revenue[i].topupMicros += amount;
+ refundedMicros += BigInt(refund.amountMicros);
+ revenue[i].refundedMicros += BigInt(refund.amountMicros);
}
+ events.sort((a, b) => b.day.localeCompare(a.day));
+
return {
canceling,
churned,
- funded: new Set(snapshot.payments.map((payment) => payment.userId)).size,
+ dashboardUrl: stripe.dashboardUrl,
+ days,
+ events,
+ funded: fundedCustomers.size,
fundedMicros: fundedMicros.toString(),
revenue: revenue.map((entry) => ({
+ cancels: entry.cancels,
+ declinedMicros: entry.declinedMicros.toString(),
+ otherMicros: entry.otherMicros.toString(),
proMicros: entry.proMicros.toString(),
+ refundedMicros: entry.refundedMicros.toString(),
topupMicros: entry.topupMicros.toString(),
})),
subscribers,
+ window: {
+ abandonedCheckouts: stripe.abandonedCheckouts.filter((c) => dayIndex.has(c.day)).length,
+ cancels: revenue.reduce((sum, entry) => sum + entry.cancels, 0),
+ declinedCustomers: declinedCustomers.size,
+ declinedMicros: declinedMicros.toString(),
+ netMicros: (paidMicros - refundedMicros).toString(),
+ paidMicros: paidMicros.toString(),
+ refundedMicros: refundedMicros.toString(),
+ },
+ };
+}
+
+// A Stripe billing webhook lands here: the Stripe record is re-read, the
+// snapshot keeps it for the next nightly consolidation, and the rollup's
+// billing section (plus each user's funded total) is rewritten in place so
+// the dashboard shows the event without waiting for the night. Without a
+// snapshot or rollup yet there is nothing to refresh; the nightly run builds
+// them.
+export async function refreshBilling(): Promise<Prisma.InputJsonValue> {
+ const [snapshot, rollup] = await Promise.all([
+ getObject(SNAPSHOT_KEY).then((obj) => readJson(obj, analyticsSnapshotFileSchema)),
+ getObject(ROLLUP_KEY).then((obj) => readJson(obj, analyticsRollupSchema)),
+ ]);
+ if (!snapshot || !rollup) return { refreshed: false };
+
+ const days = billingDays();
+ const stripe = await pullStripeSnapshot(days[0]);
+ await putJson(SNAPSHOT_KEY, { ...snapshot, stripe });
+
+ const fundedByUser = fundedMicrosByUser(stripe);
+ const users = rollup.users.map((user) => ({
+ ...user,
+ fundedMicros: fundedByUser.get(user.id)?.toString(),
+ }));
+ await putJson(ROLLUP_KEY, { ...rollup, billing: buildBilling(stripe, days), users });
+ return {
+ charges: stripe.charges.length,
+ refreshed: true,
+ subscriptions: stripe.subscriptions.length,
};
}
diff --git a/site/src/lib/analytics/schema.ts b/site/src/lib/analytics/schema.ts
index 477c5c25..4f3eb4fb 100644
--- a/site/src/lib/analytics/schema.ts
+++ b/site/src/lib/analytics/schema.ts
@@ -61,6 +61,69 @@ export const analyticsPosthogDayFileSchema = z.object({
});
export type AnalyticsPosthogDayFile = z.infer<typeof analyticsPosthogDayFileSchema>;
+// What the nightly run and the webhook-driven refresh read from Stripe. Money
+// is BigInt micros as decimal strings; times are ISO. Every row keeps its
+// Stripe id so the dashboard links straight to the object.
+export const analyticsStripeSnapshotSchema = z.object({
+ // Root of the Stripe dashboard for this account's mode (live or test).
+ dashboardUrl: z.string(),
+ // Every Pro subscription ever created, whatever its status now.
+ subscriptions: z.array(
+ z.object({
+ id: z.string(),
+ customerId: z.string().nullable(),
+ userId: z.string().nullable(),
+ email: z.string().nullable(),
+ status: z.string(),
+ createdAt: z.string(),
+ // True while the subscription is live but set to end on its own.
+ cancelScheduled: z.boolean(),
+ // When it ends (or ended), and when the person asked for that.
+ cancelAt: z.string().nullable(),
+ canceledAt: z.string().nullable(),
+ // What they told the portal on the way out.
+ feedback: z.string().nullable(),
+ comment: z.string().nullable(),
+ }),
+ ),
+ // Every charge ever attempted: paid ones are the revenue, declined ones are
+ // people who tried to pay.
+ charges: z.array(
+ z.object({
+ id: z.string(),
+ paymentIntentId: z.string().nullable(),
+ customerId: z.string().nullable(),
+ userId: z.string().nullable(),
+ email: z.string().nullable(),
+ day: analyticsDaySchema,
+ kind: z.enum(["pro", "topup", "other"]),
+ status: z.enum(["paid", "declined"]),
+ amountMicros: z.string(),
+ failure: z.string().nullable(),
+ }),
+ ),
+ // Refunds issued inside the window.
+ refunds: z.array(
+ z.object({
+ id: z.string(),
+ chargeId: z.string().nullable(),
+ day: analyticsDaySchema,
+ amountMicros: z.string(),
+ }),
+ ),
+ // Checkout pages opened inside the window that expired unpaid.
+ abandonedCheckouts: z.array(
+ z.object({
+ id: z.string(),
+ customerId: z.string().nullable(),
+ email: z.string().nullable(),
+ day: analyticsDaySchema,
+ kind: z.enum(["pro", "topup"]),
+ }),
+ ),
+});
+export type AnalyticsStripeSnapshot = z.infer<typeof analyticsStripeSnapshotSchema>;
+
export const analyticsSnapshotFileSchema = z.object({
version: z.literal(1),
generatedAt: z.string(),
@@ -83,25 +146,9 @@ export const analyticsSnapshotFileSchema = z.object({
// Cloud storage counters: bytes held in R2 per user, as decimal strings.
// Absent from snapshots written before this shipped.
storage: z.array(z.object({ userId: z.string(), bytes: z.string() })).optional(),
- // Every Donkey Pro subscription row, whatever its Stripe status.
- subscriptions: z.array(
- z.object({
- userId: z.string(),
- status: z.string(),
- cancelAtPeriodEnd: z.boolean(),
- }),
- ),
- // One entry per paid Stripe credit grant — top-ups, auto-reloads, and Pro
- // monthly allowances. Each grant's amount equals the dollars charged, so
- // together they are the revenue record.
- payments: z.array(
- z.object({
- userId: z.string(),
- day: analyticsDaySchema,
- source: z.string(),
- amountMicros: z.string(),
- }),
- ),
+ // The billing record, read from Stripe. Absent from snapshots written
+ // before this shipped.
+ stripe: analyticsStripeSnapshotSchema.optional().catch(undefined),
});
export type AnalyticsSnapshotFile = z.infer<typeof analyticsSnapshotFileSchema>;
@@ -136,26 +183,79 @@ export const analyticsRollupSchema = z.object({
),
})
.optional(),
- // Subscription and revenue rollup from the snapshot's Stripe-backed rows.
- // Counts are current state at consolidation; revenue aligns with days.
- // Absent from rollups written before this shipped.
+ // Subscriptions and money, derived from the snapshot's Stripe record.
+ // Counts are current state at consolidation; per-day series align with
+ // days. Refreshed in place by the billing-refresh job when Stripe sends a
+ // billing webhook, so it is as fresh as the last Stripe event. Absent from
+ // rollups written before this shipped.
billing: z
.object({
+ dashboardUrl: z.string(),
+ // The billing window, oldest → newest, ending today: money and cancels
+ // land the moment Stripe reports them, so today is part of the record.
+ // The per-day series align with this list.
+ days: z.array(analyticsDaySchema),
// Pro subscriptions with an active status (active or trialing).
subscribers: z.number(),
- // Active subscriptions set to cancel at period end.
- canceling: z.number(),
+ // Live subscriptions set to end on their own, oldest end first.
+ canceling: z.array(
+ z.object({
+ subscriptionId: z.string(),
+ customerId: z.string().nullable(),
+ email: z.string().nullable(),
+ endsAt: z.string().nullable(),
+ requestedAt: z.string().nullable(),
+ feedback: z.string().nullable(),
+ comment: z.string().nullable(),
+ }),
+ ),
// Subscriptions that ended after being live (canceled or unpaid);
// abandoned checkouts never count.
churned: z.number(),
- // Users with at least one paid Stripe grant, and their all-time total.
+ // Customers with at least one paid charge, and their all-time total.
funded: z.number(),
fundedMicros: z.string(),
- // Per-day paid charges, aligned with days: Pro allowances vs top-ups
- // (one-time and auto-reload). BigInt micros as decimal strings.
- revenue: z.array(z.object({ proMicros: z.string(), topupMicros: z.string() })),
+ // Window totals. Net = paid minus refunded; declined is money that was
+ // attempted and never arrived, so it sits outside net.
+ window: z.object({
+ paidMicros: z.string(),
+ refundedMicros: z.string(),
+ netMicros: z.string(),
+ declinedMicros: z.string(),
+ declinedCustomers: z.number(),
+ abandonedCheckouts: z.number(),
+ cancels: z.number(),
+ }),
+ // Per day, aligned with billing.days. BigInt micros as decimal strings.
+ revenue: z.array(
+ z.object({
+ proMicros: z.string(),
+ topupMicros: z.string(),
+ otherMicros: z.string(),
+ refundedMicros: z.string(),
+ declinedMicros: z.string(),
+ // Cancel requests made that day.
+ cancels: z.number(),
+ }),
+ ),
+ // The window's declined charges and cancel requests, newest first, each
+ // with the ids that link into Stripe.
+ events: z.array(
+ z.object({
+ day: analyticsDaySchema,
+ kind: z.enum(["declined", "canceled"]),
+ email: z.string().nullable(),
+ customerId: z.string().nullable(),
+ // Payment intent for a decline, subscription for a cancel.
+ objectId: z.string().nullable(),
+ amountMicros: z.string().nullable(),
+ // The decline reason, or the cancel feedback and comment.
+ detail: z.string().nullable(),
+ }),
+ ),
})
- .optional(),
+ .optional()
+ .catch(undefined),
users: z.array(
z.object({
id: z.string(),
diff --git a/site/src/lib/analytics/stripe.ts b/site/src/lib/analytics/stripe.ts
new file mode 100644
index 00000000..86a47c9f
--- /dev/null
+++ b/site/src/lib/analytics/stripe.ts
@@ -0,0 +1,155 @@
+// The billing side of the analytics snapshot, read straight from Stripe.
+// Stripe is where the money is, so its charges, refunds, subscriptions and
+// abandoned checkouts are the record; every row keeps the Stripe id so the
+// dashboard can link into it.
+
+import { drainStripe, getStripe, stripeId, StripeNotConfiguredError } from "@/lib/billing/stripe";
+import { subscriptionCancelScheduled, subscriptionIsPro, syncProSubscription } from "@/lib/billing/pro-subscription";
+import { creditMicrosPerCent } from "@/lib/credits/amounts";
+import { creditAutoReloadKind, creditTopUpKind } from "@/lib/credits/top-up";
+import { type AnalyticsStripeSnapshot, utcDayOf } from "@/lib/analytics/schema";
+import { prisma } from "@/lib/prisma";
+
+const PAGE = { limit: 100 } as const;
+// The credit-purchase kinds stamped on a PaymentIntent at checkout.
+const TOPUP_KINDS = new Set<string>([creditTopUpKind, creditAutoReloadKind]);
+
+const microsOf = (cents: number) => (BigInt(cents) * creditMicrosPerCent).toString();
+const dayOfUnix = (seconds: number) => utcDayOf(new Date(seconds * 1000));
+const isoOfUnix = (seconds: number) => new Date(seconds * 1000).toISOString();
+
+// The dashboard for the account the key belongs to: a test-mode key names
+// test-mode objects, which live under /test.
+export function stripeDashboardUrl(): string {
+ const key = process.env.STRIPE_SECRET_KEY;
+ if (!key) throw new StripeNotConfiguredError();
+ return key.includes("_test_") ? "https://dashboard.stripe.com/test" : "https://dashboard.stripe.com";
+}
+
+/** Everything the rollup's billing section is derived from. `since` bounds
+ * the window-scoped lists (refunds, declines, abandoned checkouts); charges
+ * and subscriptions come whole because the funded-all-time figures need them. */
+export async function pullStripeSnapshot(since: string): Promise<AnalyticsStripeSnapshot> {
+ const stripe = getStripe();
+ const sinceUnix = Math.floor(Date.parse(`${since}T00:00:00Z`) / 1000);
+
+ // A customer names its user through the metadata stamped at creation, or
+ // through the customer id the user row keeps, the same two routes the
+ // webhook sync resolves by.
+ const customers = await drainStripe(stripe.customers.list(PAGE));
+ const customerById = new Map(customers.map((c) => [c.id, c]));
+ const userByCustomer = new Map(
+ (
+ await prisma.user.findMany({
+ select: { id: true, stripeCustomerId: true },
+ where: { stripeCustomerId: { in: customers.map((c) => c.id) } },
+ })
+ ).map((user) => [user.stripeCustomerId as string, user.id]),
+ );
+ const customerOf = (ref: string | { id: string } | null | undefined) => {
+ const id = stripeId(ref);
+ const customer = id ? customerById.get(id) : undefined;
+ return {
+ customerId: id,
+ email: customer?.email ?? null,
+ userId: customer?.metadata?.userId ?? (id ? (userByCustomer.get(id) ?? null) : null),
+ };
+ };
+
+ // Stripe lists newest first. A user has one row in our database, so only
+ // their newest subscription is synced into it: that row follows Stripe
+ // here too, and a cancel scheduled through the portal reaches the
+ // account's settings card without waiting on a webhook.
+ const subscriptions: AnalyticsStripeSnapshot["subscriptions"] = [];
+ const synced = new Set<string>();
+ for (const sub of await drainStripe(stripe.subscriptions.list({ ...PAGE, status: "all" }))) {
+ if (!subscriptionIsPro(sub)) continue;
+ const who = customerOf(sub.customer);
+ const owner = sub.metadata?.userId ?? who.userId ?? who.customerId ?? sub.id;
+ if (!synced.has(owner)) {
+ synced.add(owner);
+ await syncProSubscription(sub);
+ }
+ subscriptions.push({
+ cancelAt: sub.cancel_at !== null ? isoOfUnix(sub.cancel_at) : null,
+ canceledAt: sub.canceled_at !== null ? isoOfUnix(sub.canceled_at) : null,
+ cancelScheduled: subscriptionCancelScheduled(sub),
+ comment: sub.cancellation_details?.comment ?? null,
+ createdAt: isoOfUnix(sub.created),
+ customerId: who.customerId,
+ email: who.email,
+ feedback: sub.cancellation_details?.feedback ?? null,
+ id: sub.id,
+ status: sub.status,
+ userId: sub.metadata?.userId ?? who.userId,
+ });
+ }
+
+ // A charge is a top-up when its PaymentIntent carries a credit-purchase
+ // kind, Pro when its customer holds a Pro subscription, and otherwise
+ // "other": money the dashboard shows as its own bucket.
+ const proCustomers = new Set(subscriptions.map((sub) => sub.customerId));
+ const charges: AnalyticsStripeSnapshot["charges"] = [];
+ for (const charge of await drainStripe(
+ stripe.charges.list({ ...PAGE, expand: ["data.payment_intent"] }),
+ )) {
+ if (charge.status === "pending") continue;
+ const intent =
+ typeof charge.payment_intent === "object" ? charge.payment_intent : null;
+ const who = customerOf(charge.customer);
+ charges.push({
+ amountMicros: microsOf(charge.amount),
+ customerId: who.customerId,
+ day: dayOfUnix(charge.created),
+ email: charge.billing_details?.email ?? who.email,
+ failure: charge.failure_message ?? charge.failure_code,
+ id: charge.id,
+ kind: TOPUP_KINDS.has(intent?.metadata?.kind ?? "")
+ ? "topup"
+ : proCustomers.has(who.customerId)
+ ? "pro"
+ : "other",
+ paymentIntentId: stripeId(charge.payment_intent),
+ status: charge.status === "succeeded" && charge.paid ? "paid" : "declined",
+ userId: intent?.metadata?.userId ?? who.userId,
+ });
+ }
+
+ const refunds: AnalyticsStripeSnapshot["refunds"] = [];
+ for (const refund of await drainStripe(
+ stripe.refunds.list({ ...PAGE, created: { gte: sinceUnix } }),
+ )) {
+ if (refund.status === "failed" || refund.status === "canceled") continue;
+ refunds.push({
+ amountMicros: microsOf(refund.amount),
+ chargeId: stripeId(refund.charge),
+ day: dayOfUnix(refund.created),
+ id: refund.id,
+ });
+ }
+
+ // A checkout that expired unpaid is someone who opened the payment page and
+ // walked away; an open session may still complete, so it waits.
+ const abandonedCheckouts: AnalyticsStripeSnapshot["abandonedCheckouts"] = [];
+ for (const session of await drainStripe(
+ stripe.checkout.sessions.list({ ...PAGE, created: { gte: sinceUnix } }),
+ )) {
+ if (session.status !== "expired") continue;
+ const who = customerOf(session.customer);
+ abandonedCheckouts.push({
+ customerId: who.customerId,
+ day: dayOfUnix(session.created),
+ email: session.customer_details?.email ?? who.email,
+ id: session.id,
+ kind: session.mode === "subscription" ? "pro" : "topup",
+ });
+ }
+
+ return {
+ abandonedCheckouts,
+ charges,
+ dashboardUrl: stripeDashboardUrl(),
+ refunds,
+ subscriptions,
+ };
+}
diff --git a/site/src/lib/billing/stripe.ts b/site/src/lib/billing/stripe.ts
index 79c0b596..9acab9a1 100644
--- a/site/src/lib/billing/stripe.ts
+++ b/site/src/lib/billing/stripe.ts
@@ -4,6 +4,25 @@ import { prisma } from "@/lib/prisma";
let cachedStripe: Stripe | null = null;
+// Every list drained through Stripe's auto-pager stops here, far above what
+// the account holds. Reaching it is an error: a figure built from a
+// truncated list would be quietly wrong.
+export const STRIPE_LIST_CAP = 10_000;
+
+export class StripeListTooLongError extends Error {
+ public constructor() {
+ super(`A Stripe list passed ${STRIPE_LIST_CAP} rows; raise STRIPE_LIST_CAP.`);
+ this.name = "StripeListTooLongError";
+ }
+}
+
+/** Drain a Stripe list to an array; throws when it reaches the cap. */
+export async function drainStripe<T>(list: Stripe.ApiListPromise<T>): Promise<T[]> {
+ const rows = await list.autoPagingToArray({ limit: STRIPE_LIST_CAP });
+ if (rows.length >= STRIPE_LIST_CAP) throw new StripeListTooLongError();
+ return rows;
+}
+
export function getStripe(): Stripe {
if (cachedStripe) {
return cachedStripe;
diff --git a/site/src/lib/billing/webhook-events.ts b/site/src/lib/billing/webhook-events.ts
new file mode 100644
index 00000000..a5ad5d83
--- /dev/null
+++ b/site/src/lib/billing/webhook-events.ts
@@ -0,0 +1,20 @@
+// Stripe events that change what the super-user analytics show: money moving
+// or failing to, a subscription changing state, a checkout walked away from.
+// The webhook queues a billing refresh for each; the ones without a handler
+// of their own exist only for that. This list, plus the handled events, is
+// what the endpoint in Stripe is subscribed to (scripts/stripe-webhook-events.ts).
+export const ANALYTICS_BILLING_EVENTS = [
+ "charge.failed",
+ "charge.refunded",
+ "charge.succeeded",
+ "checkout.session.completed",
+ "checkout.session.expired",
+ "customer.subscription.created",
+ "customer.subscription.deleted",
+ "customer.subscription.updated",
+ "invoice.paid",
+ "invoice.payment_failed",
+ "payment_intent.payment_failed",
+ "payment_intent.succeeded",
+ "refund.created",
+] as const;
diff --git a/site/src/lib/jobs/analytics-daily.ts b/site/src/lib/jobs/analytics-daily.ts
index b49cab71..e11636d5 100644
--- a/site/src/lib/jobs/analytics-daily.ts
+++ b/site/src/lib/jobs/analytics-daily.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
import { R2NotConfiguredError } from "@/cut/server/cloud/r2";
import { InvalidDayError, runAnalyticsDaily } from "@/lib/analytics/pipeline";
import { PosthogConfigError } from "@/lib/analytics/posthog";
+import { StripeListTooLongError, StripeNotConfiguredError } from "@/lib/billing/stripe";
import { defineJob, JobFailure } from "@/lib/jobs/registry";
// The nightly analytics run, also retriggerable by hand. An empty payload is
@@ -22,12 +23,15 @@ export const analyticsDailyJob = defineJob(
try {
return await runAnalyticsDaily(payload);
} catch (e) {
- // All three are permanent: retrying an unconfigured store, a bad
- // PostHog project id, or an impossible day can never succeed.
+ // All of these are permanent: retrying an unconfigured store or Stripe,
+ // a bad PostHog project id, an impossible day, or a Stripe list past
+ // the cap can never succeed.
if (
e instanceof R2NotConfiguredError ||
e instanceof InvalidDayError ||
- e instanceof PosthogConfigError
+ e instanceof PosthogConfigError ||
+ e instanceof StripeNotConfiguredError ||
+ e instanceof StripeListTooLongError
) {
throw new JobFailure(e.message);
}
diff --git a/site/src/lib/jobs/billing-refresh.ts b/site/src/lib/jobs/billing-refresh.ts
new file mode 100644
index 00000000..ea8428da
--- /dev/null
+++ b/site/src/lib/jobs/billing-refresh.ts
@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+import { R2NotConfiguredError } from "@/cut/server/cloud/r2";
+import { refreshBilling } from "@/lib/analytics/pipeline";
+import { StripeListTooLongError, StripeNotConfiguredError } from "@/lib/billing/stripe";
+import { defineJob, JobFailure } from "@/lib/jobs/registry";
+
+// Re-reads the Stripe record into the analytics snapshot and rewrites the
+// rollup's billing section. Queued by the Stripe webhook on every billing
+// event, so the dashboard's money and subscription figures follow Stripe as
+// it happens; also retriggerable by hand.
+export const billingRefreshJob = defineJob(z.object({}).strict(), async () => {
+ try {
+ return await refreshBilling();
+ } catch (e) {
+ if (
+ e instanceof R2NotConfiguredError ||
+ e instanceof StripeNotConfiguredError ||
+ e instanceof StripeListTooLongError
+ ) {
+ throw new JobFailure(e.message);
+ }
+ throw e;
+ }
+});
diff --git a/site/src/lib/jobs/registry.ts b/site/src/lib/jobs/registry.ts
index c06c57d0..52d0b739 100644
--- a/site/src/lib/jobs/registry.ts
+++ b/site/src/lib/jobs/registry.ts
@@ -2,6 +2,7 @@ import type { z } from "zod";
import type { Prisma } from "@/generated/prisma/client";
import { analyticsDailyJob } from "@/lib/jobs/analytics-daily";
+import { billingRefreshJob } from "@/lib/jobs/billing-refresh";
import { deleteUserJob } from "@/lib/jobs/delete-user";
import { experimentResultsJob } from "@/lib/jobs/experiment-results";
import { outreachScanJob } from "@/lib/jobs/outreach-scan";
@@ -27,6 +28,7 @@ export function defineJob<S extends z.ZodType<unknown>>(
export const jobKinds: Record<string, JobKind> = {
"analytics-daily": analyticsDailyJob,
+ "billing-refresh": billingRefreshJob,
"delete-user": deleteUserJob,
"experiment-results": experimentResultsJob,
"outreach-scan": outreachScanJob,