@zenstackhq/server 3.5.0-beta.2 → 3.5.0-beta.4

package/dist/api.cjs

@@ -37,7 +37,7 @@ __export(api_exports, {
 module.exports = __toCommonJS(api_exports);
 
 // src/api/rest/index.ts
-var import_common_helpers = require("@zenstackhq/common-helpers");
+var import_common_helpers3 = require("@zenstackhq/common-helpers");
 var import_orm2 = require("@zenstackhq/orm");
 var import_decimal2 = require("decimal.js");
 var import_superjson3 = __toESM(require("superjson"), 1);
@@ -127,6 +127,26 @@ var loggerSchema = import_zod.default.union([
   ]).array(),
   import_zod.default.function()
 ]);
+var fieldSlicingSchema = import_zod.default.looseObject({
+  includedFilterKinds: import_zod.default.string().array().optional(),
+  excludedFilterKinds: import_zod.default.string().array().optional()
+});
+var modelSlicingSchema = import_zod.default.looseObject({
+  includedOperations: import_zod.default.array(import_zod.default.string()).optional(),
+  excludedOperations: import_zod.default.array(import_zod.default.string()).optional(),
+  fields: import_zod.default.record(import_zod.default.string(), fieldSlicingSchema).optional()
+});
+var slicingSchema = import_zod.default.looseObject({
+  includedModels: import_zod.default.array(import_zod.default.string()).optional(),
+  excludedModels: import_zod.default.array(import_zod.default.string()).optional(),
+  models: import_zod.default.record(import_zod.default.string(), modelSlicingSchema).optional(),
+  includedProcedures: import_zod.default.array(import_zod.default.string()).optional(),
+  excludedProcedures: import_zod.default.array(import_zod.default.string()).optional()
+});
+var queryOptionsSchema = import_zod.default.looseObject({
+  omit: import_zod.default.record(import_zod.default.string(), import_zod.default.record(import_zod.default.string(), import_zod.default.boolean())).optional(),
+  slicing: slicingSchema.optional()
+});
 
 // src/api/common/utils.ts
 var import_superjson = __toESM(require("superjson"), 1);
@@ -229,6 +249,1401 @@ function getZodErrorMessage(error) {
 }
 __name(getZodErrorMessage, "getZodErrorMessage");
 
