@emeryld/rrroutes-openapi 2.3.1 → 2.3.3

package/dist/index.mjs

@@ -8,6 +8,11 @@ import { fileURLToPath } from "url";
 // src/docs/LeafDocsPage.tsx
 import { renderToStaticMarkup } from "react-dom/server";
 
+// src/docs/serializer.ts
+import {
+  routeSchemaParse
+} from "@emeryld/rrroutes-contract";
+
 // src/docs/schemaIntrospection.ts
 import * as z from "zod";
 function getDef(schema) {
@@ -136,30 +141,54 @@ function inferKind(schema) {
 function serializeLeaf(leaf) {
   const cfg = leaf.cfg;
   const tags = Array.isArray(cfg.tags) ? cfg.tags.slice() : [];
+  const stability = cfg.stability ?? "experimental";
+  const now = Date.now();
   return {
+    id: buildLeafId(leaf),
+    name: inferName(cfg, leaf.path),
+    description: cfg.description,
+    groupId: cfg.docsGroup,
+    tags: tags.length > 0 ? tags : void 0,
+    createdAt: now,
+    updatedAt: now,
     method: leaf.method,
-    // 'get' | 'post' | ...
     path: leaf.path,
-    cfg: {
-      description: cfg.description,
-      summary: cfg.summary,
-      docsGroup: cfg.docsGroup,
-      tags,
-      deprecated: cfg.deprecated,
-      stability: cfg.stability,
-      feed: !!cfg.feed,
-      docsMeta: cfg.docsMeta,
-      hasBody: !!cfg.bodySchema || !!cfg.bodyFiles?.length,
-      hasQuery: !!cfg.querySchema,
-      hasParams: !!cfg.paramsSchema,
-      hasOutput: !!cfg.outputSchema,
-      bodySchema: introspectSchema(cfg.bodySchema),
-      querySchema: introspectSchema(cfg.querySchema),
-      paramsSchema: introspectSchema(cfg.paramsSchema),
-      outputSchema: introspectSchema(cfg.outputSchema)
-    }
+    contract: {
+      body: serializeContractSchema(cfg.bodySchema),
+      query: serializeContractSchema(cfg.querySchema),
+      params: serializeContractSchema(cfg.paramsSchema),
+      output: serializeContractSchema(cfg.outputSchema),
+      bodyFiles: serializeBodyFiles(cfg)
+    },
+    feed: cfg.feed ?? void 0,
+    summary: cfg.summary,
+    stability,
+    hidden: cfg.docsHidden,
+    meta: serializeMeta(cfg.docsMeta)
   };
 }
+function serializeContractSchema(schema) {
+  return schema ? introspectSchema(routeSchemaParse(schema)) : void 0;
+}
+function serializeBodyFiles(cfg) {
+  if (!Array.isArray(cfg.bodyFiles) || cfg.bodyFiles.length === 0)
+    return void 0;
+  return cfg.bodyFiles.map(({ name, maxCount }) => ({ name, maxCount }));
+}
+function serializeMeta(meta) {
+  if (!meta) return {};
+  const entries = Object.entries(meta).filter(([, value]) => value !== void 0 && value !== null).map(([key, value]) => [
+    key,
+    typeof value === "string" ? value : JSON.stringify(value)
+  ]);
+  return Object.fromEntries(entries);
+}
+function buildLeafId(leaf) {
+  return `${leaf.method.toUpperCase()} ${leaf.path}`;
+}
+function inferName(cfg, path2) {
+  return cfg.summary || cfg.description || path2;
+}
 
 // src/docs/LeafDocsPage.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -173,25 +202,17 @@ function normalizeDocsBase(base) {
   if (base === "/") return "/";
   return base.endsWith("/") && base.length > 1 ? base.slice(0, -1) : base;
 }
-function normalizeBaseUrlSuffix(suffix) {
-  if (!suffix) return "";
-  const trimmed = suffix.endsWith("/") && suffix.length > 1 ? suffix.slice(0, -1) : suffix;
-  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-}
 var DocsDocument = ({
-  leavesJson,
-  presetsJson,
   assetBase,
   docsBase,
-  historyJson,
-  logsJson,
-  baseUrlSuffix,
-  webhooks,
   cspNonce
 }) => {
   const cssHref = `${assetBase}/docs.css`;
   const jsSrc = `${assetBase}/docs.js`;
-  const configJson = serializeConfig({ docsBasePath: docsBase, baseUrlSuffix, webhooks });
+  const configJson = serializeConfig({
+    docsBasePath: docsBase,
+    cspNonce
+  });
   return /* @__PURE__ */ jsxs("html", { lang: "en", children: [
     /* @__PURE__ */ jsxs("head", { children: [
       /* @__PURE__ */ jsx("meta", { charSet: "UTF-8" }),
@@ -201,42 +222,6 @@ var DocsDocument = ({
     ] }),
     /* @__PURE__ */ jsxs("body", { children: [
       /* @__PURE__ */ jsx("div", { id: "docs-root" }),
-      /* @__PURE__ */ jsx(
-        "script",
-        {
-          id: "leaf-data",
-          type: "application/json",
-          nonce: cspNonce,
-          dangerouslySetInnerHTML: { __html: leavesJson }
-        }
-      ),
-      /* @__PURE__ */ jsx(
-        "script",
-        {
-          id: "preset-data",
-          type: "application/json",
-          nonce: cspNonce,
-          dangerouslySetInnerHTML: { __html: presetsJson }
-        }
-      ),
-      /* @__PURE__ */ jsx(
-        "script",
-        {
-          id: "history-data",
-          type: "application/json",
-          nonce: cspNonce,
-          dangerouslySetInnerHTML: { __html: historyJson }
-        }
-      ),
-      /* @__PURE__ */ jsx(
-        "script",
-        {
-          id: "logs-data",
-          type: "application/json",
-          nonce: cspNonce,
-          dangerouslySetInnerHTML: { __html: logsJson }
-        }
-      ),
       /* @__PURE__ */ jsx(
         "script",
         {
@@ -250,627 +235,34 @@ var DocsDocument = ({
     ] })
   ] });
 };
-function serializeLeaves(leaves) {
-  return JSON.stringify(leaves.map(serializeLeaf)).replace(/<\//g, "<\\/");
-}
-function serializePresets(presets) {
-  return JSON.stringify(Array.isArray(presets) ? presets : []).replace(/<\//g, "<\\/");
-}
-function serializeHistorySeeds(historySeeds) {
-  return JSON.stringify(Array.isArray(historySeeds) ? historySeeds : []).replace(/<\//g, "<\\/");
-}
-function serializeLogSeeds(logSeeds) {
-  return JSON.stringify(Array.isArray(logSeeds) ? logSeeds : []).replace(/<\//g, "<\\/");
-}
 function serializeConfig(config) {
   return JSON.stringify(config).replace(/<\//g, "<\\/");
 }
-function createLeafDocsDocument(leaves, options = {}) {
+function createLeafDocsDocument(options = {}) {
   const assetBase = normalizeBase(options.assetBasePath ?? DEFAULT_ASSET_BASE);
-  const leavesJson = serializeLeaves(leaves);
-  const presetsJson = serializePresets(options.presets);
   const docsBase = normalizeDocsBase(options.docsBasePath);
-  const historyJson = serializeHistorySeeds(options.historySeeds);
-  const logsJson = serializeLogSeeds(options.logSeeds);
-  const baseUrlSuffix = normalizeBaseUrlSuffix(options.baseUrlSuffix);
-  const webhooks = options.webhooks;
   return /* @__PURE__ */ jsx(
     DocsDocument,
     {
-      leavesJson,
-      presetsJson,
       assetBase,
       docsBase,
-      historyJson,
-      logsJson,
-      baseUrlSuffix,
-      webhooks,
       cspNonce: options.cspNonce
     }
   );
 }
-function renderLeafDocsHTML(leaves, options = {}) {
-  const doc = createLeafDocsDocument(leaves, options);
+function renderLeafDocsHTML(options = {}) {
+  const doc = createLeafDocsDocument(options);
   const html = renderToStaticMarkup(doc);
   return `<!DOCTYPE html>${html}`;
 }
 
 // src/docs/docs.ts
-function renderLeafDocsHTML2(leaves, options = {}) {
-  return renderLeafDocsHTML(leaves, options);
+function renderLeafDocsHTML2(options = {}) {
+  return renderLeafDocsHTML(options);
 }
 
-// src/webhooks.ts
-import { z as z2 } from "zod";
-var logTypeSchema = z2.enum(["debug", "info", "warn", "error", "system"]);
-var historyFeedEntrySchema = z2.object({
-  id: z2.string(),
-  requestId: z2.string().optional(),
-  timestamp: z2.number(),
-  method: z2.string(),
-  path: z2.string(),
-  fullUrl: z2.string().optional(),
-  params: z2.record(z2.string(), z2.string()).optional(),
-  query: z2.record(z2.string(), z2.string()).optional(),
-  body: z2.string().optional(),
-  output: z2.string().optional(),
-  status: z2.number().optional(),
-  durationMs: z2.number(),
-  error: z2.string().optional()
-});
-var logFeedEntrySchema = z2.object({
-  id: z2.string(),
-  type: logTypeSchema,
-  message: z2.string(),
-  timestamp: z2.number(),
-  requestId: z2.string().optional(),
-  tags: z2.array(z2.string()).optional(),
-  metadata: z2.string().optional()
-});
-var historyFeedQuerySchema = z2.object({
-  cursor: z2.string().optional(),
-  limit: z2.number().int().positive().optional(),
-  methods: z2.array(z2.string()).optional(),
-  path: z2.string().optional(),
-  status: z2.string().optional(),
-  text: z2.string().optional(),
-  from: z2.number().optional(),
-  to: z2.number().optional(),
-  sortBy: z2.enum(["timestamp", "path", "duration"]).optional(),
-  sortDir: z2.enum(["asc", "desc"]).optional()
-});
-var logFeedQuerySchema = z2.object({
-  cursor: z2.string().optional(),
-  limit: z2.number().int().positive().optional(),
-  types: z2.array(logTypeSchema).optional(),
-  tags: z2.array(z2.string()).optional(),
-  requestId: z2.string().optional(),
-  text: z2.string().optional(),
-  from: z2.number().optional(),
-  to: z2.number().optional(),
-  sortDir: z2.enum(["asc", "desc"]).optional()
-});
-var webhookPageSchema = (itemSchema) => z2.object({
-  items: z2.array(itemSchema).default([]),
-  nextCursor: z2.string().optional(),
-  prevCursor: z2.string().optional(),
-  total: z2.number().optional()
-});
-var historyWebhookResponseSchema = webhookPageSchema(historyFeedEntrySchema);
-var logWebhookResponseSchema = webhookPageSchema(logFeedEntrySchema);
-
-// src/index.ts
-var trimTrailingSlash = (value) => value.endsWith("/") && value.length > 1 ? value.slice(0, -1) : value;
-function mountRRRoutesDocs({
-  router,
-  leaves,
-  presets = [],
-  options = {}
-}) {
-  const prefix = options.prefix ? trimTrailingSlash(options.prefix) : "";
-  const docsPath = options.path ?? "/__rrroutes/docs";
-  const normalizedDocsPath = trimTrailingSlash(docsPath);
-  const assetsMountPath = trimTrailingSlash(
-    options.assetBasePath ?? `${normalizedDocsPath}/assets`
-  );
-  const webhookBaseInput = options.logWebhook?.basePath ?? `${normalizedDocsPath}/webhooks`;
-  const webhookBasePath = trimTrailingSlash(
-    webhookBaseInput.startsWith("/") ? webhookBaseInput : `/${webhookBaseInput}`
-  );
-  const defaultHistoryLimit = 200;
-  const defaultLogLimit = 400;
-  const redactLogEntry = createLogRedactor(options.redactLogEntry);
-  const seededHistory = normalizeHistorySeeds(options.historySeeds, defaultHistoryLimit);
-  const seededLogs = normalizeLogSeeds(options.logSeeds, defaultLogLimit, redactLogEntry);
-  const inMemoryHistory = seededHistory.slice();
-  const inMemoryLogs = seededLogs.slice();
-  const historySeedsForUi = seededHistory.map((entry) => ({
-    ...entry,
-    fullUrl: entry.fullUrl || entry.path
-  }));
-  const webhookPaths = {
-    history: `${webhookBasePath}/history`,
-    logs: `${webhookBasePath}/logs`
-  };
-  const webhookSchemas = {
-    history: {
-      query: historyFeedQuerySchema,
-      response: historyWebhookResponseSchema,
-      entry: historyFeedEntrySchema
-    },
-    logs: {
-      query: logFeedQuerySchema,
-      response: logWebhookResponseSchema,
-      entry: logFeedEntrySchema
-    }
-  };
-  const webhookLeaves = {
-    history: {
-      method: "get",
-      path: webhookPaths.history,
-      cfg: {
-        summary: "RRRoutes docs history feed",
-        description: "Returns request history for the docs UI.",
-        querySchema: historyFeedQuerySchema,
-        outputSchema: historyWebhookResponseSchema,
-        tags: ["rrroutes", "docs"]
-      }
-    },
-    logs: {
-      method: "get",
-      path: webhookPaths.logs,
-      cfg: {
-        summary: "RRRoutes docs request logs",
-        description: "Returns request logs for the docs UI.",
-        querySchema: logFeedQuerySchema,
-        outputSchema: logWebhookResponseSchema,
-        tags: ["rrroutes", "docs"]
-      }
-    }
-  };
-  const publicDir = resolvePublicDir();
-  const assetsDir = path.join(publicDir, "assets");
-  const cspEnabled = options.csp !== false;
-  const authConfig = options.auth;
-  const authEnabled = authConfig?.enabled !== false;
-  const docsPassword = resolveDocsPassword(authConfig);
-  const authRealm = authConfig?.realm || "RRRoutes Docs";
-  if (authEnabled) {
-    const guard = docsPassword ? createPasswordGuard(docsPassword, authRealm) : createMissingPasswordGuard();
-    [normalizedDocsPath, assetsMountPath, webhookBasePath].forEach((p) => {
-      router.use(p, guard);
-    });
-  }
-  router.use(assetsMountPath, expressStatic(assetsDir, { immutable: true, maxAge: "365d" }));
-  const usingFakeHistory = !options.logWebhook?.history;
-  const usingFakeLogs = !options.logWebhook?.logs;
-  if (usingFakeHistory || usingFakeLogs) {
-    router.use((req, res, next) => {
-      if (req.path.startsWith(webhookBasePath) || req.path.startsWith(assetsMountPath) || req.path.startsWith(normalizedDocsPath)) {
-        return next();
-      }
-      const start = Date.now();
-      const requestIdHeader = req.headers["x-request-id"] || req.headers["x-requestid"] || req.headers["x-request_id"];
-      const requestId = Array.isArray(requestIdHeader) ? requestIdHeader[0] : requestIdHeader;
-      res.once("finish", () => {
-        const timestamp = Date.now();
-        const durationMs = Math.max(timestamp - start, 0);
-        const methodUpper = String(req.method || "GET").toUpperCase();
-        const pathOnly = req.path || req.originalUrl || "";
-        const status = res.statusCode;
-        const errorMsg = status >= 400 ? `${status}` : void 0;
-        if (usingFakeHistory) {
-          inMemoryHistory.unshift({
-            id: randomBytes(8).toString("hex"),
-            requestId: requestId ? String(requestId) : void 0,
-            timestamp,
-            method: methodUpper,
-            path: pathOnly,
-            fullUrl: req.originalUrl || pathOnly,
-            params: {},
-            query: coerceQueryRecord(req.query),
-            body: coercePayload(req.body),
-            output: "",
-            status,
-            durationMs,
-            error: errorMsg
-          });
-          if (inMemoryHistory.length > defaultHistoryLimit) inMemoryHistory.length = defaultHistoryLimit;
-        }
-        if (usingFakeLogs) {
-          const logType = status >= 500 ? "error" : status >= 400 ? "warn" : "info";
-          const metadata = JSON.stringify({
-            query: req.query,
-            durationMs
-          });
-          const redacted = redactLogEntry({
-            id: randomBytes(8).toString("hex"),
-            type: logType,
-            message: `${methodUpper} ${pathOnly} -> ${status}`,
-            timestamp,
-            requestId: requestId ? String(requestId) : void 0,
-            tags: [],
-            metadata
-          });
-          if (redacted) {
-            inMemoryLogs.unshift(redacted);
-            if (inMemoryLogs.length > defaultLogLimit) inMemoryLogs.length = defaultLogLimit;
-          }
-        }
-      });
-      next();
-    });
-  }
-  router.get(webhookPaths.history, async (req, res) => {
-    const handler = options.logWebhook?.history;
-    try {
-      applyDocsSecurityHeaders(res);
-      const query = parseHistoryWebhookQuery(req);
-      if (!handler) {
-        const filtered2 = applyHistoryQuery(inMemoryHistory, query, defaultHistoryLimit);
-        res.json(filtered2);
-        return;
-      }
-      const result = await handler({ query, req, res });
-      const normalized = normalizeWebhookPage(result);
-      const filtered = applyHistoryQuery(normalized.items, query, defaultHistoryLimit);
-      res.json(filtered);
-    } catch (err) {
-      console.error("Failed to serve history webhook", err);
-      res.status(500).json({ error: "Failed to load history feed" });
-    }
-  });
-  router.get(webhookPaths.logs, async (req, res) => {
-    const handler = options.logWebhook?.logs;
-    try {
-      applyDocsSecurityHeaders(res);
-      const query = parseLogWebhookQuery(req);
-      if (!handler) {
-        const filtered2 = applyLogsQuery(inMemoryLogs, query, defaultLogLimit);
-        res.json(filtered2);
-        return;
-      }
-      const result = await handler({ query, req, res });
-      const normalized = normalizeWebhookPage(result);
-      const redacted = applyLogRedaction(normalized.items, redactLogEntry);
-      const filtered = applyLogsQuery(redacted, query, defaultLogLimit);
-      res.json(filtered);
-    } catch (err) {
-      console.error("Failed to serve log webhook", err);
-      res.status(500).json({ error: "Failed to load logs feed" });
-    }
-  });
-  const docsRoutePaths = [normalizedDocsPath, `${normalizedDocsPath}/`, `${normalizedDocsPath}/*id`];
-  router.get(docsRoutePaths, (req, res) => {
-    const preparedLeaves = Array.isArray(leaves) ? leaves.filter((leaf) => leaf.cfg.docsHidden !== true) : [];
-    const preparedPresets = Array.isArray(presets) ? presets : [];
-    const onRequestResult = options.onRequest?.({ req, res, leaves: preparedLeaves, presets: preparedPresets }) ?? {};
-    const finalLeaves = onRequestResult.leaves ?? preparedLeaves;
-    const finalPresets = onRequestResult.presets ?? preparedPresets;
-    const hasCustomHtml = typeof onRequestResult.html === "string";
-    let nonce = onRequestResult.nonce;
-    if (!nonce && cspEnabled && !hasCustomHtml) {
-      nonce = randomBytes(16).toString("base64");
-    }
-    const html = hasCustomHtml ? onRequestResult.html : renderLeafDocsHTML2(finalLeaves, {
-      cspNonce: nonce,
-      assetBasePath: `${prefix}${assetsMountPath}`,
-      docsBasePath: `${prefix}${normalizedDocsPath}`,
-      baseUrlSuffix: prefix,
-      historySeeds: historySeedsForUi,
-      logSeeds: seededLogs,
-      presets: normalizePresets(finalPresets),
-      webhooks: {
-        history: `${prefix}${webhookPaths.history}`,
-        logs: `${prefix}${webhookPaths.logs}`
-      }
-    });
-    applyDocsSecurityHeaders(res);
-    if (cspEnabled && nonce) {
-      res.setHeader(
-        "Content-Security-Policy",
-        [
-          "default-src 'self'",
-          `script-src 'self' 'nonce-${nonce}'`,
-          `style-src 'self' 'nonce-${nonce}'`,
-          "img-src 'self' data:",
-          "connect-src 'self'",
-          "font-src 'self'",
-          "frame-ancestors 'self'"
-        ].join("; ")
-      );
-    }
-    res.send(html);
-  });
-  return { path: docsPath, webhooks: webhookPaths, webhookLeaves, webhookSchemas };
-}
-function resolvePublicDir() {
-  const moduleDir = typeof __dirname !== "undefined" ? __dirname : path.dirname(fileURLToPath(import.meta.url));
-  const fromModule = path.resolve(moduleDir, "../public");
-  if (fs.existsSync(fromModule)) return fromModule;
-  const fallback = path.resolve(moduleDir, "../dist/public");
-  if (fs.existsSync(fallback)) return fallback;
-  return fromModule;
-}
-function normalizePresets(presets) {
-  if (!Array.isArray(presets)) return [];
-  return presets.map((preset) => ({
-    name: preset.name,
-    description: preset.description,
-    tags: Array.isArray(preset.tags) ? preset.tags.slice() : [],
-    docsGroup: preset.docsGroup,
-    ops: Array.isArray(preset.ops) ? preset.ops.map((op) => ({
-      method: typeof op.method === "string" ? op.method.toUpperCase() : "",
-      path: typeof op.path === "string" ? op.path : "",
-      body: op.body,
-      query: op.query,
-      params: op.params
-    })) : []
-  }));
-}
-function parseHistoryWebhookQuery(req) {
-  const query = req.query || {};
-  const methods = parseStringList(query.methods);
-  const path2 = typeof query.path === "string" ? query.path : void 0;
-  const status = typeof query.status === "string" ? query.status : void 0;
-  const text = typeof query.text === "string" ? query.text : void 0;
-  const cursor = typeof query.cursor === "string" ? query.cursor : void 0;
-  const sortBy = isSortKey(query.sortBy) ? query.sortBy : void 0;
-  const sortDir = isSortDir(query.sortDir) ? query.sortDir : void 0;
-  const limit = parseLimit(query.limit);
-  const from = parseDateInput(query.from);
-  const to = parseDateInput(query.to);
-  return {
-    cursor,
-    methods,
-    path: path2,
-    status,
-    text,
-    limit,
-    from,
-    to,
-    sortBy,
-    sortDir
-  };
-}
-function parseLogWebhookQuery(req) {
-  const query = req.query || {};
-  const types = parseStringList(query.types);
-  const tags = parseStringList(query.tags);
-  const requestId = typeof query.requestId === "string" ? query.requestId : void 0;
-  const text = typeof query.text === "string" ? query.text : void 0;
-  const cursor = typeof query.cursor === "string" ? query.cursor : void 0;
-  const limit = parseLimit(query.limit);
-  const from = parseDateInput(query.from);
-  const to = parseDateInput(query.to);
-  const sortDir = isSortDir(query.sortDir) ? query.sortDir : void 0;
-  return {
-    cursor,
-    types,
-    tags,
-    requestId,
-    text,
-    limit,
-    from,
-    to,
-    sortDir
-  };
-}
-function parseStringList(value) {
-  if (typeof value !== "string") return void 0;
-  const parts = value.split(",").map((p) => p.trim()).filter(Boolean);
-  return parts.length ? parts : void 0;
-}
-function parseLimit(value) {
-  if (value === void 0) return void 0;
-  const num = Number(value);
-  if (!Number.isFinite(num) || num <= 0) return void 0;
-  return num;
-}
-function parseDateInput(value) {
-  if (typeof value !== "string") return void 0;
-  const numeric = Number(value);
-  if (Number.isFinite(numeric)) return numeric;
-  const timestamp = Date.parse(value);
-  if (Number.isNaN(timestamp)) return void 0;
-  return timestamp;
-}
-function isSortKey(value) {
-  return value === "timestamp" || value === "path" || value === "duration";
-}
-function isSortDir(value) {
-  return value === "asc" || value === "desc";
-}
-function normalizeWebhookPage(page) {
-  if (!page || typeof page !== "object") return { items: [] };
-  return {
-    items: Array.isArray(page.items) ? page.items : [],
-    nextCursor: page.nextCursor,
-    prevCursor: page.prevCursor,
-    total: page.total
-  };
-}
-function applyHistoryQuery(items, query, hardLimit) {
-  const fromTs = typeof query.from === "number" ? query.from : void 0;
-  const toTs = typeof query.to === "number" ? query.to : void 0;
-  const methods = query.methods ? new Set(query.methods.map((m) => m.toUpperCase())) : void 0;
-  const pathNeedle = (query.path || "").toLowerCase();
-  const textNeedle = (query.text || "").toLowerCase();
-  const statusNeedle = (query.status || "").trim();
-  const filtered = (Array.isArray(items) ? items : []).filter((entry) => {
-    if (methods?.size && !methods.has(String(entry.method || "").toUpperCase())) return false;
-    if (pathNeedle && !String(entry.path || "").toLowerCase().includes(pathNeedle)) return false;
-    if (statusNeedle) {
-      const statusStr = entry.status !== void 0 && entry.status !== null ? String(entry.status) : "ERR";
-      if (!statusStr.startsWith(statusNeedle)) return false;
-    }
-    if (Number.isFinite(fromTs) && entry.timestamp < fromTs) return false;
-    if (Number.isFinite(toTs) && entry.timestamp > toTs) return false;
-    if (textNeedle) {
-      const haystack = [
-        entry.path,
-        entry.fullUrl,
-        entry.body,
-        entry.output,
-        entry.error,
-        JSON.stringify(entry.params || {}),
-        JSON.stringify(entry.query || {})
-      ].filter(Boolean).join(" ").toLowerCase();
-      if (!haystack.includes(textNeedle)) return false;
-    }
-    return true;
-  });
-  const sortBy = query.sortBy || "timestamp";
-  const direction = query.sortDir === "asc" ? 1 : -1;
-  const sorted = filtered.slice().sort((a, b) => {
-    let delta = 0;
-    if (sortBy === "path") {
-      delta = String(a.path || "").localeCompare(String(b.path || ""));
-    } else if (sortBy === "duration") {
-      delta = (a.durationMs || 0) - (b.durationMs || 0);
-    } else {
-      delta = (a.timestamp || 0) - (b.timestamp || 0);
-    }
-    return delta * direction;
-  });
-  return paginateItems(sorted, query.cursor, query.limit, hardLimit, 25);
-}
-function applyLogsQuery(items, query, hardLimit) {
-  const fromTs = typeof query.from === "number" ? query.from : void 0;
-  const toTs = typeof query.to === "number" ? query.to : void 0;
-  const textNeedle = (query.text || "").toLowerCase();
-  const requestIdNeedle = (query.requestId || "").toLowerCase();
-  const types = query.types ? new Set(query.types) : void 0;
-  const tags = query.tags ? new Set(query.tags) : void 0;
-  const filtered = (Array.isArray(items) ? items : []).filter((entry) => {
-    if (types?.size && !types.has(entry.type)) return false;
-    const entryTags = Array.isArray(entry.tags) ? entry.tags : [];
-    if (tags?.size && !entryTags.some((tag) => tags.has(tag))) return false;
-    if (requestIdNeedle && !(entry.requestId || "").toLowerCase().includes(requestIdNeedle))
-      return false;
-    if (Number.isFinite(fromTs) && entry.timestamp < fromTs) return false;
-    if (Number.isFinite(toTs) && entry.timestamp > toTs) return false;
-    if (textNeedle) {
-      const haystack = [
-        entry.message,
-        entry.requestId,
-        entryTags.join(" "),
-        typeof entry.metadata === "string" ? entry.metadata : JSON.stringify(entry.metadata || "")
-      ].filter(Boolean).join(" ").toLowerCase();
-      if (!haystack.includes(textNeedle)) return false;
-    }
-    return true;
-  });
-  const direction = query.sortDir === "asc" ? 1 : -1;
-  const sorted = filtered.slice().sort((a, b) => (a.timestamp - b.timestamp) * direction);
-  return paginateItems(sorted, query.cursor, query.limit, hardLimit, 50);
-}
-function paginateItems(items, cursor, limit, hardLimit, fallbackLimit) {
-  const safeLimit = clampLimit(limit, hardLimit, fallbackLimit);
-  const start = parseCursor(cursor);
-  const end = start + safeLimit;
-  const slice = items.slice(start, end);
-  const nextCursor = end < items.length ? String(end) : void 0;
-  const prevCursor = start > 0 ? String(Math.max(start - safeLimit, 0)) : void 0;
-  return {
-    items: slice,
-    nextCursor,
-    prevCursor,
-    total: items.length
-  };
-}
-function clampLimit(value, hardLimit, fallback) {
-  if (!Number.isFinite(value)) return Math.min(hardLimit, fallback);
-  const safe = Math.max(1, Math.min(hardLimit, value));
-  return safe;
-}
-function parseCursor(cursor) {
-  const num = Number(cursor);
-  if (Number.isFinite(num) && num >= 0) return Math.floor(num);
-  return 0;
-}
-function normalizeHistorySeeds(seeds, hardLimit) {
-  if (!Array.isArray(seeds)) return [];
-  return seeds.slice(0, hardLimit).map((entry, idx) => ({
-    id: entry.id || randomBytes(8).toString("hex"),
-    requestId: typeof entry.requestId === "string" ? entry.requestId : void 0,
-    timestamp: entry.timestamp ?? Date.now() - idx * 1e3,
-    method: entry.method || "GET",
-    path: entry.path || "/",
-    fullUrl: entry.fullUrl || entry.path || "/",
-    params: entry.params || {},
-    query: entry.query || {},
-    body: entry.body || "",
-    output: entry.output || "",
-    status: entry.status,
-    durationMs: entry.durationMs ?? 0,
-    error: entry.error
-  })).filter((entry) => entry.method && entry.path);
-}
-function normalizeLogSeeds(seeds, hardLimit, redactor) {
-  if (!Array.isArray(seeds)) return [];
-  const normalized = seeds.slice(0, hardLimit).map((entry, idx) => ({
-    id: entry.id || randomBytes(8).toString("hex"),
-    type: entry.type || "info",
-    message: entry.message || "",
-    timestamp: entry.timestamp ?? Date.now() - idx * 1e3,
-    requestId: entry.requestId,
-    tags: Array.isArray(entry.tags) ? entry.tags : [],
-    metadata: entry.metadata
-  })).filter((entry) => entry.message);
-  return applyLogRedaction(normalized, redactor);
-}
-function coerceQueryRecord(query) {
-  if (!query || typeof query !== "object") return {};
-  return Object.fromEntries(
-    Object.entries(query).map(([key, value]) => [key, coerceValue(value)])
-  );
-}
-function coercePayload(body) {
-  if (body === void 0 || body === null) return "";
-  if (typeof body === "string") return body;
-  try {
-    return JSON.stringify(body);
-  } catch {
-    return String(body);
-  }
-}
-function coerceValue(value) {
-  if (value === void 0 || value === null) return "";
-  if (Array.isArray(value)) return value.map(coerceValue).join(",");
-  if (typeof value === "object") {
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return String(value);
-    }
-  }
-  return String(value);
-}
-function createLogRedactor(redactor) {
-  if (!redactor) return (entry) => entry;
-  return (entry) => {
-    try {
-      return redactor(entry) ?? null;
-    } catch (err) {
-      console.error("Log redaction failed \u2013 dropping log entry", err);
-      return null;
-    }
-  };
-}
-function applyLogRedaction(entries, redactor) {
-  if (!Array.isArray(entries)) return [];
-  const next = [];
-  for (const entry of entries) {
-    const redacted = redactor(entry);
-    if (redacted) next.push(redacted);
-  }
-  return next;
-}
-function resolveDocsPassword(auth) {
-  if (auth?.password) return auth.password;
-  return void 0;
-}
+// src/web/utils/security.ts
+import net from "net";
 function createPasswordGuard(password, realm) {
   const trimmed = password.trim();
   return (req, res, next) => {
@@ -880,19 +272,40 @@ function createPasswordGuard(password, realm) {
     }
     applyDocsSecurityHeaders(res);
     res.setHeader("WWW-Authenticate", `Basic realm="${realm}"`);
-    res.status(401).send(renderAuthErrorPage("Docs are password protected. Provide the configured password."));
+    res.status(401).send(
+      renderAuthErrorPage(
+        "Docs are password protected. Provide the configured password."
+      )
+    );
+  };
+}
+function createCookieGuard(cookieName, cookieSecret) {
+  return (req, res, next) => {
+    const cookies = req.cookies;
+    const value = cookies?.[cookieName];
+    const valid = cookieSecret ? value === cookieSecret : Boolean(value);
+    if (valid) {
+      return next();
+    }
+    applyDocsSecurityHeaders(res);
+    res.status(401).send(
+      renderAuthErrorPage(
+        "Docs are protected. You must be authenticated to access this page."
+      )
+    );
   };
 }
 function createMissingPasswordGuard() {
   return (_req, res) => {
     applyDocsSecurityHeaders(res);
-    res.status(500).send(renderAuthErrorPage("Provide password to mounted docs"));
+    res.status(500).send(renderAuthErrorPage("Provide auth configuration to mounted docs"));
   };
 }
 function extractPassword(authHeader) {
   if (!authHeader) return void 0;
   const header = Array.isArray(authHeader) ? authHeader[0] : authHeader;
-  if (typeof header !== "string" || !header.startsWith("Basic ")) return void 0;
+  if (typeof header !== "string" || !header.startsWith("Basic "))
+    return void 0;
   const token = header.slice("Basic ".length);
   try {
     const decoded = Buffer.from(token, "base64").toString("utf8");
@@ -903,6 +316,64 @@ function extractPassword(authHeader) {
     return void 0;
   }
 }
+function createIpAllowListGuard(allowed) {
+  const ranges = allowed.map((raw) => raw.trim()).filter(Boolean).map(parseIpPattern).filter((r) => r !== null);
+  return (req, res, next) => {
+    const rawIp = req.ip || req.connection && req.connection.remoteAddress || "";
+    const ip = normalizeIp(rawIp);
+    if (!ip || !isIpAllowed(ip, ranges)) {
+      applyDocsSecurityHeaders(res);
+      res.status(403).send(
+        renderAuthErrorPage(
+          "Access to docs is restricted from this IP address."
+        )
+      );
+      return;
+    }
+    next();
+  };
+}
+function normalizeIp(ip) {
+  if (!ip) return "";
+  if (ip.startsWith("::ffff:")) return ip.slice(7);
+  if (ip === "::1") return "127.0.0.1";
+  return ip;
+}
+function parseIpPattern(raw) {
+  if (raw.includes("/")) {
+    const cidr = parseCidr(raw);
+    if (!cidr) return null;
+    return { kind: "cidr", base: cidr.base, mask: cidr.mask };
+  }
+  return { kind: "exact", value: normalizeIp(raw) };
+}
+function parseCidr(raw) {
+  const [baseIp, bitsStr] = raw.split("/");
+  const bits = Number(bitsStr);
+  if (!Number.isInteger(bits) || bits < 0 || bits > 32) return null;
+  if (net.isIP(baseIp) !== 4) return null;
+  const baseLong = ipToLong(baseIp);
+  if (baseLong == null) return null;
+  const mask = bits === 0 ? 0 : ~0 << 32 - bits >>> 0;
+  return { base: (baseLong & mask) >>> 0, mask };
+}
+function ipToLong(ip) {
+  const parts = ip.split(".").map((n) => Number(n));
+  if (parts.length !== 4) return null;
+  if (parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
+  return (parts[0] << 24 >>> 0) + (parts[1] << 16 >>> 0) + (parts[2] << 8 >>> 0) + parts[3];
+}
+function isIpAllowed(ip, ranges) {
+  const ipv4 = net.isIP(ip) === 4 ? ipToLong(ip) : null;
+  for (const r of ranges) {
+    if (r.kind === "exact") {
+      if (ip === r.value) return true;
+    } else if (r.kind === "cidr" && ipv4 != null) {
+      if ((ipv4 & r.mask) === r.base) return true;
+    }
+  }
+  return false;
+}
 function renderAuthErrorPage(message) {
   return `<!DOCTYPE html>
 <html lang="en">
@@ -931,10 +402,340 @@ function applyDocsSecurityHeaders(res) {
   res.setHeader("Referrer-Policy", "same-origin");
   res.setHeader("X-Frame-Options", "SAMEORIGIN");
   res.setHeader("Cache-Control", "no-store");
+  res.setHeader(
+    "Strict-Transport-Security",
+    "max-age=31536000; includeSubDomains"
+  );
+}
+
+// src/web/utils/types.ts
+import {
+  finalize,
+  resource as resource6
+} from "@emeryld/rrroutes-contract";
+
+// src/web/v2/types/types.cacheLog.ts
+import { resource } from "@emeryld/rrroutes-contract";
+import z3 from "zod";
+
+// src/web/v2/types/types.base.ts
+import z2 from "zod";
+var METHODS = ["get", "post", "put", "patch", "delete"];
+var baseEntitySchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  description: z2.string().optional(),
+  groupId: z2.string().optional(),
+  tags: z2.string().array().optional(),
+  createdAt: z2.number(),
+  updatedAt: z2.number()
+});
+var baseQuerySchema = z2.object({
+  beforeDate: z2.string().optional(),
+  afterDate: z2.string().optional(),
+  orderBy: z2.enum(["timestamp", "duration", "level", "path"]).default("timestamp"),
+  orderDirection: z2.enum(["asc", "desc"]).default("desc"),
+  searchQuery: z2.string().optional(),
+  groups: z2.string().array().optional(),
+  tags: z2.string().array().optional(),
+  cursor: z2.string().optional()
+});
+
+// src/web/v2/types/types.cacheLog.ts
+var operationEnum = z3.enum(["hit", "miss", "set", "delete"]);
+var cacheLogSchema = baseEntitySchema.extend({
+  operation: operationEnum,
+  // on hit, value = value retrieved
+  // on miss, value = null
+  // on set, value = value set
+  // on delete, value = value deleted
+  value: z3.any().nullable(),
+  size: z3.number().optional()
+});
+var cacheLogQuerySchema = baseQuerySchema.extend({
+  operations: operationEnum.array().optional()
+});
+var cacheLeaves = resource("cache").get({
+  feed: true,
+  outputSchema: cacheLogSchema.array(),
+  querySchema: cacheLogQuerySchema,
+  outputMetaSchema: z3.object({
+    totalCount: z3.number().optional()
+  })
+}).post({
+  querySchema: cacheLogQuerySchema
+}).done();
+
+// src/web/v2/types/types.endpoint.ts
+import { resource as resource4 } from "@emeryld/rrroutes-contract";
+import z6 from "zod";
+
+// src/web/v2/types/types.requestLog.ts
+import { resource as resource3 } from "@emeryld/rrroutes-contract";
+import z5 from "zod";
+
+// src/web/v2/types/types.log.ts
+import { resource as resource2 } from "@emeryld/rrroutes-contract";
+import z4 from "zod";
+var levelSchema = z4.enum(["info", "warning", "error", "debug", "trace"]);
+var logSchema = baseEntitySchema.extend({
+  level: levelSchema,
+  meta: z4.json()
+});
+var logQuerySchema = baseQuerySchema.extend({
+  level: levelSchema.array().optional()
+});
+var logLeaves = resource2("logs").get({
+  feed: true,
+  outputSchema: logSchema.array(),
+  querySchema: logQuerySchema,
+  outputMetaSchema: z4.object({
+    totalCount: z4.number().optional()
+  })
+}).done();
+
+// src/web/v2/types/types.requestLog.ts
+var requestSchema = baseEntitySchema.extend({
+  status: z5.number(),
+  body: z5.any().optional(),
+  fullUrl: z5.string(),
+  path: z5.string(),
+  method: z5.enum(METHODS),
+  query: z5.record(z5.string(), z5.any()).optional(),
+  params: z5.record(z5.string(), z5.any()).optional(),
+  output: z5.any().optional(),
+  headers: z5.record(z5.string(), z5.any()).optional(),
+  error: z5.string().optional(),
+  durationMs: z5.number()
+});
+var requestQuerySchema = baseQuerySchema.extend({
+  methods: z5.enum(METHODS).array().default([]),
+  statuses: z5.number().array().default([]),
+  path: z5.string().optional()
+});
+var requestLogLeaves = resource3("requests").get({
+  feed: true,
+  outputSchema: requestSchema.array(),
+  querySchema: requestQuerySchema,
+  outputMetaSchema: z5.object({
+    totalCount: z5.number().optional()
+  })
+}).sub(
+  resource3(":requestId", void 0, z5.string()).get({
+    outputSchema: requestSchema.extend({
+      // Related by groupId
+      // Do I just use the existing feed endpoints with filter: groupId=?
+      logs: z5.array(logSchema),
+      caches: z5.array(cacheLogSchema)
+    })
+  }).done()
+).done();
+
+// src/web/v2/types/types.endpoint.ts
+var nodeKind = [
+  "object",
+  "string",
+  "number",
+  "boolean",
+  "bigint",
+  "date",
+  "array",
+  "enum",
+  "literal",
+  "union",
+  "record",
+  "tuple",
+  "unknown",
+  "any"
+];
+var serializableSchemaSchema = z6.lazy(
+  () => z6.object({
+    kind: z6.enum(nodeKind),
+    optional: z6.boolean().optional(),
+    nullable: z6.boolean().optional(),
+    description: z6.string().optional(),
+    // object
+    properties: z6.record(z6.string(), serializableSchemaSchema).optional(),
+    // array
+    element: serializableSchemaSchema.optional(),
+    // union
+    union: z6.array(serializableSchemaSchema).optional(),
+    // literal
+    literal: z6.unknown().optional(),
+    // enum
+    enumValues: z6.array(z6.string()).optional()
+  })
+);
+var STABILITIES = [
+  "experimental",
+  "beta",
+  "stable",
+  "deprecated"
+];
+var stabilityEnum = z6.enum(STABILITIES);
+var endpointSchema = baseEntitySchema.extend({
+  method: z6.enum(METHODS),
+  path: z6.string(),
+  contract: z6.object({
+    body: serializableSchemaSchema.optional(),
+    query: serializableSchemaSchema.optional(),
+    output: serializableSchemaSchema.optional(),
+    params: serializableSchemaSchema.optional(),
+    bodyFiles: z6.array(z6.object({ name: z6.string(), maxCount: z6.number() })).optional()
+  }),
+  feed: z6.boolean().optional(),
+  summary: z6.string().optional(),
+  stability: stabilityEnum,
+  hidden: z6.boolean().optional(),
+  meta: z6.record(z6.string(), z6.string())
+});
+var endpointFilterSchema = baseQuerySchema.extend({
+  methods: z6.enum(METHODS).array().optional(),
+  path: z6.string().optional(),
+  stability: stabilityEnum.array().optional()
+});
+var endpointLeaves = resource4("endpoints").get({
+  feed: true,
+  querySchema: endpointFilterSchema,
+  outputSchema: endpointSchema.array(),
+  outputMetaSchema: z6.object({
+    totalCount: z6.number().optional()
+  })
+}).sub(
+  resource4(":endpointId", void 0, z6.string()).get({
+    outputSchema: endpointSchema.extend({
+      // Related by groupId. Just use the existing feed endpoints with filter: groupId=?
+      requests: z6.array(requestSchema),
+      // Summary stats: return with the feed?
+      volumeTS: z6.array(
+        z6.object({
+          timestamp: z6.string(),
+          count: z6.number()
+        })
+      ),
+      averageDurationMs: z6.number(),
+      successRate: z6.number(),
+      // Add id as query param to the existing feed endpoints? This way "requests" field can also be only Ids
+      latestErrorRequestIds: z6.array(z6.string())
+    })
+  }).done()
+).done();
+
+// src/web/v2/types/types.preset.ts
+import { resource as resource5 } from "@emeryld/rrroutes-contract";
+import z7 from "zod";
+var presetSchema = baseEntitySchema.extend({
+  operations: z7.array(
+    z7.object({
+      endpointId: z7.string().optional(),
+      method: z7.enum(METHODS),
+      path: z7.string(),
+      body: z7.json().optional(),
+      extraHeaders: z7.record(z7.string(), z7.any()).optional(),
+      query: z7.record(z7.string(), z7.any()).optional()
+    })
+  )
+});
+var presetQuerySchema = baseQuerySchema.extend({
+  name: z7.string().optional(),
+  tags: z7.string().array().optional(),
+  group: z7.string().optional()
+});
+var presetLeaves = resource5("presets").get({
+  feed: true,
+  querySchema: presetQuerySchema.array(),
+  outputMetaSchema: z7.object({
+    totalCount: z7.number().optional()
+  }),
+  outputSchema: presetSchema
+}).post({
+  bodySchema: presetSchema,
+  outputSchema: presetSchema
+}).put({
+  bodySchema: presetSchema,
+  outputSchema: presetSchema
+}).done();
+
+// src/web/utils/types.ts
+var allLeaves = resource6().sub(
+  resource6("/__rrroutes").sub(
+    endpointLeaves,
+    requestLogLeaves,
+    logLeaves,
+    cacheLeaves,
+    presetLeaves
+  ).done()
+).done();
+var leaves = finalize(allLeaves);
+
+// src/index.ts
+function resolvePublicDir() {
+  const moduleDir = typeof __dirname !== "undefined" ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+  const fromModule = path.resolve(moduleDir, "../public");
+  if (fs.existsSync(fromModule)) return fromModule;
+  const fallback = path.resolve(moduleDir, "../dist/public");
+  if (fs.existsSync(fallback)) return fallback;
+  return fromModule;
+}
+function mountRRRoutesDocs({
+  router,
+  auth = {}
+}) {
+  const docsPath = "/__rrroutes/docs";
+  const publicDir = resolvePublicDir();
+  const assetsDir = path.join(publicDir, "assets");
+  const cspEnabled = auth.csp !== false;
+  const authEnabled = auth.enabled !== false;
+  const docsPassword = auth.password;
+  const authRealm = auth.realm || "RRRoutes Docs";
+  const allowedIps = auth.allowedIps ?? [];
+  const cookieName = auth.cookieName;
+  const cookieSecret = auth?.cookieSecret;
+  const customGuard = auth?.guardMiddleware;
+  const ipGuard = allowedIps.length > 0 ? createIpAllowListGuard(allowedIps) : void 0;
+  const authGuard = !authEnabled ? (_req, _res, next) => next() : customGuard ? customGuard : cookieName ? createCookieGuard(cookieName, cookieSecret) : docsPassword ? createPasswordGuard(docsPassword, authRealm) : createMissingPasswordGuard();
+  [docsPath, `${docsPath}/assets`, `__rrroutes/`].forEach((p) => {
+    if (ipGuard) router.use(p, ipGuard);
+    router.use(p, authGuard);
+  });
+  router.use(
+    `${docsPath}/assets`,
+    expressStatic(assetsDir, { immutable: true, maxAge: "365d" })
+  );
+  const docsRoutePaths = [docsPath, `${docsPath}/`, `${docsPath}/*id`];
+  router.get(docsRoutePaths, (_req, res) => {
+    const nonce = cspEnabled ? randomBytes(16).toString("base64") : void 0;
+    const html = renderLeafDocsHTML2({
+      cspNonce: nonce,
+      assetBasePath: `${`${docsPath}/assets`}`,
+      docsBasePath: `${docsPath}`
+    });
+    applyDocsSecurityHeaders(res);
+    if (cspEnabled && nonce) {
+      res.setHeader(
+        "Content-Security-Policy",
+        [
+          "default-src 'self'",
+          `script-src 'self' 'nonce-${nonce}'`,
+          `style-src 'self' 'nonce-${nonce}'`,
+          "img-src 'self' data:",
+          "connect-src 'self'",
+          "font-src 'self'",
+          "frame-ancestors 'self'",
+          "object-src 'none'",
+          "base-uri 'self'"
+        ].join("; ")
+      );
+    }
+    res.send(html);
+  });
+  return docsPath;
 }
 export {
+  introspectSchema,
   mountRRRoutesDocs,
   renderLeafDocsHTML2 as renderLeafDocsHTML,
+  leaves as requiredRoutes,
   serializeLeaf
 };
 //# sourceMappingURL=index.mjs.map