create-nexwire 4.0.0

package/express/src/framework/maker-cli/stubs/example/controller.ts.stub

@@ -0,0 +1,418 @@
+import crypto from "node:crypto";
+import type { Request, Response } from "express";
+import { cache, dispatchCommand, dispatchEvent, session, storage } from "@/framework/facade.js";
+
+/**
+ * Example controller guide:
+ * - req.body / req.params: validated payloads from the route schema (validation middleware runs first).
+ * - dispatchEvent(name, payload, options): emits domain events.
+ * - dispatchCommand(name, payload, { async, queue }): queues command-style work.
+ * - storage.generateForDownload(...): creates one-time temp download token.
+ * - storage.consumeGenerated(token): reads temp file and deletes it.
+ * - cache.put/get/remember: lightweight state for async flows (PDF status).
+ * - securityMiddleware: sets CSP, HSTS, X-Frame headers (toggle via SECURITY_HEADERS env).
+ */
+
+type PdfRequest = {
+  title: string;
+  rows: number;
+  chunkSize: number;
+};
+
+function pdfStatusKey(requestId: string) {
+  return "{{module}}:pdf:status:" + requestId;
+}
+
+function sessionId(res: Response) {
+  return res.locals.sessionId as string;
+}
+
+/**
+ * Why: Demonstrates event dispatch with both queue and websocket broadcast.
+ * When: Use as the baseline event example for async + realtime flow.
+ * Where: POST /{{module}}/event.
+ */
+export const fire = async (req: Request, res: Response) => {
+  // Route validates body using ExampleEventSchema in route stub.
+  const body = req.body;
+
+  // Session example: keeps last payload for this visitor/session.
+  await session.put(sessionId(res), "lastExampleEvent", body);
+
+  // Event options shown here:
+  // - queue: true -> send to default async event queue
+  // - broadcast: { all: true } -> fanout to realtime listeners
+  await dispatchEvent("{{module}}.created", body, {
+    queue: true,
+    broadcast: { all: true }
+  });
+
+  res.status(202).json({ message: "Event dispatched", data: body });
+};
+
+/**
+ * Why: Demonstrates command-style background processing via queue.
+ * When: Use when work should run asynchronously and return 202 immediately.
+ * Where: POST /{{module}}/queue/command.
+ */
+export const queueCommand = async (req: Request, res: Response) => {
+  const body = req.body;
+
+  // Command options:
+  // - async: true -> run in worker, do not block request
+  // - queue: "default" -> explicit queue channel
+  await dispatchCommand("{{module}}.process", body, {
+    async: true,
+    queue: "default"
+  });
+
+  res.status(202).json({ message: "Queue command dispatched", data: body });
+};
+
+/**
+ * Why: Demonstrates queued events without realtime fanout.
+ * When: Use when consumers should process event in workers only.
+ * Where: POST /{{module}}/event/queued.
+ */
+export const fireQueued = async (req: Request, res: Response) => {
+  const body = req.body;
+
+  await dispatchEvent("{{module}}.created", body, { queue: "default" });
+
+  res.status(202).json({ message: "Queued event dispatched", data: body });
+};
+
+/**
+ * Why: Demonstrates one event feeding both queue workers and broadcast listeners.
+ * When: Use when background processing and client updates are both needed.
+ * Where: POST /{{module}}/event/queued-broadcast.
+ */
+export const fireQueuedBroadcast = async (req: Request, res: Response) => {
+  const body = req.body;
+
+  await dispatchEvent("{{module}}.created", body, {
+    queue: "default",
+    broadcast: { all: true }
+  });
+
+  res.status(202).json({ message: "Queued broadcast event dispatched", data: body });
+};
+
+/**
+ * Why: Demonstrates broadcast-only realtime events.
+ * When: Use for transient notifications with no worker processing.
+ * Where: POST /{{module}}/event/broadcast.
+ */
+export const fireBroadcast = async (_req: Request, res: Response) => {
+  const payload = {
+    message: "Examples broadcast fired",
+    firedAt: new Date().toISOString()
+  };
+
+  await dispatchEvent("{{module}}.realtime", payload, { broadcast: { all: true } });
+
+  res.json({ message: "Broadcast event dispatched", data: payload });
+};
+
+/**
+ * Why: Demonstrates multipart upload with storage facade.
+ * When: Use when API accepts binary files from forms/clients.
+ * Where: POST /{{module}}/upload.
+ */
+export const upload = async (req: Request, res: Response) => {
+  const file = (req.body as any)?.file;
+
+  if (!(file instanceof File)) {
+    return res.status(422).json({ message: "File is required" });
+  }
+
+  // Writes to public disk. Name is auto-generated when omitted.
+  const path = await storage.disk("public").putFile("uploads", file);
+
+  res.json({
+    message: "File uploaded successfully",
+    path,
+    url: storage.disk("public").url(path)
+  });
+};
+
+/**
+ * Why: Demonstrates Excel import by reading uploaded workbook rows.
+ * When: Use when clients submit .xlsx files for server-side processing.
+ * Where: POST /{{module}}/import/excel.
+ */
+export const importExcel = async (req: Request, res: Response) => {
+  let ExcelJS: any;
+  try {
+    ({ default: ExcelJS } = await import("exceljs"));
+  } catch {
+    return res.status(500).json({ message: "Missing optional dependency 'exceljs'. Install with: bun add exceljs" });
+  }
+
+  const file = (req.body as any)?.file;
+  if (!(file instanceof File)) {
+    return res.status(422).json({ message: "File is required" });
+  }
+
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const workbook = new ExcelJS.Workbook();
+  await workbook.xlsx.load(buffer);
+  const sheet = workbook.worksheets[0];
+  if (!sheet) return res.status(422).json({ message: "Workbook has no sheets" });
+
+  const headerRow = sheet.getRow(1);
+  const headers = headerRow.values.slice(1).map((value: unknown) => String(value || "").trim());
+  const rows: Record<string, string | number | null>[] = [];
+  sheet.eachRow((row: any, rowNumber: number) => {
+    if (rowNumber === 1) return;
+    const values = row.values.slice(1);
+    const record: Record<string, string | number | null> = {};
+    for (let i = 0; i < headers.length; i++) {
+      const value = values[i];
+      record[headers[i] || `column_${i + 1}`] = value == null ? null : (typeof value === "object" && "text" in value ? String(value.text) : value);
+    }
+    rows.push(record);
+  });
+
+  res.json({
+    message: "Excel imported",
+    data: {
+      sheetName: sheet.name,
+      headers,
+      totalRows: rows.length,
+      preview: rows.slice(0, 20)
+    }
+  });
+};
+
+/**
+ * Why: Demonstrates short-lived generated downloads with one-time token consume.
+ * When: Use for temporary export artifacts that should not persist.
+ * Where: POST /{{module}}/download/generate.
+ */
+export const generateDownload = async (_req: Request, res: Response) => {
+  const csv = ["id,title", "1,nexwire report", "2,generated and temporary"].join("\n");
+  const token = await storage.generateForDownload({
+    prefix: "{{module}}-report",
+    extension: "csv",
+    data: csv
+  });
+  res.json({
+    message: "Temporary file generated",
+    token,
+    downloadUrl: `/{{module}}/download/${encodeURIComponent(token)}`
+  });
+};
+
+/**
+ * Why: Consumes a temporary token and returns the generated CSV file.
+ * When: Called after generateDownload to perform one-time download.
+ * Where: GET /{{module}}/download/{*token}.
+ */
+export const downloadGenerated = async (req: Request, res: Response) => {
+  const token = decodeURIComponent(req.params.token);
+  try {
+    const file = await storage.consumeGenerated(token);
+    res.type("text/csv").attachment("{{module}}-report.csv").send(file);
+  } catch {
+    res.status(404).json({ message: "Download token expired or invalid" });
+  }
+};
+
+/**
+ * Why: Demonstrates styled Excel export generation and temporary delivery.
+ * When: Use when spreadsheet output with formatting/totals is needed.
+ * Where: POST /{{module}}/download/excel/generate.
+ */
+export const generateExcelDownload = async (req: Request, res: Response) => {
+  let ExcelJS: any;
+  try {
+    ({ default: ExcelJS } = await import("exceljs"));
+  } catch {
+    return res.status(500).json({ message: "Missing optional dependency 'exceljs'. Install with: bun add exceljs" });
+  }
+
+  const title = (req.body as { title?: string })?.title ?? "";
+  // remember(key, ttl, factory) caches expensive work for repeated requests.
+  const rows = await cache.remember("{{module}}:index", 60, async () => [
+    { id: 1, title: "nexwire framework ready" },
+    { id: 2, title: "modules are auto-discovered" }
+  ]);
+
+  const workbook = new ExcelJS.Workbook();
+  const sheet = workbook.addWorksheet("Examples");
+  sheet.mergeCells("A1:C1");
+  sheet.getCell("A1").value = title;
+  sheet.getCell("A1").font = { bold: true, size: 14, color: { argb: "FFFFFFFF" } };
+  sheet.getCell("A1").alignment = { horizontal: "center", vertical: "middle" };
+  sheet.getCell("A1").fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FF1F4E78" } };
+  sheet.addRow(["ID", "Title", "Length"]);
+  sheet.getRow(2).font = { bold: true, color: { argb: "FFFFFFFF" } };
+  sheet.getRow(2).alignment = { horizontal: "center" };
+  sheet.getRow(2).fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FF2E75B6" } };
+  for (const row of rows) sheet.addRow([row.id, row.title, row.title.length]);
+
+  const dataStart = 3;
+  const dataEnd = dataStart + rows.length - 1;
+  const subtotalRow = dataEnd + 1;
+  const grandTotalRow = subtotalRow + 1;
+  sheet.getCell(`A${subtotalRow}`).value = "Subtotal";
+  sheet.getCell(`B${subtotalRow}`).value = rows.length;
+  sheet.getCell(`C${subtotalRow}`).value = { formula: `SUM(C${dataStart}:C${dataEnd})` };
+  sheet.getCell(`A${grandTotalRow}`).value = "Grand Total";
+  sheet.getCell(`B${grandTotalRow}`).value = rows.length;
+  sheet.getCell(`C${grandTotalRow}`).value = { formula: `SUM(C${dataStart}:C${dataEnd})` };
+  for (const rowNumber of [subtotalRow, grandTotalRow]) {
+    sheet.getRow(rowNumber).font = { bold: true };
+    sheet.getRow(rowNumber).fill = { type: "pattern", pattern: "solid", fgColor: { argb: rowNumber === grandTotalRow ? "FFFCE4D6" : "FFE2EFDA" } };
+  }
+  sheet.columns = [{ width: 10 }, { width: 48 }, { width: 14 }];
+  sheet.views = [{ state: "frozen", ySplit: 2 }];
+
+  const buffer = Buffer.from(await workbook.xlsx.writeBuffer());
+  const token = await storage.generateForDownload({
+    prefix: "{{module}}-report",
+    extension: "xlsx",
+    data: buffer
+  });
+  res.json({
+    message: "Excel generated",
+    token,
+    downloadUrl: `/{{module}}/download/excel/${encodeURIComponent(token)}`
+  });
+};
+
+/**
+ * Why: Consumes a temporary token and returns the generated XLSX file.
+ * When: Called after generateExcelDownload for one-time Excel download.
+ * Where: GET /{{module}}/download/excel/{*token}.
+ */
+export const downloadGeneratedExcel = async (req: Request, res: Response) => {
+  const token = decodeURIComponent(req.params.token);
+  try {
+    const file = await storage.consumeGenerated(token);
+    res.type("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet").attachment("{{module}}-report.xlsx").send(file);
+  } catch {
+    res.status(404).json({ message: "Download token expired or invalid" });
+  }
+};
+
+/**
+ * Why: Starts hybrid PDF generation for heavy design + large data.
+ * When: Use when reports should be rendered with HTML/CSS and processed in background.
+ * Where: POST /{{module}}/download/pdf/generate.
+ */
+export const generatePdfDownload = async (req: Request, res: Response) => {
+  const body = req.body as PdfRequest;
+  const requestId = crypto.randomUUID();
+
+  // Queue mode path: store status in cache, then worker updates it.
+  if (cache.isAvailable()) {
+    await cache.put(pdfStatusKey(requestId), {
+      state: "pending",
+      createdAt: new Date().toISOString(),
+      mode: "queued"
+    }, 1800);
+    await dispatchCommand("{{module}}.pdf.generate", { requestId, ...body }, {
+      async: true,
+      queue: "default"
+    });
+    return res.status(202).json({
+      message: "PDF generation queued",
+      requestId,
+      mode: "queued",
+      statusUrl: `/{{module}}/download/pdf/${requestId}`,
+      downloadUrl: `/{{module}}/download/pdf/${requestId}`
+    });
+  }
+
+  const token = await generatePdfToken(body);
+  res.status(202).json({
+    message: "PDF generated",
+    requestId,
+    mode: "inline",
+    statusUrl: `/{{module}}/download/pdf/${requestId}`,
+    downloadUrl: `/{{module}}/download/pdf/${encodeURIComponent(token)}`
+  });
+};
+
+/**
+ * Why: Polls queued PDF status, then serves one-time PDF download when ready.
+ * When: Use after generatePdfDownload returns queued request id.
+ * Where: GET /{{module}}/download/pdf/{requestId}.
+ */
+export const downloadGeneratedPdf = async (req: Request, res: Response) => {
+  const requestId = decodeURIComponent(req.params.requestId);
+  if (cache.isAvailable()) {
+    // Status API contract:
+    // - pending -> return 202
+    // - ready + token -> return file
+    // - failed -> return 500 with message
+    const status = await cache.get<{ state: string; token?: string; message?: string }>(pdfStatusKey(requestId));
+
+    if (!status) return res.status(404).json({ message: "Unknown PDF request id" });
+    if (status.state === "pending") return res.status(202).json({ message: "PDF is still generating", state: "pending" });
+    if (status.state === "failed") return res.status(500).json({ message: status.message || "PDF generation failed" });
+    
+    if (status.token) {
+      try {
+        const file = await storage.consumeGenerated(status.token);
+        await cache.forget(pdfStatusKey(requestId));
+        res.type("application/pdf").attachment("{{module}}-report.pdf").send(file);
+        return;
+      } catch {
+        return res.status(404).json({ message: "PDF token expired or invalid" });
+      }
+    }
+  }
+
+  try {
+    const file = await storage.consumeGenerated(requestId);
+    res.type("application/pdf").attachment("{{module}}-report.pdf").send(file);
+  } catch {
+    res.status(404).json({ message: "PDF token expired or invalid" });
+  }
+};
+
+export async function generatePdfToken(payload: PdfRequest) {
+  let chromium: any;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    throw new Error("Missing optional dependency 'playwright'. Install with: bun add playwright and run: bunx playwright install chromium");
+  }
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const page = await browser.newPage();
+    await page.setContent(buildPdfHtml(payload), { waitUntil: "networkidle" });
+    const pdf = await page.pdf({
+      format: "A4",
+      printBackground: true,
+      margin: { top: "16mm", right: "12mm", bottom: "16mm", left: "12mm" }
+    });
+    return storage.generateForDownload({
+      prefix: "{{module}}-report",
+      extension: "pdf",
+      data: pdf
+    });
+  } finally {
+    await browser.close();
+  }
+}
+
+function buildPdfHtml(payload: PdfRequest) {
+  const rows = Array.from({ length: payload.rows }, (_, i) => ({
+    id: i + 1,
+    label: `Record ${i + 1}`,
+    value: ((i + 1) * 17) % 1000
+  }));
+  const chunks: typeof rows[] = [];
+  for (let i = 0; i < rows.length; i += payload.chunkSize) {
+    chunks.push(rows.slice(i, i + payload.chunkSize));
+  }
+  const sections = chunks.map((chunk, index) => {
+    const tableRows = chunk.map(item => `<tr><td>${item.id}</td><td>${item.label}</td><td>${item.value}</td></tr>`).join("");
+    return `<section class="page"><h2>Batch ${index + 1}</h2><table><thead><tr><th>ID</th><th>Label</th><th>Value</th></tr></thead><tbody>${tableRows}</tbody></table></section>`;
+  }).join("");
+  return `<!doctype html><html><head><meta charset="utf-8" /><style>body{font-family:Arial,sans-serif;color:#1f2937;margin:0}.hero{padding:24px;background:linear-gradient(120deg,#0f766e,#1d4ed8);color:#fff}.hero h1{margin:0 0 4px 0;font-size:22px}.hero p{margin:0;font-size:12px;opacity:.9}.page{padding:16px 20px;page-break-after:always}.page:last-child{page-break-after:auto}h2{margin:0 0 10px 0;font-size:14px;color:#0f172a}table{width:100%;border-collapse:collapse;font-size:11px}th,td{border:1px solid #cbd5e1;padding:6px}th{background:#e2e8f0;text-align:left}tr:nth-child(even){background:#f8fafc}</style></head><body><div class="hero"><h1>${payload.title}</h1><p>Rows: ${payload.rows} | Chunk size: ${payload.chunkSize}</p></div>${sections}</body></html>`;
+}