+// src/api/rest/openapi.ts
+var import_common_helpers2 = require("@zenstackhq/common-helpers");
+
+// src/api/common/spec-utils.ts
+var import_common_helpers = require("@zenstackhq/common-helpers");
+var import_schema = require("@zenstackhq/orm/schema");
+function isModelIncluded(modelName, queryOptions) {
+  const slicing = queryOptions?.slicing;
+  if (!slicing) return true;
+  const excluded = slicing.excludedModels;
+  if (excluded?.includes(modelName)) return false;
+  const included = slicing.includedModels;
+  if (included && !included.includes(modelName)) return false;
+  return true;
+}
+__name(isModelIncluded, "isModelIncluded");
+function isOperationIncluded(modelName, op, queryOptions) {
+  const slicing = queryOptions?.slicing;
+  if (!slicing?.models) return true;
+  const modelKey = (0, import_common_helpers.lowerCaseFirst)(modelName);
+  const modelSlicing = slicing.models[modelKey] ?? slicing.models.$all;
+  if (!modelSlicing) return true;
+  const excluded = modelSlicing.excludedOperations;
+  if (excluded?.includes(op)) return false;
+  const included = modelSlicing.includedOperations;
+  if (included && !included.includes(op)) return false;
+  return true;
+}
+__name(isOperationIncluded, "isOperationIncluded");
+function isProcedureIncluded(procName, queryOptions) {
+  const slicing = queryOptions?.slicing;
+  if (!slicing) return true;
+  const excluded = slicing.excludedProcedures;
+  if (excluded?.includes(procName)) return false;
+  const included = slicing.includedProcedures;
+  if (included && !included.includes(procName)) return false;
+  return true;
+}
+__name(isProcedureIncluded, "isProcedureIncluded");
+function isFieldOmitted(modelName, fieldName, queryOptions) {
+  const omit = queryOptions?.omit;
+  return omit?.[modelName]?.[fieldName] === true;
+}
+__name(isFieldOmitted, "isFieldOmitted");
+function getIncludedModels(schema, queryOptions) {
+  return Object.keys(schema.models).filter((name) => isModelIncluded(name, queryOptions));
+}
+__name(getIncludedModels, "getIncludedModels");
+function isFilterKindIncluded(modelName, fieldName, filterKind, queryOptions) {
+  const slicing = queryOptions?.slicing;
+  if (!slicing?.models) return true;
+  const modelKey = (0, import_common_helpers.lowerCaseFirst)(modelName);
+  const modelSlicing = slicing.models[modelKey] ?? slicing.models.$all;
+  if (!modelSlicing?.fields) return true;
+  const fieldSlicing = modelSlicing.fields[fieldName] ?? modelSlicing.fields.$all;
+  if (!fieldSlicing) return true;
+  const excluded = fieldSlicing.excludedFilterKinds;
+  if (excluded?.includes(filterKind)) return false;
+  const included = fieldSlicing.includedFilterKinds;
+  if (included && !included.includes(filterKind)) return false;
+  return true;
+}
+__name(isFilterKindIncluded, "isFilterKindIncluded");
+function getMetaDescription(attributes) {
+  if (!attributes) return void 0;
+  for (const attr of attributes) {
+    if (attr.name !== "@meta" && attr.name !== "@@meta") continue;
+    const nameArg = attr.args?.find((a) => a.name === "name");
+    if (!nameArg || import_schema.ExpressionUtils.getLiteralValue(nameArg.value) !== "description") continue;
+    const valueArg = attr.args?.find((a) => a.name === "value");
+    if (valueArg) {
+      return import_schema.ExpressionUtils.getLiteralValue(valueArg.value);
+    }
+  }
+  return void 0;
+}
+__name(getMetaDescription, "getMetaDescription");
+
+// src/api/rest/openapi.ts
+function errorResponse(description) {
+  return {
+    description,
+    content: {
+      "application/vnd.api+json": {
+        schema: {
+          $ref: "#/components/schemas/_errorResponse"
+        }
+      }
+    }
+  };
+}
+__name(errorResponse, "errorResponse");
+var ERROR_400 = errorResponse("Error occurred while processing the request");
+var ERROR_403 = errorResponse("Forbidden: insufficient permissions to perform this operation");
+var ERROR_404 = errorResponse("Resource not found");
+var ERROR_422 = errorResponse("Operation is unprocessable due to validation errors");
+var SCALAR_STRING_OPS = [
+  "$contains",
+  "$icontains",
+  "$search",
+  "$startsWith",
+  "$endsWith"
+];
+var SCALAR_COMPARABLE_OPS = [
+  "$lt",
+  "$lte",
+  "$gt",
+  "$gte"
+];
+var SCALAR_ARRAY_OPS = [
+  "$has",
+  "$hasEvery",
+  "$hasSome",
+  "$isEmpty"
+];
+var RestApiSpecGenerator = class {
+  static {
+    __name(this, "RestApiSpecGenerator");
+  }
+  handlerOptions;
+  specOptions;
+  constructor(handlerOptions) {
+    this.handlerOptions = handlerOptions;
+  }
+  get schema() {
+    return this.handlerOptions.schema;
+  }
+  get modelNameMapping() {
+    const mapping = {};
+    if (this.handlerOptions.modelNameMapping) {
+      for (const [k, v] of Object.entries(this.handlerOptions.modelNameMapping)) {
+        mapping[(0, import_common_helpers2.lowerCaseFirst)(k)] = v;
+      }
+    }
+    return mapping;
+  }
+  get queryOptions() {
+    return this.handlerOptions?.queryOptions;
+  }
+  generateSpec(options) {
+    this.specOptions = options;
+    return {
+      openapi: "3.1.0",
+      info: {
+        title: options?.title ?? "ZenStack Generated API",
+        version: options?.version ?? "1.0.0",
+        ...options?.description && {
+          description: options.description
+        },
+        ...options?.summary && {
+          summary: options.summary
+        }
+      },
+      tags: this.generateTags(),
+      paths: this.generatePaths(),
+      components: {
+        schemas: this.generateSchemas(),
+        parameters: this.generateSharedParams()
+      }
+    };
+  }
+  generateTags() {
+    return getIncludedModels(this.schema, this.queryOptions).map((modelName) => ({
+      name: (0, import_common_helpers2.lowerCaseFirst)(modelName),
+      description: `${modelName} operations`
+    }));
+  }
+  getModelPath(modelName) {
+    const lower = (0, import_common_helpers2.lowerCaseFirst)(modelName);
+    return this.modelNameMapping[lower] ?? lower;
+  }
+  generatePaths() {
+    const paths = {};
+    for (const modelName of getIncludedModels(this.schema, this.queryOptions)) {
+      const modelDef = this.schema.models[modelName];
+      const idFields = this.getIdFields(modelDef);
+      if (idFields.length === 0) continue;
+      const modelPath = this.getModelPath(modelName);
+      const tag = (0, import_common_helpers2.lowerCaseFirst)(modelName);
+      const collectionPath = this.buildCollectionPath(modelName, modelDef, tag);
+      if (Object.keys(collectionPath).length > 0) {
+        paths[`/${modelPath}`] = collectionPath;
+      }
+      const singlePath = this.buildSinglePath(modelDef, tag);
+      if (Object.keys(singlePath).length > 0) {
+        paths[`/${modelPath}/{id}`] = singlePath;
+      }
+      for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
+        if (!fieldDef.relation) continue;
+        if (!isModelIncluded(fieldDef.type, this.queryOptions)) continue;
+        const relModelDef = this.schema.models[fieldDef.type];
+        if (!relModelDef) continue;
+        const relIdFields = this.getIdFields(relModelDef);
+        if (relIdFields.length === 0) continue;
+        paths[`/${modelPath}/{id}/${fieldName}`] = this.buildFetchRelatedPath(modelName, fieldName, fieldDef, tag);
+        paths[`/${modelPath}/{id}/relationships/${fieldName}`] = this.buildRelationshipPath(modelDef, fieldName, fieldDef, tag);
+      }
+    }
+    if (this.schema.procedures) {
+      for (const [procName, procDef] of Object.entries(this.schema.procedures)) {
+        if (!isProcedureIncluded(procName, this.queryOptions)) continue;
+        const isMutation = !!procDef.mutation;
+        if (isMutation) {
+          paths[`/${PROCEDURE_ROUTE_PREFIXES}/${procName}`] = {
+            post: this.buildProcedureOperation(procName, "post")
+          };
+        } else {
+          paths[`/${PROCEDURE_ROUTE_PREFIXES}/${procName}`] = {
+            get: this.buildProcedureOperation(procName, "get")
+          };
+        }
+      }
+    }
+    return paths;
+  }
+  buildCollectionPath(modelName, modelDef, tag) {
+    const filterParams = this.buildFilterParams(modelName, modelDef);
+    const listOp = {
+      tags: [
+        tag
+      ],
+      summary: `List ${modelName} resources`,
+      operationId: `list${modelName}`,
+      parameters: [
+        {
+          $ref: "#/components/parameters/include"
+        },
+        {
+          $ref: "#/components/parameters/sort"
+        },
+        {
+          $ref: "#/components/parameters/pageOffset"
+        },
+        {
+          $ref: "#/components/parameters/pageLimit"
+        },
+        ...filterParams
+      ],
+      responses: {
+        "200": {
+          description: `List of ${modelName} resources`,
+          content: {
+            "application/vnd.api+json": {
+              schema: {
+                $ref: `#/components/schemas/${modelName}ListResponse`
+              }
+            }
+          }
+        },
+        "400": ERROR_400
+      }
+    };
+    const createOp = {
+      tags: [
+        tag
+      ],
+      summary: `Create a ${modelName} resource`,
+      operationId: `create${modelName}`,
+      requestBody: {
+        required: true,
+        content: {
+          "application/vnd.api+json": {
+            schema: {
+              $ref: `#/components/schemas/${modelName}CreateRequest`
+            }
+          }
+        }
+      },
+      responses: {
+        "201": {
+          description: `Created ${modelName} resource`,
+          content: {
+            "application/vnd.api+json": {
+              schema: {
+                $ref: `#/components/schemas/${modelName}Response`
+              }
+            }
+          }
+        },
+        "400": ERROR_400,
+        ...this.mayDenyAccess(modelDef, "create") && {
+          "403": ERROR_403
+        },
+        "422": ERROR_422
+      }
+    };
+    const result = {};
+    if (isOperationIncluded(modelName, "findMany", this.queryOptions)) {
+      result["get"] = listOp;
+    }
+    if (isOperationIncluded(modelName, "create", this.queryOptions)) {
+      result["post"] = createOp;
+    }
+    return result;
+  }
+  buildSinglePath(modelDef, tag) {
+    const modelName = modelDef.name;
+    const idParam = {
+      $ref: "#/components/parameters/id"
+    };
+    const result = {};
+    if (isOperationIncluded(modelName, "findUnique", this.queryOptions)) {
+      result["get"] = {
+        tags: [
+          tag
+        ],
+        summary: `Get a ${modelName} resource by ID`,
+        operationId: `get${modelName}`,
+        parameters: [
+          idParam,
+          {
+            $ref: "#/components/parameters/include"
+          }
+        ],
+        responses: {
+          "200": {
+            description: `${modelName} resource`,
+            content: {
+              "application/vnd.api+json": {
+                schema: {
+                  $ref: `#/components/schemas/${modelName}Response`
+                }
+              }
+            }
+          },
+          "404": ERROR_404
+        }
+      };
+    }
+    if (isOperationIncluded(modelName, "update", this.queryOptions)) {
+      result["patch"] = {
+        tags: [
+          tag
+        ],
+        summary: `Update a ${modelName} resource`,
+        operationId: `update${modelName}`,
+        parameters: [
+          idParam
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/vnd.api+json": {
+              schema: {
+                $ref: `#/components/schemas/${modelName}UpdateRequest`
+              }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: `Updated ${modelName} resource`,
+            content: {
+              "application/vnd.api+json": {
+                schema: {
+                  $ref: `#/components/schemas/${modelName}Response`
+                }
+              }
+            }
+          },
+          "400": ERROR_400,
+          ...this.mayDenyAccess(modelDef, "update") && {
+            "403": ERROR_403
+          },
+          "404": ERROR_404,
+          "422": ERROR_422
+        }
+      };
+    }
+    if (isOperationIncluded(modelName, "delete", this.queryOptions)) {
+      result["delete"] = {
+        tags: [
+          tag
+        ],
+        summary: `Delete a ${modelName} resource`,
+        operationId: `delete${modelName}`,
+        parameters: [
+          idParam
+        ],
+        responses: {
+          "200": {
+            description: "Deleted successfully"
+          },
+          ...this.mayDenyAccess(modelDef, "delete") && {
+            "403": ERROR_403
+          },
+          "404": ERROR_404
+        }
+      };
+    }
+    return result;
+  }
+  buildFetchRelatedPath(modelName, fieldName, fieldDef, tag) {
+    const isCollection = !!fieldDef.array;
+    const params = [
+      {
+        $ref: "#/components/parameters/id"
+      },
+      {
+        $ref: "#/components/parameters/include"
+      }
+    ];
+    if (isCollection && this.schema.models[fieldDef.type]) {
+      const relModelDef = this.schema.models[fieldDef.type];
+      params.push({
+        $ref: "#/components/parameters/sort"
+      }, {
+        $ref: "#/components/parameters/pageOffset"
+      }, {
+        $ref: "#/components/parameters/pageLimit"
+      }, ...this.buildFilterParams(fieldDef.type, relModelDef));
+    }
+    return {
+      get: {
+        tags: [
+          tag
+        ],
+        summary: `Fetch related ${fieldDef.type} for ${modelName}`,
+        operationId: `get${modelName}_${fieldName}`,
+        parameters: params,
+        responses: {
+          "200": {
+            description: `Related ${fieldDef.type} resource(s)`,
+            content: {
+              "application/vnd.api+json": {
+                schema: isCollection ? {
+                  $ref: `#/components/schemas/${fieldDef.type}ListResponse`
+                } : {
+                  $ref: `#/components/schemas/${fieldDef.type}Response`
+                }
+              }
+            }
+          },
+          "404": ERROR_404
+        }
+      }
+    };
+  }
+  buildRelationshipPath(modelDef, fieldName, fieldDef, tag) {
+    const modelName = modelDef.name;
+    const isCollection = !!fieldDef.array;
+    const idParam = {
+      $ref: "#/components/parameters/id"
+    };
+    const relSchemaRef = isCollection ? {
+      $ref: "#/components/schemas/_toManyRelationshipWithLinks"
+    } : {
+      $ref: "#/components/schemas/_toOneRelationshipWithLinks"
+    };
+    const relRequestRef = isCollection ? {
+      $ref: "#/components/schemas/_toManyRelationshipRequest"
+    } : {
+      $ref: "#/components/schemas/_toOneRelationshipRequest"
+    };
+    const mayDeny = this.mayDenyAccess(modelDef, "update");
+    const pathItem = {
+      get: {
+        tags: [
+          tag
+        ],
+        summary: `Fetch ${fieldName} relationship`,
+        operationId: `get${modelName}_relationships_${fieldName}`,
+        parameters: [
+          idParam
+        ],
+        responses: {
+          "200": {
+            description: `${fieldName} relationship`,
+            content: {
+              "application/vnd.api+json": {
+                schema: relSchemaRef
+              }
+            }
+          },
+          "404": ERROR_404
+        }
+      },
+      put: {
+        tags: [
+          tag
+        ],
+        summary: `Replace ${fieldName} relationship`,
+        operationId: `put${modelName}_relationships_${fieldName}`,
+        parameters: [
+          idParam
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/vnd.api+json": {
+              schema: relRequestRef
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Relationship updated"
+          },
+          "400": ERROR_400,
+          ...mayDeny && {
+            "403": ERROR_403
+          }
+        }
+      },
+      patch: {
+        tags: [
+          tag
+        ],
+        summary: `Update ${fieldName} relationship`,
+        operationId: `patch${modelName}_relationships_${fieldName}`,
+        parameters: [
+          idParam
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/vnd.api+json": {
+              schema: relRequestRef
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Relationship updated"
+          },
+          "400": ERROR_400,
+          ...mayDeny && {
+            "403": ERROR_403
+          }
+        }
+      }
+    };
+    if (isCollection) {
+      pathItem["post"] = {
+        tags: [
+          tag
+        ],
+        summary: `Add to ${fieldName} collection relationship`,
+        operationId: `post${modelName}_relationships_${fieldName}`,
+        parameters: [
+          idParam
+        ],
+        requestBody: {
+          required: true,
+          content: {
+            "application/vnd.api+json": {
+              schema: {
+                $ref: "#/components/schemas/_toManyRelationshipRequest"
+              }
+            }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Added to relationship collection"
+          },
+          "400": ERROR_400,
+          ...mayDeny && {
+            "403": ERROR_403
+          }
+        }
+      };
+    }
+    return pathItem;
+  }
+  buildProcedureOperation(procName, method) {
+    const op = {
+      tags: [
+        "$procs"
+      ],
+      summary: `Execute procedure ${procName}`,
+      operationId: `proc_${procName}`,
+      responses: {
+        "200": {
+          description: `Result of ${procName}`
+        },
+        "400": ERROR_400
+      }
+    };
+    if (method === "get") {
+      op["parameters"] = [
+        {
+          name: "q",
+          in: "query",
+          description: "Procedure arguments as JSON",
+          schema: {
+            type: "string"
+          }
+        }
+      ];
+    } else {
+      op["requestBody"] = {
+        content: {
+          "application/json": {
+            schema: {
+              type: "object"
+            }
+          }
+        }
+      };
+    }
+    return op;
+  }
+  buildFilterParams(modelName, modelDef) {
+    const params = [];
+    const idFieldNames = new Set(modelDef.idFields);
+    if (isFilterKindIncluded(modelName, "id", "Equality", this.queryOptions)) {
+      params.push({
+        name: "filter[id]",
+        in: "query",
+        schema: {
+          type: "string"
+        },
+        description: `Filter by ${modelName} ID`
+      });
+    }
+    for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
+      if (fieldDef.relation) continue;
+      if (idFieldNames.has(fieldName)) continue;
+      const type = fieldDef.type;
+      if (isFilterKindIncluded(modelName, fieldName, "Equality", this.queryOptions)) {
+        params.push({
+          name: `filter[${fieldName}]`,
+          in: "query",
+          schema: {
+            type: "string"
+          },
+          description: `Filter by ${fieldName}`
+        });
+      }
+      if (type === "String" && isFilterKindIncluded(modelName, fieldName, "Like", this.queryOptions)) {
+        for (const op of SCALAR_STRING_OPS) {
+          params.push({
+            name: `filter[${fieldName}][${op}]`,
+            in: "query",
+            schema: {
+              type: "string"
+            }
+          });
+        }
+      } else if ((type === "Int" || type === "Float" || type === "BigInt" || type === "Decimal" || type === "DateTime") && isFilterKindIncluded(modelName, fieldName, "Range", this.queryOptions)) {
+        for (const op of SCALAR_COMPARABLE_OPS) {
+          params.push({
+            name: `filter[${fieldName}][${op}]`,
+            in: "query",
+            schema: {
+              type: "string"
+            }
+          });
+        }
+      }
+      if (fieldDef.array && isFilterKindIncluded(modelName, fieldName, "List", this.queryOptions)) {
+        for (const op of SCALAR_ARRAY_OPS) {
+          params.push({
+            name: `filter[${fieldName}][${op}]`,
+            in: "query",
+            schema: {
+              type: "string"
+            }
+          });
+        }
+      }
+    }
+    return params;
+  }
+  generateSchemas() {
+    const schemas = {};
+    Object.assign(schemas, this.buildSharedSchemas());
+    if (this.schema.enums) {
+      for (const [_enumName, enumDef] of Object.entries(this.schema.enums)) {
+        schemas[_enumName] = this.buildEnumSchema(enumDef);
+      }
+    }
+    if (this.schema.typeDefs) {
+      for (const [typeName, typeDef] of Object.entries(this.schema.typeDefs)) {
+        schemas[typeName] = this.buildTypeDefSchema(typeDef);
+      }
+    }
+    for (const modelName of getIncludedModels(this.schema, this.queryOptions)) {
+      const modelDef = this.schema.models[modelName];
+      const idFields = this.getIdFields(modelDef);
+      if (idFields.length === 0) continue;
+      schemas[modelName] = this.buildModelReadSchema(modelName, modelDef);
+      schemas[`${modelName}CreateRequest`] = this.buildCreateRequestSchema(modelName, modelDef);
+      schemas[`${modelName}UpdateRequest`] = this.buildUpdateRequestSchema(modelDef);
+      schemas[`${modelName}Response`] = this.buildModelResponseSchema(modelName);
+      schemas[`${modelName}ListResponse`] = this.buildModelListResponseSchema(modelName);
+    }
+    return schemas;
+  }
+  buildSharedSchemas() {
+    const nullableString = {
+      oneOf: [
+        {
+          type: "string"
+        },
+        {
+          type: "null"
+        }
+      ]
+    };
+    return {
+      _jsonapi: {
+        type: "object",
+        properties: {
+          version: {
+            type: "string"
+          },
+          meta: {
+            type: "object"
+          }
+        }
+      },
+      _meta: {
+        type: "object",
+        additionalProperties: true
+      },
+      _links: {
+        type: "object",
+        properties: {
+          self: {
+            type: "string"
+          },
+          related: {
+            type: "string"
+          }
+        }
+      },
+      _pagination: {
+        type: "object",
+        properties: {
+          first: nullableString,
+          last: nullableString,
+          prev: nullableString,
+          next: nullableString
+        }
+      },
+      _errors: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            status: {
+              type: "integer"
+            },
+            code: {
+              type: "string"
+            },
+            title: {
+              type: "string"
+            },
+            detail: {
+              type: "string"
+            }
+          },
+          required: [
+            "status",
+            "title"
+          ]
+        }
+      },
+      _errorResponse: {
+        type: "object",
+        properties: {
+          errors: {
+            $ref: "#/components/schemas/_errors"
+          }
+        },
+        required: [
+          "errors"
+        ]
+      },
+      _resourceIdentifier: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string"
+          },
+          id: {
+            type: "string"
+          }
+        },
+        required: [
+          "type",
+          "id"
+        ]
+      },
+      _resource: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string"
+          },
+          id: {
+            type: "string"
+          },
+          attributes: {
+            type: "object"
+          },
+          relationships: {
+            type: "object"
+          },
+          links: {
+            $ref: "#/components/schemas/_links"
+          },
+          meta: {
+            $ref: "#/components/schemas/_meta"
+          }
+        },
+        required: [
+          "type",
+          "id"
+        ]
+      },
+      _relationLinks: {
+        type: "object",
+        properties: {
+          self: {
+            type: "string"
+          },
+          related: {
+            type: "string"
+          }
+        }
+      },
+      _pagedRelationLinks: {
+        type: "object",
+        allOf: [
+          {
+            $ref: "#/components/schemas/_relationLinks"
+          },
+          {
+            $ref: "#/components/schemas/_pagination"
+          }
+        ]
+      },
+      _toOneRelationship: {
+        type: "object",
+        properties: {
+          data: {
+            oneOf: [
+              {
+                $ref: "#/components/schemas/_resourceIdentifier"
+              },
+              {
+                type: "null"
+              }
+            ]
+          }
+        }
+      },
+      _toManyRelationship: {
+        type: "object",
+        properties: {
+          data: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/_resourceIdentifier"
+            }
+          }
+        }
+      },
+      _toOneRelationshipWithLinks: {
+        type: "object",
+        allOf: [
+          {
+            $ref: "#/components/schemas/_toOneRelationship"
+          },
+          {
+            properties: {
+              links: {
+                $ref: "#/components/schemas/_relationLinks"
+              }
+            }
+          }
+        ]
+      },
+      _toManyRelationshipWithLinks: {
+        type: "object",
+        allOf: [
+          {
+            $ref: "#/components/schemas/_toManyRelationship"
+          },
+          {
+            properties: {
+              links: {
+                $ref: "#/components/schemas/_pagedRelationLinks"
+              }
+            }
+          }
+        ]
+      },
+      _toManyRelationshipRequest: {
+        type: "object",
+        properties: {
+          data: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/_resourceIdentifier"
+            }
+          }
+        },
+        required: [
+          "data"
+        ]
+      },
+      _toOneRelationshipRequest: {
+        type: "object",
+        properties: {
+          data: {
+            oneOf: [
+              {
+                $ref: "#/components/schemas/_resourceIdentifier"
+              },
+              {
+                type: "null"
+              }
+            ]
+          }
+        },
+        required: [
+          "data"
+        ]
+      },
+      _toManyRelationshipResponse: {
+        type: "object",
+        properties: {
+          data: {
+            type: "array",
+            items: {
+              $ref: "#/components/schemas/_resourceIdentifier"
+            }
+          },
+          links: {
+            $ref: "#/components/schemas/_pagedRelationLinks"
+          },
+          meta: {
+            $ref: "#/components/schemas/_meta"
+          }
+        }
+      },
+      _toOneRelationshipResponse: {
+        type: "object",
+        properties: {
+          data: {
+            oneOf: [
+              {
+                $ref: "#/components/schemas/_resourceIdentifier"
+              },
+              {
+                type: "null"
+              }
+            ]
+          },
+          links: {
+            $ref: "#/components/schemas/_relationLinks"
+          },
+          meta: {
+            $ref: "#/components/schemas/_meta"
+          }
+        }
+      }
+    };
+  }
+  buildEnumSchema(enumDef) {
+    return {
+      type: "string",
+      enum: Object.values(enumDef.values)
+    };
+  }
+  buildTypeDefSchema(typeDef) {
+    const properties = {};
+    const required = [];
+    for (const [fieldName, fieldDef] of Object.entries(typeDef.fields)) {
+      properties[fieldName] = this.fieldToSchema(fieldDef);
+      if (!fieldDef.optional && !fieldDef.array) {
+        required.push(fieldName);
+      }
+    }
+    const result = {
+      type: "object",
+      properties
+    };
+    if (required.length > 0) {
+      result.required = required;
+    }
+    return result;
+  }
+  buildModelReadSchema(modelName, modelDef) {
+    const attrProperties = {};
+    const attrRequired = [];
+    const relProperties = {};
+    for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
+      if (fieldDef.omit) continue;
+      if (isFieldOmitted(modelName, fieldName, this.queryOptions)) continue;
+      if (fieldDef.relation && !isModelIncluded(fieldDef.type, this.queryOptions)) continue;
+      if (fieldDef.relation) {
+        const relRef = fieldDef.array ? {
+          $ref: "#/components/schemas/_toManyRelationshipWithLinks"
+        } : {
+          $ref: "#/components/schemas/_toOneRelationshipWithLinks"
+        };
+        relProperties[fieldName] = fieldDef.optional ? {
+          oneOf: [
+            {
+              type: "null"
+            },
+            relRef
+          ]
+        } : relRef;
+      } else {
+        const schema = this.fieldToSchema(fieldDef);
+        const fieldDescription = getMetaDescription(fieldDef.attributes);
+        if (fieldDescription && !("$ref" in schema)) {
+          schema.description = fieldDescription;
+        }
+        attrProperties[fieldName] = schema;
+        if (!fieldDef.optional && !fieldDef.array) {
+          attrRequired.push(fieldName);
+        }
+      }
+    }
+    const properties = {};
+    if (Object.keys(attrProperties).length > 0) {
+      const attrSchema = {
+        type: "object",
+        properties: attrProperties
+      };
+      if (attrRequired.length > 0) attrSchema.required = attrRequired;
+      properties["attributes"] = attrSchema;
+    }
+    if (Object.keys(relProperties).length > 0) {
+      properties["relationships"] = {
+        type: "object",
+        properties: relProperties
+      };
+    }
+    const result = {
+      type: "object",
+      properties
+    };
+    const description = getMetaDescription(modelDef.attributes);
+    if (description) {
+      result.description = description;
+    }
+    return result;
+  }
+  buildCreateRequestSchema(_modelName, modelDef) {
+    const idFieldNames = new Set(modelDef.idFields);
+    const attributes = {};
+    const attrRequired = [];
+    const relationships = {};
+    for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
+      if (fieldDef.updatedAt) continue;
+      if (fieldDef.foreignKeyFor) continue;
+      if (idFieldNames.has(fieldName) && fieldDef.default !== void 0) continue;
+      if (fieldDef.relation && !isModelIncluded(fieldDef.type, this.queryOptions)) continue;
+      if (fieldDef.relation) {
+        relationships[fieldName] = fieldDef.array ? {
+          type: "object",
+          properties: {
+            data: {
+              type: "array",
+              items: {
+                $ref: "#/components/schemas/_resourceIdentifier"
+              }
+            }
+          }
+        } : {
+          type: "object",
+          properties: {
+            data: {
+              $ref: "#/components/schemas/_resourceIdentifier"
+            }
+          }
+        };
+      } else {
+        attributes[fieldName] = this.fieldToSchema(fieldDef);
+        if (!fieldDef.optional && fieldDef.default === void 0 && !fieldDef.array) {
+          attrRequired.push(fieldName);
+        }
+      }
+    }
+    const dataProperties = {
+      type: {
+        type: "string"
+      }
+    };
+    if (Object.keys(attributes).length > 0) {
+      const attrSchema = {
+        type: "object",
+        properties: attributes
+      };
+      if (attrRequired.length > 0) attrSchema.required = attrRequired;
+      dataProperties["attributes"] = attrSchema;
+    }
+    if (Object.keys(relationships).length > 0) {
+      dataProperties["relationships"] = {
+        type: "object",
+        properties: relationships
+      };
+    }
+    return {
+      type: "object",
+      properties: {
+        data: {
+          type: "object",
+          properties: dataProperties,
+          required: [
+            "type"
+          ]
+        }
+      },
+      required: [
+        "data"
+      ]
+    };
+  }
+  buildUpdateRequestSchema(modelDef) {
+    const attributes = {};
+    const relationships = {};
+    for (const [fieldName, fieldDef] of Object.entries(modelDef.fields)) {
+      if (fieldDef.updatedAt) continue;
+      if (fieldDef.foreignKeyFor) continue;
+      if (fieldDef.relation && !isModelIncluded(fieldDef.type, this.queryOptions)) continue;
+      if (fieldDef.relation) {
+        relationships[fieldName] = fieldDef.array ? {
+          type: "object",
+          properties: {
+            data: {
+              type: "array",
+              items: {
+                $ref: "#/components/schemas/_resourceIdentifier"
+              }
+            }
+          }
+        } : {
+          type: "object",
+          properties: {
+            data: {
+              $ref: "#/components/schemas/_resourceIdentifier"
+            }
+          }
+        };
+      } else {
+        attributes[fieldName] = this.fieldToSchema(fieldDef);
+      }
+    }
+    const dataProperties = {
+      type: {
+        type: "string"
+      },
+      id: {
+        type: "string"
+      }
+    };
+    if (Object.keys(attributes).length > 0) {
+      dataProperties["attributes"] = {
+        type: "object",
+        properties: attributes
+      };
+    }
+    if (Object.keys(relationships).length > 0) {
+      dataProperties["relationships"] = {
+        type: "object",
+        properties: relationships
+      };
+    }
+    return {
+      type: "object",
+      properties: {
+        data: {
+          type: "object",
+          properties: dataProperties,
+          required: [
+            "type",
+            "id"
+          ]
+        }
+      },
+      required: [
+        "data"
+      ]
+    };
+  }
+  buildModelResponseSchema(modelName) {
+    return {
+      type: "object",
+      properties: {
+        jsonapi: {
+          $ref: "#/components/schemas/_jsonapi"
+        },
+        data: {
+          allOf: [
+            {
+              $ref: `#/components/schemas/${modelName}`
+            },
+            {
+              $ref: "#/components/schemas/_resource"
+            }
+          ]
+        },
+        meta: {
+          $ref: "#/components/schemas/_meta"
+        }
+      }
+    };
+  }
+  buildModelListResponseSchema(modelName) {
+    return {
+      type: "object",
+      properties: {
+        jsonapi: {
+          $ref: "#/components/schemas/_jsonapi"
+        },
+        data: {
+          type: "array",
+          items: {
+            allOf: [
+              {
+                $ref: `#/components/schemas/${modelName}`
+              },
+              {
+                $ref: "#/components/schemas/_resource"
+              }
+            ]
+          }
+        },
+        links: {
+          allOf: [
+            {
+              $ref: "#/components/schemas/_pagination"
+            },
+            {
+              $ref: "#/components/schemas/_links"
+            }
+          ]
+        },
+        meta: {
+          $ref: "#/components/schemas/_meta"
+        }
+      }
+    };
+  }
+  generateSharedParams() {
+    return {
+      id: {
+        name: "id",
+        in: "path",
+        required: true,
+        schema: {
+          type: "string"
+        },
+        description: "Resource ID"
+      },
+      include: {
+        name: "include",
+        in: "query",
+        schema: {
+          type: "string"
+        },
+        description: "Comma-separated list of relationships to include"
+      },
+      sort: {
+        name: "sort",
+        in: "query",
+        schema: {
+          type: "string"
+        },
+        description: "Comma-separated list of fields to sort by. Prefix with - for descending"
+      },
+      pageOffset: {
+        name: "page[offset]",
+        in: "query",
+        schema: {
+          type: "integer",
+          minimum: 0
+        },
+        description: "Page offset"
+      },
+      pageLimit: {
+        name: "page[limit]",
+        in: "query",
+        schema: {
+          type: "integer",
+          minimum: 1
+        },
+        description: "Page limit"
+      }
+    };
+  }
+  fieldToSchema(fieldDef) {
+    const baseSchema = this.typeToSchema(fieldDef.type);
+    if (fieldDef.array) {
+      return {
+        type: "array",
+        items: baseSchema
+      };
+    }
+    if (fieldDef.optional) {
+      return {
+        oneOf: [
+          baseSchema,
+          {
+            type: "null"
+          }
+        ]
+      };
+    }
+    return baseSchema;
+  }
+  typeToSchema(type) {
+    switch (type) {
+      case "String":
+        return {
+          type: "string"
+        };
+      case "Int":
+      case "BigInt":
+        return {
+          type: "integer"
+        };
+      case "Float":
+        return {
+          type: "number"
+        };
+      case "Decimal":
+        return {
+          oneOf: [
+            {
+              type: "number"
+            },
+            {
+              type: "string"
+            }
+          ]
+        };
+      case "Boolean":
+        return {
+          type: "boolean"
+        };
+      case "DateTime":
+        return {
+          type: "string",
+          format: "date-time"
+        };
+      case "Bytes":
+        return {
+          type: "string",
+          format: "byte"
+        };
+      case "Json":
+      case "Unsupported":
+        return {};
+      default:
+        return {
+          $ref: `#/components/schemas/${type}`
+        };
+    }
+  }
+  getIdFields(modelDef) {
+    return modelDef.idFields.map((name) => modelDef.fields[name]).filter((f) => f !== void 0);
+  }
+  /**
+   * Checks if an operation on a model may be denied by access policies.
+   * Returns true when `respectAccessPolicies` is enabled and the model's
+   * policies for the given operation are NOT a constant allow (i.e., not
+   * simply `@@allow('...', true)` with no `@@deny` rules).
+   */
+  mayDenyAccess(modelDef, operation) {
+    if (!this.specOptions?.respectAccessPolicies) return false;
+    const policyAttrs = (modelDef.attributes ?? []).filter((attr) => attr.name === "@@allow" || attr.name === "@@deny");
+    if (policyAttrs.length === 0) return true;
+    const getArgByName = /* @__PURE__ */ __name((args, name) => args?.find((a) => a.name === name)?.value, "getArgByName");
+    const matchesOperation = /* @__PURE__ */ __name((args) => {
+      const val = getArgByName(args, "operation");
+      if (!val || val.kind !== "literal" || typeof val.value !== "string") return false;
+      const ops = val.value.split(",").map((s) => s.trim());
+      return ops.includes(operation) || ops.includes("all");
+    }, "matchesOperation");
+    const hasEffectiveDeny = policyAttrs.some((attr) => {
+      if (attr.name !== "@@deny" || !matchesOperation(attr.args)) return false;
+      const condition = getArgByName(attr.args, "condition");
+      return !(condition?.kind === "literal" && condition.value === false);
+    });
+    if (hasEffectiveDeny) return true;
+    const relevantAllow = policyAttrs.filter((attr) => attr.name === "@@allow" && matchesOperation(attr.args));
+    const hasConstantAllow = relevantAllow.some((attr) => {
+      const condition = getArgByName(attr.args, "condition");
+      return condition?.kind === "literal" && condition.value === true;
+    });
+    return !hasConstantAllow;
+  }
+};
+
 // src/api/rest/index.ts
 var InvalidValueError = class InvalidValueError2 extends Error {
   static {
@@ -411,7 +1826,7 @@ var RestApiHandler = class {
     const segmentCharset = options.urlSegmentCharset ?? "a-zA-Z0-9-_~ %";
     this.modelNameMapping = options.modelNameMapping ?? {};
     this.modelNameMapping = Object.fromEntries(Object.entries(this.modelNameMapping).map(([k, v]) => [
-      (0, import_common_helpers.lowerCaseFirst)(k),
+      (0, import_common_helpers3.lowerCaseFirst)(k),
       v
     ]));
     this.reverseModelNameMapping = Object.fromEntries(Object.entries(this.modelNameMapping).map(([k, v]) => [
@@ -420,7 +1835,7 @@ var RestApiHandler = class {
     ]));
     this.externalIdMapping = options.externalIdMapping ?? {};
     this.externalIdMapping = Object.fromEntries(Object.entries(this.externalIdMapping).map(([k, v]) => [
-      (0, import_common_helpers.lowerCaseFirst)(k),
+      (0, import_common_helpers3.lowerCaseFirst)(k),
       v
     ]));
     this.urlPatternMap = this.buildUrlPatternMap(segmentCharset);
@@ -439,7 +1854,8 @@ var RestApiHandler = class {
       idDivider: import_zod2.default.string().min(1).optional(),
       urlSegmentCharset: import_zod2.default.string().min(1).optional(),
       modelNameMapping: import_zod2.default.record(import_zod2.default.string(), import_zod2.default.string()).optional(),
-      externalIdMapping: import_zod2.default.record(import_zod2.default.string(), import_zod2.default.string()).optional()
+      externalIdMapping: import_zod2.default.record(import_zod2.default.string(), import_zod2.default.string()).optional(),
+      queryOptions: queryOptionsSchema.optional()
     });
     const parseResult = schema.safeParse(options);
     if (!parseResult.success) {
@@ -597,8 +2013,9 @@ var RestApiHandler = class {
     }
   }
   handleGenericError(err) {
-    return this.makeError("unknownError", err instanceof Error ? `${err.message}
-${err.stack}` : "Unknown error");
+    const resp = this.makeError("unknownError", err instanceof Error ? `${err.message}` : "Unknown error");
+    log(this.options.log, "debug", () => `sending error response: ${(0, import_common_helpers3.safeJSONStringify)(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
+    return resp;
   }
   async processProcedureRequest({ client, method, proc, query, requestBody }) {
     if (!proc) {
@@ -656,13 +2073,13 @@ ${err.stack}` : "Unknown error");
   }
   makeProcBadInputErrorResponse(message) {
     const resp = this.makeError("invalidPayload", message, 400);
-    log(this.log, "debug", () => `sending error response: ${JSON.stringify(resp)}`);
+    log(this.log, "debug", () => `sending error response: ${(0, import_common_helpers3.safeJSONStringify)(resp)}`);
     return resp;
   }
   makeProcGenericErrorResponse(err) {
     const message = err instanceof Error ? err.message : "unknown error";
     const resp = this.makeError("unknownError", message, 500);
-    log(this.log, "debug", () => `sending error response: ${JSON.stringify(resp)}`);
+    log(this.log, "debug", () => `sending error response: ${(0, import_common_helpers3.safeJSONStringify)(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
     return resp;
   }
   async processSingleRead(client, type, resourceId, query) {
@@ -735,7 +2152,7 @@ ${err.stack}` : "Unknown error");
       select = relationSelect;
     }
     if (!select) {
-      const { select: partialFields, error } = this.buildPartialSelect((0, import_common_helpers.lowerCaseFirst)(relationInfo.type), query);
+      const { select: partialFields, error } = this.buildPartialSelect((0, import_common_helpers3.lowerCaseFirst)(relationInfo.type), query);
       if (error) return error;
       select = partialFields ? {
         [relationship]: {
@@ -1030,7 +2447,7 @@ ${err.stack}` : "Unknown error");
         }
         if (relationInfo.isCollection) {
           createPayload.data[key] = {
-            connect: (0, import_common_helpers.enumerate)(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
+            connect: (0, import_common_helpers3.enumerate)(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
           };
         } else {
           if (typeof data.data !== "object") {
@@ -1096,10 +2513,10 @@ ${err.stack}` : "Unknown error");
         }
         if (relationInfo.isCollection) {
           upsertPayload.create[key] = {
-            connect: (0, import_common_helpers.enumerate)(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
+            connect: (0, import_common_helpers3.enumerate)(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
           };
           upsertPayload.update[key] = {
-            set: (0, import_common_helpers.enumerate)(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
+            set: (0, import_common_helpers3.enumerate)(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
           };
         } else {
           if (typeof data.data !== "object") {
@@ -1180,7 +2597,7 @@ ${err.stack}` : "Unknown error");
       const relationVerb = mode === "create" ? "connect" : mode === "delete" ? "disconnect" : "set";
       updateArgs.data = {
         [relationship]: {
-          [relationVerb]: (0, import_common_helpers.enumerate)(parsed.data.data).map((item) => this.makeIdFilter(relationInfo.idFields, item.id))
+          [relationVerb]: (0, import_common_helpers3.enumerate)(parsed.data.data).map((item) => this.makeIdFilter(relationInfo.idFields, item.id))
         }
       };
     }
@@ -1223,7 +2640,7 @@ ${err.stack}` : "Unknown error");
         }
         if (relationInfo.isCollection) {
           updatePayload.data[key] = {
-            set: (0, import_common_helpers.enumerate)(data.data).map((item) => ({
+            set: (0, import_common_helpers3.enumerate)(data.data).map((item) => ({
               [this.makeDefaultIdKey(relationInfo.idFields)]: item.id
             }))
           };
@@ -1279,7 +2696,7 @@ ${err.stack}` : "Unknown error");
   }
   getIdFields(model) {
     const modelDef = this.requireModel(model);
-    const modelLower = (0, import_common_helpers.lowerCaseFirst)(model);
+    const modelLower = (0, import_common_helpers3.lowerCaseFirst)(model);
     if (!(modelLower in this.externalIdMapping)) {
       return Object.values(modelDef.fields).filter((f) => modelDef.idFields.includes(f.name));
     }
@@ -1313,7 +2730,7 @@ ${err.stack}` : "Unknown error");
         log(this.options.log, "warn", `Not including model ${model} in the API because it has no ID field`);
         continue;
       }
-      const modelInfo = this.typeMap[(0, import_common_helpers.lowerCaseFirst)(model)] = {
+      const modelInfo = this.typeMap[(0, import_common_helpers3.lowerCaseFirst)(model)] = {
         name: model,
         idFields,
         relationships: {},
@@ -1338,7 +2755,7 @@ ${err.stack}` : "Unknown error");
     }
   }
   getModelInfo(model) {
-    return this.typeMap[(0, import_common_helpers.lowerCaseFirst)(model)];
+    return this.typeMap[(0, import_common_helpers3.lowerCaseFirst)(model)];
   }
   makeLinkUrl(path) {
     return `${this.options.endpoint}${path}`;
@@ -1347,7 +2764,7 @@ ${err.stack}` : "Unknown error");
     const linkers = {};
     for (const model of Object.keys(this.schema.models)) {
       const ids = this.getIdFields(model);
-      const modelLower = (0, import_common_helpers.lowerCaseFirst)(model);
+      const modelLower = (0, import_common_helpers3.lowerCaseFirst)(model);
       const mappedModel = this.mapModelName(modelLower);
       if (ids.length < 1) {
         continue;
@@ -1376,7 +2793,7 @@ ${err.stack}` : "Unknown error");
       this.serializers.set(modelLower, serializer);
     }
     for (const model of Object.keys(this.schema.models)) {
-      const modelLower = (0, import_common_helpers.lowerCaseFirst)(model);
+      const modelLower = (0, import_common_helpers3.lowerCaseFirst)(model);
       const serializer = this.serializers.get(modelLower);
       if (!serializer) {
         continue;
@@ -1387,7 +2804,7 @@ ${err.stack}` : "Unknown error");
         if (!fieldDef.relation) {
           continue;
         }
-        const fieldSerializer = this.serializers.get((0, import_common_helpers.lowerCaseFirst)(fieldDef.type));
+        const fieldSerializer = this.serializers.get((0, import_common_helpers3.lowerCaseFirst)(fieldDef.type));
         if (!fieldSerializer) {
           continue;
         }
@@ -1421,12 +2838,12 @@ ${err.stack}` : "Unknown error");
     }
   }
   async serializeItems(model, items, options) {
-    model = (0, import_common_helpers.lowerCaseFirst)(model);
+    model = (0, import_common_helpers3.lowerCaseFirst)(model);
     const serializer = this.serializers.get(model);
     if (!serializer) {
       throw new Error(`serializer not found for model ${model}`);
     }
-    const itemsWithId = (0, import_common_helpers.clone)(items);
+    const itemsWithId = (0, import_common_helpers3.clone)(items);
     this.injectCompoundId(model, itemsWithId);
     const serialized = await serializer.serialize(itemsWithId, options);
     const plainResult = this.toPlainObject(serialized);
@@ -1445,7 +2862,7 @@ ${err.stack}` : "Unknown error");
     if (!typeInfo) {
       return;
     }
-    (0, import_common_helpers.enumerate)(items).forEach((item) => {
+    (0, import_common_helpers3.enumerate)(items).forEach((item) => {
       if (!item) {
         return;
       }
@@ -1620,7 +3037,7 @@ ${err.stack}` : "Unknown error");
     const url = new URL(this.makeLinkUrl(path));
     for (const [key, value] of Object.entries(query ?? {})) {
       if (key.startsWith("filter[") || key.startsWith("sort[") || key === "include" || key.startsWith("include[") || key.startsWith("fields[")) {
-        for (const v of (0, import_common_helpers.enumerate)(value)) {
+        for (const v of (0, import_common_helpers3.enumerate)(value)) {
           url.searchParams.append(key, v);
         }
       }
@@ -1692,7 +3109,7 @@ ${err.stack}` : "Unknown error");
       const item = {};
       let curr = item;
       let currType = typeInfo;
-      for (const filterValue of (0, import_common_helpers.enumerate)(value)) {
+      for (const filterValue of (0, import_common_helpers3.enumerate)(value)) {
         for (let i = 0; i < filterKeys.length; i++) {
           let filterKey = filterKeys[i];
           let filterOp;
@@ -1771,7 +3188,7 @@ ${err.stack}` : "Unknown error");
       };
     }
     const result = [];
-    for (const sortSpec of (0, import_common_helpers.enumerate)(query["sort"])) {
+    for (const sortSpec of (0, import_common_helpers3.enumerate)(query["sort"])) {
       const sortFields = sortSpec.split(",").filter((i) => i);
       for (const sortField of sortFields) {
         const dir = sortField.startsWith("-") ? "desc" : "asc";
@@ -1840,7 +3257,7 @@ ${err.stack}` : "Unknown error");
     }
     const result = {};
     const allIncludes = [];
-    for (const includeItem of (0, import_common_helpers.enumerate)(include)) {
+    for (const includeItem of (0, import_common_helpers3.enumerate)(include)) {
       const inclusions = includeItem.split(",").filter((i) => i);
       for (const inclusion of inclusions) {
         allIncludes.push(inclusion);
@@ -1863,7 +3280,7 @@ ${err.stack}` : "Unknown error");
               error: this.makeUnsupportedModelError(relationInfo.type)
             };
           }
-          const { select, error } = this.buildPartialSelect((0, import_common_helpers.lowerCaseFirst)(relationInfo.type), query);
+          const { select, error } = this.buildPartialSelect((0, import_common_helpers3.lowerCaseFirst)(relationInfo.type), query);
           if (error) return {
             select: void 0,
             error
@@ -2041,7 +3458,7 @@ ${err.stack}` : "Unknown error");
     status = status ?? this.errors[code]?.status ?? 500;
     const error = {
       status,
-      code: (0, import_common_helpers.paramCase)(code),
+      code: (0, import_common_helpers3.paramCase)(code),
       title: this.errors[code]?.title
     };
     if (detail) {
@@ -2063,10 +3480,15 @@ ${err.stack}` : "Unknown error");
   makeUnsupportedRelationshipError(model, relationship, status) {
     return this.makeError("unsupportedRelationship", `Relationship ${model}.${relationship} doesn't exist`, status);
   }
+  //#endregion
+  async generateSpec(options) {
+    const generator = new RestApiSpecGenerator(this.options);
+    return generator.generateSpec(options);
+  }
 };
 
 // src/api/rpc/index.ts
-var import_common_helpers2 = require("@zenstackhq/common-helpers");
+var import_common_helpers4 = require("@zenstackhq/common-helpers");
 var import_orm3 = require("@zenstackhq/orm");
 var import_superjson4 = __toESM(require("superjson"), 1);
 var import_ts_pattern3 = require("ts-pattern");
@@ -2087,7 +3509,8 @@ var RPCApiHandler = class {
   validateOptions(options) {
     const schema = import_zod3.default.strictObject({
       schema: import_zod3.default.object(),
-      log: loggerSchema.optional()
+      log: loggerSchema.optional(),
+      queryOptions: queryOptionsSchema.optional()
     });
     const parseResult = schema.safeParse(options);
     if (!parseResult.success) {
@@ -2124,7 +3547,7 @@ var RPCApiHandler = class {
         requestBody
       });
     }
-    model = (0, import_common_helpers2.lowerCaseFirst)(model);
+    model = (0, import_common_helpers4.lowerCaseFirst)(model);
     method = method.toUpperCase();
     let args;
     let resCode = 200;
@@ -2191,7 +3614,7 @@ var RPCApiHandler = class {
       if (!this.isValidModel(client, model)) {
         return this.makeBadInputErrorResponse(`unknown model name: ${model}`);
       }
-      log(this.options.log, "debug", () => `handling "${model}.${op}" request with args: ${(0, import_common_helpers2.safeJSONStringify)(processedArgs)}`);
+      log(this.options.log, "debug", () => `handling "${model}.${op}" request with args: ${(0, import_common_helpers4.safeJSONStringify)(processedArgs)}`);
       const clientResult = await client[model][op](processedArgs);
       let responseBody = {
         data: clientResult
@@ -2211,7 +3634,7 @@ var RPCApiHandler = class {
         status: resCode,
         body: responseBody
       };
-      log(this.options.log, "debug", () => `sending response for "${model}.${op}" request: ${(0, import_common_helpers2.safeJSONStringify)(response)}`);
+      log(this.options.log, "debug", () => `sending response for "${model}.${op}" request: ${(0, import_common_helpers4.safeJSONStringify)(response)}`);
       return response;
     } catch (err) {
       log(this.options.log, "error", `error occurred when handling "${model}.${op}" request`, err);
@@ -2248,7 +3671,7 @@ var RPCApiHandler = class {
       if (!VALID_OPS.has(itemOp)) {
         return this.makeBadInputErrorResponse(`operation at index ${i} has invalid op: ${itemOp}`);
       }
-      if (!this.isValidModel(client, (0, import_common_helpers2.lowerCaseFirst)(itemModel))) {
+      if (!this.isValidModel(client, (0, import_common_helpers4.lowerCaseFirst)(itemModel))) {
         return this.makeBadInputErrorResponse(`operation at index ${i} has unknown model: ${itemModel}`);
       }
       if (itemArgs !== void 0 && itemArgs !== null && (typeof itemArgs !== "object" || Array.isArray(itemArgs))) {
@@ -2259,7 +3682,7 @@ var RPCApiHandler = class {
         return this.makeBadInputErrorResponse(`operation at index ${i}: ${argsError}`);
       }
       processedOps.push({
-        model: (0, import_common_helpers2.lowerCaseFirst)(itemModel),
+        model: (0, import_common_helpers4.lowerCaseFirst)(itemModel),
         op: itemOp,
         args: processedArgs
       });
@@ -2283,7 +3706,7 @@ var RPCApiHandler = class {
         status: 200,
         body: responseBody
       };
-      log(this.options.log, "debug", () => `sending response for "$transaction" request: ${(0, import_common_helpers2.safeJSONStringify)(response)}`);
+      log(this.options.log, "debug", () => `sending response for "$transaction" request: ${(0, import_common_helpers4.safeJSONStringify)(response)}`);
       return response;
     } catch (err) {
       log(this.options.log, "error", `error occurred when handling "$transaction" request`, err);
@@ -2345,7 +3768,7 @@ var RPCApiHandler = class {
         status: 200,
         body: responseBody
       };
-      log(this.options.log, "debug", () => `sending response for "$procs.${proc}" request: ${(0, import_common_helpers2.safeJSONStringify)(response)}`);
+      log(this.options.log, "debug", () => `sending response for "$procs.${proc}" request: ${(0, import_common_helpers4.safeJSONStringify)(response)}`);
       return response;
     } catch (err) {
       log(this.options.log, "error", `error occurred when handling "$procs.${proc}" request`, err);
@@ -2356,7 +3779,7 @@ var RPCApiHandler = class {
     }
   }
   isValidModel(client, model) {
-    return Object.keys(client.$schema.models).some((m) => (0, import_common_helpers2.lowerCaseFirst)(m) === (0, import_common_helpers2.lowerCaseFirst)(model));
+    return Object.keys(client.$schema.models).some((m) => (0, import_common_helpers4.lowerCaseFirst)(m) === (0, import_common_helpers4.lowerCaseFirst)(model));
   }
   makeBadInputErrorResponse(message) {
     const resp = {
@@ -2367,7 +3790,7 @@ var RPCApiHandler = class {
         }
       }
     };
-    log(this.options.log, "debug", () => `sending error response: ${(0, import_common_helpers2.safeJSONStringify)(resp)}`);
+    log(this.options.log, "debug", () => `sending error response: ${(0, import_common_helpers4.safeJSONStringify)(resp)}`);
     return resp;
   }
   makeGenericErrorResponse(err) {
@@ -2379,7 +3802,7 @@ var RPCApiHandler = class {
         }
       }
     };
-    log(this.options.log, "debug", () => `sending error response: ${(0, import_common_helpers2.safeJSONStringify)(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
+    log(this.options.log, "debug", () => `sending error response: ${(0, import_common_helpers4.safeJSONStringify)(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
     return resp;
   }
   makeORMErrorResponse(err) {
@@ -2411,7 +3834,7 @@ var RPCApiHandler = class {
         error
       }
     };
-    log(this.options.log, "debug", () => `sending error response: ${(0, import_common_helpers2.safeJSONStringify)(resp)}`);
+    log(this.options.log, "debug", () => `sending error response: ${(0, import_common_helpers4.safeJSONStringify)(resp)}`);
     return resp;
   }
   async processRequestPayload(args) {