feat: add lead-to-approved campaign cycle-time benchmark

0xNyk · 0xNyk · commit 65c55afe88ac · 2026-03-05T19:27:43.000+07:00
diff --git a/src/app/api/benchmarks/cycle-time/route.ts b/src/app/api/benchmarks/cycle-time/route.ts
@@ -0,0 +1,116 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { requireApiUser } from '@/lib/api-auth';
+import { getDb } from '@/lib/db';
+import { clampDays } from '@/lib/analytics';
+import { summarizeCycleTimes, percentImprovement } from '@/lib/benchmarks';
+import { maybeSeedExclude } from '@/lib/seed-filter';
+
+export const dynamic = 'force-dynamic';
+
+type CycleTimeRow = {
+  cycle_hours: number;
+};
+
+function parseLaunchDate(raw: string | null | undefined): Date | null {
+  if (!raw) return null;
+  const d = new Date(raw);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+function toIsoOrNull(date: Date | null): string | null {
+  return date ? date.toISOString() : null;
+}
+
+function queryCycleTimes(
+  request: Request,
+  startIso: string,
+  endIso: string,
+): number[] {
+  const db = getDb();
+  const leadSeedFilter = maybeSeedExclude(request, 'leads', 'l.id');
+  const seqSeedFilter = maybeSeedExclude(request, 'sequences', 's.id');
+  const rows = db.prepare(
+    `
+      SELECT ((julianday(MIN(s.created_at)) - julianday(l.created_at)) * 24.0) AS cycle_hours
+      FROM leads l
+      JOIN sequences s ON s.lead_id = l.id
+      WHERE s.status IN ('approved', 'queued')
+        AND julianday(l.created_at) >= julianday(?)
+        AND julianday(l.created_at) < julianday(?)
+        ${leadSeedFilter}
+        ${seqSeedFilter}
+      GROUP BY l.id, l.created_at
+    `,
+  ).all(startIso, endIso) as CycleTimeRow[];
+
+  return rows
+    .map((r) => Number(r.cycle_hours))
+    .filter((h) => Number.isFinite(h) && h >= 0);
+}
+
+export async function GET(req: NextRequest) {
+  const auth = requireApiUser(req as Request);
+  if (auth) return auth;
+
+  const days = clampDays(req.nextUrl.searchParams.get('days'), 30);
+  const now = new Date();
+  const launchAt = parseLaunchDate(
+    req.nextUrl.searchParams.get('launch_at') || process.env.HERMES_BENCHMARK_HERMES_LAUNCH_AT,
+  );
+
+  let beforeStart: Date;
+  let beforeEnd: Date;
+  let afterStart: Date;
+  let afterEnd: Date;
+  let baselineMode: 'rolling_window' | 'launch_anchored';
+
+  if (launchAt) {
+    baselineMode = 'launch_anchored';
+    const dMs = days * 24 * 60 * 60 * 1000;
+    beforeEnd = new Date(launchAt.getTime());
+    beforeStart = new Date(launchAt.getTime() - dMs);
+    afterStart = new Date(launchAt.getTime());
+    const launchPlusWindow = new Date(launchAt.getTime() + dMs);
+    afterEnd = launchPlusWindow.getTime() < now.getTime() ? launchPlusWindow : now;
+  } else {
+    baselineMode = 'rolling_window';
+    const dMs = days * 24 * 60 * 60 * 1000;
+    afterEnd = new Date(now.getTime());
+    afterStart = new Date(now.getTime() - dMs);
+    beforeEnd = new Date(afterStart.getTime());
+    beforeStart = new Date(afterStart.getTime() - dMs);
+  }
+
+  const beforeValues = queryCycleTimes(req as Request, beforeStart.toISOString(), beforeEnd.toISOString());
+  const afterValues = queryCycleTimes(req as Request, afterStart.toISOString(), afterEnd.toISOString());
+
+  const beforeStats = summarizeCycleTimes(beforeValues.map((cycleHours) => ({ cycleHours })));
+  const afterStats = summarizeCycleTimes(afterValues.map((cycleHours) => ({ cycleHours })));
+
+  const medianDeltaPct = percentImprovement(beforeStats.medianHours, afterStats.medianHours);
+  const p90DeltaPct = percentImprovement(beforeStats.p90Hours, afterStats.p90Hours);
+
+  return NextResponse.json({
+    metric: 'lead_to_approved_campaign_cycle_time_hours',
+    days,
+    baseline_mode: baselineMode,
+    window: {
+      before: { start: beforeStart.toISOString(), end: beforeEnd.toISOString() },
+      after: { start: afterStart.toISOString(), end: afterEnd.toISOString() },
+      now: now.toISOString(),
+      launch_at: toIsoOrNull(launchAt),
+    },
+    before: beforeStats,
+    after: afterStats,
+    delta: {
+      median_pct: medianDeltaPct,
+      p90_pct: p90DeltaPct,
+    },
+    inclusion_rules: [
+      'Lead cohort is based on lead.created_at within each window.',
+      "Cycle time is MIN(sequence.created_at where sequence.status in ['approved','queued']) - lead.created_at.",
+      'Only non-negative cycle times are counted.',
+      'real=true excludes seeded records.',
+    ],
+  });
+}
diff --git a/src/app/page.tsx b/src/app/page.tsx
@@ -61,6 +61,21 @@ interface OverviewData {
 
 type Role = 'admin' | 'editor' | 'viewer';
 
+interface CycleTimeBenchmarkPayload {
+  metric: string;
+  days: number;
+  baseline_mode: 'rolling_window' | 'launch_anchored';
+  window: {
+    before: { start: string; end: string };
+    after: { start: string; end: string };
+    now: string;
+    launch_at: string | null;
+  };
+  before: { n: number; medianHours: number | null; p90Hours: number | null };
+  after: { n: number; medianHours: number | null; p90Hours: number | null };
+  delta: { median_pct: number | null; p90_pct: number | null };
+}
+
 export default function OverviewPage() {
   const { realOnly } = useDashboard();
   const realParam = realOnly ? '?real=true' : '';
@@ -77,6 +92,11 @@ export default function OverviewPage() {
     { interval: 60_000 },
   );
 
+  const { data: cycleBenchmark } = useSmartPoll<CycleTimeBenchmarkPayload>(
+    () => fetch(`/api/benchmarks/cycle-time?days=30${realOnly ? '&real=true' : ''}`).then(r => r.json()),
+    { interval: 300_000, key: `cycle-${realOnly}` },
+  );
+
   useEffect(() => {
     fetch('/api/auth/me')
       .then((r) => r.json())
@@ -248,6 +268,8 @@ export default function OverviewPage() {
         />
       </div>
 
+      <CycleTimeBenchmarkPanel data={cycleBenchmark || undefined} />
+
       {/* Charts */}
       <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
         <div className="panel">
@@ -382,6 +404,64 @@ function BudgetBar({ label, used, limit, icon }: { label: string; used: number;
   );
 }
 
+function formatHours(value: number | null): string {
+  if (value === null || !Number.isFinite(value)) return '—';
+  if (value < 1) return `${Math.round(value * 60)}m`;
+  return `${value.toFixed(1)}h`;
+}
+
+function formatDelta(deltaPct: number | null): string {
+  if (deltaPct === null || !Number.isFinite(deltaPct)) return '—';
+  const rounded = Math.round(deltaPct * 10) / 10;
+  const prefix = rounded > 0 ? '+' : '';
+  return `${prefix}${rounded}%`;
+}
+
+function CycleTimeBenchmarkPanel({ data }: { data?: CycleTimeBenchmarkPayload }) {
+  if (!data) return null;
+  const improveCls = (data.delta.median_pct ?? -1) >= 0 ? 'text-success' : 'text-warning';
+
+  return (
+    <div className="panel">
+      <div className="panel-header flex items-center justify-between">
+        <h3 className="section-title">Lead → Approved Campaign Cycle Time</h3>
+        <span className="text-[10px] text-muted-foreground font-mono">
+          {data.baseline_mode === 'launch_anchored' ? 'launch anchored' : `rolling ${data.days}d`}
+        </span>
+      </div>
+      <div className="panel-body space-y-4">
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-3">
+          <div className="card p-4">
+            <div className="text-xs text-muted-foreground">Before median</div>
+            <div className="text-lg font-mono font-semibold mt-1">{formatHours(data.before.medianHours)}</div>
+          </div>
+          <div className="card p-4">
+            <div className="text-xs text-muted-foreground">After median</div>
+            <div className="text-lg font-mono font-semibold mt-1">{formatHours(data.after.medianHours)}</div>
+          </div>
+          <div className="card p-4">
+            <div className="text-xs text-muted-foreground">Before p90</div>
+            <div className="text-lg font-mono font-semibold mt-1">{formatHours(data.before.p90Hours)}</div>
+          </div>
+          <div className="card p-4">
+            <div className="text-xs text-muted-foreground">After p90</div>
+            <div className="text-lg font-mono font-semibold mt-1">{formatHours(data.after.p90Hours)}</div>
+          </div>
+        </div>
+
+        <div className="card p-4 text-sm flex flex-wrap items-center justify-between gap-2">
+          <div className="text-muted-foreground">
+            n before <span className="font-mono text-foreground">{data.before.n}</span> · n after <span className="font-mono text-foreground">{data.after.n}</span>
+          </div>
+          <div className={`font-mono ${improveCls}`}>
+            median {formatDelta(data.delta.median_pct)} · p90 {formatDelta(data.delta.p90_pct)}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
 function ActionItemCard({ item, onAction, canEdit }: { item: ActionItem; onAction: () => void; canEdit: boolean }) {
   const [acting, setActing] = useState<string | null>(null);
 
diff --git a/src/lib/benchmarks.test.ts b/src/lib/benchmarks.test.ts
@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { percentImprovement, percentile, summarizeCycleTimes } from './benchmarks';
+
+test('percentile returns null for empty and correct values for p50/p90', () => {
+  assert.equal(percentile([], 50), null);
+  assert.equal(percentile([10, 20, 30, 40], 50), 20);
+  assert.equal(percentile([10, 20, 30, 40], 90), 40);
+});
+
+test('summarizeCycleTimes computes n, median and p90', () => {
+  const stats = summarizeCycleTimes([
+    { cycleHours: 10 },
+    { cycleHours: 2 },
+    { cycleHours: 18 },
+    { cycleHours: 4 },
+    { cycleHours: 36 },
+  ]);
+  assert.equal(stats.n, 5);
+  assert.equal(stats.medianHours, 10);
+  assert.equal(stats.p90Hours, 36);
+});
+
+test('percentImprovement returns null on invalid baseline and percent otherwise', () => {
+  assert.equal(percentImprovement(null, 10), null);
+  assert.equal(percentImprovement(0, 10), null);
+  assert.equal(Math.round((percentImprovement(20, 10) || 0) * 100) / 100, 50);
+});
diff --git a/src/lib/benchmarks.ts b/src/lib/benchmarks.ts
@@ -0,0 +1,33 @@
+export interface CycleTimeSample {
+  cycleHours: number;
+}
+
+export interface CycleTimeStats {
+  n: number;
+  medianHours: number | null;
+  p90Hours: number | null;
+}
+
+export function percentile(values: number[], p: number): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+  return sorted[rank];
+}
+
+export function summarizeCycleTimes(samples: CycleTimeSample[]): CycleTimeStats {
+  const values = samples
+    .map((s) => s.cycleHours)
+    .filter((v) => Number.isFinite(v) && v >= 0);
+  return {
+    n: values.length,
+    medianHours: percentile(values, 50),
+    p90Hours: percentile(values, 90),
+  };
+}
+
+export function percentImprovement(before: number | null, after: number | null): number | null {
+  if (before === null || after === null) return null;
+  if (!Number.isFinite(before) || !Number.isFinite(after) || before <= 0) return null;
+  return ((before - after) / before) * 100;
+}
diff --git a/tests/e2e/auth-and-api.spec.ts b/tests/e2e/auth-and-api.spec.ts
@@ -90,4 +90,16 @@ test.describe('auth and api gate', () => {
     expect(Array.isArray(payload.tables)).toBeTruthy();
     expect(typeof payload.db_size_mb).toBe('number');
   });
+
+  test('cycle-time benchmark api returns before/after deltas after login', async ({ request }) => {
+    const headers = await getAuthHeaders(request);
+    const res = await request.get('/api/benchmarks/cycle-time?days=30', { headers });
+    expect(res.status()).toBe(200);
+    const payload = await res.json();
+    expect(payload.metric).toBe('lead_to_approved_campaign_cycle_time_hours');
+    expect(payload).toHaveProperty('before');
+    expect(payload).toHaveProperty('after');
+    expect(payload).toHaveProperty('delta');
+    expect(Array.isArray(payload.inclusion_rules)).toBeTruthy();
+  });
 });
