Open source CapCut alternative.
TypeScript
feat(site): email sends budgeted over the plan's billing cycle
David Le7cc6102ddfb8
diff --git a/site/prisma/Email.prisma b/site/prisma/Email.prismaindex bc479f92..1dcd7336 100644--- a/site/prisma/Email.prisma+++ b/site/prisma/Email.prisma@@ -9,14 +9,14 @@ model UserEmailSettings {// Claimed before sending, so a retried signup can never double-send.welcomeEmailSentAt DateTime?// Null means subscribed. Set by the one-click endpoint, the /unsubscribe- // page, the settings toggle, or the Resend webhook.+ // page, or the settings toggle.marketingUnsubscribedAt DateTime?createdAt DateTime @default(now())updatedAt DateTime @updatedAt}// The outbox. Every email the site sends is a row here first; one drainer-// sends rows in priority order under the day's quota+// sends rows in priority order under the plan's monthly budget// (src/lib/email/outbox.ts). The row is the send's record: a retried queue// call adds nothing because the idempotency key is unique.model EmailSend {@@ -25,7 +25,9 @@ model EmailSend {kind String// Higher goes first: the kind's priority when the row was queued.priority Int- // Order within a priority. A promotion's most recently active recipient is 0.+ // Order within a priority. A promotion row holds the seconds since its+ // recipient last used the product when it was queued, so the most recently+ // active go first.rank Int @default(0)userId String?user User? @relation(fields: [userId], references: [id], onDelete: Cascade)diff --git a/site/scripts/send-credits-expiring.ts b/site/scripts/send-credits-expiring.tsindex 1a4bde67..314fd4f3 100644--- a/site/scripts/send-credits-expiring.ts+++ b/site/scripts/send-credits-expiring.ts@@ -17,7 +17,7 @@ import { getGlobalSetting } from "../src/lib/config/effective";import { creditMicrosToString } from "../src/lib/credits/amounts";import { pendingCreditExpiryGrants } from "../src/lib/email/credit-expiry-due";import { queueDueCreditExpiryNotices } from "../src/lib/email/credit-expiry-notices";-import { withDailyEmailQuota } from "../src/lib/email/daily-send-limit";+import { withEmailBudget } from "../src/lib/email/send-budget";import { drainOutbox } from "../src/lib/email/outbox";import { getResend } from "../src/lib/email/resend";import { buildCreditsExpiringEmail } from "../src/lib/email/send-credits-expiring";@@ -61,7 +61,7 @@ if (preview) {creditMicrosToString(sample.remainingAmountMicros),sample.expiresAt,);- const result = await withDailyEmailQuota("manual", () =>+ const result = await withEmailBudget("manual", () =>// Every preview is its own send, whatever the copy did in between.getResend().emails.send(message, { idempotencyKey: `credits-expiring-preview:${preview}:${Date.now()}` }),);diff --git a/site/src/app/su/jobs/email/page.tsx b/site/src/app/su/jobs/email/page.tsxindex d35bcb60..ed6a67c2 100644--- a/site/src/app/su/jobs/email/page.tsx+++ b/site/src/app/su/jobs/email/page.tsx@@ -28,11 +28,17 @@ function formatWhen(iso: string): string {}function formatDuration(seconds: number): string {- const h = Math.floor(seconds / 3600);+ const d = Math.floor(seconds / 86400);+ const h = Math.floor((seconds % 86400) / 3600);const m = Math.floor((seconds % 3600) / 60);+ if (d > 0) return `${d}d ${h}h`;return h > 0 ? `${h}h ${m}m` : `${m}m`;}+function formatDay(iso: string): string {+ return new Date(iso).toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: "UTC" });+}+const stateDot: Record<string, string> = {queued: "bg-muted-foreground/40",sending: "bg-blue-500 animate-pulse",@@ -41,8 +47,9 @@ const stateDot: Record<string, string> = {failed: "bg-destructive",};-// The day's quota as three stop lines on one counter. Each bar is how far-// that class of send may go today; the fill is what has gone out so far.+// The cycle's budget as three stop lines on one counter. Each bar is how far+// that class of send may go before the plan renews; the fill is what has+// gone out so far this cycle.function QuotaSection({ quota }: { quota: OutboxOverview["quota"] }) {const { forecast } = quota;const classes = [@@ -51,29 +58,31 @@ function QuotaSection({ quota }: { quota: OutboxOverview["quota"] }) {ceiling: quota.ceilings.manual,note:quota.manualReserve > 0- ? `${quota.manualReserve} held below this for hand-sent mail while work hours remain`- : "work hours over; the hand-sent reserve is released",+ ? `${quota.manualReserve} held below this for hand-sent mail on the work days left`+ : "no work days left; the hand-sent reserve is released",},{ label: "Transactional", ceiling: quota.ceilings.transactional, note: "welcome and credit emails" },{label: "Bulk",ceiling: quota.ceilings.bulk,- note: `holds back ${forecast.total} for the rest of today: ${forecast.signups} signups expected, ${forecast.expiry} expiry notices owed, ${forecast.headroom} headroom`,+ note: `holds back ${forecast.total} for the rest of the cycle: ${forecast.signups} signups expected, ${forecast.expiry} expiry notices owed, ${forecast.headroom} headroom`,},];return (<section className="space-y-3"><div className="flex flex-wrap items-baseline gap-x-3 text-sm">- <span className="font-medium">Today, {quota.day} UTC</span>+ <span className="font-medium">+ Cycle {formatDay(quota.cycle.start)} – {formatDay(quota.cycle.end)}+ </span><span className="text-muted-foreground">- {quota.sent} of {quota.providerLimit} sent · resets in {formatDuration(quota.resetsInSeconds)}+ {quota.sent} of {quota.allowance} sent · {quota.sentToday} today · renews in {formatDuration(quota.renewsInSeconds)}</span></div><ul className="space-y-3">{classes.map((c) => {const ceiling = Math.max(0, c.ceiling);- const width = Math.min(100, (100 * ceiling) / quota.providerLimit);- const fill = Math.min(100, (100 * Math.min(quota.sent, ceiling)) / quota.providerLimit);+ const width = Math.min(100, (100 * ceiling) / quota.allowance);+ const fill = Math.min(100, (100 * Math.min(quota.sent, ceiling)) / quota.allowance);const left = Math.max(0, ceiling - quota.sent);return (<li key={c.label} className="grid grid-cols-[120px_1fr_72px] items-center gap-x-3 gap-y-0.5 text-sm">@@ -285,7 +294,7 @@ function ItemsSection({);}-// The outbox: where the day's quota stands, what each kind has queued and+// The outbox: where the cycle's budget stands, what each kind has queued and// sent, and the rows waiting, failed, and lately sent. The layout gates this// route to super users, so the hook runs unconditionally.export default function SuEmailPage() {diff --git a/site/src/lib/config/registry.ts b/site/src/lib/config/registry.tsindex 183d6159..0df7b935 100644--- a/site/src/lib/config/registry.ts+++ b/site/src/lib/config/registry.ts@@ -96,13 +96,15 @@ export const SETTINGS = defineSettings({title: "Signup credits",description: "USD a new account is granted at signup, and how many days the grant lives.",},- emailDailySend: {+ emailSendBudget: {schema: z.object({- // Emails the provider lets the account send per UTC day.- providerLimit: z.number().int().min(1).max(100000),- // Slots kept free for emails sent by hand while work hours remain in- // the UTC day; released once the work day is over.+ // Emails the provider's plan includes per billing cycle.+ monthlyAllowance: z.number().int().min(1).max(10_000_000),+ // Day of the month the plan renews, at UTC midnight.+ renewalDay: z.number().int().min(1).max(31),+ // Slots kept free per work day for emails sent by hand, held for+ // every work day left in the cycle.manualReserve: z.number().int().min(0).max(100000),manualTimeZone: z.string().refine(validTimeZone, "Unknown IANA time zone"),// Work hours in that zone, start inclusive and end exclusive.@@ -113,27 +115,29 @@ export const SETTINGS = defineSettings({signupLookbackDays: z.number().int().min(1).max(90),// Slots kept free beyond the forecast for transactional email the// forecast cannot see, such as credit offers sent by hand.- transactionalHeadroom: z.number().int().min(0).max(100000),+ transactionalHeadroom: z.number().int().min(0).max(1_000_000),}).strict().refine((v) => v.manualStartHour < v.manualEndHour, { message: "Work hours must end after they start." })- .refine((v) => v.manualReserve + v.transactionalHeadroom < v.providerLimit, {- message: "The reserves must leave room for bulk sends.",+ // A cycle holds at most 31 work days, so this keeps every ceiling above zero.+ .refine((v) => v.manualReserve * 31 + v.transactionalHeadroom < v.monthlyAllowance, {+ message: "The reserves must leave room for bulk sends over a 31-day cycle.",}),default: {- providerLimit: 99,+ monthlyAllowance: 50000,+ renewalDay: 11,manualReserve: 10,manualTimeZone: "Asia/Seoul",manualStartHour: 9,manualEndHour: 18,manualWeekdaysOnly: true,signupLookbackDays: 7,- transactionalHeadroom: 5,+ transactionalHeadroom: 200,},public: false,- title: "Daily email sends",+ title: "Email send budget",description:- "The provider's daily send cap, the slots held for emails sent by hand during work hours, and how the transactional forecast that holds slots ahead of promotions is sized.",+ "The plan's monthly allowance and renewal day, the slots held per work day for emails sent by hand, and how the transactional forecast that holds slots ahead of promotions is sized.",},emailPriorities: {schema: z@@ -142,7 +146,7 @@ export const SETTINGS = defineSettings({default: { ...DEFAULT_EMAIL_PRIORITIES },public: false,title: "Email priorities",- description: "The order the outbox sends in when the day's quota is short: higher goes first. A change applies to emails queued from then on.",+ description: "The order the outbox sends in when the budget is short: higher goes first. A change applies to emails queued from then on.",},creditExpiryNotice: {schema: zdiff --git a/site/src/lib/email/daily-send-limit.ts b/site/src/lib/email/daily-send-limit.tsdeleted file mode 100644index 7ce12817..00000000--- a/site/src/lib/email/daily-send-limit.ts+++ /dev/null@@ -1,129 +0,0 @@-import { utcDayOf } from "@/lib/analytics/schema";-import { getGlobalSetting } from "@/lib/config/effective";-import { expectedTransactionalSends, manualHoursRemainToday, type TransactionalForecast } from "@/lib/email/send-forecast";-import { prisma } from "@/lib/prisma";--// One counter per UTC day, three ceilings on it. Manual sends run up to the-// provider's cap. Transactional sends stop below the slots held for hand-sent-// mail while work hours remain. Bulk sends stop below what the rest of the-// day is forecast to need for transactional email, so a promotion never-// blocks a welcome email and takes the slots the forecast releases as the-// day runs down. A slot is counted when it is reserved and given back when-// the send fails, so a process that dies mid-send costs the day one slot.-export type EmailSendKind = "manual" | "transactional" | "bulk";--// How long a refused send waits before asking again while the day's-// ceilings still hold slots back; they rise as the day goes on.-const FORECAST_RETRY_SECONDS = 15 * 60;--export class DailyEmailSendLimitError extends Error {- public constructor(- public readonly day: string,- public readonly kind: EmailSendKind,- public readonly limit: number,- public readonly remaining: number,- public readonly retryAfterSeconds: number,- ) {- super(`Daily email limit reached for ${kind} sends on ${day}: ${remaining} of ${limit} available.`);- this.name = "DailyEmailSendLimitError";- }-}--function secondsUntilNextUtcDay(now: Date): number {- const next = new Date(now);- next.setUTCHours(24, 0, 0, 0);- return Math.max(1, Math.ceil((next.getTime() - now.getTime()) / 1000));-}--export type DailyEmailQuotaStatus = {- day: string;- sent: number;- providerLimit: number;- // Slots held for hand-sent mail right now; 0 once the work day is over.- manualReserve: number;- forecast: TransactionalForecast;- ceilings: Record<EmailSendKind, number>;- resetsInSeconds: number;-};--/** Where the day stands: what went, and how far each kind of send can go. */-export async function dailyEmailQuotaStatus(now = new Date()): Promise<DailyEmailQuotaStatus> {- const day = utcDayOf(now);- const [setting, row] = await Promise.all([- getGlobalSetting("emailDailySend"),- prisma.emailDailyQuota.findUnique({ select: { sent: true }, where: { day } }),- ]);- const manualReserve = manualHoursRemainToday(now, setting) ? setting.manualReserve : 0;- const forecast = await expectedTransactionalSends(now, setting);- const transactional = setting.providerLimit - manualReserve;- return {- day,- sent: row?.sent ?? 0,- providerLimit: setting.providerLimit,- manualReserve,- forecast,- ceilings: { manual: setting.providerLimit, transactional, bulk: transactional - forecast.total },- resetsInSeconds: secondsUntilNextUtcDay(now),- };-}--async function ceilingFor(kind: EmailSendKind, now: Date): Promise<{ limit: number; floor: number }> {- const { ceilings, forecast, providerLimit } = await dailyEmailQuotaStatus(now);- // The lowest any ceiling can settle at tonight: the cap minus the headroom- // the forecast keeps to the end.- const floor = kind === "bulk" ? providerLimit - forecast.headroom : providerLimit;- return { limit: ceilings[kind], floor };-}--async function reserveSlot(day: string, kind: EmailSendKind, now: Date): Promise<void> {- const { limit, floor } = await ceilingFor(kind, now);- await prisma.emailDailyQuota.createMany({ data: [{ day }], skipDuplicates: true });- // One conditional increment: the row moves only while it is under the- // ceiling, so two senders can never both take the last slot.- const taken = await prisma.emailDailyQuota.updateMany({- data: { sent: { increment: 1 } },- where: { day, sent: { lt: limit } },- });- if (taken.count > 0) return;-- const row = await prisma.emailDailyQuota.findUnique({ select: { sent: true }, where: { day } });- const sent = row?.sent ?? 0;- const retryAfterSeconds = sent < floor ? FORECAST_RETRY_SECONDS : secondsUntilNextUtcDay(now);- throw new DailyEmailSendLimitError(day, kind, limit, Math.max(0, limit - sent), retryAfterSeconds);-}--async function releaseSlot(day: string): Promise<void> {- await prisma.emailDailyQuota.updateMany({- data: { sent: { decrement: 1 } },- where: { day, sent: { gt: 0 } },- });-}--/** Runs one provider send inside the day's quota, with the slot held before- * the callback starts so what it builds goes out at once. The slot is kept- * only when the provider accepted the email: a thrown error, a resolved- * `{ error }`, or null (nothing to send) gives it back. */-export async function withDailyEmailQuota<T extends { error: unknown }>(- kind: EmailSendKind,- send: () => Promise<T | null>,-): Promise<T | null> {- const now = new Date();- const day = utcDayOf(now);- await reserveSlot(day, kind, now);- const release = () =>- releaseSlot(day).catch((releaseError) => {- console.error("[email] failed to release a daily email slot", {- day,- error: releaseError instanceof Error ? releaseError.message : String(releaseError),- });- });- let result: T | null;- try {- result = await send();- } catch (error) {- await release();- throw error;- }- if (result === null || result.error) await release();- return result;-}diff --git a/site/src/lib/email/kinds.ts b/site/src/lib/email/kinds.tsindex 2e22b068..809330e1 100644--- a/site/src/lib/email/kinds.ts+++ b/site/src/lib/email/kinds.ts@@ -3,7 +3,7 @@ import { z } from "zod";import { creditOfferClaimUrl, createPromotionCreditOffer } from "@/lib/credits/offers";import { clickUrl } from "@/lib/email/click";import { recordExpiryNoticeSent } from "@/lib/email/credit-expiry-notices";-import type { EmailSendKind } from "@/lib/email/daily-send-limit";+import type { EmailSendKind } from "@/lib/email/send-budget";import { PermanentSendError } from "@/lib/email/errors";import type { EmailKindId } from "@/lib/email/kindIds";import type { EmailMessage, EmailUser } from "@/lib/email/resend";diff --git a/site/src/lib/email/outbox.ts b/site/src/lib/email/outbox.tsindex 75617c80..8a5cfc12 100644--- a/site/src/lib/email/outbox.ts+++ b/site/src/lib/email/outbox.ts@@ -1,12 +1,12 @@import type { Prisma } from "@/generated/prisma/client";import { getGlobalSetting } from "@/lib/config/effective";import {- DailyEmailSendLimitError,- dailyEmailQuotaStatus,- type DailyEmailQuotaStatus,+ EmailBudgetError,+ emailBudgetStatus,+ type EmailBudgetStatus,type EmailSendKind,- withDailyEmailQuota,-} from "@/lib/email/daily-send-limit";+ withEmailBudget,+} from "@/lib/email/send-budget";import { PermanentSendError } from "@/lib/email/errors";import { EMAIL_KIND_IDS, type EmailKindId } from "@/lib/email/kindIds";import { EMAIL_KINDS, type OutboxRow } from "@/lib/email/kinds";@@ -15,9 +15,9 @@ import { UnknownPlaceholderError } from "@/lib/marketing/placeholders";import { prisma } from "@/lib/prisma";// The outbox. Every email is queued as a row and sent by the drainer in-// priority order, each row under its kind's share of the day's quota. An+// priority order, each row under its kind's share of the cycle's budget. An// interactive send (an operator's note, a signup's welcome) is queued and-// tried at once; when the quota refuses it, it waits its turn. The row is+// tried at once; when the budget refuses it, it waits its turn. The row is// the record: what went, what failed and why, and what is still owed.const PAGE = 50;@@ -89,7 +89,7 @@ export async function queueEmails(inputs: QueueEmailInput[]): Promise<number> {return count;}-/** Queues one email and tries to send it now. When the quota refuses it, the+/** Queues one email and tries to send it now. When the budget refuses it, the* row waits for the drainer; a permanent failure is reported on the result. */export async function deliverEmail(input: QueueEmailInput): Promise<DeliverResult> {const [data] = await rowsOf([input]);@@ -113,7 +113,7 @@ export async function scheduleDrain(delaySeconds: number): Promise<void> {}/** Starts a drainer for one kind now, on an operator's say-so. Its own job,- * so a drainer held back by another kind's quota wait does not stand in+ * so a drainer held back by another kind's budget wait does not stand in* for it. */export async function drainKindNow(kind: EmailKindId, createdBy: string): Promise<void> {const { enqueueJob } = await import("@/lib/jobs/queue");@@ -149,7 +149,7 @@ async function sendRow(row: DrainableRow, now: Date): Promise<Outcome> {if (!isResendConfigured()) throw new ResendNotConfiguredError();// The slot is held before the message is built, so anything the build// writes down (a claim window, say) dates from the send itself.- const result = await withDailyEmailQuota(kind.quota, async () => {+ const result = await withEmailBudget(kind.quota, async () => {const message = await kind.build(payload, outboxRow);return message ? getResend().emails.send(message, { idempotencyKey: row.idempotencyKey }) : null;});@@ -162,7 +162,7 @@ async function sendRow(row: DrainableRow, now: Date): Promise<Outcome> {await kind.afterSend?.(payload, outboxRow);return { outcome: "sent" };} catch (error) {- if (error instanceof DailyEmailSendLimitError) {+ if (error instanceof EmailBudgetError) {await settle({ state: "queued" });return { outcome: "refused", retryAfterSeconds: error.retryAfterSeconds };}@@ -183,15 +183,15 @@ export type DrainResult = {failed: number;skipped: number;retried: number;- // Seconds until the next thing worth coming back for: a refused quota+ // Seconds until the next thing worth coming back for: a refused budget// expected to open, or a backed-off row coming due. Null when nothing waits.retryAfterSeconds: number | null;// Whether the budget ran out with rows still owed.more: boolean;};-/** Sends what the outbox holds, highest priority first, until the budget or- * the quota runs out. A refused quota class is left alone for the rest of+/** Sends what the outbox holds, highest priority first, until the time or+ * the budget runs out. A refused budget class is left alone for the rest of* the run; the classes above it keep going. Given a kind, only that kind's* rows go. */export async function drainOutbox(budgetMs: number, kind?: EmailKindId): Promise<DrainResult> {@@ -214,7 +214,7 @@ export async function drainOutbox(budgetMs: number, kind?: EmailKindId): Promiseclaimable(now),{ kind: kind ?? { notIn: refusedKinds() }, notBefore: { lte: now } },// A paused promotion's rows wait where they are.- { OR: [{ promotionId: null }, { promotion: { status: "sending" } }] },+ { OR: [{ promotionId: null }, { promotion: { status: { in: ["queuing", "sending"] } } }] },],},});@@ -254,13 +254,14 @@ async function nextBackedOffRow(now: Date, kind?: EmailKindId): Promise<Date | nkind,notBefore: { gt: now },state: "queued",- OR: [{ promotionId: null }, { promotion: { status: "sending" } }],+ OR: [{ promotionId: null }, { promotion: { status: { in: ["queuing", "sending"] } } }],},});return row?.notBefore ?? null;}-// A promotion with nothing left to send is sent.+// A promotion with every recipient queued and nothing left to send is sent.+// One still queuing is left to its job, which finishes it or hands it here.async function finishPromotions(promotionIds: Set<string>): Promise<void> {for (const promotionId of promotionIds) {const owed = await prisma.emailSend.count({ where: { promotionId, state: { in: ["queued", "sending"] } } });@@ -314,7 +315,7 @@ export type OutboxCampaign = {};export type OutboxOverview = {- quota: DailyEmailQuotaStatus;+ quota: EmailBudgetStatus;kinds: OutboxKindRow[];campaigns: OutboxCampaign[];// What is waiting, then what failed, then what went most recently.@@ -323,12 +324,12 @@ export type OutboxOverview = {const ITEMS = 60;-/** The outbox as su sees it: the day's quota, every kind's standing, and the+/** The outbox as su sees it: the cycle's budget, every kind's standing, and the* rows worth a look. */export async function outboxOverview(now = new Date()): Promise<OutboxOverview> {const dayStart = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));const [quota, priorities, queued, sentToday, failed, byCampaign, waiting, broken, recent, drains] = await Promise.all([- dailyEmailQuotaStatus(now),+ emailBudgetStatus(now),getGlobalSetting("emailPriorities"),prisma.emailSend.groupBy({ _count: true, by: ["kind"], where: { state: { in: ["queued", "sending"] } } }),prisma.emailSend.groupBy({ _count: true, by: ["kind"], where: { sentAt: { gte: dayStart }, state: "sent" } }),@@ -358,7 +359,7 @@ export async function outboxOverview(now = new Date()): Promise<OutboxOverview>}),]);// A drainer without a kind covers every kind. One running or due now is- // draining; one held back for later is waiting on the quota, and the kind+ // draining; one held back for later is waiting on the budget, and the kind// reports the earliest of those.const drainers = drains.map((d) => ({kind: (d.payload as { kind?: EmailKindId } | null)?.kind ?? null,diff --git a/site/src/lib/email/send-budget.ts b/site/src/lib/email/send-budget.tsnew file mode 100644index 00000000..2dc56e8a--- /dev/null+++ b/site/src/lib/email/send-budget.ts@@ -0,0 +1,142 @@+import { utcDayOf } from "@/lib/analytics/schema";+import { getGlobalSetting } from "@/lib/config/effective";+import {+ billingCycle,+ expectedTransactionalSends,+ workDaysRemaining,+ type BillingCycle,+ type TransactionalForecast,+} from "@/lib/email/send-forecast";+import { prisma } from "@/lib/prisma";++// The plan's monthly allowance, spent across its billing cycle with three+// ceilings on it. Manual sends run up to the allowance. Transactional sends+// stop below the slots held for hand-sent mail on the work days left.+// Bulk sends stop below what the rest of the cycle is forecast to need for+// transactional email, so a campaign of any size goes out the day it is+// sent and never blocks a welcome email, and takes the slots the forecast+// releases as the cycle runs down. The count is kept per UTC day: a slot is+// counted when it is reserved and given back when the send fails, so a+// process that dies mid-send costs the cycle one slot.+export type EmailSendKind = "manual" | "transactional" | "bulk";++// How long a refused send waits before asking again while the reserves+// still hold slots back; they release as work days and cycle days pass.+const RESERVE_RETRY_SECONDS = 60 * 60;++export class EmailBudgetError extends Error {+ public constructor(+ public readonly kind: EmailSendKind,+ public readonly limit: number,+ public readonly remaining: number,+ public readonly retryAfterSeconds: number,+ ) {+ super(`Email budget reached for ${kind} sends this cycle: ${remaining} of ${limit} available.`);+ this.name = "EmailBudgetError";+ }+}++function secondsUntil(date: Date, now: Date): number {+ return Math.max(1, Math.ceil((date.getTime() - now.getTime()) / 1000));+}++export type EmailBudgetStatus = {+ cycle: { start: string; end: string };+ // Sent this cycle, and the part of that sent today.+ sent: number;+ sentToday: number;+ allowance: number;+ // Slots held for hand-sent mail over the work days left in the cycle.+ manualReserve: number;+ forecast: TransactionalForecast;+ // How far each kind of send may go this cycle.+ ceilings: Record<EmailSendKind, number>;+ renewsInSeconds: number;+};++function cycleDays(cycle: BillingCycle) {+ return { gte: utcDayOf(cycle.start), lt: utcDayOf(cycle.end) };+}++/** Where the cycle stands: what went, and how far each kind of send can go. */+export async function emailBudgetStatus(now = new Date()): Promise<EmailBudgetStatus> {+ const setting = await getGlobalSetting("emailSendBudget");+ const cycle = billingCycle(now, setting.renewalDay);+ const today = utcDayOf(now);+ const [total, todayRow] = await Promise.all([+ prisma.emailDailyQuota.aggregate({ _sum: { sent: true }, where: { day: cycleDays(cycle) } }),+ prisma.emailDailyQuota.findUnique({ select: { sent: true }, where: { day: today } }),+ ]);+ const manualReserve = setting.manualReserve * workDaysRemaining(now, cycle, setting);+ const forecast = await expectedTransactionalSends(now, cycle, setting);+ const transactional = setting.monthlyAllowance - manualReserve;+ return {+ cycle: { start: cycle.start.toISOString(), end: cycle.end.toISOString() },+ sent: total._sum.sent ?? 0,+ sentToday: todayRow?.sent ?? 0,+ allowance: setting.monthlyAllowance,+ manualReserve,+ forecast,+ ceilings: { manual: setting.monthlyAllowance, transactional, bulk: transactional - forecast.total },+ renewsInSeconds: secondsUntil(cycle.end, now),+ };+}++async function reserveSlot(day: string, kind: EmailSendKind, now: Date): Promise<void> {+ const status = await emailBudgetStatus(now);+ const limit = status.ceilings[kind];+ // Today's row may climb to the cycle ceiling less what earlier days spent.+ const todayLimit = limit - (status.sent - status.sentToday);+ await prisma.emailDailyQuota.createMany({ data: [{ day }], skipDuplicates: true });+ // One conditional increment: the row moves only while it is under the+ // ceiling, so two senders can never both take the last slot.+ const taken = await prisma.emailDailyQuota.updateMany({+ data: { sent: { increment: 1 } },+ where: { day, sent: { lt: todayLimit } },+ });+ if (taken.count > 0) return;++ // The lowest the ceiling can settle at before the renewal: the allowance+ // less the headroom the forecast keeps to the end. Under it, the reserves+ // are what holds the send back and they release with time; at it, the+ // plan is spent until it renews.+ const floor = kind === "bulk" ? status.allowance - status.forecast.headroom : status.allowance;+ const retryAfterSeconds = status.sent < floor ? RESERVE_RETRY_SECONDS : status.renewsInSeconds;+ throw new EmailBudgetError(kind, limit, Math.max(0, limit - status.sent), retryAfterSeconds);+}++async function releaseSlot(day: string): Promise<void> {+ await prisma.emailDailyQuota.updateMany({+ data: { sent: { decrement: 1 } },+ where: { day, sent: { gt: 0 } },+ });+}++/** Runs one provider send inside the cycle's budget, with the slot held+ * before the callback starts so what it builds goes out at once. The slot is+ * kept only when the provider accepted the email: a thrown error, a resolved+ * `{ error }`, or null (nothing to send) gives it back. */+export async function withEmailBudget<T extends { error: unknown }>(+ kind: EmailSendKind,+ send: () => Promise<T | null>,+): Promise<T | null> {+ const now = new Date();+ const day = utcDayOf(now);+ await reserveSlot(day, kind, now);+ const release = () =>+ releaseSlot(day).catch((releaseError) => {+ console.error("[email] failed to release an email budget slot", {+ day,+ error: releaseError instanceof Error ? releaseError.message : String(releaseError),+ });+ });+ let result: T | null;+ try {+ result = await send();+ } catch (error) {+ await release();+ throw error;+ }+ if (result === null || result.error) await release();+ return result;+}diff --git a/site/src/lib/email/send-forecast.ts b/site/src/lib/email/send-forecast.tsindex ed7360de..b922b3d0 100644--- a/site/src/lib/email/send-forecast.ts+++ b/site/src/lib/email/send-forecast.ts@@ -3,11 +3,11 @@ import { pendingCreditExpiryGrants } from "@/lib/email/credit-expiry-due";import { prisma } from "@/lib/prisma";import type { Settings } from "@/lib/config/registry";-// What the rest of the UTC day still needs from the provider's send cap, so-// bulk sends stop where transactional email and hand-sent mail begin and take-// whatever those leave behind as the day runs down.+// What the rest of the plan's billing cycle still needs from its allowance,+// so bulk sends stop where transactional email and hand-sent mail begin and+// take whatever those leave behind as the cycle runs down.-export type EmailDailySendSetting = Settings["emailDailySend"];+export type EmailSendBudgetSetting = Settings["emailSendBudget"];const DAY_MS = 24 * 60 * 60 * 1000;const HOUR_MS = 60 * 60 * 1000;@@ -16,45 +16,85 @@ function msOfUtcDay(date: Date): number {return date.getTime() - Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());}-function startOfUtcDay(date: Date): Date {+export function startOfUtcDay(date: Date): Date {return new Date(date.getTime() - msOfUtcDay(date));}-function localHourAndWeekday(date: Date, timeZone: string): { hour: number; weekday: string } {- const parts = new Intl.DateTimeFormat("en-US", { hour: "numeric", hour12: false, timeZone, weekday: "short" }).formatToParts(date);- const hour = Number(parts.find((p) => p.type === "hour")?.value ?? 0) % 24;- const weekday = parts.find((p) => p.type === "weekday")?.value ?? "";- return { hour, weekday };+export type BillingCycle = { start: Date; end: Date };++// The plan renews on one day of the month, at UTC midnight here; a month+// too short for that day renews on its last day.+function renewalOn(year: number, monthIndex: number, renewalDay: number): Date {+ const lastDay = new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate();+ return new Date(Date.UTC(year, monthIndex, Math.min(renewalDay, lastDay)));+}++/** The billing cycle `now` falls in: from the latest renewal to the next. */+export function billingCycle(now: Date, renewalDay: number): BillingCycle {+ let start = renewalOn(now.getUTCFullYear(), now.getUTCMonth(), renewalDay);+ if (start > now) start = renewalOn(now.getUTCFullYear(), now.getUTCMonth() - 1, renewalDay);+ const end = renewalOn(start.getUTCFullYear(), start.getUTCMonth() + 1, renewalDay);+ return { start, end };}-function inManualHours(date: Date, setting: EmailDailySendSetting): boolean {- const { hour, weekday } = localHourAndWeekday(date, setting.manualTimeZone);- if (setting.manualWeekdaysOnly && (weekday === "Sat" || weekday === "Sun")) return false;- return hour >= setting.manualStartHour && hour < setting.manualEndHour;+/** Days left in the cycle, today's remainder counted as a fraction. */+export function daysRemaining(now: Date, cycle: BillingCycle): number {+ return Math.max(0, (cycle.end.getTime() - now.getTime()) / DAY_MS);}-/** Whether any work hour is still ahead in the current UTC day, sampled at- * now and at every top of the hour until UTC midnight. */-export function manualHoursRemainToday(now: Date, setting: EmailDailySendSetting): boolean {- const dayEnd = startOfUtcDay(now).getTime() + DAY_MS;- for (let t = now.getTime(); t < dayEnd; t = Math.floor(t / HOUR_MS + 1) * HOUR_MS) {- if (inManualHours(new Date(t), setting)) return true;+const formatters = new Map<string, Intl.DateTimeFormat>();++function localParts(date: Date, timeZone: string): { day: string; hour: number; weekday: string } {+ let formatter = formatters.get(timeZone);+ if (!formatter) {+ formatter = new Intl.DateTimeFormat("en-US", {+ day: "2-digit",+ hour: "numeric",+ hour12: false,+ month: "2-digit",+ timeZone,+ weekday: "short",+ year: "numeric",+ });+ formatters.set(timeZone, formatter);}- return false;+ const parts = formatter.formatToParts(date);+ const part = (type: string) => parts.find((p) => p.type === type)?.value ?? "";+ return { day: `${part("year")}-${part("month")}-${part("day")}`, hour: Number(part("hour")) % 24, weekday: part("weekday") };+}++function inManualHours(local: { hour: number; weekday: string }, setting: EmailSendBudgetSetting): boolean {+ if (setting.manualWeekdaysOnly && (local.weekday === "Sat" || local.weekday === "Sun")) return false;+ return local.hour >= setting.manualStartHour && local.hour < setting.manualEndHour;}-/** Welcome emails still expected today: signups over the lookback window that- * landed later in their UTC day than now is in this one, averaged per day. */-async function expectedSignupsRemaining(now: Date, lookbackDays: number): Promise<number> {+const workDaysCache = new Map<string, number>();++/** Work days left before the renewal, in the work zone's own calendar: the+ * local dates with a work hour still ahead, sampled at `now` and at every+ * top of the hour until the cycle ends. The answer moves by the hour, so+ * one count serves an hour of sends. */+export function workDaysRemaining(now: Date, cycle: BillingCycle, setting: EmailSendBudgetSetting): number {+ const hour = Math.floor(now.getTime() / HOUR_MS);+ const key = `${hour}:${cycle.end.getTime()}:${JSON.stringify(setting)}`;+ const cachedDays = workDaysCache.get(key);+ if (cachedDays !== undefined) return cachedDays;+ const days = new Set<string>();+ for (let t = now.getTime(); t < cycle.end.getTime(); t = Math.floor(t / HOUR_MS + 1) * HOUR_MS) {+ const local = localParts(new Date(t), setting.manualTimeZone);+ if (inManualHours(local, setting)) days.add(local.day);+ }+ workDaysCache.clear();+ workDaysCache.set(key, days.size);+ return days.size;+}++/** Signups a day, averaged over the lookback window of whole UTC days. */+async function signupsPerDay(now: Date, lookbackDays: number): Promise<number> {const today = startOfUtcDay(now);const since = new Date(today.getTime() - lookbackDays * DAY_MS);- const users = await prisma.user.findMany({- select: { createdAt: true },- where: { createdAt: { gte: since, lt: today } },- });- const cutoff = msOfUtcDay(now);- const later = users.filter((u) => msOfUtcDay(u.createdAt) >= cutoff).length;- return Math.ceil(later / lookbackDays);+ const count = await prisma.user.count({ where: { createdAt: { gte: since, lt: today } } });+ return count / lookbackDays;}// A campaign asks once per email, every half second; the answer moves by the@@ -63,7 +103,7 @@ const FORECAST_TTL_MS = 60 * 1000;let cached: { at: number; value: Promise<TransactionalForecast> } | null = null;export type TransactionalForecast = {- // Welcome emails for the signups still expected today.+ // Welcome emails for the signups expected before the renewal.signups: number;// Expiry notices owed and not yet sent.expiry: number;@@ -71,10 +111,14 @@ export type TransactionalForecast = {total: number;};-/** Transactional sends the rest of today is expected to need. */-export function expectedTransactionalSends(now: Date, setting: EmailDailySendSetting): Promise<TransactionalForecast> {+/** Transactional sends the rest of the cycle is expected to need. */+export function expectedTransactionalSends(+ now: Date,+ cycle: BillingCycle,+ setting: EmailSendBudgetSetting,+): Promise<TransactionalForecast> {if (cached && now.getTime() - cached.at < FORECAST_TTL_MS) return cached.value;- const value = forecast(now, setting);+ const value = forecast(now, cycle, setting);cached = { at: now.getTime(), value };value.catch(() => {cached = null;@@ -82,12 +126,13 @@ export function expectedTransactionalSends(now: Date, setting: EmailDailySendSetreturn value;}-async function forecast(now: Date, setting: EmailDailySendSetting): Promise<TransactionalForecast> {+async function forecast(now: Date, cycle: BillingCycle, setting: EmailSendBudgetSetting): Promise<TransactionalForecast> {const { daysBefore } = await getGlobalSetting("creditExpiryNotice");- const [signups, pending] = await Promise.all([- expectedSignupsRemaining(now, setting.signupLookbackDays),+ const [perDay, pending] = await Promise.all([+ signupsPerDay(now, setting.signupLookbackDays),pendingCreditExpiryGrants(now, daysBefore),]);+ const signups = Math.ceil(perDay * daysRemaining(now, cycle));const expiry = pending.pending.length;const headroom = setting.transactionalHeadroom;return { signups, expiry, headroom, total: signups + expiry + headroom };diff --git a/site/src/lib/jobs/email-drain.ts b/site/src/lib/jobs/email-drain.tsindex c17ffd58..0ff322fb 100644--- a/site/src/lib/jobs/email-drain.ts+++ b/site/src/lib/jobs/email-drain.ts@@ -9,7 +9,7 @@ import { defineJob, JobDeferred } from "@/lib/jobs/registry";const BUDGET_MS = 200_000;/** Runs the drainer inside a job: a run that ran out of time queues its- * continuation, and one that ran out of quota comes back when the quota is+ * continuation, and one that ran out of budget comes back when the budget is* expected to open. A run for one kind continues for that kind. */export async function drainAsJob(kind?: EmailKindId): Promise<DrainResult> {const result = await drainOutbox(BUDGET_MS, kind);@@ -19,7 +19,7 @@ export async function drainAsJob(kind?: EmailKindId): Promise<DrainResult> {return result;}if (result.retryAfterSeconds !== null) {- throw new JobDeferred("Daily email quota reached; the outbox resumes when it opens.", result.retryAfterSeconds);+ throw new JobDeferred("Email budget reached; the outbox resumes when it opens.", result.retryAfterSeconds);}return result;}diff --git a/site/src/queries/emailOutbox.ts b/site/src/queries/emailOutbox.tsindex dacebca1..0740695c 100644--- a/site/src/queries/emailOutbox.ts+++ b/site/src/queries/emailOutbox.ts@@ -10,7 +10,7 @@ export type { OutboxCampaign, OutboxItem, OutboxKindRow, OutboxOverview } from "export const emailOutboxQueryKey = ["su", "email", "outbox"] as const;-// Super-user only: the outbox and the day's quota. Polls while anything is+// Super-user only: the outbox and the cycle's budget. Polls while anything is// queued so sends settle on screen without a refresh.export function useEmailOutbox() {return useQuery({