@btst/stack 1.6.0 → 1.8.0

package/dist/packages/better-stack/src/plugins/route-docs/client/plugin.cjs

@@ -0,0 +1,111 @@
+'use strict';
+
+const jsxRuntime = require('react/jsx-runtime');
+const React = require('react');
+const client = require('@btst/stack/plugins/client');
+const yar = require('@btst/yar');
+const generator = require('../generator.cjs');
+
+const DocsPageComponent = React.lazy(
+  () => import('./components/pages/docs-page.cjs').then((m) => ({
+    default: m.DocsPageComponent
+  }))
+);
+const DocsPageSkeleton = React.lazy(
+  () => import('./components/loading/docs-skeleton.cjs').then((m) => ({
+    default: m.DocsPageSkeleton
+  }))
+);
+const ROUTE_DOCS_QUERY_KEY = ["route-docs", "schema"];
+let moduleStoredContext = null;
+function getStoredContext() {
+  return moduleStoredContext;
+}
+async function generateSchema() {
+  if (!moduleStoredContext) {
+    return {
+      plugins: [],
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      allSitemapEntries: []
+    };
+  }
+  try {
+    const sitemapEntries = await generator.fetchAllSitemapEntries(moduleStoredContext);
+    return generator.generateRouteDocsSchema(moduleStoredContext, sitemapEntries);
+  } catch (error) {
+    console.warn("Failed to generate route docs schema:", error);
+    return generator.generateRouteDocsSchema(moduleStoredContext, []);
+  }
+}
+function createDocsMeta(config) {
+  return () => {
+    const title = config.title || "Route Documentation";
+    return [
+      { title },
+      { name: "title", content: title },
+      { name: "robots", content: "noindex" }
+    ];
+  };
+}
+function DocsErrorComponent() {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex items-center justify-center min-h-screen bg-background", children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "text-center", children: [
+    /* @__PURE__ */ jsxRuntime.jsx("h1", { className: "text-2xl font-semibold text-destructive mb-2", children: "Error Loading Documentation" }),
+    /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-muted-foreground", children: "An error occurred while loading the documentation." })
+  ] }) });
+}
+function createRouteDocsLoader(config) {
+  return async () => {
+    if (typeof window === "undefined" && moduleStoredContext) {
+      const { queryClient } = config;
+      try {
+        const sitemapEntries = await generator.fetchAllSitemapEntries(moduleStoredContext);
+        const schema = generator.generateRouteDocsSchema(
+          moduleStoredContext,
+          sitemapEntries
+        );
+        queryClient.setQueryData(ROUTE_DOCS_QUERY_KEY, schema);
+      } catch (error) {
+        console.warn("Failed to load route docs schema:", error);
+        queryClient.setQueryData(ROUTE_DOCS_QUERY_KEY, {
+          plugins: [],
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          allSitemapEntries: []
+        });
+      }
+    }
+  };
+}
+const routeDocsClientPlugin = (config) => {
+  return client.defineClientPlugin({
+    name: "route-docs",
+    routes: (context) => {
+      moduleStoredContext = context || null;
+      return {
+        docs: yar.createRoute("/route-docs", () => {
+          return {
+            PageComponent: () => /* @__PURE__ */ jsxRuntime.jsx(
+              DocsPageComponent,
+              {
+                title: config.title,
+                description: config.description,
+                siteBasePath: config.siteBasePath || "/pages"
+              }
+            ),
+            LoadingComponent: () => /* @__PURE__ */ jsxRuntime.jsx(DocsPageSkeleton, {}),
+            ErrorComponent: () => /* @__PURE__ */ jsxRuntime.jsx(DocsErrorComponent, {}),
+            loader: createRouteDocsLoader(config),
+            meta: createDocsMeta(config)
+          };
+        })
+      };
+    },
+    sitemap: async () => {
+      return [];
+    }
+  });
+};
+
+exports.ROUTE_DOCS_QUERY_KEY = ROUTE_DOCS_QUERY_KEY;
+exports.generateSchema = generateSchema;
+exports.getStoredContext = getStoredContext;
+exports.routeDocsClientPlugin = routeDocsClientPlugin;

package/dist/packages/better-stack/src/plugins/route-docs/client/plugin.mjs

