Comprehensive admin + user dashboards (production-ready)

app/api/episodes/[id]/export/route.ts

@@ -0,0 +1,126 @@
+import { NextRequest } from "next/server";
+import JSZip from "jszip";
+import { getServerSession } from "@/lib/auth/guards";
+import { prisma } from "@/lib/db";
+import { storage } from "@/lib/storage";
+import type { StructuredScript } from "@/lib/ai/types";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * Bundle everything for an episode into a single .zip download:
+ *   - audio.mp3        (the rendered episode, if present)
+ *   - cover.png        (the cover art, if present)
+ *   - script.txt       (the full transcript, speaker-labelled)
+ *   - show-notes.md    (title + section outline)
+ *
+ * Ownership-gated: only the owning user (or an admin) may export.
+ */
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+
+  const session = await getServerSession();
+  if (!session) return new Response("Unauthorized", { status: 401 });
+
+  const episode = await prisma.episode.findUnique({
+    where: { id },
+    include: {
+      script: true,
+      audioAsset: true,
+      coverArt: true,
+      speakers: true,
+    },
+  });
+  if (!episode) return new Response("Not found", { status: 404 });
+  if (episode.userId !== session.user.id && session.user.role !== "admin") {
+    return new Response("Forbidden", { status: 403 });
+  }
+
+  const speakerNames: Record<string, string> = {};
+  for (const s of episode.speakers) speakerNames[s.speakerKey] = s.displayName;
+
+  const zip = new JSZip();
+
+  // Audio (if rendered).
+  if (episode.audioAsset && (await storage().exists(episode.audioAsset.storageKey))) {
+    const audio = await storage().get(episode.audioAsset.storageKey);
+    const ext = episode.audioAsset.format || "mp3";
+    zip.file(`audio.${ext}`, audio);
+  }
+
+  // Cover art (if present).
+  if (episode.coverArt && (await storage().exists(episode.coverArt.storageKey))) {
+    const art = await storage().get(episode.coverArt.storageKey);
+    const ext = episode.coverArt.storageKey.split(".").pop()?.toLowerCase() ?? "png";
+    zip.file(`cover.${ext}`, art);
+  }
+
+  // Transcript + show notes derived from the structured script.
+  if (episode.script) {
+    const script = episode.script.content as unknown as StructuredScript;
+    zip.file("script.txt", buildTranscript(episode.title, script, speakerNames));
+    zip.file("show-notes.md", buildShowNotes(episode, script));
+  }
+
+  const blob = await zip.generateAsync({ type: "nodebuffer" });
+  const filename = `${slugify(episode.title) || "episode"}.zip`;
+
+  return new Response(blob as BodyInit, {
+    headers: {
+      "Content-Type": "application/zip",
+      "Content-Length": String(blob.byteLength),
+      "Content-Disposition": `attachment; filename="${filename}"`,
+      "Cache-Control": "private, no-store",
+    },
+  });
+}
+
+function buildTranscript(
+  title: string,
+  script: StructuredScript,
+  speakerNames: Record<string, string>
+): string {
+  const lines: string[] = [title, "=".repeat(title.length), ""];
+  for (const section of script.sections ?? []) {
+    lines.push(`## ${section.title}`, "");
+    for (const turn of section.turns ?? []) {
+      const name = speakerNames[turn.speakerKey] ?? turn.speakerKey;
+      lines.push(`${name}: ${turn.text}`, "");
+    }
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+function buildShowNotes(
+  episode: { title: string; topic: string; format: string; language: string; targetLengthMin: number },
+  script: StructuredScript
+): string {
+  const lines: string[] = [
+    `# ${episode.title}`,
+    "",
+    episode.topic,
+    "",
+    `- **Format:** ${episode.format.replace("_", "-").toLowerCase()}`,
+    `- **Language:** ${episode.language.toUpperCase()}`,
+    `- **Target length:** ${episode.targetLengthMin} min`,
+    "",
+    "## In this episode",
+    "",
+  ];
+  for (const section of script.sections ?? []) {
+    lines.push(`- ${section.title}`);
+  }
+  lines.push("", "---", "Generated with PodcastYes.");
+  return lines.join("\n") + "\n";
+}
+
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}

app/api/episodes/[id]/stream/route.ts

@@ -5,6 +5,28 @@ import { isTerminal } from "@/lib/episodes/status";
 
 export const dynamic = "force-dynamic";
 
+/**
+ * Per-user concurrency cap for SSE streams. Each open connection polls the DB
+ * every 1.5s, so unbounded streams per user are a cheap DoS / resource leak.
+ * This is an in-process counter (one web instance); see the rate-limiter note
+ * about scaling to multiple nodes.
+ */
+const MAX_STREAMS_PER_USER = 5;
+const activeStreams = new Map<string, number>();
+
+function tryAcquireStream(userId: string): boolean {
+  const current = activeStreams.get(userId) ?? 0;
+  if (current >= MAX_STREAMS_PER_USER) return false;
+  activeStreams.set(userId, current + 1);
+  return true;
+}
+
+function releaseStream(userId: string): void {
+  const current = activeStreams.get(userId) ?? 0;
+  if (current <= 1) activeStreams.delete(userId);
+  else activeStreams.set(userId, current - 1);
+}
+
 /**
  * Server-Sent Events stream of an episode's generation status. Polls the row
  * every 1.5s and emits on change until the episode reaches a terminal state.
@@ -22,7 +44,19 @@ export async function GET(req: NextRequest, { params }: { params: Promise<{ id:
     return new Response("Forbidden", { status: 403 });
   }
 
+  // Cap concurrent streams per user. Released in EVERY stop path below.
+  const streamUserId = session.user.id;
+  if (!tryAcquireStream(streamUserId)) {
+    return new Response("Too many concurrent streams", {
+      status: 429,
+      headers: { "Retry-After": "5" },
+    });
+  }
+
   const encoder = new TextEncoder();
+  // Exposed so the ReadableStream's `cancel` can also release the slot if the
+  // consumer tears down without an abort signal.
+  let stopRef: () => void = () => releaseStream(streamUserId);
 
   const stream = new ReadableStream({
     start(controller) {
@@ -38,6 +72,9 @@ export async function GET(req: NextRequest, { params }: { params: Promise<{ id:
       const stop = () => {
         if (stopped) return;
         stopped = true;
+        // Release the per-user stream slot exactly once (terminal status,
+        // abort, not-found, or error all route through here).
+        releaseStream(streamUserId);
         clearInterval(pollTimer);
         clearInterval(pingTimer);
         try {
@@ -66,6 +103,8 @@ export async function GET(req: NextRequest, { params }: { params: Promise<{ id:
         if (isTerminal(e.status)) stop();
       };
 
+      stopRef = stop;
+
       send({ type: "open" });
       void poll();
       pollTimer = setInterval(poll, 1500);
@@ -75,6 +114,10 @@ export async function GET(req: NextRequest, { params }: { params: Promise<{ id:
 
       req.signal.addEventListener("abort", stop);
     },
+    cancel() {
+      // Consumer disconnected/cancelled — ensure the slot is released.
+      stopRef();
+    },
   });
 
   return new Response(stream, {

app/api/public/episodes/[shareId]/audio/route.ts

@@ -0,0 +1,63 @@
+import { NextRequest } from "next/server";
+import { prisma } from "@/lib/db";
+import { storage } from "@/lib/storage";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * Stream an episode's MP3 to anonymous visitors, authorized purely by a valid,
+ * still-enabled public `shareId` (NOT a session). Returns 404 when the share is
+ * disabled or the audio is missing so we never disclose private episode state.
+ *
+ * Supports HTTP Range requests so the audio element can seek/scrub.
+ */
+export async function GET(
+  req: NextRequest,
+  { params }: { params: Promise<{ shareId: string }> }
+) {
+  const { shareId } = await params;
+
+  const episode = await prisma.episode.findUnique({
+    where: { shareId },
+    select: { audioAsset: { select: { storageKey: true } } },
+  });
+  const key = episode?.audioAsset?.storageKey;
+  if (!key) return new Response("Not found", { status: 404 });
+
+  if (!(await storage().exists(key))) return new Response("Not found", { status: 404 });
+
+  const data = await storage().get(key);
+  const total = data.byteLength;
+  const contentType = "audio/mpeg";
+
+  const range = req.headers.get("range");
+  if (range) {
+    const match = /bytes=(\d+)-(\d*)/.exec(range);
+    if (match) {
+      const start = Number(match[1]);
+      const end = match[2] ? Math.min(Number(match[2]), total - 1) : total - 1;
+      if (start <= end && start < total) {
+        const chunk = data.subarray(start, end + 1);
+        return new Response(chunk as BodyInit, {
+          status: 206,
+          headers: {
+            "Content-Type": contentType,
+            "Content-Length": String(chunk.byteLength),
+            "Content-Range": `bytes ${start}-${end}/${total}`,
+            "Accept-Ranges": "bytes",
+            "Cache-Control": "public, max-age=3600",
+          },
+        });
+      }
+    }
+  }
+
+  return new Response(data as BodyInit, {
+    headers: {
+      "Content-Type": contentType,
+      "Content-Length": String(total),
+      "Accept-Ranges": "bytes",
+      "Cache-Control": "public, max-age=3600",
+    },
+  });
+}

app/api/public/episodes/[shareId]/cover/route.ts

@@ -0,0 +1,42 @@
+import { NextRequest } from "next/server";
+import { prisma } from "@/lib/db";
+import { storage } from "@/lib/storage";
+
+export const dynamic = "force-dynamic";
+
+const CONTENT_TYPES: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+};
+
+/**
+ * Serve an episode's cover art to anonymous visitors, authorized by a valid,
+ * still-enabled public `shareId`. Used as a fallback when the storage provider
+ * doesn't expose a directly-fetchable public URL for cover art.
+ */
+export async function GET(
+  _req: NextRequest,
+  { params }: { params: Promise<{ shareId: string }> }
+) {
+  const { shareId } = await params;
+
+  const episode = await prisma.episode.findUnique({
+    where: { shareId },
+    select: { coverArt: { select: { storageKey: true } } },
+  });
+  const key = episode?.coverArt?.storageKey;
+  if (!key) return new Response("Not found", { status: 404 });
+  if (!(await storage().exists(key))) return new Response("Not found", { status: 404 });
+
+  const data = await storage().get(key);
+  const ext = key.split(".").pop()?.toLowerCase() ?? "png";
+  return new Response(data as BodyInit, {
+    headers: {
+      "Content-Type": CONTENT_TYPES[ext] ?? "image/png",
+      "Content-Length": String(data.byteLength),
+      "Cache-Control": "public, max-age=3600",
+    },
+  });
+}

