@emeryld/rrroutes-openapi 2.2.27 → 2.3.0-alpha.0

package/dist/index.mjs

@@ -184,12 +184,14 @@ var DocsDocument = ({
   assetBase,
   docsBase,
   historyJson,
+  logsJson,
   baseUrlSuffix,
+  webhooks,
   cspNonce
 }) => {
   const cssHref = `${assetBase}/docs.css`;
   const jsSrc = `${assetBase}/docs.js`;
-  const configJson = serializeConfig({ docsBasePath: docsBase, baseUrlSuffix });
+  const configJson = serializeConfig({ docsBasePath: docsBase, baseUrlSuffix, webhooks });
   return /* @__PURE__ */ jsxs("html", { lang: "en", children: [
     /* @__PURE__ */ jsxs("head", { children: [
       /* @__PURE__ */ jsx("meta", { charSet: "UTF-8" }),
@@ -226,6 +228,15 @@ var DocsDocument = ({
           dangerouslySetInnerHTML: { __html: historyJson }
         }
       ),
+      /* @__PURE__ */ jsx(
+        "script",
+        {
+          id: "logs-data",
+          type: "application/json",
+          nonce: cspNonce,
+          dangerouslySetInnerHTML: { __html: logsJson }
+        }
+      ),
       /* @__PURE__ */ jsx(
         "script",
         {
@@ -248,6 +259,9 @@ function serializePresets(presets) {
 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, "<\\/");
 }
@@ -257,7 +271,9 @@ function createLeafDocsDocument(leaves, options = {}) {
   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,
     {
@@ -266,7 +282,9 @@ function createLeafDocsDocument(leaves, options = {}) {
       assetBase,
       docsBase,
       historyJson,
+      logsJson,
       baseUrlSuffix,
+      webhooks,
       cspNonce: options.cspNonce
     }
   );
@@ -282,6 +300,65 @@ function renderLeafDocsHTML2(leaves, options = {}) {
   return renderLeafDocsHTML(leaves, 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({
@@ -296,10 +373,150 @@ function mountRRRoutesDocs({
   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 inMemoryHistory = normalizeHistorySeeds(options.historySeeds, defaultHistoryLimit);
+  const inMemoryLogs = normalizeLogSeeds(options.logSeeds, defaultLogLimit);
+  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;
   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
+          });
+          inMemoryLogs.unshift({
+            id: randomBytes(8).toString("hex"),
+            type: logType,
+            message: `${methodUpper} ${pathOnly} -> ${status}`,
+            timestamp,
+            requestId: requestId ? String(requestId) : void 0,
+            tags: [],
+            metadata
+          });
+          if (inMemoryLogs.length > defaultLogLimit) inMemoryLogs.length = defaultLogLimit;
+        }
+      });
+      next();
+    });
+  }
+  router.get(webhookPaths.history, async (req, res) => {
+    const handler = options.logWebhook?.history;
+    try {
+      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 {
+      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 filtered = applyLogsQuery(normalized.items, 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) : [];
@@ -318,7 +535,12 @@ function mountRRRoutesDocs({
       docsBasePath: `${prefix}${normalizedDocsPath}`,
       baseUrlSuffix: prefix,
       historySeeds: options.historySeeds,
-      presets: normalizePresets(finalPresets)
+      logSeeds: options.logSeeds,
+      presets: normalizePresets(finalPresets),
+      webhooks: {
+        history: `${prefix}${webhookPaths.history}`,
+        logs: `${prefix}${webhookPaths.logs}`
+      }
     });
     if (cspEnabled && nonce) {
       res.setHeader(
@@ -336,7 +558,7 @@ function mountRRRoutesDocs({
     }
     res.send(html);
   });
-  return { path: docsPath };
+  return { path: docsPath, webhooks: webhookPaths, webhookLeaves, webhookSchemas };
 }
 function resolvePublicDir() {
   const moduleDir = typeof __dirname !== "undefined" ? __dirname : path.dirname(fileURLToPath(import.meta.url));
@@ -362,6 +584,244 @@ function normalizePresets(presets) {
     })) : []
   }));
 }
+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) {
+  if (!Array.isArray(seeds)) return [];
+  return 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);
+}
+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);
+}
 export {
   mountRRRoutesDocs,
   renderLeafDocsHTML2 as renderLeafDocsHTML,