@@ -0,0 +1,106 @@
+import { jsx, jsxs } from 'react/jsx-runtime';
+import { lazy } from 'react';
+import { defineClientPlugin } from '@btst/stack/plugins/client';
+import { createRoute } from '@btst/yar';
+import { fetchAllSitemapEntries, generateRouteDocsSchema } from '../generator.mjs';
+
+const DocsPageComponent = lazy(
+  () => import('./components/pages/docs-page.mjs').then((m) => ({
+    default: m.DocsPageComponent
+  }))
+);
+const DocsPageSkeleton = lazy(
+  () => import('./components/loading/docs-skeleton.mjs').then((m) => ({
+    default: m.DocsPageSkeleton
+  }))
+);
+const ROUTE_DOCS_QUERY_KEY = ["route-docs", "schema"];
+let moduleStoredContext = null;
+function getStoredContext() {
+  return moduleStoredContext;
+}
+async function generateSchema() {
+  if (!moduleStoredContext) {
+    return {
+      plugins: [],
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      allSitemapEntries: []
+    };
+  }
+  try {
+    const sitemapEntries = await fetchAllSitemapEntries(moduleStoredContext);
+    return generateRouteDocsSchema(moduleStoredContext, sitemapEntries);
+  } catch (error) {
+    console.warn("Failed to generate route docs schema:", error);
+    return generateRouteDocsSchema(moduleStoredContext, []);
+  }
+}
+function createDocsMeta(config) {
+  return () => {
+    const title = config.title || "Route Documentation";
+    return [
+      { title },
+      { name: "title", content: title },
+      { name: "robots", content: "noindex" }
+    ];
+  };
+}
+function DocsErrorComponent() {
+  return /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center min-h-screen bg-background", children: /* @__PURE__ */ jsxs("div", { className: "text-center", children: [
+    /* @__PURE__ */ jsx("h1", { className: "text-2xl font-semibold text-destructive mb-2", children: "Error Loading Documentation" }),
+    /* @__PURE__ */ jsx("p", { className: "text-muted-foreground", children: "An error occurred while loading the documentation." })
+  ] }) });
+}
+function createRouteDocsLoader(config) {
+  return async () => {
+    if (typeof window === "undefined" && moduleStoredContext) {
+      const { queryClient } = config;
+      try {
+        const sitemapEntries = await fetchAllSitemapEntries(moduleStoredContext);
+        const schema = generateRouteDocsSchema(
+          moduleStoredContext,
+          sitemapEntries
+        );
+        queryClient.setQueryData(ROUTE_DOCS_QUERY_KEY, schema);
+      } catch (error) {
+        console.warn("Failed to load route docs schema:", error);
+        queryClient.setQueryData(ROUTE_DOCS_QUERY_KEY, {
+          plugins: [],
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          allSitemapEntries: []
+        });
+      }
+    }
+  };
+}
+const routeDocsClientPlugin = (config) => {
+  return defineClientPlugin({
+    name: "route-docs",
+    routes: (context) => {
+      moduleStoredContext = context || null;
+      return {
+        docs: createRoute("/route-docs", () => {
+          return {
+            PageComponent: () => /* @__PURE__ */ jsx(
+              DocsPageComponent,
+              {
+                title: config.title,
+                description: config.description,
+                siteBasePath: config.siteBasePath || "/pages"
+              }
+            ),
+            LoadingComponent: () => /* @__PURE__ */ jsx(DocsPageSkeleton, {}),
+            ErrorComponent: () => /* @__PURE__ */ jsx(DocsErrorComponent, {}),
+            loader: createRouteDocsLoader(config),
+            meta: createDocsMeta(config)
+          };
+        })
+      };
+    },
+    sitemap: async () => {
+      return [];
+    }
+  });
+};
+
+export { ROUTE_DOCS_QUERY_KEY, generateSchema, getStoredContext, routeDocsClientPlugin };

package/dist/packages/better-stack/src/plugins/route-docs/generator.cjs

