@zenstackhq/server 3.5.0-beta.3 → 3.5.0-beta.5

package/dist/api.js

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/api/rest/index.ts
-import { clone, enumerate, lowerCaseFirst, paramCase } from "@zenstackhq/common-helpers";
+import { clone, enumerate, lowerCaseFirst as lowerCaseFirst3, paramCase, safeJSONStringify } from "@zenstackhq/common-helpers";
 import { ORMError as ORMError2, ORMErrorReason } from "@zenstackhq/orm";
 import { Decimal as Decimal2 } from "decimal.js";
 import SuperJSON3 from "superjson";
@@ -92,6 +92,26 @@ var loggerSchema = z.union([
   ]).array(),
   z.function()
 ]);
+var fieldSlicingSchema = z.looseObject({
+  includedFilterKinds: z.string().array().optional(),
+  excludedFilterKinds: z.string().array().optional()
+});
+var modelSlicingSchema = z.looseObject({
+  includedOperations: z.array(z.string()).optional(),
+  excludedOperations: z.array(z.string()).optional(),
+  fields: z.record(z.string(), fieldSlicingSchema).optional()
+});
+var slicingSchema = z.looseObject({
+  includedModels: z.array(z.string()).optional(),
+  excludedModels: z.array(z.string()).optional(),
+  models: z.record(z.string(), modelSlicingSchema).optional(),
+  includedProcedures: z.array(z.string()).optional(),
+  excludedProcedures: z.array(z.string()).optional()
+});
+var queryOptionsSchema = z.looseObject({
+  omit: z.record(z.string(), z.record(z.string(), z.boolean())).optional(),
+  slicing: slicingSchema.optional()
+});
 
 // src/api/common/utils.ts
 import SuperJSON from "superjson";
@@ -194,6 +214,1401 @@ function getZodErrorMessage(error) {
 }
 __name(getZodErrorMessage, "getZodErrorMessage");
 
