@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/desk/http.ts

@@ -0,0 +1,460 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { EngineProbes } from "../product/engines.js";
+import { mp4For } from "../project/videos.js";
+import { redact } from "../queue/seal.js";
+import type { Store } from "../queue/store.js";
+import { handlePreview, type PreviewOptions } from "./preview.js";
+import { closeStudios, studioRoute, type StudioRouteOptions } from "./studio-route.js";
+import { engageView, publicationsView, sourcesView, trendsView } from "./screens.js";
+import { buildState } from "./state.js";
+import { topicsRoute } from "./topics-route.js";
+import { creatorsRoute } from "./creators-route.js";
+import { mailRoute } from "./mail-route.js";
+import { createTickRunner, type TickFn } from "./tick-runner.js";
+import * as verbs from "./verbs.js";
+
+export interface DashboardOptions {
+  store: Store;
+  dataDir: string;
+  env: Record<string, string | undefined>;
+  /** 0 picks a free port. */
+  port: number;
+  probes?: EngineProbes;
+  /** Runs one tick. The CLI passes `runDeskTick`; tests inject a fake. Receives the `desk tick` argv. */
+  tick?: TickFn;
+  /** The project this desk belongs to. Reported by /api/state so a client can tell which desk it reached. */
+  project?: { id: string; name: string } | null;
+  /** Renders one frame of a Remotion scene for the Review screen. Defaults to `render --frame`; tests inject a fake. */
+  renderFrame?: PreviewOptions["renderFrame"];
+  /** Starts a scene studio for "Edit in studio". Defaults to the vendored Framey studio; tests inject a fake. */
+  startStudio?: StudioRouteOptions["start"];
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const uiDir = path.join(here, "ui");
+const fontsDir = path.join(here, "fonts");
+const FONT_FILES = new Set(["google-sans-flex-latin.woff2", "jetbrains-mono-medium.woff2"]);
+
+const BODY_CAP = 64 * 1024;
+const ID = /^[A-Za-z0-9-]{1,64}$/;
+const PAGES = [/^\/$/, /^\/keys$/, /^\/runs$/, /^\/runs\/[^/]+$/, /^\/series$/, /^\/series\/[^/]+$/, /^\/metrics$/, /^\/warnings$/, /^\/settings$/, /^\/topics$/, /^\/publications$/, /^\/sources$/, /^\/engage$/, /^\/trends$/, /^\/review$/, /^\/creators$/, /^\/mail$/];
+const MIME: Record<string, string> = {
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".html": "text/html; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".woff2": "font/woff2",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+};
+
+type Json = Record<string, unknown>;
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const text = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+  });
+  res.end(text);
+}
+
+function refuse(res: ServerResponse, status: number, refusal: string, fix: string, code?: string): void {
+  sendJson(res, status, { ok: false, refusal: redact(refusal), fix: redact(fix), ...(code ? { code } : {}) });
+}
+
+const notFound = (res: ServerResponse) => refuse(res, 404, "Not found.", "Check the address, or open the dashboard home.");
+
+class BodyError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly fix: string,
+  ) {
+    super(message);
+  }
+}
+
+function readBody(req: IncomingMessage): Promise<Json> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let done = false;
+    req.on("data", (chunk: Buffer) => {
+      if (done) return;
+      size += chunk.length;
+      if (size > BODY_CAP) {
+        done = true;
+        chunks.length = 0;
+        reject(new BodyError(413, "The request body is too large.", "Send a body under 64 KB."));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (done) return;
+      done = true;
+      const raw = Buffer.concat(chunks).toString("utf8");
+      if (!raw.trim()) return resolve({});
+      try {
+        const parsed: unknown = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not an object");
+        resolve(parsed as Json);
+      } catch {
+        reject(new BodyError(400, "The body is not a JSON object.", "Send a JSON object such as {}."));
+      }
+    });
+    req.on("error", () => {
+      if (!done) {
+        done = true;
+        reject(new BodyError(400, "The request body could not be read.", "Send the request again."));
+      }
+    });
+  });
+}
+
+const str = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
+const bool = (value: unknown): boolean | undefined => (typeof value === "boolean" ? value : undefined);
+const num = (value: unknown): number => (typeof value === "number" ? value : Number.NaN);
+const strList = (value: unknown): string[] | undefined =>
+  Array.isArray(value) && value.every((item) => typeof item === "string") ? (value as string[]) : undefined;
+
+function decode(segment: string): string | null {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+}
+
+function typeOf(file: string): string {
+  return MIME[path.extname(file)] ?? "application/octet-stream";
+}
+
+function serveWhole(res: ServerResponse, file: string, type: string, extra: Record<string, string> = {}): void {
+  if (!existsSync(file)) return notFound(res);
+  res.writeHead(200, { "content-type": type, "cache-control": "no-store", "x-content-type-options": "nosniff", ...extra });
+  createReadStream(file).pipe(res);
+}
+
+function serveMedia(req: IncomingMessage, res: ServerResponse, file: string, type: string): void {
+  if (!existsSync(file)) return notFound(res);
+  const size = statSync(file).size;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(String(req.headers.range ?? ""));
+  if (!match || (!match[1] && !match[2])) {
+    res.writeHead(200, { "content-type": type, "content-length": size, "accept-ranges": "bytes", "cache-control": "no-store" });
+    createReadStream(file).pipe(res);
+    return;
+  }
+  let start: number;
+  let end: number;
+  if (match[1]) {
+    start = Number(match[1]);
+    end = match[2] ? Math.min(Number(match[2]), size - 1) : size - 1;
+  } else {
+    const suffix = Number(match[2]);
+    start = Math.max(size - suffix, 0);
+    end = size - 1;
+  }
+  if (size === 0 || start >= size || start > end) {
+    res.writeHead(416, { "content-range": `bytes */${size}`, "content-type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ ok: false, refusal: "That byte range is outside the file.", fix: "Request a range inside the file." }));
+    return;
+  }
+  res.writeHead(206, {
+    "content-type": type,
+    "content-range": `bytes ${start}-${end}/${size}`,
+    "content-length": end - start + 1,
+    "accept-ranges": "bytes",
+    "cache-control": "no-store",
+  });
+  createReadStream(file, { start, end }).pipe(res);
+}
+
+function verbResponse(res: ServerResponse, result: verbs.VerbResult): void {
+  if (!result.ok) return refuse(res, 400, result.refusal, result.fix, result.code);
+  sendJson(res, 200, { ok: true, ...(result.data ?? {}) });
+}
+
+export async function startDashboard(options: DashboardOptions): Promise<Server> {
+  const { store, dataDir, env } = options;
+  const probes = options.probes ?? { hyperframesCli: false, comfyReachable: false };
+  const userId = env.VFREY_USER ?? "local";
+  const tickFn: TickFn =
+    options.tick ??
+    (async (argv) => {
+      const { runDeskTick } = await import("./tick.js");
+      return runDeskTick({ store, env: env as Record<string, string | undefined>, argv });
+    });
+  const runner = createTickRunner(tickFn);
+  let boundPort = options.port;
+  const studios: StudioRouteOptions["running"] = new Map();
+  // A project desk keeps its data in <project>/.vfrey; "Study formats" writes next to it, in <project>/research.
+  const projectRoot = options.project ? path.dirname(dataDir) : null;
+
+  const guard = (req: IncomingMessage, res: ServerResponse): boolean => {
+    const hosts = new Set([`127.0.0.1:${boundPort}`, `localhost:${boundPort}`]);
+    if (!hosts.has(req.headers.host ?? "")) {
+      refuse(res, 403, "Unknown host.", `Open the dashboard at http://127.0.0.1:${boundPort}.`);
+      return false;
+    }
+    if (req.method === "GET" || req.method === "HEAD" || req.method === "OPTIONS") return true;
+    if (!String(req.headers["content-type"] ?? "").startsWith("application/json")) {
+      refuse(res, 403, "Writes must be JSON.", "Send Content-Type: application/json.");
+      return false;
+    }
+    const origins = new Set([`http://127.0.0.1:${boundPort}`, `http://localhost:${boundPort}`]);
+    const origin = req.headers.origin;
+    if (origin && !origins.has(origin)) {
+      refuse(res, 403, "That origin may not write.", "Use the dashboard page itself.");
+      return false;
+    }
+    const site = req.headers["sec-fetch-site"];
+    if (site && site !== "same-origin" && site !== "none") {
+      refuse(res, 403, "Cross-site writes are refused.", "Use the dashboard page itself.");
+      return false;
+    }
+    return true;
+  };
+
+  const rendersFile = (id: string, ext: "mp4" | "txt"): string | null => {
+    if (!ID.test(id)) return null;
+    const known = store.db.prepare(`SELECT payload FROM jobs WHERE id = ?`).get(id) as { payload: string } | undefined;
+    if (!known) return null;
+    let stored: unknown = null;
+    try {
+      stored = (JSON.parse(known.payload) as { content?: { outputPath?: unknown } | null }).content?.outputPath ?? null;
+    } catch {
+      stored = null;
+    }
+    const mp4 = mp4For(dataDir, id, stored);
+    return ext === "mp4" ? mp4 : mp4.replace(/\.mp4$/, ".txt");
+  };
+
+  async function read(req: IncomingMessage, res: ServerResponse, pathname: string): Promise<void> {
+    if (pathname.startsWith("/preview/") && (await handlePreview({ store, dataDir, env, project: options.project ?? null, renderFrame: options.renderFrame }, req, res, pathname))) return;
+    if (PAGES.some((re) => re.test(pathname))) {
+      return serveWhole(res, path.join(uiDir, "index.html"), MIME[".html"]!);
+    }
+    let m: RegExpExecArray | null;
+    if ((m = /^\/assets\/(.+)$/.exec(pathname))) {
+      const name = decode(m[1]!);
+      if (!name || /[/\\]/.test(name) || name.includes("..") || name.startsWith(".")) return notFound(res);
+      const file = path.join(uiDir, name);
+      if (!existsSync(file) || !statSync(file).isFile()) return notFound(res);
+      return serveWhole(res, file, typeOf(name));
+    }
+    if ((m = /^\/fonts\/([a-z0-9.-]+\.woff2)$/.exec(pathname)) && FONT_FILES.has(m[1]!)) {
+      return serveWhole(res, path.join(fontsDir, m[1]!), "font/woff2", { "cache-control": "public, max-age=86400" });
+    }
+    if (pathname === "/favicon.ico") {
+      return serveWhole(res, path.join(uiDir, "favicon.ico"), MIME[".ico"]!, { "cache-control": "public, max-age=86400" });
+    }
+    if (pathname === "/api/topics" || pathname === "/api/topics/niches") {
+      const reply = await topicsRoute({ env }, pathname, new URL(req.url ?? "/", "http://127.0.0.1").searchParams);
+      return reply ? sendJson(res, reply.status, reply.body) : notFound(res);
+    }
+    if (pathname.startsWith("/api/creators/")) {
+      const reply = await creatorsRoute({ env }, { method: "GET", pathname, params: new URL(req.url ?? "/", "http://127.0.0.1").searchParams, body: {}, projectRoot });
+      return reply ? sendJson(res, reply.status, reply.body) : notFound(res);
+    }
+    if (pathname.startsWith("/api/mail/")) {
+      const reply = await mailRoute({ env }, { method: "GET", pathname, params: new URL(req.url ?? "/", "http://127.0.0.1").searchParams, body: {} });
+      return reply ? sendJson(res, reply.status, reply.body) : notFound(res);
+    }
+    if (pathname === "/api/publications") return sendJson(res, 200, publicationsView(store, new URL(req.url ?? "/", "http://127.0.0.1").searchParams));
+    if (pathname === "/api/sources") return sendJson(res, 200, sourcesView(store));
+    if (pathname === "/api/engage") return sendJson(res, 200, engageView(store, new URL(req.url ?? "/", "http://127.0.0.1").searchParams));
+    if (pathname === "/api/trends") return sendJson(res, 200, trendsView(store));
+    if (pathname === "/api/state") {
+      return sendJson(res, 200, await buildState({ store, dataDir, env, userId, tick: runner.status(), probes, project: options.project ?? null }));
+    }
+    if (pathname === "/api/review") return sendJson(res, 200, { ok: true, jobs: store.reviewQueue(dataDir) });
+    if ((m = /^\/api\/runs\/([^/]+)$/.exec(pathname))) {
+      const id = decode(m[1]!);
+      const detail = id && ID.test(id) ? store.runDetail(id) : null;
+      if (!detail) return refuse(res, 404, "No run has that id.", "Open a run from the Runs list.");
+      return sendJson(res, 200, { ok: true, run: detail });
+    }
+    if ((m = /^\/media\/runs\/([^/]+)\.(mp4|txt)$/.exec(pathname))) {
+      const ext = m[2] as "mp4" | "txt";
+      const id = decode(m[1]!);
+      const file = id ? rendersFile(id, ext) : null;
+      if (!file) return refuse(res, 404, "No file for that run.", "The render has not produced it.");
+      if (ext === "txt") return serveWhole(res, file, "text/plain; charset=utf-8");
+      return serveMedia(req, res, file, "video/mp4");
+    }
+    return notFound(res);
+  }
+
+  async function write(res: ServerResponse, pathname: string, body: Json): Promise<void> {
+    let m: RegExpExecArray | null;
+    const seg = (value: string | undefined): string => decode(value ?? "") ?? "";
+    if (pathname === "/api/creators/watch" || pathname === "/api/creators/study") {
+      const reply = await creatorsRoute({ env }, { method: "POST", pathname, params: new URLSearchParams(), body, projectRoot });
+      return reply ? sendJson(res, reply.status, reply.body) : notFound(res);
+    }
+    if (pathname.startsWith("/api/mail/")) {
+      const reply = await mailRoute({ env }, { method: "POST", pathname, params: new URLSearchParams(), body });
+      return reply ? sendJson(res, reply.status, reply.body) : notFound(res);
+    }
+    if (pathname === "/api/studio") {
+      const reply = await studioRoute({ store, dataDir, env, project: options.project ?? null, running: studios, start: options.startStudio }, body);
+      return sendJson(res, reply.status, reply.body);
+    }
+    if (pathname === "/api/tick") {
+      const about = str(body.about)?.trim() || null;
+      if (about && about.length > 300) return refuse(res, 400, "The subject is too long.", "Keep it under 300 characters.");
+      const started = runner.start({ now: bool(body.now) ?? false, dryRun: bool(body.dryRun) ?? false, series: str(body.series) ?? null, about });
+      if (!started.ok) return refuse(res, 409, started.refusal, started.fix);
+      return sendJson(res, 202, { ok: true, tick: started.tick });
+    }
+    if ((m = /^\/api\/jobs\/([^/]+)\/(approve|reject)$/.exec(pathname))) {
+      const id = seg(m[1]);
+      return verbResponse(res, m[2] === "approve" ? verbs.jobApprove(store, { id }) : verbs.jobReject(store, { id, reason: str(body.reason) }));
+    }
+    if ((m = /^\/api\/jobs\/([^/]+)\/(retry|cancel)$/.exec(pathname))) {
+      const id = seg(m[1]);
+      return verbResponse(res, m[2] === "retry" ? verbs.jobRetry(store, { id }) : verbs.jobCancel(store, { id }));
+    }
+    if (pathname === "/api/series") {
+      const id = str(body.id);
+      const accountId = str(body.accountId);
+      const niche = str(body.niche);
+      if (!id || !accountId || niche === undefined) {
+        return refuse(res, 400, "A series needs an id, an account, and a niche.", "Send id, accountId, and niche.");
+      }
+      const result = verbs.seriesCreate(store, { id, accountId, niche, language: str(body.language), timezone: str(body.timezone), engine: str(body.engine) });
+      return verbResponse(res, result.ok ? { ok: true, data: { id } } : result);
+    }
+    if ((m = /^\/api\/series\/([^/]+)\/(pause|resume|delete|cadence|quota|platforms|sources|live|dry-run)$/.exec(pathname))) {
+      const id = seg(m[1]);
+      switch (m[2]) {
+        case "pause":
+          return verbResponse(res, verbs.seriesPause(store, { id }));
+        case "resume":
+          return verbResponse(res, verbs.seriesResume(store, { id }));
+        case "delete":
+          return verbResponse(res, verbs.seriesDelete(store, { id }));
+        case "live":
+          return verbResponse(res, verbs.seriesLive(store, { id, confirm: str(body.confirm), key: env.CREDENTIALS_KEY }));
+        case "dry-run":
+          return verbResponse(res, verbs.seriesOff(store, { id }));
+        case "cadence": {
+          const windows = strList(body.windows);
+          const timezone = str(body.timezone);
+          if (!timezone || !windows) return refuse(res, 400, "Cadence needs a timezone and windows.", "Send timezone, minHoursBetweenPosts, maxPostsPerDay, and windows.");
+          return verbResponse(res, verbs.cadenceSet(store, { seriesId: id, timezone, minHoursBetweenPosts: num(body.minHoursBetweenPosts), maxPostsPerDay: num(body.maxPostsPerDay), windows }));
+        }
+        case "quota": {
+          const current = (store.snapshot(userId).series as Array<Record<string, unknown>>).find((s) => s.id === id);
+          if (!current) return refuse(res, 400, `Series ${id} was not found.`, "Check the series id on the Series page.");
+          const pick = (key: string): number => (key in body ? num(body[key]) : Number(current[key]));
+          return verbResponse(res, verbs.quotaSet(store, { seriesId: id, youtubeDailyUploadCap: pick("youtubeDailyUploadCap"), maxRepliesPerDay: pick("maxRepliesPerDay"), minSecondsBetween: pick("minSecondsBetween") }));
+        }
+        case "platforms": {
+          const platform = str(body.platform);
+          const enabled = bool(body.enabled);
+          if (!platform || enabled === undefined) return refuse(res, 400, "A platform needs a name and an enabled flag.", "Send platform and enabled.");
+          const config = body.config && typeof body.config === "object" && !Array.isArray(body.config) ? (body.config as Json) : undefined;
+          return verbResponse(res, verbs.platformSet(store, { seriesId: id, platform, enabled, config }));
+        }
+        default: {
+          const kind = str(body.kind);
+          const value = str(body.value);
+          if (!kind || value === undefined) return refuse(res, 400, "A source needs a kind and a value.", "Send kind and value.");
+          const result = verbs.sourceAdd(store, { seriesId: id, kind, value });
+          return verbResponse(res, result.ok ? { ok: true, data: { id: result.data?.id } } : result);
+        }
+      }
+    }
+    if ((m = /^\/api\/series\/([^/]+)$/.exec(pathname))) {
+      const patch = {
+        niche: str(body.niche),
+        language: str(body.language),
+        voices: strList(body.voices),
+        hashtagPool: strList(body.hashtagPool),
+        autopilot: bool(body.autopilot),
+        engageEnabled: bool(body.engageEnabled),
+        publishEnabled: bool(body.publishEnabled),
+        reviewEnabled: bool(body.reviewEnabled),
+        allowSpicy: bool(body.allowSpicy),
+        stylePath: str(body.stylePath),
+        engine: str(body.engine),
+      };
+      return verbResponse(res, verbs.seriesUpdate(store, { id: seg(m[1]), patch }));
+    }
+    if ((m = /^\/api\/sources\/([^/]+)\/(update|delete)$/.exec(pathname))) {
+      const id = seg(m[1]);
+      if (m[2] === "delete") return verbResponse(res, verbs.sourceRemove(store, { id }));
+      const value = str(body.value);
+      if (value === undefined) return refuse(res, 400, "A source update needs a value.", "Send value.");
+      return verbResponse(res, verbs.sourceUpdate(store, { id, value }));
+    }
+    if (pathname === "/api/secrets" || pathname === "/api/secrets/clear") {
+      const ownerKind = str(body.ownerKind);
+      const ownerId = str(body.ownerId);
+      const field = str(body.field);
+      if ((ownerKind !== "account" && ownerKind !== "series") || !ownerId || !field) {
+        return refuse(res, 400, "A secret needs an owner kind, an owner id, and a field.", "Send ownerKind (account or series), ownerId, and field.");
+      }
+      if (pathname === "/api/secrets/clear") return verbResponse(res, verbs.secretClear(store, { ownerKind, ownerId, field }));
+      const value = str(body.value);
+      if (value === undefined) return refuse(res, 400, "A secret needs a value.", "Send value, or an empty string to leave it unchanged.");
+      return verbResponse(res, verbs.secretSet(store, { ownerKind, ownerId, field, value, key: env.CREDENTIALS_KEY }));
+    }
+    if ((m = /^\/api\/warnings\/([^/]+)\/ack$/.exec(pathname))) {
+      return verbResponse(res, verbs.warningAck(store, { id: seg(m[1]) }));
+    }
+    if (pathname === "/api/mode") {
+      const mode = str(body.mode) ?? "";
+      return verbResponse(res, verbs.modeSet(store, { userId, mode, llmKeyPresent: Boolean(env.LLM_API_KEY) }));
+    }
+    return notFound(res);
+  }
+
+  const server = createServer((req, res) => {
+    handle(req, res).catch((error: unknown) => {
+      if (error instanceof BodyError) {
+        if (!res.headersSent) refuse(res, error.status, error.message, error.fix);
+        if (error.status === 413) req.resume();
+        return;
+      }
+      if (!res.headersSent) refuse(res, 500, "The dashboard hit an error.", "Try again, or restart `vfrey dashboard`.");
+      else res.end();
+    });
+  });
+
+  async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    if (!guard(req, res)) return;
+    const method = req.method ?? "GET";
+    if (method === "OPTIONS") return refuse(res, 405, "OPTIONS is not supported.", "Use GET or POST from the dashboard page.");
+    const pathname = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+    if (method === "GET" || method === "HEAD") return read(req, res, pathname);
+    if (method !== "POST") return refuse(res, 405, `${method} is not supported.`, "Use GET or POST.");
+    const body = await readBody(req);
+    try {
+      return await write(res, pathname, body);
+    } catch (error) {
+      if (res.headersSent) throw error;
+      const message = error instanceof Error ? error.message : "The change failed.";
+      return refuse(res, 400, message.split("\n")[0] ?? "The change failed.", "Check the values and try again.");
+    }
+  }
+
+  server.on("close", () => void closeStudios(studios));
+  return new Promise<Server>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, "127.0.0.1", () => {
+      server.off("error", reject);
+      const address = server.address();
+      boundPort = address && typeof address === "object" ? address.port : options.port;
+      resolve(server);
+    });
+  });
+}

