@emeryld/rrroutes-contract 2.1.11 → 2.1.13

package/dist/core/routesV3.core.d.ts

@@ -1,4 +1,4 @@
-import { z, ZodTypeAny } from 'zod';
+import { z, ZodType } from 'zod';
 /** Supported HTTP verbs for the routes DSL. */
 export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 /** Declarative description of a multipart upload field. */
@@ -16,13 +16,13 @@ export type NodeCfg = {
 /** Per-method configuration merged with inherited node config. */
 export type MethodCfg = {
     /** Zod schema describing the request body. */
-    bodySchema?: ZodTypeAny;
+    bodySchema?: ZodType;
     /** Zod schema describing the query string. */
-    querySchema?: ZodTypeAny;
+    querySchema?: ZodType;
     /** Zod schema describing path params (overrides inferred params). */
-    paramsSchema?: ZodTypeAny;
+    paramsSchema?: ZodType;
     /** Zod schema describing the response payload. */
-    outputSchema?: ZodTypeAny;
+    outputSchema?: ZodType;
     /** Multipart upload definitions for the route. */
     bodyFiles?: FileField[];
     /** Marks the route as an infinite feed (enables cursor helpers). */
@@ -102,13 +102,13 @@ export declare function buildCacheKey<L extends AnyLeaf>(args: {
     query?: InferQuery<L>;
 }): readonly [HttpMethod, string, {}];
 /** Infer params either from the explicit params schema or from the path literal. */
-export type InferParams<L extends AnyLeaf> = L['cfg']['paramsSchema'] extends ZodTypeAny ? z.infer<L['cfg']['paramsSchema']> : ExtractParamsFromPath<L['path']>;
+export type InferParams<L extends AnyLeaf> = L['cfg']['paramsSchema'] extends ZodType ? z.infer<L['cfg']['paramsSchema']> : ExtractParamsFromPath<L['path']>;
 /** Infer query shape from a Zod schema when present. */
-export type InferQuery<L extends AnyLeaf> = L['cfg']['querySchema'] extends ZodTypeAny ? z.infer<L['cfg']['querySchema']> : never;
+export type InferQuery<L extends AnyLeaf> = L['cfg']['querySchema'] extends ZodType ? z.infer<L['cfg']['querySchema']> : never;
 /** Infer request body shape from a Zod schema when present. */
-export type InferBody<L extends AnyLeaf> = L['cfg']['bodySchema'] extends ZodTypeAny ? z.infer<L['cfg']['bodySchema']> : never;
+export type InferBody<L extends AnyLeaf> = L['cfg']['bodySchema'] extends ZodType ? z.infer<L['cfg']['bodySchema']> : never;
 /** Infer handler output shape from a Zod schema. Defaults to unknown. */
-export type InferOutput<L extends AnyLeaf> = L['cfg']['outputSchema'] extends ZodTypeAny ? z.infer<L['cfg']['outputSchema']> : unknown;
+export type InferOutput<L extends AnyLeaf> = L['cfg']['outputSchema'] extends ZodType ? z.infer<L['cfg']['outputSchema']> : unknown;
 /** Render a type as if it were a simple object literal. */
 export type Prettify<T> = {
     [K in keyof T]: T[K];

package/dist/docs/docs.d.ts

@@ -1,2 +1,6 @@
 import { AnyLeaf } from "../core/routesV3.core";
-export declare function renderLeafDocsHTML(leaves: AnyLeaf[]): string;
+interface RenderOptions {
+    cspNonce?: string;
+}
+export declare function renderLeafDocsHTML(leaves: AnyLeaf[], options?: RenderOptions): string;
+export {};

package/dist/docs/schemaIntrospection.d.ts

@@ -0,0 +1,15 @@
+import * as z from "zod";
+export type SerializableSchemaNode = {
+    kind: string;
+    optional?: boolean;
+    nullable?: boolean;
+    description?: string;
+    properties?: Record<string, SerializableSchemaNode>;
+    element?: SerializableSchemaNode;
+    union?: SerializableSchemaNode[];
+    literal?: unknown;
+    enumValues?: string[];
+};
+type ZodAny = z.ZodTypeAny;
+export declare function introspectSchema(schema: ZodAny | undefined): SerializableSchemaNode | undefined;
+export {};

package/dist/docs/serializer.d.ts

@@ -1,9 +1,14 @@
 import { AnyLeaf, MethodCfg } from "../core/routesV3.core";
-type SerializableMethodCfg = Pick<MethodCfg, 'description' | 'summary' | 'docsGroup' | 'tags' | 'deprecated' | 'stability' | 'feed' | 'docsMeta'> & {
+import { SerializableSchemaNode } from "./schemaIntrospection";
+type SerializableMethodCfg = Pick<MethodCfg, "description" | "summary" | "docsGroup" | "tags" | "deprecated" | "stability" | "feed" | "docsMeta"> & {
     hasBody: boolean;
     hasQuery: boolean;
     hasParams: boolean;
     hasOutput: boolean;
+    bodySchema?: SerializableSchemaNode;
+    querySchema?: SerializableSchemaNode;
+    paramsSchema?: SerializableSchemaNode;
+    outputSchema?: SerializableSchemaNode;
 };
 export type SerializableLeaf = {
     method: string;

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -299,6 +309,130 @@ function defineSocketEvents(config, events) {
   return { config, events };
 }
 
+// src/docs/schemaIntrospection.ts
+var z3 = __toESM(require("zod"), 1);
+function getDef(schema) {
+  if (!schema || typeof schema !== "object") return void 0;
+  const anySchema = schema;
+  return anySchema._zod?.def ?? anySchema._def;
+}
+function getDescription(schema) {
+  const anyZ = z3;
+  const registry = anyZ.globalRegistry?.get ? anyZ.globalRegistry.get(schema) : void 0;
+  if (registry && typeof registry.description === "string") {
+    return registry.description;
+  }
+  const def = getDef(schema);
+  if (def && typeof def.description === "string") {
+    return def.description;
+  }
+  return void 0;
+}
+function unwrap(schema) {
+  let s = schema;
+  let optional = false;
+  let nullable = false;
+  const ZodEffectsCtor = z3.ZodEffects;
+  while (true) {
+    if (ZodEffectsCtor && s instanceof ZodEffectsCtor) {
+      const def = getDef(s) || {};
+      const sourceType = typeof s.sourceType === "function" ? s.sourceType() : def.schema;
+      if (!sourceType) break;
+      s = sourceType;
+      continue;
+    }
+    if (s instanceof z3.ZodOptional) {
+      optional = true;
+      const def = getDef(s);
+      s = def && def.innerType || s;
+      continue;
+    }
+    if (s instanceof z3.ZodNullable) {
+      nullable = true;
+      const def = getDef(s);
+      s = def && def.innerType || s;
+      continue;
+    }
+    if (s instanceof z3.ZodDefault) {
+      const def = getDef(s);
+      s = def && def.innerType || s;
+      continue;
+    }
+    break;
+  }
+  return { base: s, optional, nullable };
+}
+function introspectSchema(schema) {
+  if (!schema) return void 0;
+  const { base, optional, nullable } = unwrap(schema);
+  const def = getDef(base);
+  const node = {
+    kind: inferKind(base),
+    optional: optional || void 0,
+    nullable: nullable || void 0,
+    description: getDescription(base)
+  };
+  if (base instanceof z3.ZodObject) {
+    const rawShape = base.shape ?? (def && typeof def.shape === "function" ? def.shape() : def?.shape);
+    const shape = typeof rawShape === "function" ? rawShape() : rawShape ?? {};
+    const props = {};
+    for (const key of Object.keys(shape)) {
+      const child = shape[key];
+      const childNode = introspectSchema(child);
+      if (childNode) props[key] = childNode;
+    }
+    node.properties = props;
+  }
+  if (base instanceof z3.ZodArray) {
+    const inner = def && def.element || def && def.type || void 0;
+    if (inner) {
+      node.element = introspectSchema(inner);
+    }
+  }
+  if (base instanceof z3.ZodUnion) {
+    const options = def && def.options || [];
+    node.union = options.map((opt) => introspectSchema(opt)).filter(Boolean);
+  }
+  if (base instanceof z3.ZodLiteral) {
+    if (def) {
+      if (Array.isArray(def.values)) {
+        node.literal = def.values.length === 1 ? def.values[0] : def.values.slice();
+      } else {
+        node.literal = def.value;
+      }
+    }
+  }
+  if (base instanceof z3.ZodEnum) {
+    if (def) {
+      if (Array.isArray(def.values)) {
+        node.enumValues = def.values.slice();
+      } else if (def.entries && typeof def.entries === "object") {
+        node.enumValues = Object.values(def.entries).map(
+          (v) => String(v)
+        );
+      }
+    }
+  }
+  return node;
+}
+function inferKind(schema) {
+  if (schema instanceof z3.ZodString) return "string";
+  if (schema instanceof z3.ZodNumber) return "number";
+  if (schema instanceof z3.ZodBoolean) return "boolean";
+  if (schema instanceof z3.ZodBigInt) return "bigint";
+  if (schema instanceof z3.ZodDate) return "date";
+  if (schema instanceof z3.ZodArray) return "array";
+  if (schema instanceof z3.ZodObject) return "object";
+  if (schema instanceof z3.ZodUnion) return "union";
+  if (schema instanceof z3.ZodLiteral) return "literal";
+  if (schema instanceof z3.ZodEnum) return "enum";
+  if (schema instanceof z3.ZodRecord) return "record";
+  if (schema instanceof z3.ZodTuple) return "tuple";
+  if (schema instanceof z3.ZodUnknown) return "unknown";
+  if (schema instanceof z3.ZodAny) return "any";
+  return "unknown";
+}
+
 // src/docs/serializer.ts
 function serializeLeaf(leaf) {
   const cfg = leaf.cfg;
@@ -319,22 +453,17 @@ function serializeLeaf(leaf) {
       hasBody: !!cfg.bodySchema || !!cfg.bodyFiles?.length,
       hasQuery: !!cfg.querySchema,
       hasParams: !!cfg.paramsSchema,
-      hasOutput: !!cfg.outputSchema
+      hasOutput: !!cfg.outputSchema,
+      bodySchema: introspectSchema(cfg.bodySchema),
+      querySchema: introspectSchema(cfg.querySchema),
+      paramsSchema: introspectSchema(cfg.paramsSchema),
+      outputSchema: introspectSchema(cfg.outputSchema)
     }
   };
 }
 
 // src/docs/docs.ts
-function renderLeafDocsHTML(leaves) {
-  const docsLeaves = leaves.map(serializeLeaf);
-  const leafJson = JSON.stringify(docsLeaves).replace(/</g, "\\u003c");
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <title>API Routes</title>
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <style>
+var styles = `
     :root {
       --bg: #020617;
       --bg-elevated: #020617;
@@ -363,6 +492,7 @@ function renderLeafDocsHTML(leaves) {
       -webkit-font-smoothing: antialiased;
     }
 
+    
     .page {
       min-height: 100vh;
       padding: 24px;
@@ -727,12 +857,121 @@ function renderLeafDocsHTML(leaves) {
       border: 1px dashed rgba(148, 163, 184, 0.5);
       background: rgba(15, 23, 42, 0.9);
     }
+        .schema-section {
+    margin-top: 8px;
+    font-size: 11px;
+    border-top: 1px dashed rgba(148, 163, 184, 0.5);
+    padding-top: 6px;
+  }
+
+  .schema-details {
+    margin-top: 6px;
+    border-radius: 10px;
+    border: 1px solid rgba(148, 163, 184, 0.4);
+    background: rgba(15, 23, 42, 0.95);
+    padding: 8px 10px;
+  }
+
+  .schema-details summary {
+    cursor: pointer;
+    list-style: none;
+    font-size: 11px;
+    color: var(--text-muted);
+  }
+
+  .schema-details summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .schema-details summary::before {
+    content: "\u25B8";
+    display: inline-block;
+    margin-right: 6px;
+    font-size: 9px;
+  }
+
+  .schema-details[open] summary::before {
+    content: "\u25BE";
+  }
+
+  .schema-table {
+    width: 100%;
+    border-collapse: collapse;
+    margin-top: 6px;
+    font-size: 11px;
+  }
+
+  .schema-table th,
+  .schema-table td {
+    padding: 3px 4px;
+    border-bottom: 1px solid rgba(30, 64, 175, 0.35);
+    text-align: left;
+  }
+
+  .schema-table th {
+    font-weight: 500;
+    color: var(--text-muted);
+  }
+
+  .schema-field-name {
+    font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco,
+      Consolas, "Liberation Mono", "Courier New", monospace;
+  }
+
+  .schema-type {
+    color: var(--accent);
+    font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco,
+      Consolas, "Liberation Mono", "Courier New", monospace;
+  }
+
+  .schema-required {
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.12em;
+    padding: 1px 5px;
+    border-radius: 999px;
+    border: 1px solid rgba(52, 211, 153, 0.7);
+    color: #bbf7d0;
+    background: rgba(22, 163, 74, 0.1);
+  }
+
+  .schema-optional {
+    font-size: 10px;
+    text-transform: uppercase;
+    letter-spacing: 0.12em;
+    padding: 1px 5px;
+    border-radius: 999px;
+    border: 1px solid rgba(148, 163, 184, 0.6);
+    color: var(--text-muted);
+    background: rgba(15, 23, 42, 0.95);
+  }
+
+  .schema-meta {
+    margin-top: 6px;
+    font-size: 10px;
+    color: var(--text-muted);
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+      `;
+function renderLeafDocsHTML(leaves, options = {}) {
+  const docsLeaves = leaves.map(serializeLeaf);
+  const leafJson = JSON.stringify(docsLeaves).replace(/</g, "\\u003c");
+  const nonceAttr = options.cspNonce ? ` nonce="${options.cspNonce}"` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>API Routes</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style${nonceAttr}>
+${styles}
   </style>
 </head>
 <body>
   <div class="page">
     <div class="shell">
-      <header class="header">
+            <header class="header">
         <div class="header-main">
           <div class="title-row">
             <div class="title">
@@ -746,8 +985,7 @@ function renderLeafDocsHTML(leaves) {
         </div>
         <div id="stats" class="stats"></div>
       </header>
-
-      <div class="layout">
+<div class="layout">
         <aside class="sidebar">
           <h2>Filters</h2>
 
@@ -784,9 +1022,102 @@ function renderLeafDocsHTML(leaves) {
     </div>
   </div>
 
-  <script id="leaf-data" type="application/json">${leafJson}</script>
-  <script>
+  <script id="leaf-data" type="application/json"${nonceAttr}>${leafJson}</script>
+  <script${nonceAttr}>
     (function () {
+
+          function typeLabel(node) {
+        if (!node) return "unknown";
+        var base = node.kind || "unknown";
+        if (node.literal !== undefined) {
+          return JSON.stringify(node.literal);
+        }
+        if (node.enumValues && node.enumValues.length) {
+          return "enum[" + node.enumValues.join(" | ") + "]";
+        }
+        if (node.kind === "array" && node.element) {
+          return "Array<" + typeLabel(node.element) + ">";
+        }
+        if (node.kind === "union" && node.union && node.union.length) {
+          return node.union.map(typeLabel).join(" | ");
+        }
+        return base;
+      }
+
+      function renderObjectRows(node, prefix) {
+        if (!node || node.kind !== "object" || !node.properties) return "";
+        var rows = "";
+        Object.keys(node.properties).forEach(function (key) {
+          var child = node.properties[key];
+          var fullName = prefix ? prefix + "." + key : key;
+          var required = !child.optional;
+          rows +=
+            "<tr>" +
+            '<td class="schema-field-name">' +
+            escapeHtml(fullName) +
+            "</td>" +
+            '<td class="schema-type">' +
+            escapeHtml(typeLabel(child)) +
+            "</td>" +
+            "<td>" +
+            (required
+              ? '<span class="schema-required">required</span>'
+              : '<span class="schema-optional">optional</span>') +
+            "</td>" +
+            "<td>" +
+            (child.description
+              ? escapeHtml(String(child.description))
+              : "") +
+            "</td>" +
+            "</tr>";
+
+          // Recursively show nested objects, arrays-of-objects, etc.
+          if (child.kind === "object") {
+            rows += renderObjectRows(child, fullName);
+          } else if (child.kind === "array" && child.element && child.element.kind === "object") {
+            rows += renderObjectRows(
+              child.element,
+              fullName + "[]."
+            );
+          }
+        });
+        return rows;
+      }
+
+      function renderSchemaSection(label, node) {
+        if (!node) return "";
+        // For non-object schemas, just show a one-line type.
+        var isObject = node.kind === "object" && node.properties;
+        var content = "";
+
+        if (isObject) {
+          var rows = renderObjectRows(node, "");
+          content =
+            '<table class="schema-table">' +
+            "<thead><tr>" +
+            "<th>Field</th><th>Type</th><th></th><th>Description</th>" +
+            "</tr></thead>" +
+            "<tbody>" +
+            rows +
+            "</tbody></table>";
+        } else {
+          content =
+            '<div class="schema-meta">' +
+            "<strong>Type:</strong> " +
+            escapeHtml(typeLabel(node)) +
+            "</div>";
+        }
+
+        return (
+          '<div class="schema-section">' +
+          "<div><strong>" +
+          escapeHtml(label) +
+          "</strong></div>" +
+          content +
+          "</div>"
+        );
+      }
+
       function escapeHtml(str) {
         return String(str)
           .replace(/&/g, '&amp;')
@@ -882,40 +1213,40 @@ function renderLeafDocsHTML(leaves) {
       }
 
       function routeToHTML(route) {
-        var method = String(route.method || '').toUpperCase();
-        var methodClass = 'method-' + String(route.method || '').toLowerCase();
+        var method = String(route.method || "").toUpperCase();
+        var methodClass = "method-" + String(route.method || "").toLowerCase();
 
         var cfg = route.cfg || {};
-        var group = cfg.docsGroup || 'Ungrouped';
+        var group = cfg.docsGroup || "Ungrouped";
 
-        var summary = cfg.summary || cfg.description || '';
+        var summary = cfg.summary || cfg.description || "";
         var description =
           cfg.description && cfg.summary !== cfg.description
             ? cfg.description
-            : '';
+            : "";
 
         var tags = Array.isArray(cfg.tags) ? cfg.tags : [];
         var tagHtml = tags
           .map(function (tag) {
             var t = String(tag);
-            var extraClass = t === 'not-implemented' ? ' tag-not-impl' : '';
-            return '<span class="tag' + extraClass + '">' + escapeHtml(t) + '</span>';
+            var extraClass = t === "not-implemented" ? " tag-not-impl" : "";
+            return '<span class="tag' + extraClass + '">' + escapeHtml(t) + "</span>";
           })
-          .join('');
+          .join("");
 
-        var metaBadges = '';
+        var metaBadges = "";
         if (cfg.feed) {
           metaBadges += '<span class="badge badge-feed">Feed</span>';
         }
-        if (cfg.deprecated || cfg.stability === 'deprecated') {
+        if (cfg.deprecated || cfg.stability === "deprecated") {
           metaBadges += '<span class="badge badge-deprecated">Deprecated</span>';
-        } else if (cfg.stability && cfg.stability !== 'stable') {
+        } else if (cfg.stability && cfg.stability !== "stable") {
           metaBadges +=
             '<span class="badge badge-' +
             escapeHtml(cfg.stability) +
             '">' +
             escapeHtml(String(cfg.stability)) +
-            '</span>';
+            "</span>";
         }
 
         var schemaPills = [];
@@ -926,8 +1257,48 @@ function renderLeafDocsHTML(leaves) {
 
         var schemaHtml =
           schemaPills.length > 0
-            ? '<div class="schema-row">' + schemaPills.join('') + '</div>'
-            : '';
+            ? '<div class="schema-row">' + schemaPills.join("") + "</div>"
+            : "";
+
+        // NEW: full expandable details including field-level schemas + docsMeta
+        var hasDetailedSchemas =
+          cfg.bodySchema || cfg.querySchema || cfg.paramsSchema || cfg.outputSchema;
+        var detailsInner = "";
+
+        if (cfg.bodySchema) {
+          detailsInner += renderSchemaSection("Request body", cfg.bodySchema);
+        }
+        if (cfg.querySchema) {
+          detailsInner += renderSchemaSection("Query params", cfg.querySchema);
+        }
+        if (cfg.paramsSchema) {
+          detailsInner += renderSchemaSection("Path params", cfg.paramsSchema);
+        }
+        if (cfg.outputSchema) {
+          detailsInner += renderSchemaSection("Response", cfg.outputSchema);
+        }
+
+        if (cfg.docsMeta) {
+          try {
+            var metaJson = JSON.stringify(cfg.docsMeta, null, 2);
+            detailsInner +=
+              '<div class="schema-section">' +
+              "<div><strong>Metadata</strong></div>" +
+              '<div class="schema-meta">' +
+              escapeHtml(metaJson) +
+              "</div>" +
+              "</div>";
+          } catch (e) {}
+        }
+
+        var detailsHtml = "";
+        if (hasDetailedSchemas || cfg.docsMeta) {
+          detailsHtml =
+            '<details class="schema-details">' +
+            "<summary>Inspect schemas & metadata</summary>" +
+            detailsInner +
+            "</details>";
+        }
 
         return (
           '<article class="route-card">' +
@@ -936,31 +1307,33 @@ function renderLeafDocsHTML(leaves) {
           methodClass +
           '">' +
           method +
-          '</span>' +
+          "</span>" +
           '<code class="route-path">' +
-          escapeHtml(route.path || '') +
-          '</code>' +
+          escapeHtml(route.path || "") +
+          "</code>" +
           (group
-            ? '<span class="group-label">' + escapeHtml(String(group)) + '</span>'
-            : '') +
-          '</header>' +
+            ? '<span class="group-label">' + escapeHtml(String(group)) + "</span>"
+            : "") +
+          "</header>" +
           '<div class="route-tags">' +
           tagHtml +
           metaBadges +
-          '</div>' +
+          "</div>" +
           (summary
-            ? '<p class="route-summary">' + escapeHtml(String(summary)) + '</p>'
-            : '') +
+            ? '<p class="route-summary">' + escapeHtml(String(summary)) + "</p>"
+            : "") +
           (description
             ? '<p class="route-description">' +
               escapeHtml(String(description)) +
-              '</p>'
-            : '') +
+              "</p>"
+            : "") +
           schemaHtml +
-          '</article>'
+          (detailsHtml ? detailsHtml : "") +
+          "</article>"
         );
       }
 
+
       function applyFilters() {
         var query = searchInput.value.toLowerCase().trim();