app/api/v1/episodes/route.ts

@@ -3,11 +3,15 @@ import { z } from "zod";
 import { verifyApiKey, bearerKey } from "@/lib/apikeys";
 import { prisma } from "@/lib/db";
 import { getEffectivePlan } from "@/lib/billing/subscription";
-import { enforceLimit, LimitExceededError } from "@/lib/usage/limits";
+import { reserveLimit, LimitExceededError } from "@/lib/usage/limits";
+import { refundUsage } from "@/lib/usage/meter";
 import { enqueueEpisodeGeneration } from "@/lib/queue/pgboss";
 import { FORMAT_SPEAKERS } from "@/lib/episodes/options";
 import { DEFAULT_VOICE_IDS, VOICE_CATALOG } from "@/lib/ai/voices";
 import { rateLimit, LIMITS } from "@/lib/ratelimit";
+import { isFlagEnabled } from "@/lib/flags";
+import { moderateText } from "@/lib/ai/moderation";
+import type { UsageMetric } from "@/lib/billing/plans";
 
 export const dynamic = "force-dynamic";
 
@@ -20,6 +24,14 @@ export async function GET(req: NextRequest) {
   const auth = await authorize(req);
   if (!auth) return Response.json({ error: "Invalid API key" }, { status: 401 });
 
+  const rl = await rateLimit("read", auth.userId, LIMITS.read);
+  if (!rl.ok) {
+    return Response.json(
+      { error: "Rate limit exceeded" },
+      { status: 429, headers: { "Retry-After": String(rl.retryAfterSec ?? 60) } }
+    );
+  }
+
   const episodes = await prisma.episode.findMany({
     where: { userId: auth.userId },
     orderBy: { createdAt: "desc" },
@@ -52,23 +64,51 @@ export async function POST(req: NextRequest) {
     );
   }
 
+  if (!(await isFlagEnabled("episode_generation_enabled"))) {
+    return Response.json({ error: "Episode generation is temporarily paused" }, { status: 503 });
+  }
+
   const parsed = createSchema.safeParse(await req.json().catch(() => ({})));
   if (!parsed.success) {
     return Response.json({ error: parsed.error.issues[0]?.message ?? "Invalid body" }, { status: 400 });
   }
   const data = parsed.data;
 
-  const { plan } = await getEffectivePlan(auth.userId);
+  const { plan, subjectId, subjectType } = await getEffectivePlan(auth.userId);
   if (data.targetLengthMin > plan.limits.maxEpisodeMinutes) {
     return Response.json(
       { error: `Plan supports episodes up to ${plan.limits.maxEpisodeMinutes} minutes` },
       { status: 402 }
     );
   }
+
+  // Screen the requested topic before reserving quota or spending AI budget.
+  if (await isFlagEnabled("ai_moderation_enabled")) {
+    const mod = await moderateText([data.title, data.topic, data.audience].filter(Boolean).join("\n"));
+    if (mod.flagged) {
+      return Response.json(
+        { error: "Topic violates the content policy and cannot be generated" },
+        { status: 422 }
+      );
+    }
+  }
+
+  // Atomically reserve quota up front (full generation = script+audio+art). The
+  // worker won't re-meter; we refund below if create/enqueue fails. See the
+  // metering invariant in lib/usage/meter.ts.
+  const reserved: UsageMetric[] = [];
+  const refundReserved = async () => {
+    for (const m of reserved) await refundUsage(subjectId, subjectType, m);
+  };
   try {
-    await enforceLimit(auth.userId, "script");
-    await enforceLimit(auth.userId, "audio");
+    await reserveLimit(auth.userId, "script");
+    reserved.push("script");
+    await reserveLimit(auth.userId, "audio");
+    reserved.push("audio");
+    await reserveLimit(auth.userId, "art");
+    reserved.push("art");
   } catch (err) {
+    await refundReserved();
     if (err instanceof LimitExceededError) {
       return Response.json({ error: `Monthly ${err.check.metric} limit reached` }, { status: 402 });
     }
@@ -81,23 +121,28 @@ export async function POST(req: NextRequest) {
     elevenVoiceId: DEFAULT_VOICE_IDS[s.speakerKey] ?? VOICE_CATALOG[i % VOICE_CATALOG.length].id,
   }));
 
-  const episode = await prisma.episode.create({
-    data: {
-      userId: auth.userId,
-      title: data.title?.trim() || data.topic.slice(0, 60),
-      topic: data.topic,
-      tone: data.tone,
-      format: data.format,
-      language: data.language,
-      targetLengthMin: data.targetLengthMin,
-      audience: data.audience,
-      status: "QUEUED",
-      stage: "Queued for generation",
-      speakers: { create: speakers },
-      jobs: { create: { type: "full", status: "queued" } },
-    },
-  });
-  await enqueueEpisodeGeneration({ episodeId: episode.id, type: "full" });
+  try {
+    const episode = await prisma.episode.create({
+      data: {
+        userId: auth.userId,
+        title: data.title?.trim() || data.topic.slice(0, 60),
+        topic: data.topic,
+        tone: data.tone,
+        format: data.format,
+        language: data.language,
+        targetLengthMin: data.targetLengthMin,
+        audience: data.audience,
+        status: "QUEUED",
+        stage: "Queued for generation",
+        speakers: { create: speakers },
+        jobs: { create: { type: "full", status: "queued" } },
+      },
+    });
+    await enqueueEpisodeGeneration({ episodeId: episode.id, type: "full" });
 
-  return Response.json({ id: episode.id, status: episode.status }, { status: 201 });
+    return Response.json({ id: episode.id, status: episode.status }, { status: 201 });
+  } catch (err) {
+    await refundReserved();
+    throw err;
+  }
 }