package/src/desk/mail-route.ts

@@ -0,0 +1,103 @@
+// The dashboard's window onto vfrey Mail. The browser asks this server; this server asks the vfrey API with the stored token.
+// The token is read here, per request, and is never put in a response. Approve and Send are separate routes, and each
+// needs `confirm: true` from the browser's inline confirm: one draft at a time, never chained.
+import { ApiFailure, clean } from "../api/client.js";
+import { ApiConfigError } from "../api/config.js";
+import { MAIL_KINDS, MAIL_STATUSES } from "../api/types.js";
+import {
+  approveMailDraft,
+  createMailDraft,
+  discardMailDraft,
+  editMailDraft,
+  getMailDraft,
+  getMailIdentity,
+  listMailDrafts,
+  saveMailIdentity,
+  sendMailDraft,
+  type MailDeps,
+} from "../api/mail.js";
+import { CREATOR_PLATFORM_IDS, normalizeHandle } from "../api/creators.js";
+import type { MailDraftBody, MailDraftPatch } from "../api/types.js";
+import { redact } from "../queue/seal.js";
+import type { RouteReply } from "./creators-route.js";
+
+export interface MailRouteInput {
+  method: "GET" | "POST";
+  pathname: string;
+  params: URLSearchParams;
+  body: Record<string, unknown>;
+}
+
+const bad = (refusal: string, fix: string): RouteReply => ({ status: 400, body: { ok: false, refusal, fix, code: "bad_request" } });
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+function refusal(error: unknown): RouteReply {
+  if (error instanceof ApiFailure || error instanceof ApiConfigError) {
+    const status = error instanceof ApiFailure ? error.status : undefined;
+    const code = error instanceof ApiFailure ? (error.code ?? "api_error") : "api_config";
+    const http = code === "not_live" || code === "not_signed_in" ? 401 : status && status >= 400 && status < 600 ? status : 502;
+    return { status: http, body: { ok: false, refusal: redact(error.message), fix: redact(error.fix), code, loginCommand: code === "not_signed_in" || code === "unauthorized" || code === "not_live" ? "npx vfrey login" : undefined } };
+  }
+  return { status: 502, body: { ok: false, refusal: redact(error instanceof Error ? clean(error.message) : "Mail could not be read."), fix: "Try again in a moment.", code: "api_error" } };
+}
+
+/** GET /api/mail/{drafts,draft,identity}; POST /api/mail/{draft,edit,approve,send,discard,identity}. Null for any other path. */
+export async function mailRoute(deps: MailDeps, input: MailRouteInput): Promise<RouteReply | null> {
+  const { method, pathname, params, body } = input;
+  try {
+    if (method === "GET" && pathname === "/api/mail/drafts") {
+      const status = params.get("status")?.trim().toLowerCase() || undefined;
+      if (status && !(MAIL_STATUSES as readonly string[]).includes(status)) return bad("Pick a status from the list.", "Choose one from the filter.");
+      return { status: 200, body: { ok: true, drafts: await listMailDrafts(deps, status ? { status } : {}) } };
+    }
+    if (method === "GET" && pathname === "/api/mail/draft") {
+      const id = params.get("id")?.trim() ?? "";
+      if (!id) return bad("Pick a draft.", "Choose one from the list.");
+      return { status: 200, body: { ok: true, draft: await getMailDraft(deps, id) } };
+    }
+    if (method === "GET" && pathname === "/api/mail/identity") return { status: 200, body: { ok: true, identity: await getMailIdentity(deps) } };
+    if (method !== "POST") return null;
+
+    if (pathname === "/api/mail/draft") {
+      const kind = str(body.kind).toLowerCase();
+      if (!(MAIL_KINDS as readonly string[]).includes(kind)) return bad("Pick what kind of message.", "Choose sponsor, brand, creator collab or client update.");
+      const need = str(body.need);
+      if (!need) return bad("Say what the message should ask or say.", "Fill in the \"What should it say\" box.");
+      const draft: MailDraftBody = { kind, need };
+      if (str(body.to)) draft.to = str(body.to);
+      if (str(body.toName)) draft.toName = str(body.toName);
+      if (str(body.tone)) draft.tone = str(body.tone);
+      if (str(body.handle)) {
+        const platform = str(body.platform).toLowerCase();
+        const handle = normalizeHandle(str(body.handle));
+        if (!(CREATOR_PLATFORM_IDS as readonly string[]).includes(platform) || !/^[a-z0-9._-]{1,80}$/i.test(handle)) return bad("The creator needs a platform and a handle.", "Pick a platform and type a handle like ana.cooks.");
+        draft.creator = { platform, handle };
+      }
+      return { status: 200, body: { ok: true, draft: await createMailDraft(deps, draft) } };
+    }
+    if (pathname === "/api/mail/identity") {
+      const input = { fromName: str(body.fromName) || undefined, replyTo: str(body.replyTo).toLowerCase() || undefined, postalAddress: str(body.postalAddress) || undefined, org: typeof body.org === "string" ? body.org.trim() : undefined };
+      return { status: 200, body: { ok: true, ...(await saveMailIdentity(deps, input)) } };
+    }
+    if (pathname === "/api/mail/edit" || pathname === "/api/mail/approve" || pathname === "/api/mail/send" || pathname === "/api/mail/discard") {
+      const id = str(body.id);
+      if (!id) return bad("Pick a draft.", "Choose one from the list.");
+      if (pathname === "/api/mail/edit") {
+        const patch: MailDraftPatch = {};
+        if (typeof body.to === "string") patch.to = body.to.trim();
+        if (typeof body.toName === "string") patch.toName = body.toName.trim() || null;
+        if (typeof body.subject === "string") patch.subject = body.subject.trim();
+        if (typeof body.text === "string") patch.text = body.text;
+        if (Object.keys(patch).length === 0) return bad("Nothing to change.", "Edit the recipient, subject or text first.");
+        return { status: 200, body: { ok: true, draft: await editMailDraft(deps, id, patch) } };
+      }
+      if (pathname === "/api/mail/discard") return { status: 200, body: { ok: true, draft: await discardMailDraft(deps, id) } };
+      // Approve and Send only run for a click the person confirmed, on the one draft named, nothing else.
+      if (body.confirm !== true) return bad("Confirm first.", "Press the button again and confirm the recipient and subject.");
+      return { status: 200, body: { ok: true, draft: pathname === "/api/mail/approve" ? await approveMailDraft(deps, id) : await sendMailDraft(deps, id) } };
+    }
+    return null;
+  } catch (error) {
+    return refusal(error);
+  }
+}