package/express/src/framework/maker-cli/stubs/example/job.ts.stub

@@ -0,0 +1,75 @@
+import { cache, dispatchEvent, shouldQueue } from "@/framework/facade.js";
+import { generatePdfToken } from "@/modules/{{module}}/controllers/{{module}}.controller.js";
+
+/**
+ * event: Event name this worker listens to.
+ * queue: Queue name where jobs are consumed from.
+ * handler: Async processor that receives `job.data`.
+ */
+shouldQueue("{{module}}.process", "default", async (job) => {
+  const waitSeconds = Number(job.data.waitSeconds || 1);
+  await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
+
+  await cache.put("{{module}}:last-command-job", {
+    payload: job.data,
+    handledAt: new Date().toISOString()
+  }, 120);
+
+  /**
+   * dispatchEvent name: Event id to publish to listeners.
+   * payload: Data sent to queue/broadcast consumers.
+   * queue: Optional queue target for async event consumers.
+   * broadcast: Optional realtime fanout (all/users/roles/rooms).
+   */
+  await dispatchEvent("{{module}}.process.finished", {
+    ...job.data,
+    handledAt: new Date().toISOString()
+  }, {
+    broadcast: { all: true }
+  });
+
+  return { ok: true, mode: "queue" };
+});
+
+shouldQueue("{{module}}.created", "default", async (job) => {
+  await cache.put("{{module}}:last-created-event", job.data, 120);
+  return { ok: true, mode: "event-queue" };
+});
+
+shouldQueue("{{module}}.scheduler.tick", "default", async (job) => {
+  await cache.put("{{module}}:last-scheduler-job", job.data, 120);
+  return { ok: true, mode: "scheduler-queue" };
+});
+
+shouldQueue("{{module}}.pdf.generate", "default", async (job) => {
+  const requestId = String(job.data.requestId || "");
+
+  if (!requestId) {
+    return { ok: false, mode: "pdf-queue", message: "Missing requestId" };
+  }
+
+  const key = `{{module}}:pdf:status:${requestId}`;
+
+  try {
+    const token = await generatePdfToken({
+      title: String(job.data.title || "Example PDF Report"),
+      rows: Number(job.data.rows || 1000),
+      chunkSize: Number(job.data.chunkSize || 250)
+    });
+
+    await cache.put(key, {
+      state: "ready",
+      token,
+      readyAt: new Date().toISOString()
+    }, 1800);
+
+    return { ok: true, mode: "pdf-queue" };
+  } catch (error) {
+    await cache.put(key, {
+      state: "failed",
+      message: error instanceof Error ? error.message : "Unknown error"
+    }, 1800);
+    return { ok: false, mode: "pdf-queue" };
+  }
+});
+

