Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

feat(email): weekly digest per person and a 60-day post-trial grace period (#1331)

Goldflag877e3c6b9020
diff --git a/client/src/app/settings/billing/page.tsx b/client/src/app/settings/billing/page.tsx
index 8cf17c440..9b3329e17 100644
--- a/client/src/app/settings/billing/page.tsx
+++ b/client/src/app/settings/billing/page.tsx
@@ -1,7 +1,8 @@
"use client";
import { useExtracted } from "next-intl";
-import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
import { ErrorState } from "@/components/ErrorState";
import { NoOrganization } from "@/components/NoOrganization";
import { AppSumoPlan } from "@/components/subscription/AppSumoPlan";
@@ -60,6 +61,32 @@ export default function OrganizationBillingPage() {
const { data: activeOrg, isPending } = authClient.useActiveOrganization();
const { data: session } = authClient.useSession();
+ const router = useRouter();
+ const orgParamHandled = useRef(false);
+ const [requestedOrgId, setRequestedOrgId] = useState<string | null>(null);
+
+ // Emails link to ?organization=<id> so an owner of several organizations lands on the one the
+ // email is about, not whichever is active. better-auth refuses organizations the user isn't in;
+ // the page then stays on the active one.
+ useEffect(() => {
+ if (isPending || orgParamHandled.current) return;
+ const params = new URLSearchParams(window.location.search);
+ const organizationId = params.get("organization");
+ if (!organizationId) return;
+ orgParamHandled.current = true;
+ params.delete("organization");
+ router.replace(params.size ? `${window.location.pathname}?${params}` : window.location.pathname);
+ if (organizationId === activeOrg?.id) return;
+ setRequestedOrgId(organizationId);
+ authClient.organization.setActive({ organizationId }).then(
+ ({ error }) => error && setRequestedOrgId(null),
+ () => setRequestedOrgId(null)
+ );
+ }, [isPending, activeOrg?.id, router]);
+
+ // setActive resolves before the active organization is refetched, so wait for the switch to
+ // land rather than show the previous organization's billing in the meantime.
+ const isSwitchingOrg = requestedOrgId !== null && activeOrg?.id !== requestedOrgId;
useEffect(() => {
const params = new URLSearchParams(window.location.search);
@@ -70,7 +97,7 @@ export default function OrganizationBillingPage() {
const canManageBilling = useCanInOrg("billing:manage", activeOrg?.id);
- const isLoading = isLoadingSubscription || isPending;
+ const isLoading = isLoadingSubscription || isPending || isSwitchingOrg;
if (isLoading) {
return <BillingSkeleton />;
diff --git a/server/src/api/stripe/getSubscription.ts b/server/src/api/stripe/getSubscription.ts
index d48d3c940..b29d053d0 100644
--- a/server/src/api/stripe/getSubscription.ts
+++ b/server/src/api/stripe/getSubscription.ts
@@ -212,6 +212,8 @@ export async function getSubscriptionInner(organizationId: string) {
// One trial per organization: false once it has had any subscription (trial ended,
// canceled, lapsed), so the app offers plans instead of a trial.
trialEligible: !(await hasHadStripeSubscription(org.stripeCustomerId)),
+ // Sites keep collecting until trialGrace.endsAt after an unpaid trial (siteRequiresPlan).
+ ...(subscription.source === "free" && subscription.trialGrace && { trialGrace: subscription.trialGrace }),
includesReplay,
...limits,
};
diff --git a/server/src/lib/email/email.ts b/server/src/lib/email/email.ts
index 720386499..b1f877d71 100644
--- a/server/src/lib/email/email.ts
+++ b/server/src/lib/email/email.ts
@@ -1,6 +1,6 @@
import { render } from "@react-email/components";
import { Resend } from "resend";
-import type { SiteReport } from "../../services/weekyReports/weeklyReportTypes.js";
+import type { SiteReport, WeeklyDigest } from "../../services/weekyReports/weeklyReportTypes.js";
import { welcome } from "../../services/lifecycleEmails/lifecycleContent.js";
import { IS_CLOUD } from "../const.js";
import { signExpiringPayload } from "../signedToken.js";
@@ -16,7 +16,9 @@ import { LetterEmail } from "./templates/LetterEmail.js";
import { LimitExceededEmail } from "./templates/LimitExceededEmail.js";
import { OTP_COPY, OtpEmail, type OtpEmailType } from "./templates/OtpEmail.js";
import { SiteTransferEmail, type SiteTransferEmailProps } from "./templates/SiteTransferEmail.js";
+import { TrialGraceEmail, trialGraceSubject, type TrialGraceEmailProps } from "./templates/TrialGraceEmail.js";
import { VerifyEmailEmail } from "./templates/VerifyEmailEmail.js";
+import { WeeklyDigestEmail, weeklyDigestSubject } from "./templates/WeeklyDigestEmail.js";
import { WeeklyReportEmail, weeklyReportSubject } from "./templates/WeeklyReportEmail.js";
let resend: Resend | undefined;
@@ -116,8 +118,20 @@ const REPLY_TO = "[email protected]";
interface SendOptions {
text?: string;
headers?: Record<string, string>;
+ /** Resend replays the first response for a repeated key (for 24 hours) instead of sending again. */
+ idempotencyKey?: string;
}
+/**
+ * Whether Resend refused a send because its idempotency key was already used: by a request with
+ * a different payload, or by one still in flight. Either way the email went out (or is going out)
+ * under that key, so the caller must not treat the send as failed and try again.
+ */
+export const isIdempotencyConflict = (error: unknown): boolean =>
+ error instanceof ResendRequestError &&
+ (error.resendError.name === "invalid_idempotent_request" ||
+ error.resendError.name === "concurrent_idempotent_requests");
+
/** Sends a transactional email. Throws when Resend does not accept it. */
export const sendEmail = async (email: string, subject: string, html: string, options: SendOptions = {}) => {
if (!resend) {
@@ -126,15 +140,18 @@ export const sendEmail = async (email: string, subject: string, html: string, op
// throw new Error("Resend is not initialized");
}
try {
- const response = await resend.emails.send({
- from: TRANSACTIONAL_FROM,
- replyTo: REPLY_TO,
- to: email,
- subject,
- html,
- ...(options.text ? { text: options.text } : {}),
- ...(options.headers ? { headers: options.headers } : {}),
- });
+ const response = await resend.emails.send(
+ {
+ from: TRANSACTIONAL_FROM,
+ replyTo: REPLY_TO,
+ to: email,
+ subject,
+ html,
+ ...(options.text ? { text: options.text } : {}),
+ ...(options.headers ? { headers: options.headers } : {}),
+ },
+ options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : undefined
+ );
if (response.error) {
throw new ResendRequestError("email send", response.error);
}
@@ -189,6 +206,11 @@ export const sendApproachingLimitEmail = async (email: string, usage: UsageEmail
await sendEmail(email, approachingLimitSubject(usage.organizationName, usage.eventCount, usage.eventLimit), html);
};
+export const sendTrialGraceEmail = async (email: string, props: TrialGraceEmailProps, idempotencyKey: string) => {
+ const html = await render(TrialGraceEmail(props));
+ await sendEmail(email, trialGraceSubject(props), html, { idempotencyKey });
+};
+
/**
* Signed one-click link that turns off weekly reports for one user, used in the
* report footer and its List-Unsubscribe header. Same 2-year TTL as the
@@ -199,6 +221,11 @@ export const weeklyReportUnsubscribeUrl = (userId: string): string => {
return `${process.env.BASE_URL}/api/user/unsubscribe-reports-oneclick?userId=${encodeURIComponent(userId)}&exp=${exp}&sig=${sig}`;
};
+const listUnsubscribeHeaders = (unsubscribeUrl: string) => ({
+ "List-Unsubscribe": `<${unsubscribeUrl}>`,
+ "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+});
+
export const sendWeeklyReportEmail = async ({
email,
userId,
@@ -210,12 +237,21 @@ export const sendWeeklyReportEmail = async ({
}) => {
const unsubscribeUrl = weeklyReportUnsubscribeUrl(userId);
const html = await render(WeeklyReportEmail({ site, unsubscribeUrl }));
- await sendEmail(email, weeklyReportSubject(site), html, {
- headers: {
- "List-Unsubscribe": `<${unsubscribeUrl}>`,
- "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
- },
- });
+ await sendEmail(email, weeklyReportSubject(site), html, { headers: listUnsubscribeHeaders(unsubscribeUrl) });
+};
+
+export const sendWeeklyDigestEmail = async ({
+ email,
+ userId,
+ digest,
+}: {
+ email: string;
+ userId: string;
+ digest: WeeklyDigest;
+}) => {
+ const unsubscribeUrl = weeklyReportUnsubscribeUrl(userId);
+ const html = await render(WeeklyDigestEmail({ digest, unsubscribeUrl }));
+ await sendEmail(email, weeklyDigestSubject(digest), html, { headers: listUnsubscribeHeaders(unsubscribeUrl) });
};
export const sendWelcomeEmail = async (email: string, name?: string) => {
diff --git a/server/src/lib/email/templates/TrialGraceEmail.tsx b/server/src/lib/email/templates/TrialGraceEmail.tsx
new file mode 100644
index 000000000..08d620467
--- /dev/null
+++ b/server/src/lib/email/templates/TrialGraceEmail.tsx
@@ -0,0 +1,200 @@
+import { DateTime } from "luxon";
+import * as React from "react";
+import { appUrl, formatCount, formatDate, plural } from "../format.js";
+import { H1, HELP_URL, LedgerLayout, Note, P, PrimaryButton, Rows, ShareTable, StatGrid } from "./ledger.js";
+
+/**
+ * Sent to an organization's owners while its sites keep collecting after an unpaid trial:
+ * when the grace period starts, halfway through, and in its last week.
+ */
+export type TrialGraceStage = "started" | "midway" | "final";
+
+export interface TrialGraceSite {
+ domain: string;
+ visitors: number;
+ pageviews: number;
+}
+
+export interface TrialGraceEmailProps {
+ stage: TrialGraceStage;
+ /** Owners of several organizations land on this one's billing page, not whichever is active. */
+ organizationId: string;
+ organizationName: string;
+ trialEndedAt: Date;
+ endsAt: Date;
+ /** Every site in the organization, busiest first, with its traffic since the trial ended. */
+ sites: TrialGraceSite[];
+ now?: DateTime;
+}
+
+const MAX_LISTED_SITES = 5;
+
+const utc = (date: Date) => DateTime.fromJSDate(date, { zone: "utc" });
+const shortDate = (date: Date) => utc(date).toFormat("LLL d");
+
+/** "acme.com", "acme.com and docs.acme.com", "your 4 sites" */
+const sitesLabel = (sites: TrialGraceSite[]) => {
+ if (sites.length === 0) return "your sites";
+ if (sites.length === 1) return sites[0].domain;
+ if (sites.length === 2) return `${sites[0].domain} and ${sites[1].domain}`;
+ return `your ${sites.length} sites`;
+};
+
+const listedSites = (sites: TrialGraceSite[]) => {
+ const listed = sites
+ .slice(0, MAX_LISTED_SITES)
+ .map(site => site.domain)
+ .join(", ");
+ const hidden = sites.length - MAX_LISTED_SITES;
+ return hidden > 0 ? `${listed} and ${hidden} more` : listed;
+};
+
+const totals = (sites: TrialGraceSite[]) => ({
+ visitors: sites.reduce((sum, site) => sum + site.visitors, 0),
+ pageviews: sites.reduce((sum, site) => sum + site.pageviews, 0),
+});
+
+const daysLeft = (endsAt: Date, now: DateTime) => Math.max(1, Math.ceil(utc(endsAt).diff(now, "days").days));
+
+export const trialGraceSubject = ({ stage, sites, endsAt }: TrialGraceEmailProps) => {
+ if (stage === "started") {
+ return `Your trial ended. Rybbit is still tracking ${sitesLabel(sites)}`;
+ }
+ if (stage === "final") {
+ return `Your Rybbit data will be deleted after ${shortDate(endsAt)}`;
+ }
+ const { visitors } = totals(sites);
+ if (visitors === 0) {
+ return `Your Rybbit data is here until ${shortDate(endsAt)}`;
+ }
+ const prefix = sites.length === 1 ? `${sites[0].domain}: ` : "";
+ return `${prefix}${plural(visitors, "visitor")} since your Rybbit trial ended`;
+};
+
+const preview = ({ stage, sites, endsAt, now = DateTime.utc() }: TrialGraceEmailProps) => {
+ if (stage === "final") {
+ return `${plural(daysLeft(endsAt, now), "day")} left. Pick a plan and everything you've collected carries over.`;
+ }
+ if (stage === "midway") {
+ return `We'll keep tracking ${sitesLabel(sites)} until ${shortDate(endsAt)}. Pick a plan to keep the data.`;
+ }
+ return `Your data is here until ${shortDate(endsAt)}. Pick a plan to keep it.`;
+};
+
+const billingUrl = (organizationId: string) =>
+ `${appUrl()}/settings/billing?organization=${encodeURIComponent(organizationId)}`;
+
+const Started = ({ organizationId, organizationName, trialEndedAt, endsAt, sites }: TrialGraceEmailProps) => (
+ <>
+ <H1>Your trial ended, but we're still tracking {sitesLabel(sites)}</H1>
+ <P>
+ Your {organizationName} trial ended on {shortDate(trialEndedAt)}. We'll keep collecting data until{" "}
+ {formatDate(utc(endsAt))}, so there's no gap if you decide to stay.
+ </P>
+ <Rows
+ rows={[
+ { label: "Trial ended", value: formatDate(utc(trialEndedAt)) },
+ ...(sites.length > 0 ? [{ label: "Still tracking", value: listedSites(sites) }] : []),
+ { label: "Data deleted after", value: formatDate(utc(endsAt)), strong: true },
+ ]}
+ />
+ <P top={24}>
+ Pick a plan before then and everything carries over. If you don't, tracking stops on {shortDate(endsAt)} and your
+ data will be deleted.
+ </P>
+ <PrimaryButton label="Choose a plan" href={billingUrl(organizationId)} />
+ </>
+);
+
+const Midway = ({
+ organizationId,
+ organizationName,
+ trialEndedAt,
+ endsAt,
+ sites,
+ now = DateTime.utc(),
+}: TrialGraceEmailProps) => {
+ const { visitors, pageviews } = totals(sites);
+ const busiest = sites.filter(site => site.visitors > 0);
+ const largest = busiest[0]?.visitors || 1;
+ return (
+ <>
+ <H1>
+ {visitors > 0
+ ? `${sites.length === 1 ? sites[0].domain : "Your sites"} had ${plural(visitors, "visitor")} since your trial ended`
+ : `Your data is still here until ${formatDate(utc(endsAt))}`}
+ </H1>
+ <Note top={8}>
+ Since {shortDate(trialEndedAt)} · {organizationName}
+ </Note>
+ <StatGrid
+ stats={[
+ { label: "Visitors", value: formatCount(visitors) },
+ { label: "Pageviews", value: formatCount(pageviews) },
+ { label: "Days left", value: formatCount(daysLeft(endsAt, now)) },
+ ]}
+ />
+ {busiest.length > 1 && (
+ <ShareTable
+ top={24}
+ labelHeader="Site"
+ valueHeader="Visitors"
+ rows={busiest.slice(0, 10).map(site => ({
+ label: site.domain,
+ value: formatCount(site.visitors),
+ share: (site.visitors / visitors) * 100,
+ bar: (site.visitors / largest) * 100,
+ }))}
+ />
+ )}
+ <P top={24}>
+ We'll keep collecting until {formatDate(utc(endsAt))}. After that, tracking stops and your data will be deleted.
+ Pick a plan to keep it.
+ </P>
+ <PrimaryButton label="Choose a plan" href={billingUrl(organizationId)} />
+ </>
+ );
+};
+
+const Final = ({ organizationId, trialEndedAt, endsAt, sites, now = DateTime.utc() }: TrialGraceEmailProps) => {
+ const { visitors, pageviews } = totals(sites);
+ return (
+ <>
+ <H1>Your Rybbit data will be deleted after {formatDate(utc(endsAt))}</H1>
+ <P>
+ That's {plural(daysLeft(endsAt, now), "day")} from now. Tracking for {sitesLabel(sites)} stops the same day.
+ </P>
+ <Rows
+ rows={[
+ {
+ label: `Since ${shortDate(trialEndedAt)}`,
+ value: `${plural(visitors, "visitor")}, ${plural(pageviews, "pageview")}`,
+ },
+ ...(sites.length > 0 ? [{ label: sites.length === 1 ? "Site" : "Sites", value: listedSites(sites) }] : []),
+ { label: "Deleted after", value: formatDate(utc(endsAt)), strong: true },
+ ]}
+ />
+ <P top={24}>Pick a plan to keep it. Everything you've collected carries over.</P>
+ <PrimaryButton label="Keep my data" href={billingUrl(organizationId)} />
+ </>
+ );
+};
+
+export const TrialGraceEmail = (props: TrialGraceEmailProps) => (
+ <LedgerLayout
+ preview={preview(props)}
+ footer={[
+ { label: "Help", href: HELP_URL },
+ { label: "Billing", href: billingUrl(props.organizationId) },
+ ]}
+ >
+ {props.stage === "started" ? (
+ <Started {...props} />
+ ) : props.stage === "midway" ? (
+ <Midway {...props} />
+ ) : (
+ <Final {...props} />
+ )}
+ <Note>Questions? Just reply.</Note>
+ </LedgerLayout>
+);
diff --git a/server/src/lib/email/templates/WeeklyDigestEmail.tsx b/server/src/lib/email/templates/WeeklyDigestEmail.tsx
new file mode 100644
index 000000000..66276a46d
--- /dev/null
+++ b/server/src/lib/email/templates/WeeklyDigestEmail.tsx
@@ -0,0 +1,261 @@
+import { DateTime } from "luxon";
+import * as React from "react";
+import type { DigestSite, WeeklyDigest } from "../../../services/weekyReports/weeklyReportTypes.js";
+import { appUrl, formatChange, formatCount, formatDateTime, percentChange, plural } from "../format.js";
+import { Bar, color, H1, H2, LedgerLayout, Note, P, PrimaryButton, Rows, tableAttrs, TextLink } from "./ledger.js";
+import { changeWords, formatWeekRange, visitorsPhrase } from "./WeeklyReportEmail.js";
+
+interface WeeklyDigestEmailProps {
+ digest: WeeklyDigest;
+ unsubscribeUrl: string;
+}
+
+const MAX_ROWS = 20;
+// Someone whose sites all went dark at once (a domain lapsing, say) would otherwise get one row each.
+const MAX_QUIET_ROWS = 10;
+const SPARK_HEIGHT = 24;
+
+const isQuiet = (site: DigestSite) => site.lastPageviewAt !== null;
+
+const totals = (sites: DigestSite[]) => ({
+ users: sites.reduce((sum, site) => sum + site.users, 0),
+ previousUsers: sites.reduce((sum, site) => sum + site.previousUsers, 0),
+});
+
+/** The organization every site belongs to, or null when the digest spans several. */
+const soleOrganization = (sites: DigestSite[]) =>
+ sites.every(site => site.organizationId === sites[0]?.organizationId) ? (sites[0]?.organizationName ?? null) : null;
+
+export const weeklyDigestSubject = ({ sites }: WeeklyDigest) => {
+ const { users } = totals(sites);
+ const org = soleOrganization(sites);
+ return `${org ? `${org} last week` : "Last week"}: ${visitorsPhrase(users)} across ${sites.length} sites`;
+};
+
+/** The site that grew the most, then any that went quiet. */
+export const weeklyDigestPreview = (digest: WeeklyDigest) => {
+ const grower = digest.sites
+ .filter(site => !isQuiet(site) && site.previousUsers > 0 && site.users > site.previousUsers)
+ .sort((a, b) => (percentChange(b.users, b.previousUsers) ?? 0) - (percentChange(a.users, a.previousUsers) ?? 0))[0];
+ const quiet = digest.sites.filter(isQuiet);
+ return [
+ grower && `${grower.siteDomain} ${changeWords(percentChange(grower.users, grower.previousUsers))}`,
+ quiet.length === 1 && `${quiet[0].siteDomain} had no pageviews all week`,
+ quiet.length > 1 && `${quiet.length} sites had no pageviews all week`,
+ formatWeekRange(digest.weekStart, digest.weekEnd),
+ ]
+ .filter(Boolean)
+ .join(" · ");
+};
+
+/** Seven sessions-per-day bars, right-aligned in an 80px cell. */
+const Sparkline = ({ daily }: { daily: number[] }) => {
+ const max = Math.max(1, ...daily);
+ return (
+ <table
+ {...tableAttrs}
+ align="right"
+ role="img"
+ aria-label={`Sessions per day: ${daily.map(formatCount).join(", ")}`}
+ >
+ <tbody>
+ <tr>
+ {daily.map((sessions, i) => (
+ <td
+ key={i}
+ valign="bottom"
+ height={SPARK_HEIGHT}
+ style={{ height: SPARK_HEIGHT, verticalAlign: "bottom", paddingLeft: i > 0 ? 2 : 0 }}
+ >
+ {sessions > 0 && (
+ <Bar width={6} height={Math.max(2, Math.round((sessions / max) * SPARK_HEIGHT))} fill={color.data} />
+ )}
+ </td>
+ ))}
+ </tr>
+ </tbody>
+ </table>
+ );
+};
+
+const NoDataPill = () => (
+ <span
+ style={{
+ display: "inline-block",
+ padding: "2px 6px",
+ borderRadius: 3,
+ fontSize: 11,
+ lineHeight: "14px",
+ fontWeight: 600,
+ backgroundColor: color.fill,
+ border: `1px solid ${color.rule}`,
+ color: color.muted,
+ }}
+ >
+ No data
+ </span>
+);
+
+const ChangeCell = ({ site }: { site: DigestSite }) => {
+ const change = percentChange(site.users, site.previousUsers);
+ if (change === null) return <span style={{ color: color.muted }}>–</span>;
+ const rounded = Math.round(change * 10) / 10;
+ return (
+ <span style={{ color: rounded === 0 ? color.muted : rounded > 0 ? color.up : color.down }}>
+ {formatChange(change)}
+ </span>
+ );
+};
+
+const SiteTable = ({ sites, top }: { sites: DigestSite[]; top: number }) => {
+ const header = {
+ fontSize: 12,
+ lineHeight: "16px",
+ fontWeight: 500,
+ color: color.muted,
+ paddingBottom: 8,
+ borderBottom: `1px solid ${color.rule}`,
+ };
+ const cell = { padding: "10px 0", borderBottom: `1px solid ${color.ruleSoft}`, verticalAlign: "middle" as const };
+ return (
+ <table {...tableAttrs} width="100%" style={{ marginTop: top, borderCollapse: "collapse", tableLayout: "fixed" }}>
+ <tbody>
+ <tr>
+ <td style={header}>Site</td>
+ <td width="72" align="right" style={{ ...header, width: 72, textAlign: "right" }}>
+ Visitors
+ </td>
+ <td width="72" align="right" style={{ ...header, width: 72, textAlign: "right" }}>
+ Change
+ </td>
+ <td className="ledger-bar" width="96" align="right" style={{ ...header, width: 96, textAlign: "right" }}>
+ Last 7 days
+ </td>
+ </tr>
+ {sites.map(site => (
+ <tr key={site.siteId}>
+ <td style={{ ...cell, fontSize: 14, lineHeight: "20px", color: color.text, wordBreak: "break-all" }}>
+ {site.siteDomain}
+ </td>
+ <td
+ align="right"
+ style={{
+ ...cell,
+ textAlign: "right",
+ fontSize: 14,
+ lineHeight: "20px",
+ fontWeight: 500,
+ color: color.text,
+ }}
+ >
+ {formatCount(site.users)}
+ </td>
+ <td
+ align="right"
+ style={{ ...cell, textAlign: "right", fontSize: 13, lineHeight: "20px", fontWeight: 500 }}
+ >
+ <ChangeCell site={site} />
+ </td>
+ <td className="ledger-bar" align="right" style={{ ...cell, textAlign: "right" }}>
+ {isQuiet(site) ? <NoDataPill /> : <Sparkline daily={site.daily} />}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ );
+};
+
+const byOrganization = (sites: DigestSite[]) => {
+ const groups = new Map<string, { id: string; name: string; sites: DigestSite[] }>();
+ for (const site of sites) {
+ const group = groups.get(site.organizationId) ?? {
+ id: site.organizationId,
+ name: site.organizationName,
+ sites: [],
+ };
+ group.sites.push(site);
+ groups.set(site.organizationId, group);
+ }
+ return [...groups.values()];
+};
+
+const lastPageview = (site: DigestSite) =>
+ `No pageviews since ${formatDateTime(DateTime.fromISO(site.lastPageviewAt!, { zone: "utc" }))}`;
+
+const QuietSites = ({ sites }: { sites: DigestSite[] }) => {
+ if (sites.length === 0) return null;
+ if (sites.length === 1) {
+ const [site] = sites;
+ return (
+ <>
+ <H2>{site.siteDomain} isn't sending data</H2>
+ <P top={8}>{lastPageview(site)}. If the site is still up, check that the tracking script is still installed.</P>
+ <P>
+ <TextLink href={`${appUrl()}/${site.siteId}`}>Check {site.siteDomain}</TextLink>
+ </P>
+ </>
+ );
+ }
+ return (
+ <>
+ <H2>{sites.length} sites aren't sending data</H2>
+ <Rows
+ top={16}
+ rows={sites.slice(0, MAX_QUIET_ROWS).map(site => ({
+ label: site.siteDomain,
+ value: <TextLink href={`${appUrl()}/${site.siteId}`}>{lastPageview(site)}</TextLink>,
+ }))}
+ />
+ {sites.length > MAX_QUIET_ROWS && (
+ <Note top={12}>Plus {plural(sites.length - MAX_QUIET_ROWS, "more site")}.</Note>
+ )}
+ <P top={16}>If they're still up, check that the tracking script is still installed.</P>
+ </>
+ );
+};
+
+export const WeeklyDigestEmail = ({ digest, unsubscribeUrl }: WeeklyDigestEmailProps) => {
+ const { users, previousUsers } = totals(digest.sites);
+ const words = changeWords(percentChange(users, previousUsers));
+ const org = soleOrganization(digest.sites);
+ const shown = digest.sites.slice(0, MAX_ROWS);
+ const hidden = digest.sites.slice(MAX_ROWS);
+ const groups = byOrganization(shown);
+
+ return (
+ <LedgerLayout
+ preview={weeklyDigestPreview(digest)}
+ footer={[
+ { label: "Turn off weekly reports", href: unsubscribeUrl },
+ { label: "Account settings", href: `${appUrl()}/settings/account` },
+ ]}
+ >
+ <H1>
+ Your {digest.sites.length} sites had {visitorsPhrase(users)} last week
+ {words === "flat" ? ", the same as the week before" : words ? `, ${words}` : ""}.
+ </H1>
+ <Note top={8}>
+ {formatWeekRange(digest.weekStart, digest.weekEnd)}
+ {org ? ` · ${org}` : ""}
+ </Note>
+ {groups.length === 1 ? (
+ <SiteTable sites={groups[0].sites} top={28} />
+ ) : (
+ groups.map(group => (
+ <React.Fragment key={group.id}>
+ <H2 top={32}>{group.name}</H2>
+ <SiteTable sites={group.sites} top={12} />
+ </React.Fragment>
+ ))
+ )}
+ {hidden.length > 0 && (
+ <Note top={16}>
+ Plus {plural(hidden.length, "more site")} with {visitorsPhrase(totals(hidden).users)}.
+ </Note>
+ )}
+ <QuietSites sites={digest.sites.filter(isQuiet)} />
+ <PrimaryButton top={40} label="Open Rybbit" href={appUrl()} />
+ </LedgerLayout>
+ );
+};
diff --git a/server/src/lib/email/templates/WeeklyReportEmail.tsx b/server/src/lib/email/templates/WeeklyReportEmail.tsx
index 11ee931f9..4861e1bfd 100644
--- a/server/src/lib/email/templates/WeeklyReportEmail.tsx
+++ b/server/src/lib/email/templates/WeeklyReportEmail.tsx
@@ -3,6 +3,7 @@ import * as React from "react";
import type { DailySessions, MetricData, SiteReport } from "../../../services/weekyReports/weeklyReportTypes.js";
import { appUrl, formatChange, formatCount, formatDuration, percentChange, truncate } from "../format.js";
import {
+ Bar,
color,
H1,
H2,
@@ -55,14 +56,14 @@ const previousRange = (site: SiteReport) =>
const visitorChange = (site: SiteReport) => percentChange(site.currentWeek.users, site.previousWeek.users);
/** "up 9.8%", "down 3.1%", "flat", or null when last week had no visitors. */
-const changeWords = (change: number | null) => {
+export const changeWords = (change: number | null) => {
if (change === null) return null;
const rounded = Math.round(change * 10) / 10;
if (rounded === 0) return "flat";
return `${rounded > 0 ? "up" : "down"} ${Math.abs(rounded).toFixed(1)}%`;
};
-const visitorsPhrase = (n: number) => `${formatCount(n)} ${n === 1 ? "visitor" : "visitors"}`;
+export const visitorsPhrase = (n: number) => `${formatCount(n)} ${n === 1 ? "visitor" : "visitors"}`;
export const weeklyReportSubject = (site: SiteReport) => {
const words = changeWords(visitorChange(site));
@@ -173,22 +174,6 @@ const LegendSwatch = ({ fill, outline }: { fill: string; outline?: string }) =>
/>
);
-/** A solid bar drawn as a table cell, which Outlook sizes where it ignores div heights. */
-const Bar = ({ width, height, fill }: { width: number; height: number; fill: string }) => (
- <table {...tableAttrs} width={width} style={{ width }}>
- <tbody>
- <tr>
- <td
- height={height}
- style={{ height, width, backgroundColor: fill, borderRadius: "2px 2px 0 0", fontSize: 0, lineHeight: "0px" }}
- >
- &nbsp;
- </td>
- </tr>
- </tbody>
- </table>
-);
-
const DailyChart = ({ site }: { site: SiteReport }) => {
const max = Math.max(1, ...site.daily.flatMap(d => [d.sessions, d.previousSessions]));
const busiest = busiestDay(site.daily);
diff --git a/server/src/lib/email/templates/ledger.tsx b/server/src/lib/email/templates/ledger.tsx
index a79b4f399..896d05846 100644
--- a/server/src/lib/email/templates/ledger.tsx
+++ b/server/src/lib/email/templates/ledger.tsx
@@ -410,6 +410,22 @@ export const Badge = ({ children, tone }: { children: React.ReactNode; tone: "da
</span>
);
+/** A solid bar drawn as a table cell, which Outlook sizes where it ignores div heights. */
+export const Bar = ({ width, height, fill }: { width: number; height: number; fill: string }) => (
+ <table {...table} width={width} style={{ width }}>
+ <tbody>
+ <tr>
+ <td
+ height={height}
+ style={{ height, width, backgroundColor: fill, borderRadius: "2px 2px 0 0", fontSize: 0, lineHeight: "0px" }}
+ >
+ &nbsp;
+ </td>
+ </tr>
+ </tbody>
+ </table>
+);
+
interface MeterProps {
used: string;
of: string;
diff --git a/server/src/lib/email/templates/templates.test.ts b/server/src/lib/email/templates/templates.test.ts
index e2f56e448..2ce208497 100644
--- a/server/src/lib/email/templates/templates.test.ts
+++ b/server/src/lib/email/templates/templates.test.ts
@@ -1,7 +1,7 @@
import { render as renderEmail } from "@react-email/components";
import { DateTime } from "luxon";
import { describe, expect, it } from "vitest";
-import type { SiteReport } from "../../../services/weekyReports/weeklyReportTypes.js";
+import type { DigestSite, SiteReport, WeeklyDigest } from "../../../services/weekyReports/weeklyReportTypes.js";
import { installSnippet, welcome } from "../../../services/lifecycleEmails/lifecycleContent.js";
import { formatChange, percentChange } from "../format.js";
import { ApproachingLimitEmail, approachingLimitSubject, projectedLimitDate } from "./ApproachingLimitEmail.js";
@@ -11,7 +11,9 @@ import { LetterEmail } from "./LetterEmail.js";
import { LimitExceededEmail } from "./LimitExceededEmail.js";
import { OtpEmail } from "./OtpEmail.js";
import { SiteTransferEmail } from "./SiteTransferEmail.js";
+import { TrialGraceEmail, trialGraceSubject } from "./TrialGraceEmail.js";
import { VerifyEmailEmail } from "./VerifyEmailEmail.js";
+import { WeeklyDigestEmail, weeklyDigestPreview, weeklyDigestSubject } from "./WeeklyDigestEmail.js";
import { WeeklyReportEmail, weeklyReportSubject } from "./WeeklyReportEmail.js";
/** Rendered HTML without the <!-- --> markers React puts between adjacent text nodes. */
@@ -195,3 +197,116 @@ describe("letters", () => {
expect(html).toContain("https://x.test/unsub");
});
});
+
+const digestSite = (overrides: Partial<DigestSite>): DigestSite => ({
+ siteId: 1,
+ siteDomain: "acme.com",
+ organizationId: "org_acme",
+ organizationName: "Acme Inc",
+ users: 100,
+ previousUsers: 80,
+ daily: [10, 12, 14, 30, 12, 8, 9],
+ lastPageviewAt: null,
+ ...overrides,
+});
+
+const digest = (sites: DigestSite[]): WeeklyDigest => ({ weekStart: "2026-10-12", weekEnd: "2026-10-18", sites });
+
+describe("weekly digest", () => {
+ const sites = [
+ digestSite({ siteId: 1, siteDomain: "acme.com", users: 6105, previousUsers: 5560 }),
+ digestSite({ siteId: 2, siteDomain: "shop.acme.com", users: 914, previousUsers: 698 }),
+ digestSite({
+ siteId: 3,
+ siteDomain: "status.acme.com",
+ users: 0,
+ previousUsers: 120,
+ daily: [0, 0, 0, 0, 0, 0, 0],
+ lastPageviewAt: "2026-10-11T23:41:00.000Z",
+ }),
+ ];
+
+ it("totals every site in the subject, naming the organization when there is one", () => {
+ expect(weeklyDigestSubject(digest(sites))).toBe("Acme Inc last week: 7,019 visitors across 3 sites");
+ expect(
+ weeklyDigestSubject(digest([...sites, digestSite({ siteId: 4, organizationId: "org_b", organizationName: "B" })]))
+ ).toBe("Last week: 7,119 visitors across 4 sites");
+ });
+
+ it("previews the fastest grower and the site that went quiet", () => {
+ expect(weeklyDigestPreview(digest(sites))).toBe(
+ "shop.acme.com up 30.9% · status.acme.com had no pageviews all week · Oct 12–18"
+ );
+ });
+
+ it("lists every site and calls out the quiet one with its last pageview", async () => {
+ const html = await render(WeeklyDigestEmail({ digest: digest(sites), unsubscribeUrl: "https://x.test/off" }));
+ expect(html).toContain("Your 3 sites had 7,019 visitors last week");
+ expect(html).toContain("shop.acme.com");
+ expect(html).toContain("status.acme.com isn&#x27;t sending data");
+ expect(html).toContain("No pageviews since Oct 11, 2026 at 23:41 UTC");
+ expect(html).toContain("https://x.test/off");
+ });
+
+ it("caps the quiet-site callout so a mass outage can't bloat the email", async () => {
+ const quiet = Array.from({ length: 13 }, (_, i) =>
+ digestSite({ ...sites[2], siteId: 100 + i, siteDomain: `quiet${i}.acme.com` })
+ );
+ const html = await render(
+ WeeklyDigestEmail({ digest: digest([sites[0], ...quiet]), unsubscribeUrl: "https://x.test/off" })
+ );
+ expect(html).toContain("13 sites aren&#x27;t sending data");
+ expect(html.split("No pageviews since").length - 1).toBe(10);
+ expect(html).toContain("Plus 3 more sites.");
+ });
+
+ it("groups sites by organization when they span several", async () => {
+ const html = await render(
+ WeeklyDigestEmail({
+ digest: digest([
+ sites[0],
+ digestSite({ siteId: 9, organizationId: "org_b", organizationName: "Side Project" }),
+ ]),
+ unsubscribeUrl: "https://x.test/off",
+ })
+ );
+ expect(html).toContain("Acme Inc");
+ expect(html).toContain("Side Project");
+ });
+});
+
+describe("trial grace emails", () => {
+ const graceNow = DateTime.fromISO("2026-10-24T12:00:00Z") as DateTime<true>;
+ const grace = (stage: "started" | "midway" | "final", visitors = 1204) => ({
+ stage,
+ organizationId: "org_acme",
+ organizationName: "Acme Inc",
+ trialEndedAt: new Date("2026-10-20T09:00:00Z"),
+ endsAt: new Date("2026-12-19T09:00:00Z"),
+ sites: [{ domain: "acme.com", visitors, pageviews: visitors * 3 }],
+ now: graceNow,
+ });
+
+ it("says tracking continues and when the data goes", async () => {
+ expect(trialGraceSubject(grace("started"))).toBe("Your trial ended. Rybbit is still tracking acme.com");
+ const html = await render(TrialGraceEmail(grace("started")));
+ expect(html).toContain("Your trial ended, but we&#x27;re still tracking acme.com");
+ expect(html).toContain("Dec 19, 2026");
+ // The owner's active organization may be another one; the link picks this one.
+ expect(html).toContain("/settings/billing?organization=org_acme");
+ });
+
+ it("counts what came in since the trial ended", async () => {
+ expect(trialGraceSubject(grace("midway"))).toBe("acme.com: 1,204 visitors since your Rybbit trial ended");
+ expect(trialGraceSubject(grace("midway", 0))).toBe("Your Rybbit data is here until Dec 19");
+ const html = await render(TrialGraceEmail(grace("midway")));
+ expect(html).toContain("acme.com had 1,204 visitors since your trial ended");
+ });
+
+ it("gives the deletion date in the last week", async () => {
+ const final = { ...grace("final"), now: DateTime.fromISO("2026-12-14T12:00:00Z") as DateTime<true> };
+ expect(trialGraceSubject(final)).toBe("Your Rybbit data will be deleted after Dec 19");
+ const html = await render(TrialGraceEmail(final));
+ expect(html).toContain("That&#x27;s 5 days from now");
+ });
+});
diff --git a/server/src/lib/subscriptionUtils.test.ts b/server/src/lib/subscriptionUtils.test.ts
index 45068291a..8466af1ff 100644
--- a/server/src/lib/subscriptionUtils.test.ts
+++ b/server/src/lib/subscriptionUtils.test.ts
@@ -17,6 +17,7 @@ const state = vi.hoisted(() => ({
const mocks = vi.hoisted(() => ({
list: vi.fn(),
+ listInvoices: vi.fn(),
stripeEnabled: true,
isCloud: true,
}));
@@ -67,7 +68,7 @@ vi.mock("../db/postgres/postgres.js", () => {
vi.mock("./stripe.js", () => ({
get stripe() {
- return mocks.stripeEnabled ? { subscriptions: { list: mocks.list } } : null;
+ return mocks.stripeEnabled ? { subscriptions: { list: mocks.list }, invoices: { list: mocks.listInvoices } } : null;
},
}));
@@ -88,11 +89,13 @@ import {
hasRenewingStripeSubscription,
invalidateAllStripeSubscriptionsCache,
invalidateStripeSubscriptionCache,
+ lapsedTrialGrace,
OverrideSubscriptionInfo,
StripeSubscriptionInfo,
stripeSubscriptionInfoFromSnapshot,
siteRequiresPlan,
subscriptionIncludesReplay,
+ TRIAL_GRACE_DAYS,
} from "./subscriptionUtils.js";
function planByName(name: string) {
@@ -122,6 +125,7 @@ function stripeSub(
interval?: string | null;
cancelAtPeriodEnd?: boolean;
trialEnd?: number | null;
+ endedAt?: number | null;
periodStart?: number;
periodEnd?: number;
noItems?: boolean;
@@ -137,6 +141,7 @@ function stripeSub(
interval = "month",
cancelAtPeriodEnd = false,
trialEnd = null,
+ endedAt = null,
periodStart = nowSeconds - 5 * 24 * HOUR,
periodEnd = nowSeconds + 25 * 24 * HOUR,
noItems = false,
@@ -149,6 +154,7 @@ function stripeSub(
created,
cancel_at_period_end: cancelAtPeriodEnd,
trial_end: trialEnd,
+ ended_at: endedAt,
items: {
data: noItems
? []
@@ -273,6 +279,7 @@ beforeEach(() => {
mocks.stripeEnabled = true;
mocks.isCloud = true;
mocks.list.mockReset();
+ mocks.listInvoices.mockReset();
listReturns([]);
invalidateAllStripeSubscriptionsCache();
// These modules log expected failures through console.error; keep test output readable.
@@ -1019,3 +1026,176 @@ describe("hasRenewingStripeSubscription", () => {
await expect(hasRenewingStripeSubscription(nextCustomer())).rejects.toThrow("stripe down");
});
});
+
+describe("post-trial grace period", () => {
+ const DAY = 24 * HOUR;
+ const nowSeconds = () => Math.floor(Date.now() / 1000);
+ const plan = () => planByName("standard100k");
+ // A grace period would carry the trialed plan's limit instead of the free one.
+ const plainFree = { source: "free", eventLimit: DEFAULT_EVENT_LIMIT };
+
+ /** Stripe's list of the subscription's paid invoices, by amount. */
+ const paidInvoices = (...amounts: number[]) =>
+ mocks.listInvoices.mockResolvedValue({ data: amounts.map(amount_paid => ({ amount_paid })) });
+
+ /** A 7-day trial that ended `daysAgo` days ago and was canceled at its end. */
+ function lapsedTrial(daysAgo: number, overrides: Parameters<typeof stripeSub>[0] = {}) {
+ const trialEnd = nowSeconds() - daysAgo * DAY;
+ return stripeSub({
+ status: "canceled",
+ priceId: plan().priceId,
+ trialEnd,
+ endedAt: trialEnd,
+ periodStart: trialEnd - 7 * DAY,
+ periodEnd: trialEnd,
+ ...overrides,
+ });
+ }
+
+ describe("lapsedTrialGrace", () => {
+ it("runs for TRIAL_GRACE_DAYS from the end of a trial canceled at its end, on the trialed plan's limit", () => {
+ const sub = lapsedTrial(3);
+ const result = lapsedTrialGrace(sub)!;
+
+ expect(result.eventLimit).toBe(plan().limits.events);
+ expect(result.grace).toMatchObject({ subscriptionId: sub.id, planName: plan().name, retryingPayment: false });
+ expect(result.grace.trialEndedAt).toEqual(new Date(sub.trial_end! * 1000));
+ expect(result.grace.endsAt.getTime() - result.grace.trialEndedAt.getTime()).toBe(TRIAL_GRACE_DAYS * DAY * 1000);
+ });
+
+ it("starts when a trial is canceled outright, not on the day it would have ended", () => {
+ const canceledAt = nowSeconds() - 2 * DAY;
+ const sub = lapsedTrial(-4, { endedAt: canceledAt });
+
+ expect(lapsedTrialGrace(sub)!.grace.trialEndedAt).toEqual(new Date(canceledAt * 1000));
+ });
+
+ it("covers a first charge that failed, flagging that Stripe is still retrying it", () => {
+ const trialEnd = nowSeconds() - 2 * DAY;
+ const sub = lapsedTrial(2, {
+ status: "past_due",
+ endedAt: null,
+ periodStart: trialEnd,
+ periodEnd: trialEnd + 30 * DAY,
+ });
+
+ expect(lapsedTrialGrace(sub)!.grace.retryingPayment).toBe(true);
+ });
+
+ it("still covers an unpaid subscription whose billing period kept advancing after the trial", () => {
+ const trialEnd = nowSeconds() - 40 * DAY;
+ const sub = lapsedTrial(40, { status: "unpaid", endedAt: null, periodStart: trialEnd + 30 * DAY });
+
+ expect(lapsedTrialGrace(sub)!.grace.trialEndedAt).toEqual(new Date(trialEnd * 1000));
+ });
+
+ it("skips subscriptions without a trial and live ones", () => {
+ expect(lapsedTrialGrace(lapsedTrial(3, { trialEnd: null }))).toBeNull();
+ expect(lapsedTrialGrace(lapsedTrial(3, { status: "active" }))).toBeNull();
+ expect(lapsedTrialGrace(lapsedTrial(3, { status: "incomplete_expired" }))).toBeNull();
+ });
+
+ it("ends after TRIAL_GRACE_DAYS", () => {
+ expect(lapsedTrialGrace(lapsedTrial(TRIAL_GRACE_DAYS - 1))).not.toBeNull();
+ expect(lapsedTrialGrace(lapsedTrial(TRIAL_GRACE_DAYS + 1))).toBeNull();
+ });
+ });
+
+ describe("getBestSubscription", () => {
+ it("keeps an unpaid lapsed trial on the free tier with the trial's event limit and its sites on", async () => {
+ const customer = nextCustomer();
+ listReturns([lapsedTrial(3, { customer })]);
+ paidInvoices(0);
+
+ const best = (await getBestSubscription("org_1", customer)) as FreeSubscriptionInfo;
+
+ expect(mocks.listInvoices).toHaveBeenCalledWith({ subscription: "sub_1", status: "paid", limit: 100 });
+ expect(best).toMatchObject({ source: "free", status: "free", eventLimit: plan().limits.events });
+ expect(best.trialGrace?.planName).toBe(plan().name);
+ expect(siteRequiresPlan(best, "2026-09-29 12:00:00")).toBe(false);
+ });
+
+ it("gives no grace period to a customer who paid before canceling, even if a $0 invoice came last", async () => {
+ const customer = nextCustomer();
+ listReturns([lapsedTrial(3, { customer })]);
+ paidInvoices(0, 2_900, 0);
+
+ const best = (await getBestSubscription("org_1", customer)) as FreeSubscriptionInfo;
+
+ expect(best).toMatchObject(plainFree);
+ expect(siteRequiresPlan(best, "2026-09-29 12:00:00")).toBe(true);
+ });
+
+ it("isn't hidden by an incomplete checkout started after the trial", async () => {
+ const customer = nextCustomer();
+ listReturns([
+ lapsedTrial(3, { customer }),
+ stripeSub({ id: "sub_incomplete", customer, status: "incomplete", created: nowSeconds() }),
+ ]);
+ paidInvoices(0);
+
+ await expect(getBestSubscription("org_1", customer)).resolves.toHaveProperty("trialGrace");
+ });
+
+ it("re-checks the invoices when a billing webhook invalidates the customer", async () => {
+ const customer = nextCustomer();
+ listReturns([lapsedTrial(3, { customer })]);
+ paidInvoices(0);
+ await expect(getBestSubscription("org_1", customer)).resolves.toHaveProperty("trialGrace");
+
+ paidInvoices(0, 2_900);
+ invalidateStripeSubscriptionCache(customer);
+
+ await expect(getBestSubscription("org_1", customer)).resolves.not.toHaveProperty("trialGrace");
+ });
+
+ it("fails like a Stripe outage when the invoice can't be read and the caller opts in", async () => {
+ const customer = nextCustomer();
+ listReturns([lapsedTrial(3, { customer })]);
+ mocks.listInvoices.mockRejectedValue(new Error("stripe is down"));
+
+ await expect(getBestSubscription("org_1", customer, { throwOnLookupError: true })).rejects.toThrow(
+ "stripe is down"
+ );
+ await expect(getBestSubscription("org_1", customer)).resolves.toMatchObject(plainFree);
+ });
+
+ it("never applies to self-hosted instances", async () => {
+ mocks.isCloud = false;
+ const customer = nextCustomer();
+ listReturns([lapsedTrial(3, { customer })]);
+
+ await expect(getBestSubscription("org_1", customer)).resolves.toMatchObject(plainFree);
+ expect(mocks.listInvoices).not.toHaveBeenCalled();
+ });
+ });
+
+ it("applies in the bulk path from the snapshot's subscription, without listing", async () => {
+ mocks.listInvoices.mockResolvedValue({ data: [] });
+ const best = await getBestSubscriptionFromStripeSub(
+ "org_1",
+ null,
+ {},
+ lapsedTrial(10, { customer: nextCustomer() })
+ );
+
+ expect(best).toMatchObject({ source: "free", eventLimit: plan().limits.events });
+ expect(mocks.list).not.toHaveBeenCalled();
+ });
+
+ it("ranks a lapsed trial above a later incomplete checkout in the account snapshot", async () => {
+ listReturns([
+ lapsedTrial(3, { id: "sub_trial", customer: "cus_grace_rank" }),
+ stripeSub({ id: "sub_incomplete", customer: "cus_grace_rank", status: "incomplete", created: nowSeconds() }),
+ ]);
+
+ const snapshot = await getAllStripeSubscriptionsByCustomer();
+
+ expect(snapshot.get("cus_grace_rank")?.id).toBe("sub_trial");
+ });
+
+ it("stops keeping sites on once the grace period is over", () => {
+ const past = { status: "free", trialGrace: { endsAt: new Date(Date.now() - 1000) } };
+ expect(siteRequiresPlan(past, "2026-09-29 12:00:00")).toBe(true);
+ });
+});
diff --git a/server/src/lib/subscriptionUtils.ts b/server/src/lib/subscriptionUtils.ts
index a2f28ce14..cb6182e8a 100644
--- a/server/src/lib/subscriptionUtils.ts
+++ b/server/src/lib/subscriptionUtils.ts
@@ -43,12 +43,34 @@ export interface StripeSubscriptionInfo {
trialEnd?: Date;
}
+/**
+ * After a free trial ends without a payment (canceled during the trial, or the first charge
+ * failed), the organization's sites keep collecting for TRIAL_GRACE_DAYS on the trialed plan's
+ * event limit. The organization is on the free tier throughout; this only keeps its sites on.
+ */
+export const TRIAL_GRACE_DAYS = 60;
+
+export interface TrialGrace {
+ subscriptionId: string;
+ /** The plan the organization trialed. */
+ planName: string;
+ trialEndedAt: Date;
+ endsAt: Date;
+ /**
+ * Stripe is still retrying the first charge (past_due). Picking a plan now would start a
+ * second subscription next to the one being retried, so the grace emails wait it out.
+ */
+ retryingPayment: boolean;
+}
+
export interface FreeSubscriptionInfo {
source: "free";
eventLimit: number;
periodStart: string;
planName: "free";
status: "free";
+ /** Set while the organization is in the grace period after an unpaid trial. */
+ trialGrace?: TrialGrace;
}
export interface OverrideSubscriptionInfo {
@@ -207,7 +229,9 @@ export async function getOverrideSubscription(
* (plan changes, new checkouts) call invalidateStripeSubscriptionCache to refresh early.
*/
const STRIPE_SUBSCRIPTION_CACHE_TTL_MS = 60_000;
-const stripeSubscriptionCache = new Map<string, { value: StripeSubscriptionInfo | null; expiresAt: number }>();
+/** `latest` is the customer's best subscription in any state, for the post-trial grace period. */
+type StripeCustomerState = { value: StripeSubscriptionInfo | null; latest: Stripe.Subscription | null };
+const stripeSubscriptionCache = new Map<string, StripeCustomerState & { expiresAt: number }>();
/**
* Drops the cached subscription for a customer so the next read fetches fresh data.
@@ -217,6 +241,7 @@ export function invalidateStripeSubscriptionCache(stripeCustomerId: string | nul
if (stripeCustomerId) {
stripeSubscriptionCache.delete(stripeCustomerId);
subscriptionHistoryCache.delete(stripeCustomerId);
+ subscriptionPaidCache.delete(stripeCustomerId);
}
// Also drop the account-wide snapshot so admin/cron reads pick up the change promptly.
allStripeSubscriptionsCache = null;
@@ -241,13 +266,15 @@ export function invalidateAllStripeSubscriptionsCache(): void {
/**
* Ranks a subscription so the "best" one per customer wins when grouping: prefer
- * active/trialing, then the most recently created.
+ * active/trialing, then anything but an abandoned first payment, then the most recently created.
*/
function rankSubscription(subscription: Stripe.Subscription): number {
const isActiveOrTrialing = subscription.status === "active" || subscription.status === "trialing";
+ // An incomplete checkout after a lapsed trial must not hide that trial's grace period.
+ const isIncomplete = subscription.status === "incomplete" || subscription.status === "incomplete_expired";
// `created` is a unix timestamp (~1.7e9); the status weight (×1e13) dominates so an
// active/trialing sub always outranks a canceled one regardless of creation time.
- return (isActiveOrTrialing ? 1 : 0) * 1e13 + subscription.created;
+ return (isActiveOrTrialing ? 2 : isIncomplete ? 0 : 1) * 1e13 + subscription.created;
}
/**
@@ -325,31 +352,38 @@ export function stripeSubscriptionInfoFromSnapshot(
*/
export async function getStripeSubscription(
stripeCustomerId: string | null,
- { throwOnError = false }: { throwOnError?: boolean } = {}
+ options: { throwOnError?: boolean } = {}
): Promise<StripeSubscriptionInfo | null> {
+ return (await getStripeCustomerState(stripeCustomerId, options)).value;
+}
+
+async function getStripeCustomerState(
+ stripeCustomerId: string | null,
+ { throwOnError = false }: { throwOnError?: boolean } = {}
+): Promise<StripeCustomerState> {
if (!stripeCustomerId) {
- return null;
+ return { value: null, latest: null };
}
const cached = stripeSubscriptionCache.get(stripeCustomerId);
if (cached && cached.expiresAt > Date.now()) {
- return cached.value;
+ return cached;
}
try {
- const value = await fetchStripeSubscription(stripeCustomerId);
+ const state = await fetchStripeSubscription(stripeCustomerId);
stripeSubscriptionCache.set(stripeCustomerId, {
- value,
+ ...state,
expiresAt: Date.now() + STRIPE_SUBSCRIPTION_CACHE_TTL_MS,
});
- return value;
+ return state;
} catch (error) {
console.error("Error fetching Stripe subscription:", error);
// Prefer the last known value (even if expired) over treating the org as having
// no subscription — that would silently downgrade a paying customer. A cached
// `null` is also trustworthy: it means we previously confirmed there was no sub.
if (cached) {
- return cached.value;
+ return cached;
}
// No cached value at all, so we genuinely don't know this customer's status.
// Callers that must not mistake a transient Stripe failure for "no subscription"
@@ -358,7 +392,7 @@ export async function getStripeSubscription(
if (throwOnError) {
throw error;
}
- return null;
+ return { value: null, latest: null };
}
}
@@ -447,7 +481,7 @@ function willRenew(sub: Stripe.Subscription): boolean {
return !(sub.cancel_at && periodEnd && sub.cancel_at <= periodEnd);
}
-async function fetchStripeSubscription(stripeCustomerId: string): Promise<StripeSubscriptionInfo | null> {
+async function fetchStripeSubscription(stripeCustomerId: string): Promise<StripeCustomerState> {
// Fetch active + trialing in a single request and filter locally.
const subs = await (stripe as Stripe).subscriptions.list({
customer: stripeCustomerId,
@@ -456,15 +490,116 @@ async function fetchStripeSubscription(stripeCustomerId: string): Promise<Stripe
expand: ["data.plan.product"],
});
+ // The same pick the bulk snapshot makes, so both paths agree on the grace period.
+ const latest = subs.data.reduce<Stripe.Subscription | null>(
+ (best, sub) => (!best || rankSubscription(sub) > rankSubscription(best) ? sub : best),
+ null
+ );
+
const allSubs = subs.data.filter(sub => sub.status === "active" || sub.status === "trialing");
if (allSubs.length === 0) {
- return null;
+ return { value: null, latest };
}
// Pick the most recently created subscription across both active and trialing
const subscription = allSubs.sort((a, b) => b.created - a.created)[0];
- return buildStripeSubscriptionInfo(subscription);
+ return { value: buildStripeSubscriptionInfo(subscription), latest };
+}
+
+const LAPSED_STATUSES = new Set<Stripe.Subscription.Status>(["canceled", "past_due", "unpaid"]);
+
+/**
+ * The grace period a lapsed subscription would earn from its trial: the trial ended (or was
+ * canceled) less than TRIAL_GRACE_DAYS ago. Pure; resolveTrialGrace also checks that the
+ * subscription never took a payment, which is what makes the trial "unpaid".
+ */
+export function lapsedTrialGrace(
+ subscription: Stripe.Subscription,
+ now: Date = new Date()
+): { grace: TrialGrace; eventLimit: number } | null {
+ const trialEnd = subscription.trial_end;
+ const item = subscription.items?.data[0];
+ if (!LAPSED_STATUSES.has(subscription.status) || !trialEnd || !item) {
+ return null;
+ }
+ const plan = getStripePrices().find((p: StripePlan) => p.priceId === item.price.id);
+ if (!plan) {
+ return null;
+ }
+
+ // Canceling during the trial ends it then, not on the date it would have run to.
+ const endedSeconds =
+ subscription.status === "canceled" && subscription.ended_at ? Math.min(subscription.ended_at, trialEnd) : trialEnd;
+ const trialEndedAt = new Date(endedSeconds * 1000);
+ const endsAt = DateTime.fromJSDate(trialEndedAt, { zone: "utc" }).plus({ days: TRIAL_GRACE_DAYS }).toJSDate();
+ if (trialEndedAt > now || endsAt <= now) {
+ return null;
+ }
+
+ return {
+ grace: {
+ subscriptionId: subscription.id,
+ planName: plan.name,
+ trialEndedAt,
+ endsAt,
+ retryingPayment: subscription.status === "past_due",
+ },
+ eventLimit: plan.limits.events,
+ };
+}
+
+// A payment is permanent, so a "paid" answer can be kept for long; "never paid" can change
+// any time and is dropped with the customer's other cached state on every billing webhook.
+const PAID_CACHE_TTL_MS = 24 * 60 * 60_000;
+const UNPAID_CACHE_TTL_MS = 5 * 60_000;
+const subscriptionPaidCache = new Map<string, { subscriptionId: string; value: boolean; expiresAt: number }>();
+
+/**
+ * Whether any invoice on the subscription took money. The trial's own invoice is for $0 and a
+ * first charge that failed is unpaid, so an unpaid trial has none. Neither the billing period
+ * (an unpaid subscription keeps advancing it) nor the latest invoice (a downgrade can leave a
+ * $0 proration invoice last) can answer this.
+ */
+async function subscriptionWasPaid(subscription: Stripe.Subscription): Promise<boolean> {
+ if (!stripe) {
+ return false;
+ }
+ const customerId = typeof subscription.customer === "string" ? subscription.customer : subscription.customer.id;
+ const cached = subscriptionPaidCache.get(customerId);
+ if (cached && cached.subscriptionId === subscription.id && cached.expiresAt > Date.now()) {
+ return cached.value;
+ }
+
+ const invoices = await stripe.invoices.list({ subscription: subscription.id, status: "paid", limit: 100 });
+ const value = invoices.data.some(invoice => invoice.amount_paid > 0);
+ subscriptionPaidCache.set(customerId, {
+ subscriptionId: subscription.id,
+ value,
+ expiresAt: Date.now() + (value ? PAID_CACHE_TTL_MS : UNPAID_CACHE_TTL_MS),
+ });
+ return value;
+}
+
+/** The grace period the customer's lapsed trial gives them right now, if any. */
+async function resolveTrialGrace(
+ subscription: Stripe.Subscription | null | undefined,
+ { throwOnError = false }: LookupOptions = {}
+): Promise<{ grace: TrialGrace; eventLimit: number } | null> {
+ if (!IS_CLOUD || !subscription) {
+ return null;
+ }
+ const candidate = lapsedTrialGrace(subscription);
+ if (!candidate) {
+ return null;
+ }
+ try {
+ return (await subscriptionWasPaid(subscription)) ? null : candidate;
+ } catch (error) {
+ logger.error({ err: error, subscriptionId: subscription.id }, "Error checking a lapsed trial's invoices");
+ if (throwOnError) throw error;
+ return null;
+ }
}
/**
@@ -595,32 +730,35 @@ export async function getBestSubscription(
}
// Get both subscription types
- const [appsumoSub, stripeSub] = await Promise.all([
+ const throwOnStripe = throwOnStripeError || throwOnLookupError;
+ const [appsumoSub, stripeState] = await Promise.all([
getAppSumoSubscription(organizationId, lookup),
- getStripeSubscription(stripeCustomerId, { throwOnError: throwOnStripeError || throwOnLookupError }),
+ getStripeCustomerState(stripeCustomerId, { throwOnError: throwOnStripe }),
]);
- if (stripeSub) {
- return stripeSub;
+ if (stripeState.value) {
+ return stripeState.value;
}
if (appsumoSub) {
return appsumoSub;
}
- return freeSubscription();
+ return freeSubscription(await resolveTrialGrace(stripeState.latest, { throwOnError: throwOnStripe }));
}
/**
* Like getBestSubscription, but uses an already-resolved Stripe subscription (e.g. from a bulk
* account snapshot) instead of making a per-customer Stripe call. Used by callers that resolve
- * many orgs at once (admin endpoints, the usage cron).
+ * many orgs at once (admin endpoints, the usage cron). Pass the customer's raw subscription from
+ * the snapshot as `latestStripeSub` to apply the grace period after an unpaid trial.
* Priority: CustomPlan > Override > Stripe > AppSumo > Free.
*/
export async function getBestSubscriptionFromStripeSub(
organizationId: string,
stripeSub: StripeSubscriptionInfo | null,
- lookup: LookupOptions = {}
+ lookup: LookupOptions = {},
+ latestStripeSub?: Stripe.Subscription | null
): Promise<SubscriptionInfo> {
const customSub = await getCustomPlanSubscription(organizationId, lookup);
if (customSub) {
@@ -641,7 +779,7 @@ export async function getBestSubscriptionFromStripeSub(
return appsumoSub;
}
- return freeSubscription();
+ return freeSubscription(await resolveTrialGrace(latestStripeSub, lookup));
}
/**
@@ -698,24 +836,30 @@ export function getReplayLimit(subscription: SubscriptionInfo): number {
* Whether a site is switched off because its organization has no plan. Only sites created
* after the free plan ended are affected; older ones keep the legacy free tier. Accepts either
* a SubscriptionInfo or the getSubscriptionInner payload — both report status "free" exactly
- * when there is no custom plan, override, Stripe subscription or AppSumo license.
+ * when there is no custom plan, override, Stripe subscription or AppSumo license. Sites stay
+ * on during the grace period after an unpaid trial.
*/
export function siteRequiresPlan(
- subscription: { status: string } | null | undefined,
+ subscription: { status: string; trialGrace?: { endsAt: Date | string } } | null | undefined,
siteCreatedAt: string | null | undefined
): boolean {
if (!IS_CLOUD || subscription?.status !== "free" || !siteCreatedAt) {
return false;
}
+ if (subscription.trialGrace && new Date(subscription.trialGrace.endsAt) > new Date()) {
+ return false;
+ }
return siteCreatedAt.slice(0, 10) >= FREE_PLAN_CUTOFF_DATE;
}
-function freeSubscription(): FreeSubscriptionInfo {
+function freeSubscription(trial: { grace: TrialGrace; eventLimit: number } | null = null): FreeSubscriptionInfo {
return {
source: "free",
- eventLimit: DEFAULT_EVENT_LIMIT,
+ // The grace period keeps the trialed plan's allowance, so sites don't stop at the free one.
+ eventLimit: trial?.eventLimit ?? DEFAULT_EVENT_LIMIT,
periodStart: getStartOfMonth(),
planName: "free",
status: "free",
+ ...(trial && { trialGrace: trial.grace }),
};
}
diff --git a/server/src/services/trialGrace/trialGraceEmails.test.ts b/server/src/services/trialGrace/trialGraceEmails.test.ts
new file mode 100644
index 000000000..9808f1d3e
--- /dev/null
+++ b/server/src/services/trialGrace/trialGraceEmails.test.ts
@@ -0,0 +1,182 @@
+import { DateTime } from "luxon";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { TrialGrace } from "../../lib/subscriptionUtils.js";
+
+/**
+ * The grace emails decide which notice an organization's owners are due and send each one
+ * once. Postgres (owners, the email log), ClickHouse (traffic) and the sender are mocked.
+ */
+const state = vi.hoisted(() => ({
+ owners: [] as Array<{ userId: string; email: string }>,
+ log: [] as Array<{ id: number; userId: string; emailKey: string; sentAt: string }>,
+ traffic: [] as Array<{ site_id: number; visitors: number; pageviews: number }>,
+ nextId: 1,
+}));
+
+const mocks = vi.hoisted(() => ({ sendTrialGraceEmail: vi.fn() }));
+
+class IdempotencyConflict extends Error {}
+
+vi.mock("../../db/postgres/postgres.js", () => {
+ const chain = (rows: () => unknown[]) => {
+ const builder: any = {
+ from: () => builder,
+ innerJoin: () => builder,
+ where: () => builder,
+ then: (resolve: any, reject: any) => Promise.resolve(rows()).then(resolve, reject),
+ };
+ return builder;
+ };
+ return {
+ db: {
+ // The owner and email-log reads are told apart by the columns each one selects.
+ select: (fields: Record<string, unknown>) => chain(() => ("emailKey" in fields ? state.log : state.owners)),
+ insert: () => ({
+ values: (row: { userId: string; emailKey: string }) => ({
+ onConflictDoNothing: () => ({
+ returning: async () => {
+ if (state.log.some(r => r.userId === row.userId && r.emailKey === row.emailKey)) return [];
+ const id = state.nextId++;
+ state.log.push({ id, ...row, sentAt: DateTime.utc().toSQL({ includeOffset: false })! });
+ return [{ id }];
+ },
+ }),
+ }),
+ }),
+ // Only ever used to release the claim just made.
+ delete: () => ({ where: async () => void state.log.pop() }),
+ },
+ };
+});
+
+vi.mock("../../db/clickhouse/clickhouse.js", () => ({
+ clickhouse: { query: async () => ({ json: async () => state.traffic }) },
+}));
+
+vi.mock("../../lib/email/email.js", () => ({
+ sendTrialGraceEmail: mocks.sendTrialGraceEmail,
+ isIdempotencyConflict: (error: unknown) => error instanceof IdempotencyConflict,
+}));
+
+vi.mock("../../lib/logger/logger.js", () => ({
+ createServiceLogger: () => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+
+import { trialGraceEmails, trialGraceStage } from "./trialGraceEmails.js";
+
+const trialEndedAt = DateTime.fromISO("2026-10-01T00:00:00Z", { zone: "utc" });
+
+const grace = (overrides: Partial<TrialGrace> = {}): TrialGrace => ({
+ subscriptionId: "sub_trial",
+ planName: "standard100k",
+ trialEndedAt: trialEndedAt.toJSDate(),
+ endsAt: trialEndedAt.plus({ days: 60 }).toJSDate(),
+ retryingPayment: false,
+ ...overrides,
+});
+
+const org = { id: "org_1", name: "Acme Inc" };
+const sites = [
+ { siteId: 1, domain: "docs.acme.com" },
+ { siteId: 2, domain: "acme.com" },
+];
+const day = (n: number) => trialEndedAt.plus({ days: n });
+
+beforeEach(() => {
+ state.owners = [{ userId: "u_owner", email: "[email protected]" }];
+ state.log = [];
+ state.traffic = [{ site_id: 2, visitors: 40, pageviews: 120 }];
+ mocks.sendTrialGraceEmail.mockReset();
+ mocks.sendTrialGraceEmail.mockResolvedValue(undefined);
+});
+
+describe("trialGraceStage", () => {
+ it("starts, turns midway after 30 days, and gives final notice in the last week", () => {
+ expect(trialGraceStage(grace(), day(0))).toBe("started");
+ expect(trialGraceStage(grace(), day(29))).toBe("started");
+ expect(trialGraceStage(grace(), day(30))).toBe("midway");
+ expect(trialGraceStage(grace(), day(52))).toBe("midway");
+ expect(trialGraceStage(grace(), day(53))).toBe("final");
+ });
+});
+
+describe("trialGraceEmails.sendDue", () => {
+ it("sends the owners the notice they're due, with each site's traffic since the trial ended", async () => {
+ await trialGraceEmails.sendDue(org, grace(), sites, day(1));
+
+ expect(mocks.sendTrialGraceEmail).toHaveBeenCalledWith(
+ {
+ stage: "started",
+ organizationId: "org_1",
+ organizationName: "Acme Inc",
+ trialEndedAt: grace().trialEndedAt,
+ endsAt: grace().endsAt,
+ sites: [
+ { domain: "acme.com", visitors: 40, pageviews: 120 },
+ { domain: "docs.acme.com", visitors: 0, pageviews: 0 },
+ ],
+ now: day(1),
+ },
+ "trial-grace:u_owner:trial_grace:sub_trial:started"
+ );
+ expect(state.log.map(r => r.emailKey)).toEqual(["trial_grace:sub_trial:started"]);
+ });
+
+ it("sends each stage once", async () => {
+ await trialGraceEmails.sendDue(org, grace(), sites, day(1));
+ await trialGraceEmails.sendDue(org, grace(), sites, day(2));
+
+ expect(mocks.sendTrialGraceEmail).toHaveBeenCalledTimes(1);
+ });
+
+ it("waits a few days after one notice before sending the next", async () => {
+ state.log = [
+ {
+ id: 99,
+ userId: "u_owner",
+ emailKey: "trial_grace:sub_trial:midway",
+ sentAt: day(51).toSQL({ includeOffset: false })!,
+ },
+ ];
+
+ await trialGraceEmails.sendDue(org, grace(), sites, day(53));
+ expect(mocks.sendTrialGraceEmail).not.toHaveBeenCalled();
+
+ await trialGraceEmails.sendDue(org, grace(), sites, day(54));
+ expect(mocks.sendTrialGraceEmail).toHaveBeenCalledWith(
+ expect.objectContaining({ stage: "final" }),
+ "trial-grace:u_owner:trial_grace:sub_trial:final"
+ );
+ });
+
+ it("stays quiet while Stripe is still retrying the first charge", async () => {
+ await trialGraceEmails.sendDue(org, grace({ retryingPayment: true }), sites, day(1));
+
+ expect(mocks.sendTrialGraceEmail).not.toHaveBeenCalled();
+ });
+
+ it("releases the claim when the send fails, so the next run tries again", async () => {
+ mocks.sendTrialGraceEmail.mockRejectedValueOnce(new Error("resend down"));
+
+ await trialGraceEmails.sendDue(org, grace(), sites, day(1));
+ expect(state.log).toEqual([]);
+
+ await trialGraceEmails.sendDue(org, grace(), sites, day(1));
+ expect(mocks.sendTrialGraceEmail).toHaveBeenCalledTimes(2);
+ expect(state.log).toHaveLength(1);
+ // Same Resend key both times, so a first send that did go out can't be repeated.
+ expect(mocks.sendTrialGraceEmail.mock.calls[0][2]).toBe(mocks.sendTrialGraceEmail.mock.calls[1][2]);
+ });
+
+ it("keeps the claim when Resend says the key was already used, because that email went out", async () => {
+ mocks.sendTrialGraceEmail.mockRejectedValueOnce(new IdempotencyConflict("invalid_idempotent_request"));
+
+ await trialGraceEmails.sendDue(org, grace(), sites, day(1));
+ await trialGraceEmails.sendDue(org, grace(), sites, day(2));
+
+ expect(state.log.map(r => r.emailKey)).toEqual(["trial_grace:sub_trial:started"]);
+ expect(mocks.sendTrialGraceEmail).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/server/src/services/trialGrace/trialGraceEmails.ts b/server/src/services/trialGrace/trialGraceEmails.ts
new file mode 100644
index 000000000..3c6767216
--- /dev/null
+++ b/server/src/services/trialGrace/trialGraceEmails.ts
@@ -0,0 +1,164 @@
+import { and, eq, inArray, like } from "drizzle-orm";
+import { DateTime } from "luxon";
+import { clickhouse } from "../../db/clickhouse/clickhouse.js";
+import { db } from "../../db/postgres/postgres.js";
+import { lifecycleEmailLog, member, user } from "../../db/postgres/schema.js";
+import { isIdempotencyConflict, sendTrialGraceEmail } from "../../lib/email/email.js";
+import type { TrialGraceSite, TrialGraceStage } from "../../lib/email/templates/TrialGraceEmail.js";
+import { createServiceLogger } from "../../lib/logger/logger.js";
+import type { TrialGrace } from "../../lib/subscriptionUtils.js";
+
+const MIDWAY_AFTER_DAYS = 30;
+const FINAL_NOTICE_DAYS = 7;
+// A grace period already under way when this shipped can owe two notices at once; space them
+// out instead of sending both from one cron run.
+const MIN_DAYS_BETWEEN_NOTICES = 3;
+
+/** Which notice the grace period calls for at `now`. Only ever moves forward. */
+export function trialGraceStage(grace: TrialGrace, now: DateTime): TrialGraceStage {
+ if (DateTime.fromJSDate(grace.endsAt).diff(now, "days").days <= FINAL_NOTICE_DAYS) return "final";
+ if (now.diff(DateTime.fromJSDate(grace.trialEndedAt), "days").days >= MIDWAY_AFTER_DAYS) return "midway";
+ return "started";
+}
+
+const parseTs = (value: string): DateTime => {
+ const sql = DateTime.fromSQL(value, { zone: "utc" });
+ return sql.isValid ? sql : DateTime.fromISO(value, { zone: "utc" });
+};
+
+/**
+ * The emails an organization's owners get while its sites keep collecting after an unpaid trial
+ * (see TRIAL_GRACE_DAYS). Each stage goes out once per owner and grace period: the
+ * lifecycle_email_log row is claimed before sending and released if the send fails.
+ *
+ * A failed send can't be told apart from "accepted but the response was lost", so the retry
+ * reuses the same Resend idempotency key. Resend then replays the original response, or, since
+ * the traffic numbers have moved on, rejects the changed payload as a conflict, which means the
+ * first one went out and the claim stays.
+ */
+class TrialGraceEmails {
+ private logger = createServiceLogger("trial-grace");
+
+ private async fetchSiteTraffic(
+ siteIds: number[],
+ since: Date
+ ): Promise<Map<number, { visitors: number; pageviews: number }>> {
+ const traffic = new Map<number, { visitors: number; pageviews: number }>();
+ if (siteIds.length === 0) return traffic;
+
+ const result = await clickhouse.query({
+ query: `
+ SELECT
+ site_id,
+ uniq(COALESCE(NULLIF(identified_user_id, ''), user_id)) AS visitors,
+ countIf(type = 'pageview') AS pageviews
+ FROM events
+ WHERE site_id IN ({siteIds:Array(Int32)})
+ AND timestamp >= toDateTime({since:String}, 'UTC')
+ GROUP BY site_id
+ `,
+ format: "JSONEachRow",
+ query_params: {
+ siteIds,
+ since: DateTime.fromJSDate(since, { zone: "utc" }).toFormat("yyyy-MM-dd HH:mm:ss"),
+ },
+ });
+ const rows = await result.json<{ site_id: number; visitors: string | number; pageviews: string | number }>();
+ for (const row of rows) {
+ traffic.set(Number(row.site_id), { visitors: Number(row.visitors), pageviews: Number(row.pageviews) });
+ }
+ return traffic;
+ }
+
+ /** Sends the organization's owners the notice they are due now, if any. */
+ async sendDue(
+ org: { id: string; name: string },
+ grace: TrialGrace,
+ sites: Array<{ siteId: number; domain: string }>,
+ now: DateTime = DateTime.utc()
+ ): Promise<void> {
+ // Stripe is still retrying the first charge and emails the customer about it itself.
+ if (grace.retryingPayment) return;
+
+ const stage = trialGraceStage(grace, now);
+ const keyPrefix = `trial_grace:${grace.subscriptionId}:`;
+ const emailKey = `${keyPrefix}${stage}`;
+
+ const owners = await db
+ .select({ userId: user.id, email: user.email })
+ .from(member)
+ .innerJoin(user, eq(member.userId, user.id))
+ .where(and(eq(member.organizationId, org.id), eq(member.role, "owner")));
+ if (owners.length === 0) return;
+
+ const sent = await db
+ .select({
+ userId: lifecycleEmailLog.userId,
+ emailKey: lifecycleEmailLog.emailKey,
+ sentAt: lifecycleEmailLog.sentAt,
+ })
+ .from(lifecycleEmailLog)
+ .where(
+ and(
+ inArray(
+ lifecycleEmailLog.userId,
+ owners.map(owner => owner.userId)
+ ),
+ like(lifecycleEmailLog.emailKey, `${keyPrefix}%`)
+ )
+ );
+
+ const due = owners.filter(owner => {
+ const mine = sent.filter(row => row.userId === owner.userId);
+ if (mine.some(row => row.emailKey === emailKey)) return false;
+ return mine.every(row => now.diff(parseTs(row.sentAt), "days").days >= MIN_DAYS_BETWEEN_NOTICES);
+ });
+ if (due.length === 0) return;
+
+ const traffic = await this.fetchSiteTraffic(
+ sites.map(site => site.siteId),
+ grace.trialEndedAt
+ );
+ const siteTraffic: TrialGraceSite[] = sites
+ .map(site => ({ domain: site.domain, visitors: 0, pageviews: 0, ...traffic.get(site.siteId) }))
+ .sort((a, b) => b.visitors - a.visitors || b.pageviews - a.pageviews);
+
+ for (const owner of due) {
+ const [claimed] = await db
+ .insert(lifecycleEmailLog)
+ .values({ userId: owner.userId, emailKey })
+ .onConflictDoNothing()
+ .returning({ id: lifecycleEmailLog.id });
+ if (!claimed) continue;
+
+ try {
+ await sendTrialGraceEmail(
+ owner.email,
+ {
+ stage,
+ organizationId: org.id,
+ organizationName: org.name,
+ trialEndedAt: grace.trialEndedAt,
+ endsAt: grace.endsAt,
+ sites: siteTraffic,
+ now,
+ },
+ `trial-grace:${owner.userId}:${emailKey}`
+ );
+ this.logger.info({ organizationId: org.id, userId: owner.userId, stage }, "Sent trial grace email");
+ } catch (error) {
+ if (isIdempotencyConflict(error)) {
+ this.logger.info({ organizationId: org.id, userId: owner.userId, stage }, "Trial grace email already sent");
+ continue;
+ }
+ await db.delete(lifecycleEmailLog).where(eq(lifecycleEmailLog.id, claimed.id));
+ this.logger.error(
+ { err: error, organizationId: org.id, userId: owner.userId, stage },
+ "Error sending trial grace email"
+ );
+ }
+ }
+ }
+}
+
+export const trialGraceEmails = new TrialGraceEmails();
diff --git a/server/src/services/usageService.test.ts b/server/src/services/usageService.test.ts
index af198ea58..c3b28bc6a 100644
--- a/server/src/services/usageService.test.ts
+++ b/server/src/services/usageService.test.ts
@@ -33,6 +33,7 @@ const mocks = vi.hoisted(() => ({
getAllStripeSubscriptionsByCustomer: vi.fn(),
sendLimitExceededEmail: vi.fn(),
sendApproachingLimitEmail: vi.fn(),
+ sendTrialGraceDue: vi.fn(),
}));
vi.mock("../db/postgres/postgres.js", () => {
@@ -88,6 +89,10 @@ vi.mock("../lib/email/email.js", () => ({
sendApproachingLimitEmail: mocks.sendApproachingLimitEmail,
}));
+vi.mock("./trialGrace/trialGraceEmails.js", () => ({
+ trialGraceEmails: { sendDue: mocks.sendTrialGraceDue },
+}));
+
vi.mock("../lib/logger/logger.js", () => ({
createServiceLogger: () => ({
info: vi.fn(),
@@ -217,6 +222,8 @@ beforeEach(() => {
mocks.sendLimitExceededEmail.mockResolvedValue(undefined);
mocks.sendApproachingLimitEmail.mockReset();
mocks.sendApproachingLimitEmail.mockResolvedValue(undefined);
+ mocks.sendTrialGraceDue.mockReset();
+ mocks.sendTrialGraceDue.mockResolvedValue(undefined);
// The service is a singleton; clear the blocked sets between tests.
usageService.setSitesOverLimit(new Set());
@@ -720,6 +727,57 @@ describe("sites that need a plan (cloud, free plan ended 2026-02-13)", () => {
expect(usageService.isSiteWithoutPlan(2)).toBe(false);
});
+ describe("after an unpaid trial", () => {
+ const graceSub = (endsAt: Date): SubscriptionInfo => ({
+ source: "free",
+ planName: "free",
+ status: "free",
+ periodStart: "2026-08-01",
+ eventLimit: 100_000,
+ trialGrace: {
+ subscriptionId: "sub_trial",
+ planName: "standard100k",
+ trialEndedAt: new Date("2026-07-30T00:00:00Z"),
+ endsAt,
+ retryingPayment: false,
+ },
+ });
+
+ it("keeps every site collecting on the trial's limit and hands the org to the grace emails", async () => {
+ const subscription = graceSub(new Date("2026-09-28T00:00:00Z"));
+ state.subscriptions.set("org_1", subscription);
+ state.eventCounts = [{ site_id: 2, count: "50000" }];
+
+ await usageService.updateOrganizationsMonthlyUsage();
+
+ expect(usageService.getSitesWithoutPlan().size).toBe(0);
+ expect(usageService.isSiteOverLimit(2)).toBe(false);
+ expect(mocks.sendTrialGraceDue).toHaveBeenCalledWith(
+ expect.objectContaining({ id: "org_1" }),
+ (subscription as Extract<SubscriptionInfo, { source: "free" }>).trialGrace,
+ [expect.objectContaining({ siteId: 1, domain: "1" }), expect.objectContaining({ siteId: 2, domain: "2" })]
+ );
+ });
+
+ it("switches the sites off once the grace period is over", async () => {
+ state.subscriptions.set("org_1", graceSub(new Date("2026-08-01T00:00:00Z")));
+
+ await usageService.updateOrganizationsMonthlyUsage();
+
+ expect(usageService.isSiteWithoutPlan(2)).toBe(true);
+ });
+
+ it("still applies the blocks when the grace email fails", async () => {
+ state.subscriptions.set("org_1", graceSub(new Date("2026-09-28T00:00:00Z")));
+ mocks.sendTrialGraceDue.mockRejectedValue(new Error("resend down"));
+
+ await usageService.updateOrganizationsMonthlyUsage();
+
+ expect(state.updates).toHaveLength(1);
+ expect(usageService.isSiteWithoutPlan(2)).toBe(false);
+ });
+ });
+
it("never blocks sites for needing a plan when self-hosted", async () => {
state.isCloud = false;
diff --git a/server/src/services/usageService.ts b/server/src/services/usageService.ts
index c16c64f27..5d71c4645 100644
--- a/server/src/services/usageService.ts
+++ b/server/src/services/usageService.ts
@@ -22,6 +22,7 @@ import {
subscriptionIncludesReplay,
SubscriptionInfo,
} from "../lib/subscriptionUtils.js";
+import { trialGraceEmails } from "./trialGrace/trialGraceEmails.js";
type UsageUpdateCallback = () => void;
@@ -248,7 +249,12 @@ class UsageService {
const stripeSub = stripeSubscriptionInfoFromSnapshot(stripeSubscriptions, orgData.stripeCustomerId);
// A failed plan lookup throws, so the caller skips this org and keeps its current blocks
// instead of treating a paying organization as free.
- const subscription = await getBestSubscriptionFromStripeSub(orgData.id, stripeSub, { throwOnError: true });
+ const subscription = await getBestSubscriptionFromStripeSub(
+ orgData.id,
+ stripeSub,
+ { throwOnError: true },
+ orgData.stripeCustomerId ? stripeSubscriptions.get(orgData.stripeCustomerId) : null
+ );
// Log subscription details
if (subscription.source === "appsumo") {
@@ -259,6 +265,10 @@ class UsageService {
this.logger.info(
`Organization ${orgData.name} using Stripe ${subscription.planName} (${subscription.interval}) with ${subscription.eventLimit} events/month`
);
+ } else if (subscription.source === "free" && subscription.trialGrace) {
+ this.logger.info(
+ `Organization ${orgData.name} in its post-trial grace period until ${subscription.trialGrace.endsAt.toISOString()} with ${subscription.eventLimit} events/month`
+ );
} else {
this.logger.info(`Organization ${orgData.name} on free tier with ${subscription.eventLimit} events/month`);
}
@@ -381,7 +391,7 @@ class UsageService {
// Step 3: Build a map of organizationId -> { sites, eventCount, replayCount }
const orgDataMap = new Map<
string,
- { sites: OrgSite[]; siteUsage: SiteUsage[]; eventCount: number; replayCount: number }
+ { sites: Array<OrgSite & { domain: string }>; siteUsage: SiteUsage[]; eventCount: number; replayCount: number }
>();
for (const site of allSites) {
const orgData = orgDataMap.get(site.organizationId) || {
@@ -391,8 +401,9 @@ class UsageService {
replayCount: 0,
};
const siteEvents = eventCountMap.get(site.siteId) || 0;
- orgData.sites.push({ siteId: site.siteId, createdAt: site.createdAt });
- orgData.siteUsage.push({ domain: site.domain ?? String(site.siteId), events: siteEvents });
+ const domain = site.domain ?? String(site.siteId);
+ orgData.sites.push({ siteId: site.siteId, createdAt: site.createdAt, domain });
+ orgData.siteUsage.push({ domain, events: siteEvents });
orgData.eventCount += siteEvents;
orgData.replayCount += replayCountMap.get(site.siteId) || 0;
orgDataMap.set(site.organizationId, orgData);
@@ -508,6 +519,14 @@ class UsageService {
}
}
+ if (subscription.source === "free" && subscription.trialGrace) {
+ try {
+ await trialGraceEmails.sendDue(orgData, subscription.trialGrace, orgSites);
+ } catch (error) {
+ this.logger.error({ err: error, organizationId: orgData.id }, "Failed to send trial grace emails");
+ }
+ }
+
// The emails above awaited; a refresh may have landed with newer data meanwhile.
if (this.refreshedSince(orgData.id, runStartedAt)) continue;
diff --git a/server/src/services/weekyReports/weeklyReportService.test.ts b/server/src/services/weekyReports/weeklyReportService.test.ts
new file mode 100644
index 000000000..af7eead04
--- /dev/null
+++ b/server/src/services/weekyReports/weeklyReportService.test.ts
@@ -0,0 +1,221 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * Who gets which weekly email: one per person, the full report when they have one site with
+ * traffic and a digest when they have more. Postgres, ClickHouse, site access and the senders
+ * are mocked; the routing is the subject under test.
+ */
+const state = vi.hoisted(() => ({
+ memberships: [] as Array<{
+ memberId: string;
+ userId: string;
+ role: string;
+ organizationId: string;
+ hasRestrictedSiteAccess: boolean;
+ email: string;
+ sendAutoEmailReports: boolean | null;
+ }>,
+ organizations: [] as Array<{ id: string; name: string }>,
+ sites: [] as Array<{ siteId: number; name: string; domain: string; organizationId: string | null }>,
+ /** Pageviews per site in the reported week and the one before. */
+ activity: [] as Array<{ site_id: number; current: number; previous: number }>,
+ /** userId -> site ids a restricted member can open. */
+ grants: new Map<string, number[]>(),
+ overviewQueries: [] as number[],
+}));
+
+const mocks = vi.hoisted(() => ({
+ sendWeeklyReportEmail: vi.fn(),
+ sendWeeklyDigestEmail: vi.fn(),
+}));
+
+vi.mock("../../db/postgres/postgres.js", () => {
+ const chain = (rows: () => unknown[]) => {
+ const builder: any = {
+ from: () => builder,
+ innerJoin: () => builder,
+ where: () => builder,
+ then: (resolve: any, reject: any) => Promise.resolve(rows()).then(resolve, reject),
+ };
+ return builder;
+ };
+ return {
+ db: {
+ // The three reads are told apart by the columns each one selects.
+ select: (fields: Record<string, unknown>) =>
+ chain(() => {
+ if ("memberId" in fields) return state.memberships;
+ if ("siteId" in fields) return state.sites;
+ return state.organizations;
+ }),
+ },
+ };
+});
+
+vi.mock("../../db/clickhouse/clickhouse.js", () => ({
+ clickhouse: { query: async (request: { query: string; query_params: { siteId?: number } }) => request },
+}));
+
+vi.mock("../../api/analytics/utils/utils.js", () => ({
+ processResults: async ({ query, query_params }: { query: string; query_params: { siteId?: number } }) => {
+ if (query.includes("{currentStart:String}")) return state.activity;
+ if (query.includes("max(timestamp) AS last")) return [{ last: "2026-10-11 23:41:00" }];
+ if (query.includes("FilteredSessionsWithStats")) {
+ state.overviewQueries.push(query_params.siteId!);
+ const site = state.activity.find(row => row.site_id === query_params.siteId);
+ return [
+ {
+ sessions: 10,
+ pageviews: site?.current ?? 0,
+ users: 7,
+ pages_per_session: 2,
+ bounce_rate: 40,
+ session_duration: 60,
+ },
+ ];
+ }
+ return [];
+ },
+}));
+
+vi.mock("../../lib/access.js", () => ({
+ filterSitesByMemberAccess: async (orgSites: Array<{ siteId: number }>, _org: string, userId: string) =>
+ orgSites.filter(site => state.grants.get(userId)?.includes(site.siteId)),
+}));
+
+vi.mock("../../lib/email/email.js", () => ({
+ sendWeeklyReportEmail: mocks.sendWeeklyReportEmail,
+ sendWeeklyDigestEmail: mocks.sendWeeklyDigestEmail,
+}));
+
+vi.mock("../../lib/const.js", async importOriginal => ({
+ ...(await importOriginal<typeof import("../../lib/const.js")>()),
+ IS_CLOUD: true,
+}));
+
+vi.mock("../../lib/logger/logger.js", () => ({
+ createServiceLogger: () => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+
+import { weeklyReportService } from "./weeklyReportService.js";
+
+const membership = (userId: string, organizationId: string, role = "owner", overrides = {}) => ({
+ memberId: `m_${userId}_${organizationId}`,
+ userId,
+ role,
+ organizationId,
+ hasRestrictedSiteAccess: false,
+ email: `${userId}@example.com`,
+ sendAutoEmailReports: true,
+ ...overrides,
+});
+
+const site = (siteId: number, organizationId: string) => ({
+ siteId,
+ name: `Site ${siteId}`,
+ domain: `site${siteId}.com`,
+ organizationId,
+});
+
+const digestRecipients = () =>
+ mocks.sendWeeklyDigestEmail.mock.calls.map(([args]) => ({
+ email: args.email,
+ sites: args.digest.sites.map((s: { siteId: number }) => s.siteId).sort(),
+ }));
+
+beforeEach(() => {
+ state.organizations = [
+ { id: "org_a", name: "Acme" },
+ { id: "org_b", name: "Side Project" },
+ ];
+ state.sites = [site(1, "org_a"), site(2, "org_a"), site(3, "org_a"), site(4, "org_b")];
+ state.activity = [];
+ state.memberships = [];
+ state.grants.clear();
+ state.overviewQueries = [];
+ mocks.sendWeeklyReportEmail.mockReset();
+ mocks.sendWeeklyDigestEmail.mockReset();
+});
+
+describe("weekly reports", () => {
+ it("sends the full report to someone with one site that had traffic", async () => {
+ state.memberships = [membership("ada", "org_a")];
+ state.activity = [{ site_id: 1, current: 50, previous: 40 }];
+
+ await weeklyReportService.generateAndSendReports();
+
+ expect(mocks.sendWeeklyDigestEmail).not.toHaveBeenCalled();
+ expect(mocks.sendWeeklyReportEmail).toHaveBeenCalledTimes(1);
+ expect(mocks.sendWeeklyReportEmail.mock.calls[0][0]).toMatchObject({
+ email: "[email protected]",
+ site: { siteId: 1, siteDomain: "site1.com" },
+ });
+ });
+
+ it("sends one digest across every organization instead of one email per site", async () => {
+ state.memberships = [membership("ada", "org_a"), membership("ada", "org_b")];
+ state.activity = [
+ { site_id: 1, current: 50, previous: 40 },
+ { site_id: 2, current: 5, previous: 0 },
+ { site_id: 4, current: 9, previous: 9 },
+ ];
+
+ await weeklyReportService.generateAndSendReports();
+
+ expect(mocks.sendWeeklyReportEmail).not.toHaveBeenCalled();
+ expect(digestRecipients()).toEqual([{ email: "[email protected]", sites: [1, 2, 4] }]);
+ });
+
+ it("lists a site that went quiet next to the busy ones, but never mails about quiet sites alone", async () => {
+ state.memberships = [membership("ada", "org_a"), membership("bob", "org_b")];
+ state.activity = [
+ { site_id: 1, current: 50, previous: 40 },
+ { site_id: 3, current: 0, previous: 30 },
+ { site_id: 4, current: 0, previous: 12 },
+ ];
+
+ await weeklyReportService.generateAndSendReports();
+
+ expect(digestRecipients()).toEqual([{ email: "[email protected]", sites: [1, 3] }]);
+ const quiet = mocks.sendWeeklyDigestEmail.mock.calls[0][0].digest.sites.find(
+ (s: { siteId: number }) => s.siteId === 3
+ );
+ expect(quiet).toMatchObject({ users: 0, lastPageviewAt: "2026-10-11T23:41:00.000Z" });
+ expect(mocks.sendWeeklyReportEmail).not.toHaveBeenCalled();
+ });
+
+ it("only reports on sites a restricted member can open, and skips people who turned reports off", async () => {
+ state.memberships = [
+ membership("ada", "org_a", "member", { hasRestrictedSiteAccess: true }),
+ membership("off", "org_a", "owner", { sendAutoEmailReports: false }),
+ ];
+ state.grants.set("ada", [2]);
+ state.activity = [
+ { site_id: 1, current: 50, previous: 40 },
+ { site_id: 2, current: 5, previous: 3 },
+ ];
+
+ await weeklyReportService.generateAndSendReports();
+
+ expect(mocks.sendWeeklyDigestEmail).not.toHaveBeenCalled();
+ expect(mocks.sendWeeklyReportEmail).toHaveBeenCalledTimes(1);
+ expect(mocks.sendWeeklyReportEmail.mock.calls[0][0]).toMatchObject({
+ email: "[email protected]",
+ site: { siteId: 2 },
+ });
+ });
+
+ it("queries a site shared by several people once per run", async () => {
+ state.memberships = [membership("ada", "org_a"), membership("bob", "org_a", "admin")];
+ state.activity = [
+ { site_id: 1, current: 50, previous: 40 },
+ { site_id: 2, current: 5, previous: 3 },
+ ];
+
+ await weeklyReportService.generateAndSendReports();
+
+ expect(digestRecipients()).toHaveLength(2);
+ // Two overview queries (this week and last) per site, not per recipient.
+ expect(state.overviewQueries.sort()).toEqual([1, 1, 2, 2]);
+ });
+});
diff --git a/server/src/services/weekyReports/weeklyReportService.ts b/server/src/services/weekyReports/weeklyReportService.ts
index 1bb6f150c..c7b0c3198 100644
--- a/server/src/services/weekyReports/weeklyReportService.ts
+++ b/server/src/services/weekyReports/weeklyReportService.ts
@@ -8,7 +8,7 @@ import { clickhouse } from "../../db/clickhouse/clickhouse.js";
import { processResults } from "../../api/analytics/utils/utils.js";
import { getTimeStatement } from "../../api/analytics/utils/timeWindow.js";
import { createServiceLogger } from "../../lib/logger/logger.js";
-import { sendWeeklyReportEmail } from "../../lib/email/email.js";
+import { sendWeeklyDigestEmail, sendWeeklyReportEmail } from "../../lib/email/email.js";
import { filterSitesByMemberAccess } from "../../lib/access.js";
import { IS_CLOUD } from "../../lib/const.js";
import {
@@ -18,9 +18,65 @@ import {
buildOverviewQuery,
SiteMetricsSpec,
} from "../siteMetrics/siteMetrics.js";
-import type { DailySessions, OverviewData, MetricData, SiteReport, OrganizationReport } from "./weeklyReportTypes.js";
+import type { DailySessions, DigestSite, OverviewData, MetricData, SiteReport } from "./weeklyReportTypes.js";
+
+/** The reported week and the one before it, as whole UTC days. */
+interface ReportWindow {
+ currentWeekStart: DateTime;
+ /** Exclusive: midnight after the last reported day. */
+ currentWeekEnd: DateTime;
+ previousWeekStart: DateTime;
+}
+
+/** Pageviews in each week. */
+interface SiteActivity {
+ current: number;
+ previous: number;
+}
+
+interface RecipientSite {
+ siteId: number;
+ name: string;
+ domain: string;
+ organizationId: string;
+ organizationName: string;
+}
-const MAX_SITE_REPORTS_PER_ORG = 10;
+interface Recipient {
+ userId: string;
+ email: string;
+ sites: RecipientSite[];
+}
+
+/** Per-run state, so a site shared by many members is queried once. */
+interface ReportRun {
+ window: ReportWindow;
+ activity: Map<number, SiteActivity>;
+ reports: Map<number, Promise<SiteReport | null>>;
+ digestSites: Map<number, Promise<DigestSite | null>>;
+}
+
+// Format dates for ClickHouse (YYYY-MM-DD HH:mm:ss). The windows are UTC, and
+// getTimeStatement anchors the comparison in UTC too — the bound
+// `toDateTime({date:String})` this replaced was interpreted in the ClickHouse
+// server's timezone, so a non-UTC server shifted the week.
+const formatDate = (date: DateTime) => date.toFormat("yyyy-MM-dd HH:mm:ss");
+
+const specFor = (from: DateTime, to: DateTime): SiteMetricsSpec => ({
+ timeStatement: getTimeStatement({
+ start_datetime: formatDate(from),
+ end_datetime: formatDate(to),
+ }),
+});
+
+const memo = <T>(cache: Map<number, Promise<T>>, key: number, load: () => Promise<T>): Promise<T> => {
+ let value = cache.get(key);
+ if (!value) {
+ value = load();
+ cache.set(key, value);
+ }
+ return value;
+};
class WeeklyReportService {
private cronTask: cron.ScheduledTask | null = null;
@@ -95,34 +151,16 @@ class WeeklyReportService {
}
}
- private async generateSiteReport(siteId: number, siteName: string, siteDomain: string): Promise<SiteReport | null> {
+ private async generateSiteReport(
+ siteId: number,
+ siteName: string,
+ siteDomain: string,
+ window: ReportWindow
+ ): Promise<SiteReport | null> {
try {
- // Whole UTC days, so the report covers exactly Monday to Sunday when the
- // cron fires at Monday midnight and the chart has one bar per day.
- const today = DateTime.utc().startOf("day");
-
- // Calculate current week (the last 7 full days)
- const currentWeekEnd = today;
- const currentWeekStart = today.minus({ days: 7 });
-
- // Calculate previous week (8-14 days ago)
- const previousWeekEnd = currentWeekStart;
- const previousWeekStart = currentWeekStart.minus({ days: 7 });
-
- // Format dates for ClickHouse (YYYY-MM-DD HH:mm:ss). The windows above are
- // UTC, and getTimeStatement anchors the comparison in UTC too — the bound
- // `toDateTime({date:String})` this replaced was interpreted in the
- // ClickHouse server's timezone, so a non-UTC server shifted the week.
- const formatDate = (date: DateTime) => date.toFormat("yyyy-MM-dd HH:mm:ss");
- const specFor = (from: DateTime, to: DateTime): SiteMetricsSpec => ({
- timeStatement: getTimeStatement({
- start_datetime: formatDate(from),
- end_datetime: formatDate(to),
- }),
- });
-
+ const { currentWeekStart, currentWeekEnd, previousWeekStart } = window;
const currentSpec = specFor(currentWeekStart, currentWeekEnd);
- const previousSpec = specFor(previousWeekStart, previousWeekEnd);
+ const previousSpec = specFor(previousWeekStart, currentWeekStart);
const [currentWeek, previousWeek, daily, topCountries, topPages, topReferrers, deviceBreakdown] =
await Promise.all([
@@ -171,122 +209,220 @@ class WeeklyReportService {
}
}
- private async generateOrganizationReport(organizationId: string): Promise<OrganizationReport | null> {
- try {
- // Fetch organization details
- const [org] = await db.select().from(organization).where(eq(organization.id, organizationId));
-
- if (!org) {
- return null;
- }
-
- // Fetch all sites for this organization
- const orgSites = await db.select().from(sites).where(eq(sites.organizationId, org.id));
-
- if (orgSites.length === 0) {
- return null;
- }
-
- const siteReports: SiteReport[] = [];
+ /**
+ * Pageviews per site in each of the two weeks, for every site that had any. One scan
+ * instead of a report query per site: most sites are idle and get no email.
+ */
+ private async fetchSiteActivity(window: ReportWindow): Promise<Map<number, SiteActivity>> {
+ const result = await clickhouse.query({
+ query: `
+ SELECT
+ site_id,
+ countIf(timestamp >= toDateTime({currentStart:String}, 'UTC')) AS current,
+ countIf(timestamp < toDateTime({currentStart:String}, 'UTC')) AS previous
+ FROM events
+ WHERE type = 'pageview'
+ AND timestamp >= toDateTime({previousStart:String}, 'UTC')
+ AND timestamp < toDateTime({end:String}, 'UTC')
+ GROUP BY site_id
+ `,
+ format: "JSONEachRow",
+ query_params: {
+ previousStart: formatDate(window.previousWeekStart),
+ currentStart: formatDate(window.currentWeekStart),
+ end: formatDate(window.currentWeekEnd),
+ },
+ });
+ const rows = await processResults<{ site_id: number; current: number; previous: number }>(result);
+ return new Map(
+ rows.map(row => [Number(row.site_id), { current: Number(row.current), previous: Number(row.previous) }])
+ );
+ }
- for (const site of orgSites) {
- if (siteReports.length >= MAX_SITE_REPORTS_PER_ORG) {
- this.logger.info(
- { organizationId, totalSites: orgSites.length, limit: MAX_SITE_REPORTS_PER_ORG },
- "Reached site report limit for organization, skipping remaining sites"
- );
- break;
- }
+ private async fetchLastPageviewAt(siteId: number, since: DateTime): Promise<string | null> {
+ const result = await clickhouse.query({
+ query: `
+ SELECT max(timestamp) AS last
+ FROM events
+ WHERE site_id = {siteId:Int32}
+ AND type = 'pageview'
+ AND timestamp >= toDateTime({since:String}, 'UTC')
+ `,
+ format: "JSONEachRow",
+ query_params: { siteId, since: formatDate(since) },
+ });
+ const [row] = await processResults<{ last: string }>(result);
+ const last = row?.last ? DateTime.fromSQL(row.last, { zone: "utc" }) : null;
+ return last?.isValid ? last.toISO() : null;
+ }
- const report = await this.generateSiteReport(site.siteId, site.name, site.domain);
- if (report) {
- siteReports.push(report);
- }
- }
+ /** A site's line in the digest: visitors in both weeks and sessions per day. */
+ private async generateDigestSite(
+ site: RecipientSite,
+ activity: SiteActivity,
+ window: ReportWindow
+ ): Promise<DigestSite | null> {
+ try {
+ const { currentWeekStart, currentWeekEnd, previousWeekStart } = window;
+ const quiet = activity.current === 0;
+ const currentSpec = specFor(currentWeekStart, currentWeekEnd);
- if (siteReports.length === 0) {
+ const [currentWeek, previousWeek, daily, lastPageviewAt] = await Promise.all([
+ quiet ? null : this.fetchOverviewData(site.siteId, currentSpec),
+ activity.previous > 0
+ ? this.fetchOverviewData(site.siteId, specFor(previousWeekStart, currentWeekStart))
+ : null,
+ quiet ? [] : this.fetchDailySessions(site.siteId, currentSpec, currentWeekStart),
+ quiet ? this.fetchLastPageviewAt(site.siteId, previousWeekStart) : null,
+ ]);
+
+ // A failed query would show a busy site as empty; leave it out instead.
+ if ((!quiet && !currentWeek) || (activity.previous > 0 && !previousWeek) || (quiet && !lastPageviewAt)) {
return null;
}
return {
- organizationId: org.id,
- organizationName: org.name,
- sites: siteReports,
+ siteId: site.siteId,
+ siteDomain: site.domain,
+ organizationId: site.organizationId,
+ organizationName: site.organizationName,
+ users: currentWeek?.users ?? 0,
+ previousUsers: previousWeek?.users ?? 0,
+ daily: quiet ? Array(7).fill(0) : daily.map(day => day.sessions),
+ lastPageviewAt: quiet ? lastPageviewAt : null,
};
} catch (error) {
- this.logger.error({ err: error, organizationId }, "Error generating organization report");
+ this.logger.error({ err: error, siteId: site.siteId }, "Error generating digest line for site");
return null;
}
}
- private async sendReportsToOrganization(report: OrganizationReport): Promise<void> {
- try {
- // Fetch all members of the organization with their access restrictions
- const members = await db
+ /**
+ * Everyone who gets weekly reports, with the sites they can open that had pageviews in
+ * either week. A member only hears about sites their role or site grants reach.
+ */
+ private async loadRecipients(activity: Map<number, SiteActivity>): Promise<Recipient[]> {
+ const [memberships, organizations, siteRows] = await Promise.all([
+ db
.select({
memberId: member.id,
userId: member.userId,
role: member.role,
+ organizationId: member.organizationId,
+ hasRestrictedSiteAccess: member.hasRestrictedSiteAccess,
email: user.email,
- name: user.name,
sendAutoEmailReports: user.sendAutoEmailReports,
- hasRestrictedSiteAccess: member.hasRestrictedSiteAccess,
})
.from(member)
- .innerJoin(user, eq(member.userId, user.id))
- .where(eq(member.organizationId, report.organizationId));
-
- // Send a separate email for each site to each member
- for (const memberData of members) {
- // Skip users who have disabled email reports
- if (memberData.sendAutoEmailReports === false) {
- continue;
- }
+ .innerJoin(user, eq(member.userId, user.id)),
+ db.select({ id: organization.id, name: organization.name }).from(organization),
+ db
+ .select({ siteId: sites.siteId, name: sites.name, domain: sites.domain, organizationId: sites.organizationId })
+ .from(sites),
+ ]);
+
+ const organizationNames = new Map(organizations.map(org => [org.id, org.name]));
+ const activeSitesByOrg = new Map<string, RecipientSite[]>();
+ for (const site of siteRows) {
+ if (!site.organizationId || !activity.has(site.siteId)) continue;
+ const orgSites = activeSitesByOrg.get(site.organizationId) ?? [];
+ orgSites.push({
+ siteId: site.siteId,
+ name: site.name,
+ domain: site.domain,
+ organizationId: site.organizationId,
+ organizationName: organizationNames.get(site.organizationId) ?? "",
+ });
+ activeSitesByOrg.set(site.organizationId, orgSites);
+ }
- // A membership whose role isn't one Rybbit knows reaches nothing
- // (the same rule the request-time resolver applies).
- if (!isOrgRole(memberData.role)) {
- continue;
- }
+ const recipients = new Map<string, Recipient>();
+ for (const membership of memberships) {
+ // Skip users who have disabled email reports
+ if (membership.sendAutoEmailReports === false) continue;
+ // A membership whose role isn't one Rybbit knows reaches nothing
+ // (the same rule the request-time resolver applies).
+ if (!isOrgRole(membership.role)) continue;
- // Only report on sites the member can actually access
- let allowedSites = report.sites;
- if (!isAdminRole(memberData.role)) {
- allowedSites = await filterSitesByMemberAccess(
- report.sites,
- report.organizationId,
- memberData.userId,
- memberData.memberId,
- memberData.hasRestrictedSiteAccess
- );
-
- // Skip this member entirely if they have no site access
- if (allowedSites.length === 0) {
- continue;
- }
- }
+ const orgSites = activeSitesByOrg.get(membership.organizationId);
+ if (!orgSites) continue;
- for (const site of allowedSites) {
- try {
- await sendWeeklyReportEmail({ email: memberData.email, userId: memberData.userId, site });
- this.logger.info(
- {
- organizationId: report.organizationId,
- siteId: site.siteId,
- },
- "Sent weekly report email for site"
- );
- } catch (error) {
- this.logger.error(
- { err: error, organizationId: report.organizationId, siteId: site.siteId },
- "Failed to send email to member for site"
+ try {
+ // Only report on sites the member can actually access
+ const allowedSites = isAdminRole(membership.role)
+ ? orgSites
+ : await filterSitesByMemberAccess(
+ orgSites,
+ membership.organizationId,
+ membership.userId,
+ membership.memberId,
+ membership.hasRestrictedSiteAccess
);
- }
- }
+ if (allowedSites.length === 0) continue;
+
+ const recipient = recipients.get(membership.userId) ?? {
+ userId: membership.userId,
+ email: membership.email,
+ sites: [],
+ };
+ recipient.sites.push(...allowedSites);
+ recipients.set(membership.userId, recipient);
+ } catch (error) {
+ this.logger.error(
+ { err: error, userId: membership.userId, organizationId: membership.organizationId },
+ "Error resolving member site access for weekly report"
+ );
}
- } catch (error) {
- this.logger.error({ err: error, organizationId: report.organizationId }, "Error sending reports to organization");
}
+ return [...recipients.values()];
+ }
+
+ /**
+ * One email per person: the full report when they have one site with traffic, a digest of
+ * every site otherwise. Returns whether an email went out.
+ */
+ private async sendToRecipient(recipient: Recipient, run: ReportRun): Promise<boolean> {
+ const active = recipient.sites.filter(site => run.activity.get(site.siteId)!.current > 0);
+ if (active.length === 0) {
+ return false;
+ }
+
+ let digestSites: DigestSite[] = [];
+ if (recipient.sites.length > 1) {
+ for (const site of recipient.sites) {
+ const line = await memo(run.digestSites, site.siteId, () =>
+ this.generateDigestSite(site, run.activity.get(site.siteId)!, run.window)
+ );
+ if (line) digestSites.push(line);
+ }
+ digestSites = digestSites.sort((a, b) => b.users - a.users || a.siteDomain.localeCompare(b.siteDomain));
+ }
+
+ if (digestSites.length > 1 && digestSites.some(site => site.lastPageviewAt === null)) {
+ await sendWeeklyDigestEmail({
+ email: recipient.email,
+ userId: recipient.userId,
+ digest: {
+ weekStart: run.window.currentWeekStart.toISODate()!,
+ weekEnd: run.window.currentWeekEnd.minus({ days: 1 }).toISODate()!,
+ sites: digestSites,
+ },
+ });
+ this.logger.info({ userId: recipient.userId, sites: digestSites.length }, "Sent weekly digest email");
+ return true;
+ }
+
+ // One site with traffic (or the digest lines failed): the full report for the busiest.
+ const [site] = active.sort((x, y) => run.activity.get(y.siteId)!.current - run.activity.get(x.siteId)!.current);
+ const report = await memo(run.reports, site.siteId, () =>
+ this.generateSiteReport(site.siteId, site.name, site.domain, run.window)
+ );
+ if (!report) {
+ return false;
+ }
+ await sendWeeklyReportEmail({ email: recipient.email, userId: recipient.userId, site: report });
+ this.logger.info({ userId: recipient.userId, siteId: site.siteId }, "Sent weekly report email for site");
+ return true;
}
public async generateAndSendReports(): Promise<void> {
@@ -298,40 +434,35 @@ class WeeklyReportService {
this.logger.info("Starting weekly report generation and sending");
try {
- // Fetch all organizations
- const organizations = await db.select().from(organization);
- const totalOrgs = organizations.length;
+ // Whole UTC days, so the report covers exactly Monday to Sunday when the cron fires at
+ // Monday midnight. Every email in the run shares the same window.
+ const today = DateTime.utc().startOf("day");
+ const window: ReportWindow = {
+ currentWeekStart: today.minus({ days: 7 }),
+ currentWeekEnd: today,
+ previousWeekStart: today.minus({ days: 14 }),
+ };
+ const activity = await this.fetchSiteActivity(window);
+ const recipients = await this.loadRecipients(activity);
+ const run: ReportRun = { window, activity, reports: new Map(), digestSites: new Map() };
- this.logger.info({ totalOrganizations: totalOrgs }, "Processing organizations");
+ this.logger.info({ activeSites: activity.size, recipients: recipients.length }, "Sending weekly reports");
- let processedCount = 0;
let sentCount = 0;
-
- for (let i = 0; i < organizations.length; i++) {
- const org = organizations[i];
-
- // Generate report for this organization
- const report = await this.generateOrganizationReport(org.id);
-
- if (report) {
- // Send reports immediately after generation
- await this.sendReportsToOrganization(report);
- sentCount++;
+ for (const [i, recipient] of recipients.entries()) {
+ try {
+ if (await this.sendToRecipient(recipient, run)) sentCount++;
+ } catch (error) {
+ this.logger.error({ err: error, userId: recipient.userId }, "Failed to send weekly report email");
}
- processedCount++;
-
- // Log progress every 10 organizations
- if (processedCount % 10 === 0 || processedCount === totalOrgs) {
- this.logger.info(
- { processed: processedCount, total: totalOrgs, sent: sentCount },
- `Progress: ${processedCount}/${totalOrgs} organizations processed, ${sentCount} reports sent`
- );
+ if ((i + 1) % 50 === 0) {
+ this.logger.info({ processed: i + 1, total: recipients.length, sent: sentCount }, "Weekly report progress");
}
}
this.logger.info(
- { totalProcessed: processedCount, totalSent: sentCount },
+ { totalRecipients: recipients.length, totalSent: sentCount },
"Completed weekly report generation and sending"
);
} catch (error) {
diff --git a/server/src/services/weekyReports/weeklyReportTypes.ts b/server/src/services/weekyReports/weeklyReportTypes.ts
index 1571f1032..986ac5132 100644
--- a/server/src/services/weekyReports/weeklyReportTypes.ts
+++ b/server/src/services/weekyReports/weeklyReportTypes.ts
@@ -29,8 +29,24 @@ export interface SiteReport {
deviceBreakdown: MetricData[];
}
-export interface OrganizationReport {
+/** One site's line in the weekly digest. */
+export interface DigestSite {
+ siteId: number;
+ siteDomain: string;
organizationId: string;
organizationName: string;
- sites: SiteReport[];
+ users: number;
+ previousUsers: number;
+ /** Sessions per UTC day of the reported week, first day first. */
+ daily: number[];
+ /** Set when the site had pageviews the week before but none last week: its last pageview. */
+ lastPageviewAt: string | null;
+}
+
+/** Everyone with more than one site gets one email for all of them instead of one per site. */
+export interface WeeklyDigest {
+ /** ISO dates (UTC): the first and last day of the reported week. */
+ weekStart: string;
+ weekEnd: string;
+ sites: DigestSite[];
}