@@ -0,0 +1,244 @@
+'use strict';
+
+const z = require('zod');
+
+function _interopNamespaceCompat(e) {
+	if (e && typeof e === 'object' && 'default' in e) return e;
+	const n = Object.create(null);
+	if (e) {
+		for (const k in e) {
+			n[k] = e[k];
+		}
+	}
+	n.default = e;
+	return n;
+}
+
+const z__namespace = /*#__PURE__*/_interopNamespaceCompat(z);
+
+function extractPathParams(path) {
+  const params = [];
+  const segments = path.split("/");
+  for (const segment of segments) {
+    if (segment.startsWith(":")) {
+      params.push(segment.slice(1));
+    } else if (segment.startsWith("*:")) {
+      params.push(segment.slice(2));
+    } else if (segment === "*") {
+      params.push("_");
+    }
+  }
+  return params;
+}
+function getTypeFromZodType(zodType) {
+  if (zodType instanceof z__namespace.ZodString) return "string";
+  if (zodType instanceof z__namespace.ZodNumber) return "number";
+  if (zodType instanceof z__namespace.ZodBoolean) return "boolean";
+  if (zodType instanceof z__namespace.ZodArray) return "array";
+  if (zodType instanceof z__namespace.ZodObject) return "object";
+  if (zodType instanceof z__namespace.ZodEnum) return "enum";
+  if (zodType instanceof z__namespace.ZodLiteral) return "literal";
+  if (zodType instanceof z__namespace.ZodUnion) return "union";
+  const type = zodType.type;
+  if (type === "string") return "string";
+  if (type === "number") return "number";
+  if (type === "boolean") return "boolean";
+  if (type === "array") return "array";
+  if (type === "object") return "object";
+  return "string";
+}
+function processZodType(zodType) {
+  if (zodType instanceof z__namespace.ZodOptional) {
+    const innerType = zodType._def?.innerType || zodType.unwrap?.();
+    if (innerType) {
+      return processZodType(innerType);
+    }
+  }
+  if (zodType instanceof z__namespace.ZodNullable) {
+    const innerType = zodType._def?.innerType || zodType.unwrap?.();
+    if (innerType) {
+      const innerSchema = processZodType(innerType);
+      return {
+        ...innerSchema,
+        nullable: true
+      };
+    }
+  }
+  if (zodType instanceof z__namespace.ZodDefault) {
+    const innerType = zodType._def?.innerType;
+    const defaultValue = zodType._def?.defaultValue?.();
+    if (innerType) {
+      const innerSchema = processZodType(innerType);
+      if (defaultValue !== void 0) {
+        return {
+          ...innerSchema,
+          default: defaultValue
+        };
+      }
+      return innerSchema;
+    }
+  }
+  if (zodType instanceof z__namespace.ZodObject) {
+    const shape = zodType.shape || zodType._def?.shape?.();
+    if (shape) {
+      const properties = {};
+      const required = [];
+      for (const [key, value] of Object.entries(shape)) {
+        if (value instanceof z__namespace.ZodType) {
+          properties[key] = processZodType(value);
+          if (!(value instanceof z__namespace.ZodOptional)) {
+            required.push(key);
+          }
+        }
+      }
+      return {
+        type: "object",
+        properties,
+        ...required.length > 0 ? { required } : {}
+      };
+    }
+  }
+  if (zodType instanceof z__namespace.ZodArray) {
+    const elementType = zodType._def?.type || zodType.element;
+    return {
+      type: "array",
+      items: elementType ? processZodType(elementType) : { type: "string" }
+    };
+  }
+  if (zodType instanceof z__namespace.ZodEnum) {
+    const values = zodType._def?.values || zodType.options;
+    return {
+      type: "string",
+      enum: values
+    };
+  }
+  if (zodType instanceof z__namespace.ZodLiteral) {
+    const value = zodType._def?.value || zodType.value;
+    return {
+      type: typeof value,
+      const: value
+    };
+  }
+  if (zodType instanceof z__namespace.ZodUnion) {
+    const options = zodType._def?.options || zodType.options;
+    if (options && Array.isArray(options)) {
+      return {
+        oneOf: options.map((opt) => processZodType(opt))
+      };
+    }
+  }
+  if (zodType._def?.coerce) {
+    const innerType = zodType._def?.innerType;
+    if (innerType) {
+      return processZodType(innerType);
+    }
+  }
+  return {
+    type: getTypeFromZodType(zodType)
+  };
+}
+function isStandardSchema(obj) {
+  return obj && typeof obj === "object" && "~standard" in obj;
+}
+function extractQueryParams(querySchema) {
+  const params = [];
+  if (!querySchema) return params;
+  if (querySchema instanceof z__namespace.ZodObject) {
+    const shape = querySchema.shape || querySchema._def?.shape?.();
+    if (shape) {
+      for (const [key, value] of Object.entries(shape)) {
+        if (value instanceof z__namespace.ZodType) {
+          params.push({
+            name: key,
+            type: getTypeFromZodType(value),
+            required: !(value instanceof z__namespace.ZodOptional),
+            schema: processZodType(value)
+          });
+        }
+      }
+    }
+  } else if (isStandardSchema(querySchema)) {
+    const zodSchema = querySchema;
+    if (zodSchema instanceof z__namespace.ZodObject) {
+      return extractQueryParams(zodSchema);
+    }
+  }
+  return params;
+}
+async function fetchAllSitemapEntries(context) {
+  const allEntries = [];
+  for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
+    if (pluginKey === "routeDocs" || plugin.name === "route-docs") {
+      continue;
+    }
+    if (plugin.sitemap) {
+      try {
+        const entries = await plugin.sitemap();
+        for (const entry of entries) {
+          allEntries.push({
+            ...entry,
+            pluginKey
+          });
+        }
+      } catch (error) {
+        console.warn(`Failed to fetch sitemap for plugin ${pluginKey}:`, error);
+      }
+    }
+  }
+  return allEntries;
+}
+function generateRouteDocsSchema(context, sitemapEntries = []) {
+  const documentedPlugins = [];
+  const sitemapByPlugin = {};
+  for (const entry of sitemapEntries) {
+    if (!sitemapByPlugin[entry.pluginKey]) {
+      sitemapByPlugin[entry.pluginKey] = [];
+    }
+    sitemapByPlugin[entry.pluginKey].push(entry);
+  }
+  for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
+    if (pluginKey === "routeDocs" || plugin.name === "route-docs") {
+      continue;
+    }
+    const pluginRoutes = plugin.routes(context);
+    const documentedRoutes = [];
+    for (const [routeKey, route] of Object.entries(pluginRoutes)) {
+      const r = route;
+      const path = r.path;
+      const routeOptions = r.options || {};
+      const routeMeta = r.meta;
+      if (!path) continue;
+      const pathParamNames = extractPathParams(path);
+      const pathParams = pathParamNames.map((name) => ({
+        name,
+        type: "string",
+        // Path params are always strings
+        required: true
+      }));
+      const queryParams = extractQueryParams(routeOptions.query);
+      documentedRoutes.push({
+        key: routeKey,
+        path,
+        pathParams,
+        queryParams,
+        meta: routeMeta
+      });
+    }
+    if (documentedRoutes.length > 0) {
+      documentedPlugins.push({
+        key: pluginKey,
+        name: plugin.name,
+        routes: documentedRoutes,
+        sitemapEntries: sitemapByPlugin[pluginKey] || []
+      });
+    }
+  }
+  return {
+    plugins: documentedPlugins,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    allSitemapEntries: sitemapEntries
+  };
+}
+
+exports.fetchAllSitemapEntries = fetchAllSitemapEntries;
+exports.generateRouteDocsSchema = generateRouteDocsSchema;

