@vertz/server 0.2.17 → 0.2.19

package/dist/index.js

@@ -6236,6 +6236,260 @@ import {
   err as err4,
   ok as ok4
 } from "@vertz/errors";
+
+// src/entity/vertzql-parser.ts
+function extractAllowKeys(allow) {
+  if (!allow)
+    return [];
+  if (Array.isArray(allow))
+    return allow;
+  return Object.keys(allow);
+}
+var MAX_CURSOR_LENGTH = 512;
+var MAX_LIMIT = 1000;
+var MAX_Q_BASE64_LENGTH = 10240;
+var ALLOWED_Q_KEYS = new Set(["select", "include", "where", "orderBy", "limit"]);
+function parseVertzQL(query) {
+  const result = {};
+  for (const [key, value] of Object.entries(query)) {
+    const whereMatch = key.match(/^where\[([^\]]+)\](?:\[([^\]]+)\])?$/);
+    if (whereMatch) {
+      if (!result.where)
+        result.where = {};
+      const field = whereMatch[1];
+      const op = whereMatch[2];
+      const existing = result.where[field];
+      if (op) {
+        const base = existing && typeof existing === "object" ? existing : existing !== undefined ? { eq: existing } : {};
+        result.where[field] = { ...base, [op]: value };
+      } else {
+        if (existing && typeof existing === "object") {
+          result.where[field] = { ...existing, eq: value };
+        } else {
+          result.where[field] = value;
+        }
+      }
+      continue;
+    }
+    if (key === "limit") {
+      const parsed = Number.parseInt(value, 10);
+      if (!Number.isNaN(parsed)) {
+        result.limit = Math.max(0, Math.min(parsed, MAX_LIMIT));
+      }
+      continue;
+    }
+    if (key === "after") {
+      if (value && value.length <= MAX_CURSOR_LENGTH) {
+        result.after = value;
+      }
+      continue;
+    }
+    if (key === "orderBy") {
+      const [field, dir] = value.split(":");
+      if (field) {
+        if (!result.orderBy)
+          result.orderBy = {};
+        result.orderBy[field] = dir === "desc" ? "desc" : "asc";
+      }
+      continue;
+    }
+    if (key === "q") {
+      try {
+        const urlDecoded = decodeURIComponent(value);
+        if (urlDecoded.length > MAX_Q_BASE64_LENGTH) {
+          result._qError = "q= parameter exceeds maximum allowed size";
+          continue;
+        }
+        const b64 = urlDecoded.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+        const decoded = JSON.parse(atob(padded));
+        for (const k of Object.keys(decoded)) {
+          if (!ALLOWED_Q_KEYS.has(k)) {
+            delete decoded[k];
+          }
+        }
+        if (decoded.select && typeof decoded.select === "object") {
+          result.select = decoded.select;
+        }
+        if (decoded.include && typeof decoded.include === "object") {
+          result.include = decoded.include;
+        }
+        if (decoded.where && typeof decoded.where === "object" && !Array.isArray(decoded.where)) {
+          result.where = { ...result.where, ...decoded.where };
+        }
+        if (decoded.orderBy && typeof decoded.orderBy === "object" && !Array.isArray(decoded.orderBy)) {
+          const orderByObj = decoded.orderBy;
+          const sanitized = {};
+          for (const [field, dir] of Object.entries(orderByObj)) {
+            sanitized[field] = dir === "desc" ? "desc" : "asc";
+          }
+          result.orderBy = { ...result.orderBy, ...sanitized };
+        }
+        if (decoded.limit !== undefined) {
+          const parsed = typeof decoded.limit === "number" ? decoded.limit : Number(decoded.limit);
+          if (!Number.isNaN(parsed)) {
+            result.limit = Math.max(0, Math.min(parsed, MAX_LIMIT));
+          }
+        }
+      } catch {
+        result._qError = "Invalid q= parameter: not valid base64 or JSON";
+      }
+    }
+  }
+  return result;
+}
+function getHiddenColumns(table) {
+  const hidden = new Set;
+  for (const key of Object.keys(table._columns)) {
+    const col = table._columns[key];
+    if (col?._meta._annotations.hidden) {
+      hidden.add(key);
+    }
+  }
+  return hidden;
+}
+function validateVertzQL(options, table, relationsConfig, exposeConfig, evaluatedExpose) {
+  if (options._qError) {
+    return { ok: false, error: options._qError };
+  }
+  const hiddenColumns = getHiddenColumns(table);
+  if (options.where) {
+    const allowWhereSet = evaluatedExpose ? evaluatedExpose.allowedWhereFields : null;
+    const allowWhereKeys = !evaluatedExpose && exposeConfig ? extractAllowKeys(exposeConfig.allowWhere) : null;
+    for (const field of Object.keys(options.where)) {
+      if (hiddenColumns.has(field)) {
+        return { ok: false, error: `Field "${field}" is not filterable` };
+      }
+      if (allowWhereSet !== null && !allowWhereSet.has(field)) {
+        return { ok: false, error: `Field "${field}" is not filterable` };
+      }
+      if (allowWhereKeys !== null && !allowWhereKeys.includes(field)) {
+        return { ok: false, error: `Field "${field}" is not filterable` };
+      }
+    }
+  }
+  if (options.orderBy) {
+    const allowOrderBySet = evaluatedExpose ? evaluatedExpose.allowedOrderByFields : null;
+    const allowOrderByKeys = !evaluatedExpose && exposeConfig ? extractAllowKeys(exposeConfig.allowOrderBy) : null;
+    for (const field of Object.keys(options.orderBy)) {
+      if (hiddenColumns.has(field)) {
+        return { ok: false, error: `Field "${field}" is not sortable` };
+      }
+      if (allowOrderBySet !== null && !allowOrderBySet.has(field)) {
+        return { ok: false, error: `Field "${field}" is not sortable` };
+      }
+      if (allowOrderByKeys !== null && !allowOrderByKeys.includes(field)) {
+        return { ok: false, error: `Field "${field}" is not sortable` };
+      }
+    }
+  }
+  if (options.select) {
+    const exposeSelectKeys = exposeConfig ? extractAllowKeys(exposeConfig.select) : null;
+    for (const field of Object.keys(options.select)) {
+      if (hiddenColumns.has(field)) {
+        return { ok: false, error: `Field "${field}" is not selectable` };
+      }
+      if (exposeSelectKeys !== null && exposeSelectKeys.length > 0 && !exposeSelectKeys.includes(field)) {
+        return { ok: false, error: `Field "${field}" is not selectable` };
+      }
+    }
+  }
+  if (options.include && relationsConfig) {
+    const includeResult = validateInclude(options.include, relationsConfig, "");
+    if (!includeResult.ok)
+      return includeResult;
+  }
+  return { ok: true };
+}
+function validateInclude(include, relationsConfig, pathPrefix) {
+  for (const [relation, requested] of Object.entries(include)) {
+    const entityConfig = relationsConfig[relation];
+    const relationPath = pathPrefix ? `${pathPrefix}.${relation}` : relation;
+    if (entityConfig === undefined || entityConfig === false) {
+      return { ok: false, error: `Relation "${relationPath}" is not exposed` };
+    }
+    if (requested === true)
+      continue;
+    const configObj = typeof entityConfig === "object" ? entityConfig : undefined;
+    if (requested.where) {
+      const allowWhereKeys = extractAllowKeys(configObj?.allowWhere);
+      if (!configObj || allowWhereKeys.length === 0) {
+        return {
+          ok: false,
+          error: `Filtering is not enabled on relation '${relationPath}'. ` + "Add 'allowWhere' to the entity relations config."
+        };
+      }
+      const allowedSet = new Set(allowWhereKeys);
+      for (const field of Object.keys(requested.where)) {
+        if (!allowedSet.has(field)) {
+          return {
+            ok: false,
+            error: `Field '${field}' is not filterable on relation '${relationPath}'. ` + `Allowed: ${allowWhereKeys.join(", ")}`
+          };
+        }
+      }
+    }
+    if (requested.orderBy) {
+      const allowOrderByKeys = extractAllowKeys(configObj?.allowOrderBy);
+      if (!configObj || allowOrderByKeys.length === 0) {
+        return {
+          ok: false,
+          error: `Sorting is not enabled on relation '${relationPath}'. ` + "Add 'allowOrderBy' to the entity relations config."
+        };
+      }
+      const allowedSet = new Set(allowOrderByKeys);
+      for (const [field, dir] of Object.entries(requested.orderBy)) {
+        if (!allowedSet.has(field)) {
+          return {
+            ok: false,
+            error: `Field '${field}' is not sortable on relation '${relationPath}'. ` + `Allowed: ${allowOrderByKeys.join(", ")}`
+          };
+        }
+        if (dir !== "asc" && dir !== "desc") {
+          return {
+            ok: false,
+            error: `Invalid orderBy direction '${String(dir)}' for field '${field}' on relation '${relationPath}'. Must be 'asc' or 'desc'.`
+          };
+        }
+      }
+    }
+    if (requested.limit !== undefined) {
+      if (typeof requested.limit !== "number" || !Number.isFinite(requested.limit)) {
+        return {
+          ok: false,
+          error: `Invalid limit on relation '${relationPath}': must be a finite number`
+        };
+      }
+      if (requested.limit < 0) {
+        requested.limit = 0;
+      }
+      if (configObj?.maxLimit !== undefined && requested.limit > configObj.maxLimit) {
+        requested.limit = configObj.maxLimit;
+      }
+    }
+    if (requested.select && configObj?.select) {
+      for (const field of Object.keys(requested.select)) {
+        if (!(field in configObj.select)) {
+          return {
+            ok: false,
+            error: `Field "${field}" is not exposed on relation "${relationPath}"`
+          };
+        }
+      }
+    }
+    if (requested.include) {
+      if (entityConfig === true) {
+        return {
+          ok: false,
+          error: `Nested includes are not supported on relation '${relationPath}' ` + "without a structured relations config."
+        };
+      }
+    }
+  }
+  return { ok: true };
+}
+
+// src/entity/crud-pipeline.ts
 function resolvePrimaryKeyColumn(table) {
   for (const key of Object.keys(table._columns)) {
     const col = table._columns[key];
@@ -6320,7 +6574,7 @@ function createCrudHandlers(def, db, options) {
       const indirectWhere = await resolveIndirectTenantWhere(ctx);
       const where = indirectWhere ? { ...directWhere, ...indirectWhere } : directWhere;
       const limit = Math.max(0, options2?.limit ?? 20);
-      const after = options2?.after && options2.after.length <= 512 ? options2.after : undefined;
+      const after = options2?.after && options2.after.length <= MAX_CURSOR_LENGTH ? options2.after : undefined;
       const orderBy = options2?.orderBy;
       const include = options2?.include;
       const { data: rows, total } = await db.list({ where, orderBy, limit, after, include });
@@ -6521,310 +6775,76 @@ async function evaluateExposeRule(rule, ctx, options) {
       return options.can(rule.entitlement);
     }
     case "where":
-      return false;
-    case "all": {
-      for (const sub of rule.rules) {
-        if (!await evaluateExposeRule(sub, ctx, options))
-          return false;
-      }
-      return true;
-    }
-    case "any": {
-      for (const sub of rule.rules) {
-        if (await evaluateExposeRule(sub, ctx, options))
-          return true;
-      }
-      return false;
-    }
-    case "fva": {
-      if (options.fvaAge === undefined)
-        return false;
-      return options.fvaAge <= rule.maxAge;
-    }
-  }
-}
-async function evaluateExposeDescriptors(expose, ctx, options = {}) {
-  const allowedSelectFields = new Set;
-  const nulledFields = new Set;
-  const allowedWhereFields = new Set;
-  const allowedOrderByFields = new Set;
-  for (const [field, value] of Object.entries(expose.select)) {
-    if (value === true) {
-      allowedSelectFields.add(field);
-    } else {
-      const passed = await evaluateExposeRule(value, ctx, options);
-      if (passed) {
-        allowedSelectFields.add(field);
-      } else {
-        allowedSelectFields.add(field);
-        nulledFields.add(field);
-      }
-    }
-  }
-  if (expose.allowWhere) {
-    for (const [field, value] of Object.entries(expose.allowWhere)) {
-      if (value === true) {
-        allowedWhereFields.add(field);
-      } else {
-        const passed = await evaluateExposeRule(value, ctx, options);
-        if (passed) {
-          allowedWhereFields.add(field);
-        }
-      }
-    }
-  }
-  if (expose.allowOrderBy) {
-    for (const [field, value] of Object.entries(expose.allowOrderBy)) {
-      if (value === true) {
-        allowedOrderByFields.add(field);
-      } else {
-        const passed = await evaluateExposeRule(value, ctx, options);
-        if (passed) {
-          allowedOrderByFields.add(field);
-        }
-      }
-    }
-  }
-  return {
-    allowedSelectFields,
-    nulledFields,
-    allowedWhereFields,
-    allowedOrderByFields
-  };
-}
-
-// src/entity/vertzql-parser.ts
-function extractAllowKeys(allow) {
-  if (!allow)
-    return [];
-  if (Array.isArray(allow))
-    return allow;
-  return Object.keys(allow);
-}
-var MAX_LIMIT = 1000;
-var MAX_Q_BASE64_LENGTH = 10240;
-var ALLOWED_Q_KEYS = new Set(["select", "include", "where", "orderBy", "limit", "offset"]);
-function parseVertzQL(query) {
-  const result = {};
-  for (const [key, value] of Object.entries(query)) {
-    const whereMatch = key.match(/^where\[([^\]]+)\](?:\[([^\]]+)\])?$/);
-    if (whereMatch) {
-      if (!result.where)
-        result.where = {};
-      const field = whereMatch[1];
-      const op = whereMatch[2];
-      const existing = result.where[field];
-      if (op) {
-        const base = existing && typeof existing === "object" ? existing : existing !== undefined ? { eq: existing } : {};
-        result.where[field] = { ...base, [op]: value };
-      } else {
-        if (existing && typeof existing === "object") {
-          result.where[field] = { ...existing, eq: value };
-        } else {
-          result.where[field] = value;
-        }
-      }
-      continue;
-    }
-    if (key === "limit") {
-      const parsed = Number.parseInt(value, 10);
-      if (!Number.isNaN(parsed)) {
-        result.limit = Math.max(0, Math.min(parsed, MAX_LIMIT));
-      }
-      continue;
-    }
-    if (key === "after") {
-      if (value) {
-        result.after = value;
-      }
-      continue;
-    }
-    if (key === "orderBy") {
-      const [field, dir] = value.split(":");
-      if (field) {
-        if (!result.orderBy)
-          result.orderBy = {};
-        result.orderBy[field] = dir === "desc" ? "desc" : "asc";
-      }
-      continue;
-    }
-    if (key === "q") {
-      try {
-        const urlDecoded = decodeURIComponent(value);
-        if (urlDecoded.length > MAX_Q_BASE64_LENGTH) {
-          result._qError = "q= parameter exceeds maximum allowed size";
-          continue;
-        }
-        const b64 = urlDecoded.replace(/-/g, "+").replace(/_/g, "/");
-        const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
-        const decoded = JSON.parse(atob(padded));
-        for (const k of Object.keys(decoded)) {
-          if (!ALLOWED_Q_KEYS.has(k)) {
-            delete decoded[k];
-          }
-        }
-        if (decoded.select && typeof decoded.select === "object") {
-          result.select = decoded.select;
-        }
-        if (decoded.include && typeof decoded.include === "object") {
-          result.include = decoded.include;
-        }
-      } catch {
-        result._qError = "Invalid q= parameter: not valid base64 or JSON";
-      }
-    }
-  }
-  return result;
-}
-function getHiddenColumns(table) {
-  const hidden = new Set;
-  for (const key of Object.keys(table._columns)) {
-    const col = table._columns[key];
-    if (col?._meta._annotations.hidden) {
-      hidden.add(key);
-    }
-  }
-  return hidden;
-}
-function validateVertzQL(options, table, relationsConfig, exposeConfig, evaluatedExpose) {
-  if (options._qError) {
-    return { ok: false, error: options._qError };
-  }
-  const hiddenColumns = getHiddenColumns(table);
-  if (options.where) {
-    const allowWhereSet = evaluatedExpose ? evaluatedExpose.allowedWhereFields : null;
-    const allowWhereKeys = !evaluatedExpose && exposeConfig ? extractAllowKeys(exposeConfig.allowWhere) : null;
-    for (const field of Object.keys(options.where)) {
-      if (hiddenColumns.has(field)) {
-        return { ok: false, error: `Field "${field}" is not filterable` };
-      }
-      if (allowWhereSet !== null && !allowWhereSet.has(field)) {
-        return { ok: false, error: `Field "${field}" is not filterable` };
-      }
-      if (allowWhereKeys !== null && !allowWhereKeys.includes(field)) {
-        return { ok: false, error: `Field "${field}" is not filterable` };
-      }
-    }
-  }
-  if (options.orderBy) {
-    const allowOrderBySet = evaluatedExpose ? evaluatedExpose.allowedOrderByFields : null;
-    const allowOrderByKeys = !evaluatedExpose && exposeConfig ? extractAllowKeys(exposeConfig.allowOrderBy) : null;
-    for (const field of Object.keys(options.orderBy)) {
-      if (hiddenColumns.has(field)) {
-        return { ok: false, error: `Field "${field}" is not sortable` };
-      }
-      if (allowOrderBySet !== null && !allowOrderBySet.has(field)) {
-        return { ok: false, error: `Field "${field}" is not sortable` };
-      }
-      if (allowOrderByKeys !== null && !allowOrderByKeys.includes(field)) {
-        return { ok: false, error: `Field "${field}" is not sortable` };
-      }
-    }
-  }
-  if (options.select) {
-    const exposeSelectKeys = exposeConfig ? extractAllowKeys(exposeConfig.select) : null;
-    for (const field of Object.keys(options.select)) {
-      if (hiddenColumns.has(field)) {
-        return { ok: false, error: `Field "${field}" is not selectable` };
-      }
-      if (exposeSelectKeys !== null && exposeSelectKeys.length > 0 && !exposeSelectKeys.includes(field)) {
-        return { ok: false, error: `Field "${field}" is not selectable` };
-      }
-    }
-  }
-  if (options.include && relationsConfig) {
-    const includeResult = validateInclude(options.include, relationsConfig, "");
-    if (!includeResult.ok)
-      return includeResult;
-  }
-  return { ok: true };
-}
-function validateInclude(include, relationsConfig, pathPrefix) {
-  for (const [relation, requested] of Object.entries(include)) {
-    const entityConfig = relationsConfig[relation];
-    const relationPath = pathPrefix ? `${pathPrefix}.${relation}` : relation;
-    if (entityConfig === undefined || entityConfig === false) {
-      return { ok: false, error: `Relation "${relationPath}" is not exposed` };
-    }
-    if (requested === true)
-      continue;
-    const configObj = typeof entityConfig === "object" ? entityConfig : undefined;
-    if (requested.where) {
-      const allowWhereKeys = extractAllowKeys(configObj?.allowWhere);
-      if (!configObj || allowWhereKeys.length === 0) {
-        return {
-          ok: false,
-          error: `Filtering is not enabled on relation '${relationPath}'. ` + "Add 'allowWhere' to the entity relations config."
-        };
-      }
-      const allowedSet = new Set(allowWhereKeys);
-      for (const field of Object.keys(requested.where)) {
-        if (!allowedSet.has(field)) {
-          return {
-            ok: false,
-            error: `Field '${field}' is not filterable on relation '${relationPath}'. ` + `Allowed: ${allowWhereKeys.join(", ")}`
-          };
-        }
+      return false;
+    case "all": {
+      for (const sub of rule.rules) {
+        if (!await evaluateExposeRule(sub, ctx, options))
+          return false;
       }
+      return true;
     }
-    if (requested.orderBy) {
-      const allowOrderByKeys = extractAllowKeys(configObj?.allowOrderBy);
-      if (!configObj || allowOrderByKeys.length === 0) {
-        return {
-          ok: false,
-          error: `Sorting is not enabled on relation '${relationPath}'. ` + "Add 'allowOrderBy' to the entity relations config."
-        };
-      }
-      const allowedSet = new Set(allowOrderByKeys);
-      for (const [field, dir] of Object.entries(requested.orderBy)) {
-        if (!allowedSet.has(field)) {
-          return {
-            ok: false,
-            error: `Field '${field}' is not sortable on relation '${relationPath}'. ` + `Allowed: ${allowOrderByKeys.join(", ")}`
-          };
-        }
-        if (dir !== "asc" && dir !== "desc") {
-          return {
-            ok: false,
-            error: `Invalid orderBy direction '${String(dir)}' for field '${field}' on relation '${relationPath}'. Must be 'asc' or 'desc'.`
-          };
-        }
+    case "any": {
+      for (const sub of rule.rules) {
+        if (await evaluateExposeRule(sub, ctx, options))
+          return true;
       }
+      return false;
     }
-    if (requested.limit !== undefined) {
-      if (typeof requested.limit !== "number" || !Number.isFinite(requested.limit)) {
-        return {
-          ok: false,
-          error: `Invalid limit on relation '${relationPath}': must be a finite number`
-        };
-      }
-      if (requested.limit < 0) {
-        requested.limit = 0;
-      }
-      if (configObj?.maxLimit !== undefined && requested.limit > configObj.maxLimit) {
-        requested.limit = configObj.maxLimit;
+    case "fva": {
+      if (options.fvaAge === undefined)
+        return false;
+      return options.fvaAge <= rule.maxAge;
+    }
+  }
+}
+async function evaluateExposeDescriptors(expose, ctx, options = {}) {
+  const allowedSelectFields = new Set;
+  const nulledFields = new Set;
+  const allowedWhereFields = new Set;
+  const allowedOrderByFields = new Set;
+  for (const [field, value] of Object.entries(expose.select)) {
+    if (value === true) {
+      allowedSelectFields.add(field);
+    } else {
+      const passed = await evaluateExposeRule(value, ctx, options);
+      if (passed) {
+        allowedSelectFields.add(field);
+      } else {
+        allowedSelectFields.add(field);
+        nulledFields.add(field);
       }
     }
-    if (requested.select && configObj?.select) {
-      for (const field of Object.keys(requested.select)) {
-        if (!(field in configObj.select)) {
-          return {
-            ok: false,
-            error: `Field "${field}" is not exposed on relation "${relationPath}"`
-          };
+  }
+  if (expose.allowWhere) {
+    for (const [field, value] of Object.entries(expose.allowWhere)) {
+      if (value === true) {
+        allowedWhereFields.add(field);
+      } else {
+        const passed = await evaluateExposeRule(value, ctx, options);
+        if (passed) {
+          allowedWhereFields.add(field);
         }
       }
     }
-    if (requested.include) {
-      if (entityConfig === true) {
-        return {
-          ok: false,
-          error: `Nested includes are not supported on relation '${relationPath}' ` + "without a structured relations config."
-        };
+  }
+  if (expose.allowOrderBy) {
+    for (const [field, value] of Object.entries(expose.allowOrderBy)) {
+      if (value === true) {
+        allowedOrderByFields.add(field);
+      } else {
+        const passed = await evaluateExposeRule(value, ctx, options);
+        if (passed) {
+          allowedOrderByFields.add(field);
+        }
       }
     }
   }
-  return { ok: true };
+  return {
+    allowedSelectFields,
+    nulledFields,
+    allowedWhereFields,
+    allowedOrderByFields
+  };
 }
 
 // src/entity/route-generator.ts
@@ -6940,6 +6960,19 @@ function generateEntityRoutes(def, registry, db, options) {
         try {
           const entityCtx = makeEntityCtx(ctx);
           const body = ctx.body ?? {};
+          if (body.after !== undefined) {
+            if (typeof body.after !== "string") {
+              return jsonResponse({ error: { code: "BadRequest", message: "cursor must be a string" } }, 400);
+            }
+            if (body.after.length > MAX_CURSOR_LENGTH) {
+              return jsonResponse({
+                error: {
+                  code: "BadRequest",
+                  message: `cursor exceeds maximum length of ${MAX_CURSOR_LENGTH}`
+                }
+              }, 400);
+            }
+          }
           const parsed = {
             where: body.where,
             orderBy: body.orderBy,
@@ -7627,6 +7660,549 @@ function entity(name, config) {
   };
   return deepFreeze(def);
 }
+// src/entity/openapi-generator.ts
+function columnToJsonSchema(column) {
+  const meta = column._meta;
+  const schema = sqlTypeToJsonSchema(meta);
+  if (meta.nullable) {
+    const baseType = schema.type;
+    if (baseType) {
+      schema.type = [baseType, "null"];
+    } else {
+      return { oneOf: [schema, { type: "null" }] };
+    }
+  }
+  return schema;
+}
+function sqlTypeToJsonSchema(meta) {
+  if (meta.format === "email") {
+    return { type: "string", format: "email" };
+  }
+  switch (meta.sqlType) {
+    case "uuid":
+      return { type: "string", format: "uuid" };
+    case "text":
+      return { type: "string" };
+    case "varchar": {
+      const schema = { type: "string" };
+      if (meta.length !== undefined)
+        schema.maxLength = meta.length;
+      return schema;
+    }
+    case "boolean":
+      return { type: "boolean" };
+    case "integer":
+    case "serial":
+      return { type: "integer" };
+    case "bigint":
+    case "decimal":
+      return { type: "string" };
+    case "real":
+      return { type: "number" };
+    case "double precision":
+      return { type: "number", format: "double" };
+    case "timestamp with time zone":
+      return { type: "string", format: "date-time" };
+    case "date":
+      return { type: "string", format: "date" };
+    case "time":
+      return { type: "string", format: "time" };
+    case "jsonb":
+      return {};
+    case "text[]":
+      return { type: "array", items: { type: "string" } };
+    case "integer[]":
+      return { type: "array", items: { type: "integer" } };
+    case "enum":
+      return { type: "string", enum: meta.enumValues };
+    default:
+      return {};
+  }
+}
+function toPascalCase(name) {
+  return name.split("-").map((s2) => s2.charAt(0).toUpperCase() + s2.slice(1)).join("");
+}
+function buildColumnsSchema(columns, selectFilter) {
+  const properties = {};
+  const required = [];
+  for (const [name, col] of Object.entries(columns)) {
+    const meta = col._meta;
+    if (meta._annotations.hidden)
+      continue;
+    if (selectFilter && !(name in selectFilter))
+      continue;
+    const isDescriptorGuarded = selectFilter && selectFilter[name] !== true;
+    let schema = columnToJsonSchema(col);
+    if (isDescriptorGuarded) {
+      const baseType = schema.type;
+      if (baseType) {
+        const typeArray = Array.isArray(baseType) ? baseType : [baseType];
+        if (!typeArray.includes("null")) {
+          schema = { ...schema, type: [...typeArray, "null"] };
+        }
+      }
+      const descriptor = selectFilter?.[name];
+      const entitlementName = descriptor.entitlement ?? descriptor.type ?? "access rule";
+      schema.description = `Requires entitlement '${entitlementName}'. Returns null when the caller lacks the entitlement.`;
+    }
+    properties[name] = schema;
+    if (!meta.nullable && !isDescriptorGuarded) {
+      required.push(name);
+    }
+  }
+  const result = { type: "object", properties };
+  if (required.length > 0)
+    result.required = required;
+  return result;
+}
+function entityResponseSchema(def, relationSchemas) {
+  const table = def.model.table;
+  const columns = table._columns;
+  const exposeSelect = def.expose?.select;
+  const schema = buildColumnsSchema(columns, exposeSelect);
+  if (def.expose?.include && relationSchemas) {
+    const relations = def.model.relations;
+    const includeConfig = def.expose.include;
+    const entityPrefix = toPascalCase(def.name);
+    for (const [relationName, config] of Object.entries(includeConfig)) {
+      if (config === false)
+        continue;
+      const relation = relations[relationName];
+      if (!relation)
+        continue;
+      const targetTable = relation._target();
+      const targetColumns = targetTable._columns;
+      const relationSchemaName = `${entityPrefix}${toPascalCase(relationName)}Response`;
+      if (config === true) {
+        relationSchemas[relationSchemaName] = buildColumnsSchema(targetColumns);
+      } else {
+        const relSelect = config.select;
+        relationSchemas[relationSchemaName] = buildColumnsSchema(targetColumns, relSelect);
+      }
+      if (schema.properties) {
+        const isMany = relation._type === "many";
+        if (isMany) {
+          schema.properties[relationName] = {
+            type: "array",
+            items: { $ref: `#/components/schemas/${relationSchemaName}` }
+          };
+        } else {
+          schema.properties[relationName] = {
+            $ref: `#/components/schemas/${relationSchemaName}`
+          };
+        }
+      }
+    }
+  }
+  return schema;
+}
+function buildInputColumnsSchema(columns, allOptional) {
+  const properties = {};
+  const required = [];
+  for (const [name, col] of Object.entries(columns)) {
+    const meta = col._meta;
+    if (meta.primary)
+      continue;
+    if (meta.isReadOnly)
+      continue;
+    if (meta.isAutoUpdate)
+      continue;
+    if (meta._annotations.hidden)
+      continue;
+    properties[name] = columnToJsonSchema(col);
+    if (!allOptional && !meta.nullable && !meta.hasDefault) {
+      required.push(name);
+    }
+  }
+  const result = { type: "object", properties };
+  if (required.length > 0)
+    result.required = required;
+  return result;
+}
+function entityCreateInputSchema(def) {
+  const table = def.model.table;
+  const columns = table._columns;
+  return buildInputColumnsSchema(columns, false);
+}
+function entityUpdateInputSchema(def) {
+  const table = def.model.table;
+  const columns = table._columns;
+  return buildInputColumnsSchema(columns, true);
+}
+var ERROR_RESPONSE_SCHEMA = {
+  type: "object",
+  required: ["error"],
+  properties: {
+    error: {
+      type: "object",
+      required: ["code", "message"],
+      properties: {
+        code: { type: "string" },
+        message: { type: "string" }
+      }
+    }
+  }
+};
+var STANDARD_RESPONSES = {
+  BadRequest: {
+    description: "Bad Request",
+    content: {
+      "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } }
+    }
+  },
+  Unauthorized: {
+    description: "Unauthorized",
+    content: {
+      "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } }
+    }
+  },
+  NotFound: {
+    description: "Not Found",
+    content: {
+      "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } }
+    }
+  }
+};
+function errorRefs(...codes) {
+  const result = {};
+  for (const code of codes) {
+    const refName = code === "400" ? "BadRequest" : code === "401" ? "Unauthorized" : "NotFound";
+    result[code] = { $ref: `#/components/responses/${refName}` };
+  }
+  return result;
+}
+function extractJsonSchema(schema, entityName, actionName, field) {
+  if (schema && typeof schema === "object" && "toJSONSchema" in schema && typeof schema.toJSONSchema === "function") {
+    return schema.toJSONSchema();
+  }
+  console.warn(`[vertz] Warning: Action "${entityName}.${actionName}" ${field} schema does not expose JSON schema — using "any" in OpenAPI spec.`);
+  return { description: "Schema not available for automated extraction." };
+}
+function generateOpenAPISpec(entities, options) {
+  const apiPrefix = options.apiPrefix ?? "/api";
+  const paths = {};
+  const schemas = {
+    ErrorResponse: ERROR_RESPONSE_SCHEMA
+  };
+  const tags = [];
+  for (const def of entities) {
+    const prefix = toPascalCase(def.name);
+    const basePath = `${apiPrefix}/${def.name}`;
+    const tag = def.name;
+    tags.push({ name: tag });
+    const relationSchemas = {};
+    schemas[`${prefix}Response`] = entityResponseSchema(def, relationSchemas);
+    Object.assign(schemas, relationSchemas);
+    if (def.access.create !== undefined) {
+      schemas[`${prefix}CreateInput`] = entityCreateInputSchema(def);
+    }
+    if (def.access.update !== undefined) {
+      schemas[`${prefix}UpdateInput`] = entityUpdateInputSchema(def);
+    }
+    const collectionPath = {};
+    const itemPath = {};
+    if (def.access.list !== undefined && def.access.list !== false) {
+      collectionPath.get = buildListOperation(def, prefix, tag);
+    }
+    if (def.access.create !== undefined && def.access.create !== false) {
+      collectionPath.post = buildCreateOperation(prefix, tag);
+    }
+    if (def.access.get !== undefined && def.access.get !== false) {
+      itemPath.get = buildGetOperation(prefix, tag);
+    }
+    if (def.access.update !== undefined && def.access.update !== false) {
+      itemPath.patch = buildUpdateOperation(prefix, tag);
+    }
+    if (def.access.delete === false) {
+      itemPath.delete = buildDisabledOperation(def.name, "delete", tag);
+    } else if (def.access.delete !== undefined) {
+      itemPath.delete = buildDeleteOperation(def.name, tag);
+    }
+    if (Object.keys(collectionPath).length > 0) {
+      paths[basePath] = collectionPath;
+    }
+    if (Object.keys(itemPath).length > 0) {
+      paths[`${basePath}/{id}`] = itemPath;
+    }
+    if (def.access.list !== undefined && def.access.list !== false) {
+      paths[`${basePath}/query`] = {
+        post: buildQueryOperation(def.name, prefix, tag)
+      };
+    }
+    if (def.actions) {
+      for (const [actionName, actionDef] of Object.entries(def.actions)) {
+        const method = (actionDef.method ?? "POST").toUpperCase();
+        const actionPath = actionDef.path ?? actionName;
+        const fullPath = `${basePath}/{id}/${actionPath}`;
+        const operation = buildActionOperation(def.name, actionName, actionDef, tag);
+        const pathItem = {};
+        if (method === "POST") {
+          pathItem.post = operation;
+        } else if (method === "PATCH") {
+          pathItem.patch = operation;
+        } else if (method === "GET") {
+          pathItem.get = operation;
+        } else if (method === "DELETE") {
+          pathItem.delete = operation;
+        }
+        paths[fullPath] = pathItem;
+      }
+    }
+  }
+  const spec = {
+    openapi: "3.1.0",
+    info: options.info,
+    paths,
+    components: {
+      schemas,
+      responses: STANDARD_RESPONSES
+    },
+    tags
+  };
+  if (options.servers) {
+    spec.servers = options.servers;
+  }
+  return spec;
+}
+function buildListOperation(def, prefix, tag) {
+  const parameters = [];
+  const table = def.model.table;
+  const columns = table._columns;
+  const expose = def.expose;
+  if (expose?.allowWhere) {
+    const allowWhere = expose.allowWhere;
+    for (const field of Object.keys(allowWhere)) {
+      const col = columns[field];
+      if (!col)
+        continue;
+      const schema = columnToJsonSchema(col);
+      parameters.push({
+        name: `where[${field}]`,
+        in: "query",
+        required: false,
+        schema
+      });
+    }
+  }
+  if (expose?.allowOrderBy) {
+    const allowedFields = Object.keys(expose.allowOrderBy);
+    parameters.push({
+      name: "orderBy",
+      in: "query",
+      required: false,
+      schema: {
+        type: "string",
+        enum: allowedFields.flatMap((f) => [`${f}:asc`, `${f}:desc`])
+      },
+      description: "Sort order. Format: field:direction"
+    });
+  }
+  parameters.push({ name: "limit", in: "query", required: false, schema: { type: "integer" } }, { name: "after", in: "query", required: false, schema: { type: "string" } }, {
+    name: "q",
+    in: "query",
+    required: false,
+    schema: { type: "string" },
+    description: "Base64-encoded VertzQL query"
+  });
+  return {
+    operationId: `${def.name}_list`,
+    tags: [tag],
+    summary: `List ${def.name}`,
+    parameters,
+    responses: {
+      "200": {
+        description: "OK",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                items: {
+                  type: "array",
+                  items: { $ref: `#/components/schemas/${prefix}Response` }
+                },
+                cursor: { type: "string" }
+              }
+            }
+          }
+        }
+      },
+      ...errorRefs("400", "401")
+    }
+  };
+}
+function buildCreateOperation(prefix, tag) {
+  return {
+    operationId: `${tag}_create`,
+    tags: [tag],
+    summary: `Create a ${tag}`,
+    requestBody: {
+      required: true,
+      content: {
+        "application/json": {
+          schema: { $ref: `#/components/schemas/${prefix}CreateInput` }
+        }
+      }
+    },
+    responses: {
+      "201": {
+        description: "Created",
+        content: {
+          "application/json": {
+            schema: { $ref: `#/components/schemas/${prefix}Response` }
+          }
+        }
+      },
+      ...errorRefs("400", "401")
+    }
+  };
+}
+function buildGetOperation(prefix, tag) {
+  return {
+    operationId: `${tag}_get`,
+    tags: [tag],
+    summary: `Get a ${tag} by ID`,
+    parameters: [
+      { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+    ],
+    responses: {
+      "200": {
+        description: "OK",
+        content: {
+          "application/json": {
+            schema: { $ref: `#/components/schemas/${prefix}Response` }
+          }
+        }
+      },
+      ...errorRefs("401", "404")
+    }
+  };
+}
+function buildUpdateOperation(prefix, tag) {
+  return {
+    operationId: `${tag}_update`,
+    tags: [tag],
+    summary: `Update a ${tag}`,
+    parameters: [
+      { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+    ],
+    requestBody: {
+      required: true,
+      content: {
+        "application/json": {
+          schema: { $ref: `#/components/schemas/${prefix}UpdateInput` }
+        }
+      }
+    },
+    responses: {
+      "200": {
+        description: "OK",
+        content: {
+          "application/json": {
+            schema: { $ref: `#/components/schemas/${prefix}Response` }
+          }
+        }
+      },
+      ...errorRefs("400", "401", "404")
+    }
+  };
+}
+function buildDeleteOperation(entityName, tag) {
+  return {
+    operationId: `${entityName}_delete`,
+    tags: [tag],
+    summary: `Delete a ${entityName}`,
+    parameters: [
+      { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+    ],
+    responses: {
+      "204": { description: "No Content" },
+      ...errorRefs("401", "404")
+    }
+  };
+}
+function buildDisabledOperation(entityName, operation, tag) {
+  return {
+    operationId: `${entityName}_${operation}`,
+    tags: [tag],
+    summary: `${operation} is disabled for ${entityName}`,
+    parameters: [
+      { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+    ],
+    responses: {
+      "405": {
+        description: `Method Not Allowed — operation "${operation}" is disabled for ${entityName}`
+      }
+    }
+  };
+}
+function buildQueryOperation(entityName, prefix, tag) {
+  return {
+    operationId: `${entityName}_query`,
+    tags: [tag],
+    summary: `Query ${entityName} (structured query via POST body)`,
+    requestBody: {
+      required: true,
+      content: {
+        "application/json": {
+          schema: { $ref: `#/components/schemas/${prefix}Query` }
+        }
+      }
+    },
+    responses: {
+      "200": {
+        description: "OK",
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: {
+                items: {
+                  type: "array",
+                  items: { $ref: `#/components/schemas/${prefix}Response` }
+                },
+                cursor: { type: "string" }
+              }
+            }
+          }
+        }
+      },
+      ...errorRefs("400", "401")
+    }
+  };
+}
+function buildActionOperation(entityName, actionName, actionDef, tag) {
+  const operation = {
+    operationId: `${entityName}_${actionName}`,
+    tags: [tag],
+    summary: `${actionName} action on ${entityName}`,
+    parameters: [
+      { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
+    ],
+    responses: {
+      "200": {
+        description: "OK",
+        content: {
+          "application/json": {
+            schema: extractJsonSchema(actionDef.response, entityName, actionName, "response")
+          }
+        }
+      },
+      ...errorRefs("400", "401", "404")
+    }
+  };
+  if (actionDef.body) {
+    operation.requestBody = {
+      required: true,
+      content: {
+        "application/json": {
+          schema: extractJsonSchema(actionDef.body, entityName, actionName, "body")
+        }
+      }
+    };
+  }
+  return operation;
+}
 // src/service/service.ts
 import { deepFreeze as deepFreeze2 } from "@vertz/core";
 var SERVICE_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -7664,8 +8240,12 @@ export {
   google,
   github,
   getIncompatibleAddOns,
+  generateOpenAPISpec,
   generateEntityRoutes,
+  entityUpdateInputSchema,
+  entityResponseSchema,
   entityErrorHandler,
+  entityCreateInputSchema,
   entity,
   enforceAccess,
   encodeAccessSet,
@@ -7693,6 +8273,7 @@ export {
   computeOverage,
   computeEntityAccess,
   computeAccessSet,
+  columnToJsonSchema,
   checkFva,
   checkAddOnCompatibility,
   calculateBillingPeriod,