app/api/webhooks/paypal/route.ts

@@ -1,6 +1,7 @@
 import { NextRequest } from "next/server";
 import { verifyPaypalWebhook } from "@/lib/billing/paypal";
 import { handlePaypalEvent } from "@/lib/billing/webhooks/paypal";
+import { alreadyProcessed, logWebhook } from "@/lib/billing/webhook-log";
 
 export const dynamic = "force-dynamic";
 
@@ -23,10 +24,16 @@ export async function POST(req: NextRequest) {
     return new Response("Invalid signature", { status: 400 });
   }
 
+  const event = JSON.parse(body) as { id?: string; event_type?: string };
+  const eventId = event.id ?? `paypal_${Date.now()}`;
+  if (event.id && (await alreadyProcessed(eventId))) return new Response("ok (duplicate)");
+
   try {
-    await handlePaypalEvent(JSON.parse(body));
+    await handlePaypalEvent(event as Parameters<typeof handlePaypalEvent>[0]);
+    await logWebhook("paypal", eventId, event.event_type ?? "unknown", "processed");
   } catch (err) {
     console.error("[paypal webhook] handler error", err);
+    await logWebhook("paypal", eventId, event.event_type ?? "unknown", "failed", err instanceof Error ? err.message : String(err));
     return new Response("Handler error", { status: 500 });
   }
   return new Response("ok");

app/api/webhooks/stripe/route.ts

@@ -2,6 +2,7 @@ import { NextRequest } from "next/server";
 import type Stripe from "stripe";
 import { stripe } from "@/lib/billing/stripe";
 import { handleStripeEvent } from "@/lib/billing/webhooks/stripe";
+import { alreadyProcessed, logWebhook } from "@/lib/billing/webhook-log";
 
 export const dynamic = "force-dynamic";
 
@@ -19,10 +20,15 @@ export async function POST(req: NextRequest) {
     return new Response("Invalid signature", { status: 400 });
   }
 
+  // Idempotency: skip events we've already processed (Stripe retries deliveries).
+  if (await alreadyProcessed(event.id)) return new Response("ok (duplicate)");
+
   try {
     await handleStripeEvent(event);
+    await logWebhook("stripe", event.id, event.type, "processed");
   } catch (err) {
     console.error("[stripe webhook] handler error", err);
+    await logWebhook("stripe", event.id, event.type, "failed", err instanceof Error ? err.message : String(err));
     return new Response("Handler error", { status: 500 });
   }
   return new Response("ok");