package/dist/packages/better-stack/src/plugins/route-docs/generator.mjs

@@ -0,0 +1,227 @@
+import * as z from 'zod';
+
+function extractPathParams(path) {
+  const params = [];
+  const segments = path.split("/");
+  for (const segment of segments) {
+    if (segment.startsWith(":")) {
+      params.push(segment.slice(1));
+    } else if (segment.startsWith("*:")) {
+      params.push(segment.slice(2));
+    } else if (segment === "*") {
+      params.push("_");
+    }
+  }
+  return params;
+}
+function getTypeFromZodType(zodType) {
+  if (zodType instanceof z.ZodString) return "string";
+  if (zodType instanceof z.ZodNumber) return "number";
+  if (zodType instanceof z.ZodBoolean) return "boolean";
+  if (zodType instanceof z.ZodArray) return "array";
+  if (zodType instanceof z.ZodObject) return "object";
+  if (zodType instanceof z.ZodEnum) return "enum";
+  if (zodType instanceof z.ZodLiteral) return "literal";
+  if (zodType instanceof z.ZodUnion) return "union";
+  const type = zodType.type;
+  if (type === "string") return "string";
+  if (type === "number") return "number";
+  if (type === "boolean") return "boolean";
+  if (type === "array") return "array";
+  if (type === "object") return "object";
+  return "string";
+}
+function processZodType(zodType) {
+  if (zodType instanceof z.ZodOptional) {
+    const innerType = zodType._def?.innerType || zodType.unwrap?.();
+    if (innerType) {
+      return processZodType(innerType);
+    }
+  }
+  if (zodType instanceof z.ZodNullable) {
+    const innerType = zodType._def?.innerType || zodType.unwrap?.();
+    if (innerType) {
+      const innerSchema = processZodType(innerType);
+      return {
+        ...innerSchema,
+        nullable: true
+      };
+    }
+  }
+  if (zodType instanceof z.ZodDefault) {
+    const innerType = zodType._def?.innerType;
+    const defaultValue = zodType._def?.defaultValue?.();
+    if (innerType) {
+      const innerSchema = processZodType(innerType);
+      if (defaultValue !== void 0) {
+        return {
+          ...innerSchema,
+          default: defaultValue
+        };
+      }
+      return innerSchema;
+    }
+  }
+  if (zodType instanceof z.ZodObject) {
+    const shape = zodType.shape || zodType._def?.shape?.();
+    if (shape) {
+      const properties = {};
+      const required = [];
+      for (const [key, value] of Object.entries(shape)) {
+        if (value instanceof z.ZodType) {
+          properties[key] = processZodType(value);
+          if (!(value instanceof z.ZodOptional)) {
+            required.push(key);
+          }
+        }
+      }
+      return {
+        type: "object",
+        properties,
+        ...required.length > 0 ? { required } : {}
+      };
+    }
+  }
+  if (zodType instanceof z.ZodArray) {
+    const elementType = zodType._def?.type || zodType.element;
+    return {
+      type: "array",
+      items: elementType ? processZodType(elementType) : { type: "string" }
+    };
+  }
+  if (zodType instanceof z.ZodEnum) {
+    const values = zodType._def?.values || zodType.options;
+    return {
+      type: "string",
+      enum: values
+    };
+  }
+  if (zodType instanceof z.ZodLiteral) {
+    const value = zodType._def?.value || zodType.value;
+    return {
+      type: typeof value,
+      const: value
+    };
+  }
+  if (zodType instanceof z.ZodUnion) {
+    const options = zodType._def?.options || zodType.options;
+    if (options && Array.isArray(options)) {
+      return {
+        oneOf: options.map((opt) => processZodType(opt))
+      };
+    }
+  }
+  if (zodType._def?.coerce) {
+    const innerType = zodType._def?.innerType;
+    if (innerType) {
+      return processZodType(innerType);
+    }
+  }
+  return {
+    type: getTypeFromZodType(zodType)
+  };
+}
+function isStandardSchema(obj) {
+  return obj && typeof obj === "object" && "~standard" in obj;
+}
+function extractQueryParams(querySchema) {
+  const params = [];
+  if (!querySchema) return params;
+  if (querySchema instanceof z.ZodObject) {
+    const shape = querySchema.shape || querySchema._def?.shape?.();
+    if (shape) {
+      for (const [key, value] of Object.entries(shape)) {
+        if (value instanceof z.ZodType) {
+          params.push({
+            name: key,
+            type: getTypeFromZodType(value),
+            required: !(value instanceof z.ZodOptional),
+            schema: processZodType(value)
+          });
+        }
+      }
+    }
+  } else if (isStandardSchema(querySchema)) {
+    const zodSchema = querySchema;
+    if (zodSchema instanceof z.ZodObject) {
+      return extractQueryParams(zodSchema);
+    }
+  }
+  return params;
+}
+async function fetchAllSitemapEntries(context) {
+  const allEntries = [];
+  for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
+    if (pluginKey === "routeDocs" || plugin.name === "route-docs") {
+      continue;
+    }
+    if (plugin.sitemap) {
+      try {
+        const entries = await plugin.sitemap();
+        for (const entry of entries) {
+          allEntries.push({
+            ...entry,
+            pluginKey
+          });
+        }
+      } catch (error) {
+        console.warn(`Failed to fetch sitemap for plugin ${pluginKey}:`, error);
+      }
+    }
+  }
+  return allEntries;
+}
+function generateRouteDocsSchema(context, sitemapEntries = []) {
+  const documentedPlugins = [];
+  const sitemapByPlugin = {};
+  for (const entry of sitemapEntries) {
+    if (!sitemapByPlugin[entry.pluginKey]) {
+      sitemapByPlugin[entry.pluginKey] = [];
+    }
+    sitemapByPlugin[entry.pluginKey].push(entry);
+  }
+  for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
+    if (pluginKey === "routeDocs" || plugin.name === "route-docs") {
+      continue;
+    }
+    const pluginRoutes = plugin.routes(context);
+    const documentedRoutes = [];
+    for (const [routeKey, route] of Object.entries(pluginRoutes)) {
+      const r = route;
+      const path = r.path;
+      const routeOptions = r.options || {};
+      const routeMeta = r.meta;
+      if (!path) continue;
+      const pathParamNames = extractPathParams(path);
+      const pathParams = pathParamNames.map((name) => ({
+        name,
+        type: "string",
+        // Path params are always strings
+        required: true
+      }));
+      const queryParams = extractQueryParams(routeOptions.query);
+      documentedRoutes.push({
+        key: routeKey,
+        path,
+        pathParams,
+        queryParams,
+        meta: routeMeta
+      });
+    }
+    if (documentedRoutes.length > 0) {
+      documentedPlugins.push({
+        key: pluginKey,
+        name: plugin.name,
+        routes: documentedRoutes,
+        sitemapEntries: sitemapByPlugin[pluginKey] || []
+      });
+    }
+  }
+  return {
+    plugins: documentedPlugins,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    allSitemapEntries: sitemapEntries
+  };
+}
+
+export { fetchAllSitemapEntries, generateRouteDocsSchema };