@vertz/server 0.2.18 → 0.2.19

package/dist/index.d.ts

@@ -2063,6 +2063,123 @@ declare function stripHiddenFields(table: TableDef2, data: Record<string, unknow
 * Used before DB writes to prevent setting immutable fields.
 */
 declare function stripReadOnlyFields(table: TableDef2, data: Record<string, unknown>): Record<string, unknown>;
+import { ColumnBuilder, ColumnMetadata } from "@vertz/db";
+interface JSONSchemaObject {
+	type?: string | string[];
+	format?: string;
+	enum?: readonly (string | number | boolean | null)[];
+	items?: JSONSchemaObject;
+	maxLength?: number;
+	description?: string;
+	$ref?: string;
+	[key: string]: unknown;
+}
+/**
+* Maps a single database column to its JSON Schema representation.
+*/
+declare function columnToJsonSchema(column: ColumnBuilder<unknown, ColumnMetadata>): JSONSchemaObject;
+interface EntitySchemaObject {
+	type: "object";
+	required?: string[];
+	properties?: Record<string, JSONSchemaObject>;
+}
+/**
+* Generates a JSON Schema for an entity's response shape.
+*
+* When `expose.select` is present, only listed fields appear.
+* Otherwise, all public (non-hidden) columns appear.
+* Descriptor-guarded fields (AccessRule values) become nullable with a description.
+*
+* If `relationSchemas` is provided, relation schemas are collected into it
+* with keys like `TasksAssigneeResponse`, and $ref properties are added
+* to the parent schema for each relation.
+*/
+declare function entityResponseSchema(def: EntityDefinition, relationSchemas?: Record<string, EntitySchemaObject>): EntitySchemaObject;
+/**
+* Generates a JSON Schema for an entity's create input.
+* Excludes PK, readOnly, autoUpdate, and hidden columns.
+* Fields with defaults or nullable are optional.
+*/
+declare function entityCreateInputSchema(def: EntityDefinition): EntitySchemaObject;
+/**
+* Generates a JSON Schema for an entity's update input (PATCH).
+* Same exclusions as create, but all fields are optional.
+*/
+declare function entityUpdateInputSchema(def: EntityDefinition): EntitySchemaObject;
+interface OpenAPISpecOptions {
+	info: {
+		title: string;
+		version: string;
+		description?: string;
+	};
+	servers?: {
+		url: string;
+		description?: string;
+	}[];
+	/** API path prefix. Defaults to '/api'. */
+	apiPrefix?: string;
+}
+interface OpenAPIOperation {
+	operationId: string;
+	tags: string[];
+	summary: string;
+	parameters?: OpenAPIParameter[];
+	requestBody?: {
+		required: boolean;
+		content: {
+			"application/json": {
+				schema: JSONSchemaObject;
+			};
+		};
+	};
+	responses: Record<string, OpenAPIResponse>;
+}
+interface OpenAPIParameter {
+	name: string;
+	in: "path" | "query";
+	required: boolean;
+	schema: JSONSchemaObject;
+	description?: string;
+}
+interface OpenAPIResponse {
+	description: string;
+	content?: {
+		"application/json": {
+			schema: JSONSchemaObject | EntitySchemaObject;
+		};
+	};
+	$ref?: string;
+}
+interface OpenAPIPathItem {
+	get?: OpenAPIOperation;
+	post?: OpenAPIOperation;
+	patch?: OpenAPIOperation;
+	delete?: OpenAPIOperation;
+}
+interface OpenAPISpec {
+	openapi: "3.1.0";
+	info: {
+		title: string;
+		version: string;
+		description?: string;
+	};
+	servers?: {
+		url: string;
+		description?: string;
+	}[];
+	paths: Record<string, OpenAPIPathItem>;
+	components?: {
+		schemas?: Record<string, EntitySchemaObject>;
+		responses?: Record<string, OpenAPIResponse>;
+	};
+	tags?: {
+		name: string;
+	}[];
+}
+/**
+* Generates a full OpenAPI 3.1 specification from entity definitions.
+*/
+declare function generateOpenAPISpec(entities: EntityDefinition[], options: OpenAPISpecOptions): OpenAPISpec;
 import { EntityRouteEntry } from "@vertz/core";
 interface EntityRouteOptions {
 	apiPrefix?: string;
@@ -2083,4 +2200,4 @@ declare function service<
 	TInject extends Record<string, EntityDefinition> = {},
 	TActions extends Record<string, ServiceActionDef<any, any, any>> = Record<string, ServiceActionDef<any, any, any>>
 >(name: string, config: ServiceConfig<TActions, TInject>): ServiceDefinition;
-export { vertz, verifyPassword, validatePassword, validateOverrides, validateAuthModels, stripReadOnlyFields, stripHiddenFields, service, rules, resolveTenantChain, makeImmutable, isContentDescriptor, initializeAuthTables, hashPassword, google, github, getIncompatibleAddOns, generateEntityRoutes, entityErrorHandler, entity, enforceAccess, encodeAccessSet, discord, defineAccess, defaultAccess, deepFreeze, decodeAccessSet, createWebhookHandler, createStripeBillingAdapter, createServer, createPlanManager, createMiddleware, createImmutableProxy, createEnv, createEntityContext, createCrudHandlers, createBillingEventEmitter, createAuth, createAccessEventBroadcaster, createAccessContext, createAccess, content, computePlanHash, computeOverage, computeEntityAccess, computeAccessSet, checkFva, checkAddOnCompatibility, calculateBillingPeriod, authModels, WebhookHandlerConfig, WalletStore, WalletEntry, VertzException, ValidationException, UserTableEntry, UserStore, UnauthorizedException, TenantOverrides, TenantChainHop, TenantChain, SubscriptionStore, Subscription, StripeProduct, StripePrice, StripeClient, StripeBillingAdapterConfig, StoredSession, StoredPasswordReset, StoredEmailVerification, SignUpInput, SignInInput, SessionStrategy, SessionStore, SessionPayload, SessionInfo, SessionConfig, Session, ServiceUnavailableException, ServiceRequestInfo, ServiceDefinition, ServiceContext, ServiceConfig, ServiceActionDef, ServerInstance, ServerHandle, ServerConfig, ServerAdapter, RuleContext, RoleAssignmentTableEntry, RoleAssignmentStore, RoleAssignment, ResourceRef, Resource, RequestInfo, RelationExposeConfig, RawRequest, RateLimitStore, RateLimitResult, RateLimitConfig, PriceInterval, PlanVersionStore, PlanVersionInfo, PlanSnapshot, PlanPrice, PlanHashInput, PlanDef, Period, PasswordResetStore, PasswordResetConfig, PasswordRequirements, ParentRef, OverrideStore, OverageInput, OverageConfig, OnUserCreatedPayload, OAuthUserInfo, OAuthTokens, OAuthProviderConfig, OAuthProvider, OAuthAccountStore, NotFoundException, NamedMiddlewareDef, MiddlewareDef, MfaSetupData, MfaConfig, MfaChallengeData, MFAStore, ListenOptions, ListResult, ListOptions2 as ListOptions, LimitOverrideDef, LimitOverride, LimitDef, InternalServerErrorException, InferSchema, Infer2 as Infer, InMemoryWalletStore, InMemoryUserStore, InMemorySubscriptionStore, InMemorySessionStore, InMemoryRoleAssignmentStore, InMemoryRateLimitStore, InMemoryPlanVersionStore, InMemoryPasswordResetStore, InMemoryOverrideStore, InMemoryOAuthAccountStore, InMemoryMFAStore, InMemoryGrandfatheringStore, InMemoryFlagStore, InMemoryEmailVerificationStore, InMemoryClosureStore, HttpStatusCode, HttpMethod, HandlerCtx, GrandfatheringStore, GrandfatheringState, ForbiddenException, FlagStore, ExposeConfig, EnvConfig, EntityRouteOptions, EntityRelationsConfig, EntityRegistry, EntityOperations, EntityErrorResult, EntityDefinition, EntityDef, EntityDbAdapter2 as EntityDbAdapter, EntityContext, EntityConfig, EntityActionDef, EntitlementValue, EntitlementRegistry, EntitlementDefinition, EntitlementDef, Entitlement, EncodedAccessSet, EmailVerificationStore, EmailVerificationConfig, EmailPasswordConfig, Deps, DenialReason, DenialMeta, DefineAccessInput, DeepReadonly, DbUserStore, DbSubscriptionStore, DbSessionStore, DbRoleAssignmentStore, DbOAuthAccountStore, DbFlagStore, DbDialectName, DbClosureStore, Ctx, CrudResult, CrudHandlers, CorsConfig, CookieConfig, ContentDescriptor, ConsumeResult, ConflictException, ComputeAccessSetConfig, ClosureStore, ClosureRow, ClosureEntry, BillingPeriod, BillingEventType, BillingEventHandler, BillingEventEmitter, BillingEvent, BillingAdapter, BaseContext, BadRequestException, AuthorizationError, AuthUser, AuthTokens, AuthInstance, AuthEntityProxy, AuthDbClient, AuthContext, AuthConfig, AuthCallbackContext, AuthApi, AppConfig2 as AppConfig, AppBuilder2 as AppBuilder, AddOnRequires, AclClaim, AccumulateProvides, AccessWsData, AccessSet, AccessRule2 as AccessRule, AccessInstance, AccessEventBroadcasterConfig, AccessEventBroadcaster, AccessEvent, AccessDefinition, AccessContextConfig, AccessContext, AccessConfig, AccessCheckResult, AccessCheckData, AUTH_TABLE_NAMES };
+export { vertz, verifyPassword, validatePassword, validateOverrides, validateAuthModels, stripReadOnlyFields, stripHiddenFields, service, rules, resolveTenantChain, makeImmutable, isContentDescriptor, initializeAuthTables, hashPassword, google, github, getIncompatibleAddOns, generateOpenAPISpec, generateEntityRoutes, entityUpdateInputSchema, entityResponseSchema, entityErrorHandler, entityCreateInputSchema, entity, enforceAccess, encodeAccessSet, discord, defineAccess, defaultAccess, deepFreeze, decodeAccessSet, createWebhookHandler, createStripeBillingAdapter, createServer, createPlanManager, createMiddleware, createImmutableProxy, createEnv, createEntityContext, createCrudHandlers, createBillingEventEmitter, createAuth, createAccessEventBroadcaster, createAccessContext, createAccess, content, computePlanHash, computeOverage, computeEntityAccess, computeAccessSet, columnToJsonSchema, checkFva, checkAddOnCompatibility, calculateBillingPeriod, authModels, WebhookHandlerConfig, WalletStore, WalletEntry, VertzException, ValidationException, UserTableEntry, UserStore, UnauthorizedException, TenantOverrides, TenantChainHop, TenantChain, SubscriptionStore, Subscription, StripeProduct, StripePrice, StripeClient, StripeBillingAdapterConfig, StoredSession, StoredPasswordReset, StoredEmailVerification, SignUpInput, SignInInput, SessionStrategy, SessionStore, SessionPayload, SessionInfo, SessionConfig, Session, ServiceUnavailableException, ServiceRequestInfo, ServiceDefinition, ServiceContext, ServiceConfig, ServiceActionDef, ServerInstance, ServerHandle, ServerConfig, ServerAdapter, RuleContext, RoleAssignmentTableEntry, RoleAssignmentStore, RoleAssignment, ResourceRef, Resource, RequestInfo, RelationExposeConfig, RawRequest, RateLimitStore, RateLimitResult, RateLimitConfig, PriceInterval, PlanVersionStore, PlanVersionInfo, PlanSnapshot, PlanPrice, PlanHashInput, PlanDef, Period, PasswordResetStore, PasswordResetConfig, PasswordRequirements, ParentRef, OverrideStore, OverageInput, OverageConfig, OpenAPISpecOptions, OnUserCreatedPayload, OAuthUserInfo, OAuthTokens, OAuthProviderConfig, OAuthProvider, OAuthAccountStore, NotFoundException, NamedMiddlewareDef, MiddlewareDef, MfaSetupData, MfaConfig, MfaChallengeData, MFAStore, ListenOptions, ListResult, ListOptions2 as ListOptions, LimitOverrideDef, LimitOverride, LimitDef, JSONSchemaObject, InternalServerErrorException, InferSchema, Infer2 as Infer, InMemoryWalletStore, InMemoryUserStore, InMemorySubscriptionStore, InMemorySessionStore, InMemoryRoleAssignmentStore, InMemoryRateLimitStore, InMemoryPlanVersionStore, InMemoryPasswordResetStore, InMemoryOverrideStore, InMemoryOAuthAccountStore, InMemoryMFAStore, InMemoryGrandfatheringStore, InMemoryFlagStore, InMemoryEmailVerificationStore, InMemoryClosureStore, HttpStatusCode, HttpMethod, HandlerCtx, GrandfatheringStore, GrandfatheringState, ForbiddenException, FlagStore, ExposeConfig, EnvConfig, EntitySchemaObject, EntityRouteOptions, EntityRelationsConfig, EntityRegistry, EntityOperations, EntityErrorResult, EntityDefinition, EntityDef, EntityDbAdapter2 as EntityDbAdapter, EntityContext, EntityConfig, EntityActionDef, EntitlementValue, EntitlementRegistry, EntitlementDefinition, EntitlementDef, Entitlement, EncodedAccessSet, EmailVerificationStore, EmailVerificationConfig, EmailPasswordConfig, Deps, DenialReason, DenialMeta, DefineAccessInput, DeepReadonly, DbUserStore, DbSubscriptionStore, DbSessionStore, DbRoleAssignmentStore, DbOAuthAccountStore, DbFlagStore, DbDialectName, DbClosureStore, Ctx, CrudResult, CrudHandlers, CorsConfig, CookieConfig, ContentDescriptor, ConsumeResult, ConflictException, ComputeAccessSetConfig, ClosureStore, ClosureRow, ClosureEntry, BillingPeriod, BillingEventType, BillingEventHandler, BillingEventEmitter, BillingEvent, BillingAdapter, BaseContext, BadRequestException, AuthorizationError, AuthUser, AuthTokens, AuthInstance, AuthEntityProxy, AuthDbClient, AuthContext, AuthConfig, AuthCallbackContext, AuthApi, AppConfig2 as AppConfig, AppBuilder2 as AppBuilder, AddOnRequires, AclClaim, AccumulateProvides, AccessWsData, AccessSet, AccessRule2 as AccessRule, AccessInstance, AccessEventBroadcasterConfig, AccessEventBroadcaster, AccessEvent, AccessDefinition, AccessContextConfig, AccessContext, AccessConfig, AccessCheckResult, AccessCheckData, AUTH_TABLE_NAMES };

package/dist/index.js

@@ -7660,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-]*$/;
@@ -7697,8 +8240,12 @@ export {
   google,
   github,
   getIncompatibleAddOns,
+  generateOpenAPISpec,
   generateEntityRoutes,
+  entityUpdateInputSchema,
+  entityResponseSchema,
   entityErrorHandler,
+  entityCreateInputSchema,
   entity,
   enforceAccess,
   encodeAccessSet,
@@ -7726,6 +8273,7 @@ export {
   computeOverage,
   computeEntityAccess,
   computeAccessSet,
+  columnToJsonSchema,
   checkFva,
   checkAddOnCompatibility,
   calculateBillingPeriod,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/server",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "type": "module",
   "license": "MIT",
   "description": "Vertz server runtime — modules, routing, and auth",
@@ -31,10 +31,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@vertz/core": "^0.2.17",
-    "@vertz/db": "^0.2.17",
-    "@vertz/errors": "^0.2.17",
-    "@vertz/schema": "^0.2.17",
+    "@vertz/core": "^0.2.18",
+    "@vertz/db": "^0.2.18",
+    "@vertz/errors": "^0.2.18",
+    "@vertz/schema": "^0.2.18",
     "bcryptjs": "^3.0.3",
     "jose": "^6.0.11"
   },