package/express/src/framework/maker-cli/stubs/example/route.api.ts.stub

@@ -0,0 +1,207 @@
+import { createRoute, createRouter, HttpStatusCodes, jsonContent, z } from "@/framework/facade.js";
+import { env } from "@/env.js";
+import { downloadGenerated, downloadGeneratedExcel, downloadGeneratedPdf, fire, fireBroadcast, fireQueued, fireQueuedBroadcast, generateDownload, generateExcelDownload, generatePdfDownload, importExcel, queueCommand, upload } from "@/modules/{{module}}/controllers/{{module}}.controller.js";
+import { DownloadTokenSchema, ExcelDownloadRequestSchema, ExampleEventSchema, PdfGenerateAcceptedSchema, PdfGenerateRequestSchema, QueueCommandRequestSchema, UploadResponseSchema } from "@/modules/{{module}}/controllers/{{module}}.schema.js";
+
+const eventRoute = createRoute({
+  path: "/event",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: jsonContent(ExampleEventSchema, "Examples event payload")
+  },
+  responses: {
+    [HttpStatusCodes.ACCEPTED]: jsonContent(z.object({ message: z.string(), data: ExampleEventSchema }), "Event accepted")
+  }
+});
+
+const queueCommandRoute = createRoute({
+  path: "/queue/command",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: jsonContent(QueueCommandRequestSchema, "Queue command payload")
+  },
+  responses: {
+    [HttpStatusCodes.ACCEPTED]: jsonContent(z.object({ message: z.string(), data: QueueCommandRequestSchema }), "Queue command dispatched")
+  }
+});
+
+const queuedEventRoute = createRoute({
+  path: "/event/queued",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: jsonContent(ExampleEventSchema, "Queued event payload")
+  },
+  responses: {
+    [HttpStatusCodes.ACCEPTED]: jsonContent(z.object({ message: z.string(), data: ExampleEventSchema }), "Queued event accepted")
+  }
+});
+
+const queuedBroadcastEventRoute = createRoute({
+  path: "/event/queued-broadcast",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: jsonContent(ExampleEventSchema, "Queued broadcast event payload")
+  },
+  responses: {
+    [HttpStatusCodes.ACCEPTED]: jsonContent(z.object({ message: z.string(), data: ExampleEventSchema }), "Queued broadcast event accepted")
+  }
+});
+
+const broadcastRoute = createRoute({
+  path: "/event/broadcast",
+  method: "post",
+  tags: ["Examples"],
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent(z.object({
+      message: z.string(),
+      data: z.object({ message: z.string(), firedAt: z.string() })
+    }), "Broadcast event dispatched")
+  }
+});
+
+const uploadRoute = createRoute({
+  path: "/upload",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: {
+      content: {
+        "multipart/form-data": {
+          schema: z.object({ file: z.any().openapi({ type: "string", format: "binary" }) })
+        }
+      }
+    }
+  },
+  responses: {
+    [HttpStatusCodes.OK]: {
+      description: "File uploaded",
+      content: { "application/json": { schema: UploadResponseSchema } }
+    }
+  }
+});
+
+const importExcelRoute = createRoute({
+  path: "/import/excel",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: {
+      content: {
+        "multipart/form-data": {
+          schema: z.object({ file: z.any().openapi({ type: "string", format: "binary" }) })
+        }
+      }
+    }
+  },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent(z.object({
+      message: z.string(),
+      data: z.object({
+        sheetName: z.string(),
+        headers: z.array(z.string()),
+        totalRows: z.number(),
+        preview: z.array(z.record(z.string(), z.union([z.string(), z.number(), z.null()])))
+      })
+    }), "Excel import preview")
+  }
+});
+
+const generateDownloadRoute = createRoute({
+  path: "/download/generate",
+  method: "post",
+  tags: ["Examples"],
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent(DownloadTokenSchema, "Temporary download token")
+  }
+});
+
+const downloadRoute = createRoute({
+  path: "/download/{*token}",
+  method: "get",
+  tags: ["Examples"],
+  request: {
+    params: z.object({ token: z.string() })
+  },
+  responses: {
+    [HttpStatusCodes.OK]: { description: "Downloads generated file and deletes it" },
+    [HttpStatusCodes.NOT_FOUND]: jsonContent(z.object({ message: z.string() }), "Invalid token")
+  }
+});
+
+const generateExcelRoute = createRoute({
+  path: "/download/excel/generate",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: jsonContent(ExcelDownloadRequestSchema, "Excel generation payload")
+  },
+  responses: {
+    [HttpStatusCodes.OK]: jsonContent(DownloadTokenSchema, "Excel temporary download token")
+  }
+});
+
+const downloadExcelRoute = createRoute({
+  path: "/download/excel/{*token}",
+  method: "get",
+  tags: ["Examples"],
+  request: {
+    params: z.object({ token: z.string() })
+  },
+  responses: {
+    [HttpStatusCodes.OK]: { description: "Downloads generated Excel file and deletes it" },
+    [HttpStatusCodes.NOT_FOUND]: jsonContent(z.object({ message: z.string() }), "Invalid token")
+  }
+});
+
+const generatePdfRoute = createRoute({
+  path: "/download/pdf/generate",
+  method: "post",
+  tags: ["Examples"],
+  request: {
+    body: jsonContent(PdfGenerateRequestSchema, "Hybrid PDF generation payload")
+  },
+  responses: {
+    [HttpStatusCodes.ACCEPTED]: jsonContent(PdfGenerateAcceptedSchema, "Queued or inline PDF response")
+  }
+});
+
+const downloadPdfRoute = createRoute({
+  path: "/download/pdf/{requestId}",
+  method: "get",
+  tags: ["Examples"],
+  request: {
+    params: z.object({ requestId: z.string() })
+  },
+  responses: {
+    [HttpStatusCodes.OK]: { description: "Downloads generated PDF" },
+    [HttpStatusCodes.ACCEPTED]: jsonContent(z.object({ message: z.string(), state: z.string() }), "Still generating"),
+    [HttpStatusCodes.NOT_FOUND]: jsonContent(z.object({ message: z.string() }), "Unknown request")
+  }
+});
+
+const enabled = env.ENABLE_EXAMPLES;
+const router = createRouter();
+
+if (enabled) {
+  router
+    .api(eventRoute, fire)
+    .api(queueCommandRoute, queueCommand)
+    .api(queuedEventRoute, fireQueued)
+    .api(queuedBroadcastEventRoute, fireQueuedBroadcast)
+    .api(broadcastRoute, fireBroadcast)
+    .api(uploadRoute, upload)
+    .api(importExcelRoute, importExcel)
+    .api(generateDownloadRoute, generateDownload)
+    .api(downloadRoute, downloadGenerated)
+    .api(generateExcelRoute, generateExcelDownload)
+    .api(downloadExcelRoute, downloadGeneratedExcel)
+    .api(generatePdfRoute, generatePdfDownload)
+    .api(downloadPdfRoute, downloadGeneratedPdf);
+}
+
+export default router;
+