Stream progress to the browser

src/handler.js

// The request handler: everything the server does for "make me a deck", as plain
// functions with no HTTP in them. They can be tested without a server, and moved
// to Express, Next.js or a serverless function without changing a line.
//
// streamDeck() reports progress as it happens; handleDeckRequest() is the same work
// for callers that just want the final answer. One code path, two ways to consume it.

import { validateRequest } from "./limits.js";
import { generateDeck } from "./pipeline.js";
import { planToPptx } from "./pptx.js";
import { createQuota } from "./quota.js";
import { createDeckStore, requestKey } from "./cache.js";
import { classifyError, friendlyMessage } from "./errors.js";
import { compileDeck } from "./compile.js";

/** Real dependencies. Tests pass their own. */
export function createDeps() {
  return {
    generateDeck,
    planToPptx,
    quota: createQuota({ limit: 10 }),
    store: createDeckStore({ maxEntries: 200 }),
  };
}

const sharedDeps = createDeps();

/**
 * Generate a deck, calling `send(event)` as things happen:
 *   { type: "stage", stage, status }          a pipeline stage started or finished
 *   { type: "slide", number, slide }          a slide was written (with its render plan, for a live preview)
 *   { type: "retry" | "fallback", … }         something went wrong and we're recovering
 *   { type: "done", deck }                    the finished deck
 *   { type: "error", status, error }          it failed; `error` is safe to show a person
 * The last event is always "done" or "error".
 */
export async function streamDeck({ body, userId = "anonymous" }, send, deps = sharedDeps) {
  const request = validateRequest(body);
  if (!request.ok) return send({ type: "error", status: 400, error: request.error });

  const key = requestKey(request.value);
  const saved = deps.store.get(key);
  if (saved) return send({ type: "done", deck: { ...publicDeck(saved), cached: true } });

  const allowance = deps.quota.consume(userId);
  if (!allowance.ok) return send({ type: "error", status: 429, error: "You've reached today's deck limit. Try again tomorrow." });

  try {
    const deck = await deps.generateDeck(request.value.topic, {
      ...request.value,
      onEvent: (event) => send(toProgressEvent(event, request.value.theme)),
    });
    const file = await deps.planToPptx({ slides: deck.slides });
    const entry = { id: key, ...deck, file };
    deps.store.set(key, entry);
    send({ type: "done", deck: { ...publicDeck(entry), remaining: allowance.remaining } });
  } catch (error) {
    deps.quota.refund(userId);
    const info = classifyError(error);
    const status = info.kind === "rate_limit" || info.kind === "quota_exhausted" ? 429 : 502;
    send({ type: "error", status, error: friendlyMessage(info) });
  }
}

/** The same work, for callers that only want the final result: { status, json }. */
export async function handleDeckRequest(input, deps = sharedDeps) {
  let last;
  await streamDeck(input, (event) => {
    if (event.type === "done" || event.type === "error") last = event;
  }, deps);
  return last.type === "done" ? { status: 200, json: last.deck } : { status: last.status, json: { error: last.error } };
}

/** Pipeline events → what the browser needs. A streamed slide is compiled so it can be previewed right away. */
function toProgressEvent(event, theme) {
  if (event.type !== "slide") return event;
  const { slides } = compileDeck(`<deck>${event.xml}</deck>`, theme);
  return { type: "slide", number: event.number, slide: slides[0] };
}

/** What the browser gets: never the raw model output or internal errors. */
function publicDeck(entry) {
  return {
    id: entry.id,
    title: entry.outline?.title ?? "Untitled deck",
    slides: entry.slides,
    problems: entry.problems,
    sources: entry.sources ?? [],
    usage: entry.usage,
    file: entry.file,
  };
}