feat(reports): weekly/monthly performance email digest (on by default)

Adds a per-user setting for receiving a combined audit + Autoblog
performance digest by email. Three cadences (off / weekly / monthly),
defaulting to weekly. Sent on Monday 09:00 (weekly) or 1st-of-month
09:00 (monthly) in the user's chosen IANA timezone.

Schema: profiles.perf_report_cadence + .timezone + .perf_report_last_sent_at.
Existing users are grandfathered onto weekly by the column default.

Cron: hourly tick at /api/cron/perf-reports walks profiles where
cadence <> 'off' and checks isReportDue(cadence, tz, now, last_sent)
— only users whose local 09:00 matches the current top-of-hour are
eligible, which naturally spreads load across the day. Capped at 50
sends per tick.

Aggregation: per-project latest score + score delta vs window-start,
audits-in-window count; plus Autoblog summary (published, failed,
queued, next publish) when the user has a site enrolled.

Manual trigger: crawlproof sweep --target=perf-reports.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ralyodio

app/(app)/settings/form.tsx

@@ -3,27 +3,47 @@
 import { useState, useTransition } from "react";
 import { saveSettings } from "@/app/actions/settings";
 
+type Cadence = "off" | "weekly" | "monthly";
+
 export function SettingsForm({
   displayName,
   retainRawHtml,
+  perfReportCadence,
+  timezone,
+  commonTimezones,
+  allTimezones,
 }: {
   displayName: string;
   retainRawHtml: boolean;
+  perfReportCadence: Cadence;
+  timezone: string;
+  commonTimezones: string[];
+  allTimezones: string[];
 }) {
   const [name, setName] = useState(displayName);
   const [retain, setRetain] = useState(retainRawHtml);
+  const [cadence, setCadence] = useState<Cadence>(perfReportCadence);
+  const [tz, setTz] = useState(timezone);
   const [saved, setSaved] = useState(false);
+  const [error, setError] = useState<string | null>(null);
   const [pending, start] = useTransition();
 
   return (
     <form
-      className="card space-y-4 p-5"
+      className="card space-y-5 p-5"
       onSubmit={(e) => {
         e.preventDefault();
         setSaved(false);
+        setError(null);
         start(async () => {
-          await saveSettings({ displayName: name, retainRawHtml: retain });
-          setSaved(true);
+          const r = await saveSettings({
+            displayName: name,
+            retainRawHtml: retain,
+            perfReportCadence: cadence,
+            timezone: tz,
+          });
+          if (r.ok) setSaved(true);
+          else setError(r.error ?? "Could not save.");
         });
       }}
     >
@@ -35,6 +55,7 @@ export function SettingsForm({
           onChange={(e) => setName(e.target.value)}
         />
       </div>
+
       <label className="flex items-center gap-2 text-sm">
         <input
           type="checkbox"
@@ -43,7 +64,58 @@ export function SettingsForm({
         />
         Retain raw HTML from audits (uncheck to keep only structured findings)
       </label>
+
+      <fieldset className="space-y-3 border-t border-[var(--color-border)] pt-4">
+        <legend className="text-sm font-semibold">Email reports</legend>
+        <p className="text-xs text-[var(--color-muted)]">
+          A combined digest of your audit scores and Autoblog activity.
+          Sent on Monday 09:00 (weekly) or the 1st of the month at 09:00
+          (monthly), in the timezone below.
+        </p>
+
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+          <div>
+            <label className="block text-sm font-medium">Cadence</label>
+            <select
+              className="input mt-1"
+              value={cadence}
+              onChange={(e) => setCadence(e.target.value as Cadence)}
+            >
+              <option value="off">Off — no email reports</option>
+              <option value="weekly">Weekly</option>
+              <option value="monthly">Monthly</option>
+            </select>
+          </div>
+
+          <div>
+            <label className="block text-sm font-medium">Timezone</label>
+            <select
+              className="input mt-1"
+              value={tz}
+              onChange={(e) => setTz(e.target.value)}
+              disabled={cadence === "off"}
+            >
+              <optgroup label="Common">
+                {commonTimezones.map((z) => (
+                  <option key={z} value={z}>
+                    {z}
+                  </option>
+                ))}
+              </optgroup>
+              <optgroup label="All">
+                {allTimezones.map((z) => (
+                  <option key={z} value={z}>
+                    {z}
+                  </option>
+                ))}
+              </optgroup>
+            </select>
+          </div>
+        </div>
+      </fieldset>
+
       {saved && <p className="text-sm text-[var(--color-pass)]">Saved.</p>}
+      {error && <p className="text-sm text-[var(--color-fail)]">{error}</p>}
       <button type="submit" className="btn btn-primary" disabled={pending}>
         {pending ? "Saving…" : "Save"}
       </button>

app/(app)/settings/page.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 import { createClient } from "@/lib/supabase/server";
 import { SettingsForm } from "./form";
+import { listTimezones } from "@/lib/timezones";
 
 export const metadata = { title: "Settings" };
 
@@ -11,9 +12,12 @@ export default async function SettingsPage() {
   } = await supabase.auth.getUser();
   const { data: profile } = await supabase
     .from("profiles")
-    .select("display_name, email, credits_balance, retain_raw_html")
+    .select(
+      "display_name, email, credits_balance, retain_raw_html, perf_report_cadence, timezone",
+    )
     .eq("id", user!.id)
     .maybeSingle();
+  const { common, all } = listTimezones();
 
   return (
     <div className="space-y-6">
@@ -32,6 +36,15 @@ export default async function SettingsPage() {
       <SettingsForm
         displayName={profile?.display_name ?? ""}
         retainRawHtml={!!profile?.retain_raw_html}
+        perfReportCadence={
+          (profile?.perf_report_cadence ?? "weekly") as
+            | "off"
+            | "weekly"
+            | "monthly"
+        }
+        timezone={profile?.timezone ?? "UTC"}
+        commonTimezones={common}
+        allTimezones={all}
       />
     </div>
   );

app/actions/settings.ts

@@ -1,19 +1,38 @@
 "use server";
 
 import { createClient } from "@/lib/supabase/server";
+import { isValidTimezone } from "@/lib/timezones";
+
+const ALLOWED_CADENCES = ["off", "weekly", "monthly"] as const;
+type Cadence = (typeof ALLOWED_CADENCES)[number];
 
 export async function saveSettings(input: {
   displayName: string;
   retainRawHtml: boolean;
-}): Promise<{ ok: boolean }> {
+  perfReportCadence: Cadence;
+  timezone: string;
+}): Promise<{ ok: boolean; error?: string }> {
   const supabase = await createClient();
   const {
     data: { user },
   } = await supabase.auth.getUser();
-  if (!user) return { ok: false };
+  if (!user) return { ok: false, error: "unauthorized" };
+
+  if (!ALLOWED_CADENCES.includes(input.perfReportCadence)) {
+    return { ok: false, error: "invalid cadence" };
+  }
+  if (!isValidTimezone(input.timezone)) {
+    return { ok: false, error: "invalid timezone" };
+  }
+
   const { error } = await supabase
     .from("profiles")
-    .update({ display_name: input.displayName, retain_raw_html: input.retainRawHtml })
+    .update({
+      display_name: input.displayName,
+      retain_raw_html: input.retainRawHtml,
+      perf_report_cadence: input.perfReportCadence,
+      timezone: input.timezone,
+    })
     .eq("id", user.id);
-  return { ok: !error };
+  return error ? { ok: false, error: error.message } : { ok: true };
 }

app/api/cron/perf-reports/route.ts

@@ -0,0 +1,116 @@
+import { NextResponse } from "next/server";
+import { serviceClient } from "@/lib/supabase/service";
+import { env } from "@/lib/env";
+import {
+  aggregatePerfReport,
+  isReportDue,
+  sendPerfReportEmail,
+  type Cadence,
+} from "@/lib/perfReport";
+
+export const runtime = "nodejs";
+
+// Bound per-tick send count so a slow Resend response can't tie up the
+// request past the cron's expectation. Most ticks send 0 messages
+// (only the user's local Mon 09:00 / 1st 09:00 tick is eligible).
+const MAX_PER_TICK = 50;
+
+type ProfileRow = {
+  id: string;
+  email: string;
+  perf_report_cadence: "off" | "weekly" | "monthly";
+  timezone: string;
+  perf_report_last_sent_at: string | null;
+};
+
+export async function GET(req: Request) {
+  return POST(req);
+}
+
+export async function POST(req: Request) {
+  const incoming =
+    req.headers.get("x-cron-secret") ??
+    req.headers.get("authorization")?.replace(/^Bearer\s+/i, "");
+  if (incoming !== env.cronSecret) {
+    return NextResponse.json({ ok: false, error: "unauthorized" }, { status: 401 });
+  }
+
+  const svc = serviceClient();
+  const now = new Date();
+
+  const { data: rows, error } = await svc
+    .from("profiles")
+    .select(
+      "id, email, perf_report_cadence, timezone, perf_report_last_sent_at",
+    )
+    .neq("perf_report_cadence", "off")
+    .not("email", "is", null)
+    .limit(1000);
+  if (error) {
+    return NextResponse.json(
+      { ok: false, error: error.message },
+      { status: 500 },
+    );
+  }
+
+  let sent = 0;
+  let skipped_not_due = 0;
+  let failed = 0;
+  for (const r of (rows ?? []) as ProfileRow[]) {
+    if (sent >= MAX_PER_TICK) break;
+
+    const lastSentAt = r.perf_report_last_sent_at
+      ? new Date(r.perf_report_last_sent_at)
+      : null;
+    const due = isReportDue(
+      r.perf_report_cadence as Cadence,
+      r.timezone ?? "UTC",
+      now,
+      lastSentAt,
+    );
+    if (!due) {
+      skipped_not_due++;
+      continue;
+    }
+
+    try {
+      const report = await aggregatePerfReport(
+        svc,
+        r.id,
+        r.perf_report_cadence as Cadence,
+        now,
+      );
+      if (!report) {
+        skipped_not_due++;
+        continue;
+      }
+      const result = await sendPerfReportEmail(r.email, report);
+      if (!result.ok) {
+        failed++;
+        console.warn(`[perf-reports] send failed user=${r.id}: ${result.error}`);
+        continue;
+      }
+      // Claim AFTER successful send so a failure leaves us eligible to
+      // retry on the next hourly tick (which only re-eligibilizes if
+      // the user's local 09:00 falls again, i.e. typically next week).
+      // For weekly that's the right behavior; a one-tick miss just
+      // skips this week.
+      await svc
+        .from("profiles")
+        .update({ perf_report_last_sent_at: now.toISOString() })
+        .eq("id", r.id);
+      sent++;
+    } catch (err) {
+      failed++;
+      console.error(`[perf-reports] crashed user=${r.id}`, err);
+    }
+  }
+
+  return NextResponse.json({
+    ok: true,
+    candidates: rows?.length ?? 0,
+    sent,
+    skipped_not_due,
+    failed,
+  });
+}

cli/index.ts

@@ -111,9 +111,16 @@ async function cmdSweep(args: Args): Promise<number> {
     return 2;
   }
   const target = (args.flags.target as string | undefined) ?? "scheduled-audits";
-  const path = target === "autoblog" ? "lx-autoblog" : "scheduled-audits";
-  if (target !== "autoblog" && target !== "scheduled-audits") {
-    console.error(`unknown --target: ${target} (expected: scheduled-audits | autoblog)`);
+  const ALLOWED: Record<string, string> = {
+    "scheduled-audits": "scheduled-audits",
+    "autoblog": "lx-autoblog",
+    "perf-reports": "perf-reports",
+  };
+  const path = ALLOWED[target];
+  if (!path) {
+    console.error(
+      `unknown --target: ${target} (expected: scheduled-audits | autoblog | perf-reports)`,
+    );
     return 2;
   }
   const base = process.env.CRAWLPROOF_SITE_URL ?? "https://crawlproof.com";
@@ -150,10 +157,11 @@ COMMANDS
       Fetch a public report by share-token from production.
       Override with CRAWLPROOF_SITE_URL.
 
-  sweep [--target=scheduled-audits|autoblog]
+  sweep [--target=scheduled-audits|autoblog|perf-reports]
       Force a cron sweep to run now. --target=scheduled-audits (default)
       fires /api/cron/scheduled-audits; --target=autoblog fires
-      /api/cron/lx-autoblog. Useful for testing without waiting for the
+      /api/cron/lx-autoblog; --target=perf-reports fires
+      /api/cron/perf-reports. Useful for testing without waiting for the
       hourly pg_cron tick. Requires CRON_SECRET. Override host with
       CRAWLPROOF_SITE_URL.