+// src/api/rest/openapi.ts
+import { lowerCaseFirst as lowerCaseFirst2 } from "@zenstackhq/common-helpers";
+
+// src/api/common/spec-utils.ts
+import { lowerCaseFirst } from "@zenstackhq/common-helpers";
+import { ExpressionUtils } from "@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 = 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 = 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 || ExpressionUtils.getLiteralValue(nameArg.value) !== "description") continue;
+    const valueArg = attr.args?.find((a) => a.name === "value");
+    if (valueArg) {
+      return 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[lowerCaseFirst2(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: lowerCaseFirst2(modelName),
+      description: `${modelName} operations`
+    }));
+  }
+  getModelPath(modelName) {
+    const lower = lowerCaseFirst2(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 = lowerCaseFirst2(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 {
@@ -369,6 +1784,7 @@ var RestApiHandler = class {
   modelNameMapping;
   reverseModelNameMapping;
   externalIdMapping;
+  nestedRoutes;
   constructor(options) {
     this.options = options;
     this.validateOptions(options);
@@ -376,7 +1792,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]) => [
-      lowerCaseFirst(k),
+      lowerCaseFirst3(k),
       v
     ]));
     this.reverseModelNameMapping = Object.fromEntries(Object.entries(this.modelNameMapping).map(([k, v]) => [
@@ -385,9 +1801,10 @@ var RestApiHandler = class {
     ]));
     this.externalIdMapping = options.externalIdMapping ?? {};
     this.externalIdMapping = Object.fromEntries(Object.entries(this.externalIdMapping).map(([k, v]) => [
-      lowerCaseFirst(k),
+      lowerCaseFirst3(k),
       v
     ]));
+    this.nestedRoutes = options.nestedRoutes ?? false;
     this.urlPatternMap = this.buildUrlPatternMap(segmentCharset);
     this.buildTypeMap();
     this.buildSerializers();
@@ -404,7 +1821,9 @@ var RestApiHandler = class {
       idDivider: z2.string().min(1).optional(),
       urlSegmentCharset: z2.string().min(1).optional(),
       modelNameMapping: z2.record(z2.string(), z2.string()).optional(),
-      externalIdMapping: z2.record(z2.string(), z2.string()).optional()
+      externalIdMapping: z2.record(z2.string(), z2.string()).optional(),
+      queryOptions: queryOptionsSchema.optional(),
+      nestedRoutes: z2.boolean().optional()
     });
     const parseResult = schema.safeParse(options);
     if (!parseResult.success) {
@@ -429,6 +1848,12 @@ var RestApiHandler = class {
         ":type",
         ":id"
       ]), options),
+      ["nestedSingle"]: new UrlPattern(buildPath([
+        ":type",
+        ":id",
+        ":relationship",
+        ":childId"
+      ]), options),
       ["fetchRelationship"]: new UrlPattern(buildPath([
         ":type",
         ":id",
@@ -448,6 +1873,81 @@ var RestApiHandler = class {
   mapModelName(modelName) {
     return this.modelNameMapping[modelName] ?? modelName;
   }
+  /**
+   * Resolves child model type and reverse relation from a parent relation name.
+   * e.g. given parentType='user', parentRelation='posts', returns { childType:'post', reverseRelation:'author' }
+   */
+  resolveNestedRelation(parentType, parentRelation) {
+    const parentInfo = this.getModelInfo(parentType);
+    if (!parentInfo) return void 0;
+    const field = this.schema.models[parentInfo.name]?.fields[parentRelation];
+    if (!field?.relation) return void 0;
+    const reverseRelation = field.relation.opposite;
+    if (!reverseRelation) return void 0;
+    return {
+      childType: lowerCaseFirst3(field.type),
+      reverseRelation,
+      isCollection: !!field.array
+    };
+  }
+  mergeFilters(left, right) {
+    if (!left) {
+      return right;
+    }
+    if (!right) {
+      return left;
+    }
+    return {
+      AND: [
+        left,
+        right
+      ]
+    };
+  }
+  /**
+   * Builds a WHERE filter for the child model that constrains results to those belonging to the given parent.
+   * @param parentType  lowercased parent model name
+   * @param parentId    parent resource ID string
+   * @param parentRelation  relation field name on the parent model (e.g. 'posts')
+   */
+  buildNestedParentFilter(parentType, parentId, parentRelation) {
+    const parentInfo = this.getModelInfo(parentType);
+    if (!parentInfo) {
+      return {
+        filter: void 0,
+        error: this.makeUnsupportedModelError(parentType)
+      };
+    }
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return {
+        filter: void 0,
+        error: this.makeError("invalidPath", `invalid nested route: cannot resolve relation "${parentType}.${parentRelation}"`)
+      };
+    }
+    const { reverseRelation } = resolved;
+    const childInfo = this.getModelInfo(resolved.childType);
+    if (!childInfo) {
+      return {
+        filter: void 0,
+        error: this.makeUnsupportedModelError(resolved.childType)
+      };
+    }
+    const reverseRelInfo = childInfo.relationships[reverseRelation];
+    const relationFilter = reverseRelInfo?.isCollection ? {
+      [reverseRelation]: {
+        some: this.makeIdFilter(parentInfo.idFields, parentId, false)
+      }
+    } : {
+      [reverseRelation]: {
+        is: this.makeIdFilter(parentInfo.idFields, parentId, false)
+      }
+    };
+    return {
+      filter: relationFilter,
+      error: void 0
+    };
+  }
   matchUrlPattern(path, routeType) {
     const pattern = this.urlPatternMap[routeType];
     if (!pattern) {
@@ -495,6 +1995,10 @@ var RestApiHandler = class {
           if (match4) {
             return await this.processReadRelationship(client, match4.type, match4.id, match4.relationship, query);
           }
+          match4 = this.matchUrlPattern(path, "nestedSingle");
+          if (match4 && this.nestedRoutes && this.resolveNestedRelation(match4.type, match4.relationship)?.isCollection) {
+            return await this.processNestedSingleRead(client, match4.type, match4.id, match4.relationship, match4.childId, query);
+          }
           match4 = this.matchUrlPattern(path, "collection");
           if (match4) {
             return await this.processCollectionRead(client, match4.type, query);
@@ -505,6 +2009,10 @@ var RestApiHandler = class {
           if (!requestBody) {
             return this.makeError("invalidPayload");
           }
+          const nestedMatch = this.matchUrlPattern(path, "fetchRelationship");
+          if (nestedMatch && this.nestedRoutes && this.resolveNestedRelation(nestedMatch.type, nestedMatch.relationship)?.isCollection) {
+            return await this.processNestedCreate(client, nestedMatch.type, nestedMatch.id, nestedMatch.relationship, query, requestBody);
+          }
           let match4 = this.matchUrlPattern(path, "collection");
           if (match4) {
             const body = requestBody;
@@ -527,24 +2035,36 @@ var RestApiHandler = class {
           if (!requestBody) {
             return this.makeError("invalidPayload");
           }
-          let match4 = this.matchUrlPattern(path, "single");
+          let match4 = this.matchUrlPattern(path, "relationship");
           if (match4) {
-            return await this.processUpdate(client, match4.type, match4.id, query, requestBody);
+            return await this.processRelationshipCRUD(client, "update", match4.type, match4.id, match4.relationship, query, requestBody);
           }
-          match4 = this.matchUrlPattern(path, "relationship");
+          const nestedToOnePatchMatch = this.matchUrlPattern(path, "fetchRelationship");
+          if (nestedToOnePatchMatch && this.nestedRoutes && this.resolveNestedRelation(nestedToOnePatchMatch.type, nestedToOnePatchMatch.relationship) && !this.resolveNestedRelation(nestedToOnePatchMatch.type, nestedToOnePatchMatch.relationship)?.isCollection) {
+            return await this.processNestedUpdate(client, nestedToOnePatchMatch.type, nestedToOnePatchMatch.id, nestedToOnePatchMatch.relationship, void 0, query, requestBody);
+          }
+          const nestedPatchMatch = this.matchUrlPattern(path, "nestedSingle");
+          if (nestedPatchMatch && this.nestedRoutes && this.resolveNestedRelation(nestedPatchMatch.type, nestedPatchMatch.relationship)?.isCollection) {
+            return await this.processNestedUpdate(client, nestedPatchMatch.type, nestedPatchMatch.id, nestedPatchMatch.relationship, nestedPatchMatch.childId, query, requestBody);
+          }
+          match4 = this.matchUrlPattern(path, "single");
           if (match4) {
-            return await this.processRelationshipCRUD(client, "update", match4.type, match4.id, match4.relationship, query, requestBody);
+            return await this.processUpdate(client, match4.type, match4.id, query, requestBody);
           }
           return this.makeError("invalidPath");
         }
         case "DELETE": {
-          let match4 = this.matchUrlPattern(path, "single");
+          let match4 = this.matchUrlPattern(path, "relationship");
           if (match4) {
-            return await this.processDelete(client, match4.type, match4.id);
+            return await this.processRelationshipCRUD(client, "delete", match4.type, match4.id, match4.relationship, query, requestBody);
           }
-          match4 = this.matchUrlPattern(path, "relationship");
+          const nestedDeleteMatch = this.matchUrlPattern(path, "nestedSingle");
+          if (nestedDeleteMatch && this.nestedRoutes && this.resolveNestedRelation(nestedDeleteMatch.type, nestedDeleteMatch.relationship)?.isCollection) {
+            return await this.processNestedDelete(client, nestedDeleteMatch.type, nestedDeleteMatch.id, nestedDeleteMatch.relationship, nestedDeleteMatch.childId);
+          }
+          match4 = this.matchUrlPattern(path, "single");
           if (match4) {
-            return await this.processRelationshipCRUD(client, "delete", match4.type, match4.id, match4.relationship, query, requestBody);
+            return await this.processDelete(client, match4.type, match4.id);
           }
           return this.makeError("invalidPath");
         }
@@ -562,8 +2082,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: ${safeJSONStringify(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
+    return resp;
   }
   async processProcedureRequest({ client, method, proc, query, requestBody }) {
     if (!proc) {
@@ -621,29 +2142,32 @@ ${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: ${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: ${safeJSONStringify(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
     return resp;
   }
-  async processSingleRead(client, type, resourceId, query) {
-    const typeInfo = this.getModelInfo(type);
-    if (!typeInfo) {
-      return this.makeUnsupportedModelError(type);
-    }
-    const args = {
-      where: this.makeIdFilter(typeInfo.idFields, resourceId)
-    };
+  /**
+   * Builds the ORM `args` object (include, select) shared by single-read operations.
+   * Returns the args to pass to findUnique/findFirst and the resolved `include` list for serialization,
+   * or an error response if query params are invalid.
+   */
+  buildSingleReadArgs(type, query) {
+    const args = {};
     this.includeRelationshipIds(type, args, "include");
     let include;
     if (query?.["include"]) {
       const { select: select2, error: error2, allIncludes } = this.buildRelationSelect(type, query["include"], query);
       if (error2) {
-        return error2;
+        return {
+          args,
+          include,
+          error: error2
+        };
       }
       if (select2) {
         args.include = {
@@ -654,7 +2178,11 @@ ${err.stack}` : "Unknown error");
       include = allIncludes;
     }
     const { select, error } = this.buildPartialSelect(type, query);
-    if (error) return error;
+    if (error) return {
+      args,
+      include,
+      error
+    };
     if (select) {
       args.select = {
         ...select,
@@ -668,6 +2196,19 @@ ${err.stack}` : "Unknown error");
         args.include = void 0;
       }
     }
+    return {
+      args,
+      include
+    };
+  }
+  async processSingleRead(client, type, resourceId, query) {
+    const typeInfo = this.getModelInfo(type);
+    if (!typeInfo) {
+      return this.makeUnsupportedModelError(type);
+    }
+    const { args, include, error } = this.buildSingleReadArgs(type, query);
+    if (error) return error;
+    args.where = this.makeIdFilter(typeInfo.idFields, resourceId);
     const entity = await client[type].findUnique(args);
     if (entity) {
       return {
@@ -700,7 +2241,7 @@ ${err.stack}` : "Unknown error");
       select = relationSelect;
     }
     if (!select) {
-      const { select: partialFields, error } = this.buildPartialSelect(lowerCaseFirst(relationInfo.type), query);
+      const { select: partialFields, error } = this.buildPartialSelect(lowerCaseFirst3(relationInfo.type), query);
       if (error) return error;
       select = partialFields ? {
         [relationship]: {
@@ -852,8 +2393,12 @@ ${err.stack}` : "Unknown error");
     }
     if (limit === Infinity) {
       const entities = await client[type].findMany(args);
+      const mappedType = this.mapModelName(type);
       const body = await this.serializeItems(type, entities, {
-        include
+        include,
+        linkers: {
+          document: new tsjapi.Linker(() => this.makeLinkUrl(`/${mappedType}`))
+        }
       });
       const total = entities.length;
       body.meta = this.addTotalCountToMeta(body.meta, total);
@@ -875,6 +2420,7 @@ ${err.stack}` : "Unknown error");
       const options = {
         include,
         linkers: {
+          document: new tsjapi.Linker(() => this.makeLinkUrl(`/${mappedType}`)),
           paginator: this.makePaginator(url, offset, limit, total)
         }
       };
@@ -886,6 +2432,278 @@ ${err.stack}` : "Unknown error");
       };
     }
   }
+  /**
+   * Builds link URL for a nested resource using parent type, parent ID, relation name, and optional child ID.
+   * Uses the parent model name mapping for the parent segment; the relation name is used as-is.
+   */
+  makeNestedLinkUrl(parentType, parentId, parentRelation, childId) {
+    const mappedParentType = this.mapModelName(parentType);
+    const base = `/${mappedParentType}/${parentId}/${parentRelation}`;
+    return childId ? `${base}/${childId}` : base;
+  }
+  async processNestedSingleRead(client, parentType, parentId, parentRelation, childId, query) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const { filter: nestedFilter, error: nestedError } = this.buildNestedParentFilter(parentType, parentId, parentRelation);
+    if (nestedError) return nestedError;
+    const childType = resolved.childType;
+    const typeInfo = this.getModelInfo(childType);
+    const { args, include, error } = this.buildSingleReadArgs(childType, query);
+    if (error) return error;
+    args.where = this.mergeFilters(this.makeIdFilter(typeInfo.idFields, childId), nestedFilter);
+    const entity = await client[childType].findFirst(args);
+    if (!entity) return this.makeError("notFound");
+    const linkUrl = this.makeLinkUrl(this.makeNestedLinkUrl(parentType, parentId, parentRelation, childId));
+    const nestedLinker = new tsjapi.Linker(() => linkUrl);
+    return {
+      status: 200,
+      body: await this.serializeItems(childType, entity, {
+        include,
+        linkers: {
+          document: nestedLinker,
+          resource: nestedLinker
+        }
+      })
+    };
+  }
+  async processNestedCreate(client, parentType, parentId, parentRelation, _query, requestBody) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const parentInfo = this.getModelInfo(parentType);
+    const childType = resolved.childType;
+    const childInfo = this.getModelInfo(childType);
+    const { attributes, relationships, error } = this.processRequestBody(requestBody);
+    if (error) return error;
+    const createData = {
+      ...attributes
+    };
+    if (relationships) {
+      for (const [key, data] of Object.entries(relationships)) {
+        if (!data?.data) {
+          return this.makeError("invalidRelationData");
+        }
+        if (key === resolved.reverseRelation) {
+          return this.makeError("invalidPayload", `Relation "${key}" is controlled by the parent route and cannot be set in the request payload`);
+        }
+        const relationInfo = childInfo.relationships[key];
+        if (!relationInfo) {
+          return this.makeUnsupportedRelationshipError(childType, key, 400);
+        }
+        if (relationInfo.isCollection) {
+          createData[key] = {
+            connect: enumerate(data.data).map((item) => this.makeIdConnect(relationInfo.idFields, item.id))
+          };
+        } else {
+          if (typeof data.data !== "object") {
+            return this.makeError("invalidRelationData");
+          }
+          createData[key] = {
+            connect: this.makeIdConnect(relationInfo.idFields, data.data.id)
+          };
+        }
+      }
+    }
+    const parentFkFields = Object.values(childInfo.fields).filter((f) => f.foreignKeyFor?.includes(resolved.reverseRelation));
+    if (parentFkFields.some((f) => Object.prototype.hasOwnProperty.call(createData, f.name))) {
+      return this.makeError("invalidPayload", `Relation "${resolved.reverseRelation}" is controlled by the parent route and cannot be set in the request payload`);
+    }
+    await client[parentType].update({
+      where: this.makeIdFilter(parentInfo.idFields, parentId),
+      data: {
+        [parentRelation]: {
+          create: createData
+        }
+      }
+    });
+    const { filter: nestedFilter, error: filterError } = this.buildNestedParentFilter(parentType, parentId, parentRelation);
+    if (filterError) return filterError;
+    const fetchArgs = {
+      where: nestedFilter
+    };
+    this.includeRelationshipIds(childType, fetchArgs, "include");
+    if (childInfo.idFields[0]) {
+      fetchArgs.orderBy = {
+        [childInfo.idFields[0].name]: "desc"
+      };
+    }
+    const entity = await client[childType].findFirst(fetchArgs);
+    if (!entity) return this.makeError("notFound");
+    const collectionPath = this.makeNestedLinkUrl(parentType, parentId, parentRelation);
+    const resourceLinker = new tsjapi.Linker((item) => this.makeLinkUrl(`${collectionPath}/${this.getId(childInfo.name, item)}`));
+    return {
+      status: 201,
+      body: await this.serializeItems(childType, entity, {
+        linkers: {
+          document: resourceLinker,
+          resource: resourceLinker
+        }
+      })
+    };
+  }
+  /**
+   * Builds the ORM `data` payload for a nested update, shared by both to-many (childId present)
+   * and to-one (childId absent) variants.  Returns either `{ updateData }` or `{ error }`.
+   */
+  buildNestedUpdatePayload(childType, typeInfo, rev, requestBody) {
+    const { attributes, relationships, error } = this.processRequestBody(requestBody);
+    if (error) return {
+      error
+    };
+    const updateData = {
+      ...attributes
+    };
+    if (relationships && Object.prototype.hasOwnProperty.call(relationships, rev)) {
+      return {
+        error: this.makeError("invalidPayload", `Relation "${rev}" cannot be changed via a nested route`)
+      };
+    }
+    const fkFields = Object.values(typeInfo.fields).filter((f) => f.foreignKeyFor?.includes(rev));
+    if (fkFields.some((f) => Object.prototype.hasOwnProperty.call(updateData, f.name))) {
+      return {
+        error: this.makeError("invalidPayload", `Relation "${rev}" cannot be changed via a nested route`)
+      };
+    }
+    if (relationships) {
+      for (const [key, data] of Object.entries(relationships)) {
+        if (!data?.data) {
+          return {
+            error: this.makeError("invalidRelationData")
+          };
+        }
+        const relationInfo = typeInfo.relationships[key];
+        if (!relationInfo) {
+          return {
+            error: this.makeUnsupportedRelationshipError(childType, key, 400)
+          };
+        }
+        if (relationInfo.isCollection) {
+          updateData[key] = {
+            set: enumerate(data.data).map((item) => ({
+              [this.makeDefaultIdKey(relationInfo.idFields)]: item.id
+            }))
+          };
+        } else {
+          if (typeof data.data !== "object") {
+            return {
+              error: this.makeError("invalidRelationData")
+            };
+          }
+          updateData[key] = {
+            connect: {
+              [this.makeDefaultIdKey(relationInfo.idFields)]: data.data.id
+            }
+          };
+        }
+      }
+    }
+    return {
+      updateData
+    };
+  }
+  /**
+   * Handles PATCH /:type/:id/:relationship/:childId (to-many) and
+   * PATCH /:type/:id/:relationship (to-one, childId undefined).
+   */
+  async processNestedUpdate(client, parentType, parentId, parentRelation, childId, _query, requestBody) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const parentInfo = this.getModelInfo(parentType);
+    const childType = resolved.childType;
+    const typeInfo = this.getModelInfo(childType);
+    const { updateData, error } = this.buildNestedUpdatePayload(childType, typeInfo, resolved.reverseRelation, requestBody);
+    if (error) return error;
+    if (childId) {
+      await client[parentType].update({
+        where: this.makeIdFilter(parentInfo.idFields, parentId),
+        data: {
+          [parentRelation]: {
+            update: {
+              where: this.makeIdFilter(typeInfo.idFields, childId),
+              data: updateData
+            }
+          }
+        }
+      });
+      const fetchArgs = {
+        where: this.makeIdFilter(typeInfo.idFields, childId)
+      };
+      this.includeRelationshipIds(childType, fetchArgs, "include");
+      const entity = await client[childType].findUnique(fetchArgs);
+      if (!entity) return this.makeError("notFound");
+      const linkUrl = this.makeLinkUrl(this.makeNestedLinkUrl(parentType, parentId, parentRelation, childId));
+      const nestedLinker = new tsjapi.Linker(() => linkUrl);
+      return {
+        status: 200,
+        body: await this.serializeItems(childType, entity, {
+          linkers: {
+            document: nestedLinker,
+            resource: nestedLinker
+          }
+        })
+      };
+    } else {
+      await client[parentType].update({
+        where: this.makeIdFilter(parentInfo.idFields, parentId),
+        data: {
+          [parentRelation]: {
+            update: updateData
+          }
+        }
+      });
+      const childIncludeArgs = {};
+      this.includeRelationshipIds(childType, childIncludeArgs, "include");
+      const fetchArgs = {
+        where: this.makeIdFilter(parentInfo.idFields, parentId),
+        select: {
+          [parentRelation]: childIncludeArgs.include ? {
+            include: childIncludeArgs.include
+          } : true
+        }
+      };
+      const parent = await client[parentType].findUnique(fetchArgs);
+      const entity = parent?.[parentRelation];
+      if (!entity) return this.makeError("notFound");
+      const linkUrl = this.makeLinkUrl(this.makeNestedLinkUrl(parentType, parentId, parentRelation));
+      const nestedLinker = new tsjapi.Linker(() => linkUrl);
+      return {
+        status: 200,
+        body: await this.serializeItems(childType, entity, {
+          linkers: {
+            document: nestedLinker,
+            resource: nestedLinker
+          }
+        })
+      };
+    }
+  }
+  async processNestedDelete(client, parentType, parentId, parentRelation, childId) {
+    const resolved = this.resolveNestedRelation(parentType, parentRelation);
+    if (!resolved) {
+      return this.makeError("invalidPath");
+    }
+    const parentInfo = this.getModelInfo(parentType);
+    const typeInfo = this.getModelInfo(resolved.childType);
+    await client[parentType].update({
+      where: this.makeIdFilter(parentInfo.idFields, parentId),
+      data: {
+        [parentRelation]: {
+          delete: this.makeIdFilter(typeInfo.idFields, childId)
+        }
+      }
+    });
+    return {
+      status: 200,
+      body: {
+        meta: {}
+      }
+    };
+  }
   buildPartialSelect(type, query) {
     const selectFieldsQuery = query?.[`fields[${type}]`];
     if (!selectFieldsQuery) {
@@ -1244,7 +3062,7 @@ ${err.stack}` : "Unknown error");
   }
   getIdFields(model) {
     const modelDef = this.requireModel(model);
-    const modelLower = lowerCaseFirst(model);
+    const modelLower = lowerCaseFirst3(model);
     if (!(modelLower in this.externalIdMapping)) {
       return Object.values(modelDef.fields).filter((f) => modelDef.idFields.includes(f.name));
     }
@@ -1278,7 +3096,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[lowerCaseFirst(model)] = {
+      const modelInfo = this.typeMap[lowerCaseFirst3(model)] = {
         name: model,
         idFields,
         relationships: {},
@@ -1303,7 +3121,7 @@ ${err.stack}` : "Unknown error");
     }
   }
   getModelInfo(model) {
-    return this.typeMap[lowerCaseFirst(model)];
+    return this.typeMap[lowerCaseFirst3(model)];
   }
   makeLinkUrl(path) {
     return `${this.options.endpoint}${path}`;
@@ -1312,7 +3130,7 @@ ${err.stack}` : "Unknown error");
     const linkers = {};
     for (const model of Object.keys(this.schema.models)) {
       const ids = this.getIdFields(model);
-      const modelLower = lowerCaseFirst(model);
+      const modelLower = lowerCaseFirst3(model);
       const mappedModel = this.mapModelName(modelLower);
       if (ids.length < 1) {
         continue;
@@ -1341,7 +3159,7 @@ ${err.stack}` : "Unknown error");
       this.serializers.set(modelLower, serializer);
     }
     for (const model of Object.keys(this.schema.models)) {
-      const modelLower = lowerCaseFirst(model);
+      const modelLower = lowerCaseFirst3(model);
       const serializer = this.serializers.get(modelLower);
       if (!serializer) {
         continue;
@@ -1352,7 +3170,7 @@ ${err.stack}` : "Unknown error");
         if (!fieldDef.relation) {
           continue;
         }
-        const fieldSerializer = this.serializers.get(lowerCaseFirst(fieldDef.type));
+        const fieldSerializer = this.serializers.get(lowerCaseFirst3(fieldDef.type));
         if (!fieldSerializer) {
           continue;
         }
@@ -1386,7 +3204,7 @@ ${err.stack}` : "Unknown error");
     }
   }
   async serializeItems(model, items, options) {
-    model = lowerCaseFirst(model);
+    model = lowerCaseFirst3(model);
     const serializer = this.serializers.get(model);
     if (!serializer) {
       throw new Error(`serializer not found for model ${model}`);
@@ -1828,7 +3646,7 @@ ${err.stack}` : "Unknown error");
               error: this.makeUnsupportedModelError(relationInfo.type)
             };
           }
-          const { select, error } = this.buildPartialSelect(lowerCaseFirst(relationInfo.type), query);
+          const { select, error } = this.buildPartialSelect(lowerCaseFirst3(relationInfo.type), query);
           if (error) return {
             select: void 0,
             error
@@ -2028,10 +3846,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
-import { lowerCaseFirst as lowerCaseFirst2, safeJSONStringify } from "@zenstackhq/common-helpers";
+import { lowerCaseFirst as lowerCaseFirst4, safeJSONStringify as safeJSONStringify2 } from "@zenstackhq/common-helpers";
 import { CoreCrudOperations, ORMError as ORMError3, ORMErrorReason as ORMErrorReason2 } from "@zenstackhq/orm";
 import SuperJSON4 from "superjson";
 import { match as match3 } from "ts-pattern";
@@ -2052,7 +3875,8 @@ var RPCApiHandler = class {
   validateOptions(options) {
     const schema = z3.strictObject({
       schema: z3.object(),
-      log: loggerSchema.optional()
+      log: loggerSchema.optional(),
+      queryOptions: queryOptionsSchema.optional()
     });
     const parseResult = schema.safeParse(options);
     if (!parseResult.success) {
@@ -2089,7 +3913,7 @@ var RPCApiHandler = class {
         requestBody
       });
     }
-    model = lowerCaseFirst2(model);
+    model = lowerCaseFirst4(model);
     method = method.toUpperCase();
     let args;
     let resCode = 200;
@@ -2156,7 +3980,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: ${safeJSONStringify(processedArgs)}`);
+      log(this.options.log, "debug", () => `handling "${model}.${op}" request with args: ${safeJSONStringify2(processedArgs)}`);
       const clientResult = await client[model][op](processedArgs);
       let responseBody = {
         data: clientResult
@@ -2176,7 +4000,7 @@ var RPCApiHandler = class {
         status: resCode,
         body: responseBody
       };
-      log(this.options.log, "debug", () => `sending response for "${model}.${op}" request: ${safeJSONStringify(response)}`);
+      log(this.options.log, "debug", () => `sending response for "${model}.${op}" request: ${safeJSONStringify2(response)}`);
       return response;
     } catch (err) {
       log(this.options.log, "error", `error occurred when handling "${model}.${op}" request`, err);
@@ -2213,7 +4037,7 @@ var RPCApiHandler = class {
       if (!VALID_OPS.has(itemOp)) {
         return this.makeBadInputErrorResponse(`operation at index ${i} has invalid op: ${itemOp}`);
       }
-      if (!this.isValidModel(client, lowerCaseFirst2(itemModel))) {
+      if (!this.isValidModel(client, lowerCaseFirst4(itemModel))) {
         return this.makeBadInputErrorResponse(`operation at index ${i} has unknown model: ${itemModel}`);
       }
       if (itemArgs !== void 0 && itemArgs !== null && (typeof itemArgs !== "object" || Array.isArray(itemArgs))) {
@@ -2224,7 +4048,7 @@ var RPCApiHandler = class {
         return this.makeBadInputErrorResponse(`operation at index ${i}: ${argsError}`);
       }
       processedOps.push({
-        model: lowerCaseFirst2(itemModel),
+        model: lowerCaseFirst4(itemModel),
         op: itemOp,
         args: processedArgs
       });
@@ -2248,7 +4072,7 @@ var RPCApiHandler = class {
         status: 200,
         body: responseBody
       };
-      log(this.options.log, "debug", () => `sending response for "$transaction" request: ${safeJSONStringify(response)}`);
+      log(this.options.log, "debug", () => `sending response for "$transaction" request: ${safeJSONStringify2(response)}`);
       return response;
     } catch (err) {
       log(this.options.log, "error", `error occurred when handling "$transaction" request`, err);
@@ -2310,7 +4134,7 @@ var RPCApiHandler = class {
         status: 200,
         body: responseBody
       };
-      log(this.options.log, "debug", () => `sending response for "$procs.${proc}" request: ${safeJSONStringify(response)}`);
+      log(this.options.log, "debug", () => `sending response for "$procs.${proc}" request: ${safeJSONStringify2(response)}`);
       return response;
     } catch (err) {
       log(this.options.log, "error", `error occurred when handling "$procs.${proc}" request`, err);
@@ -2321,7 +4145,7 @@ var RPCApiHandler = class {
     }
   }
   isValidModel(client, model) {
-    return Object.keys(client.$schema.models).some((m) => lowerCaseFirst2(m) === lowerCaseFirst2(model));
+    return Object.keys(client.$schema.models).some((m) => lowerCaseFirst4(m) === lowerCaseFirst4(model));
   }
   makeBadInputErrorResponse(message) {
     const resp = {
@@ -2332,7 +4156,7 @@ var RPCApiHandler = class {
         }
       }
     };
-    log(this.options.log, "debug", () => `sending error response: ${safeJSONStringify(resp)}`);
+    log(this.options.log, "debug", () => `sending error response: ${safeJSONStringify2(resp)}`);
     return resp;
   }
   makeGenericErrorResponse(err) {
@@ -2344,7 +4168,7 @@ var RPCApiHandler = class {
         }
       }
     };
-    log(this.options.log, "debug", () => `sending error response: ${safeJSONStringify(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
+    log(this.options.log, "debug", () => `sending error response: ${safeJSONStringify2(resp)}${err instanceof Error ? "\n" + err.stack : ""}`);
     return resp;
   }
   makeORMErrorResponse(err) {
@@ -2376,7 +4200,7 @@ var RPCApiHandler = class {
         error
       }
     };
-    log(this.options.log, "debug", () => `sending error response: ${safeJSONStringify(resp)}`);
+    log(this.options.log, "debug", () => `sending error response: ${safeJSONStringify2(resp)}`);
     return resp;
   }
   async processRequestPayload(args) {