@edium/halifax 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+
+First public release.
+
+### Added
+
+- **Auto-CRUD engine** — generate standards-compliant REST endpoints (list, read, create,
+  update, upsert, delete, and bulk update/delete) from a single `ResourceDefinition`, with
+  correct status codes, a consistent `{ errors: [...] }` body, content negotiation (406/415),
+  method-not-allowed (405 + `Allow`), and `X-Correlation-ID` / `Idempotency-Key` support.
+- **HTTP adapters** — Express 4/5, Fastify, HyperExpress, and Ultimate Express, each published
+  as its own subpath entry point and verified against one shared conformance suite.
+- **Prisma repository adapter** — one `PrismaAdapter` for every Prisma provider (PostgreSQL,
+  MySQL/MariaDB, SQL Server, SQLite, CockroachDB, MongoDB).
+- **Dynamic query-builder endpoint** (`POST /:resource/query`) — a validated query AST
+  (filter/sort/paginate/project, `AND`/`OR`/nesting, `IN`, `BETWEEN`, `CONTAINS`,
+  `STARTS WITH`, `ENDS WITH`, …) compiled to portable Prisma Client calls — no raw SQL, so
+  the same request behaves identically on every database.
+- **Multi-tenancy** — per-resource tenant scoping with fail-closed guarantees.
+- **Read-through caching** — pluggable `CacheStore` (in-memory default, `RedisCacheStore`
+  provided), per-resource TTLs, never-expire mode, automatic write-invalidation, tenant-safe
+  keys, and a `Cache-Control` cache-bust header.
+- **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action
+  required permissions; and `filterable`/`sortable`/`selectable`/`writable` field flags.
+
+[1.0.0]: https://github.com/splayfee/halifax/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# Halifax
+
+[![CI](https://github.com/splayfee/halifax/actions/workflows/ci.yml/badge.svg)](https://github.com/splayfee/halifax/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@edium/halifax.svg)](https://www.npmjs.com/package/@edium/halifax)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)](https://www.typescriptlang.org/)
+
+Halifax is an adapter-driven TypeScript framework for building standardized REST CRUD APIs automatically from resource definitions. It generates standards-compliant REST endpoints from your data models, wires up authentication, and exposes a dynamic query-builder endpoint for advanced read/update/delete operations.
+
+The package is split into small, replaceable layers — nothing is imported into the core engine. Your ORM, HTTP server, and auth provider are all injected at startup.
+
+## Why Halifax?
+
+- 🚀 **Zero-boilerplate CRUD** — define a resource once and get standards-compliant REST endpoints (list, read, create, update, upsert, delete, bulk) with correct status codes and a consistent error shape.
+- 🧩 **Adapter-driven & swappable** — your HTTP framework, ORM/database, and auth provider are injected, not baked in. Switch any layer without touching your resource definitions.
+- 🌐 **4 HTTP frameworks, identical behavior** — Express 4/5, Fastify, HyperExpress, and Ultimate Express, all verified against one shared conformance suite.
+- 🗄️ **Many databases, one adapter** — PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, CockroachDB, and MongoDB via [Prisma](https://www.prisma.io/). The query builder compiles to portable Prisma calls (never raw SQL), so the **same client request behaves identically on every database** — switch engines by changing one line. (PostgreSQL, MySQL, and SQLite run in CI; the rest use the same adapter and test harness.)
+- 🔎 **Dynamic query-builder endpoint** — let the front-end compose rich filtered/sorted/paginated queries "for free" (`AND`/`OR`/nesting, `IN`, `BETWEEN`, `CONTAINS`, …) without hand-writing endpoints. Fully validated — bad fields/operators return structured `4xx` errors, never leaked DB internals.
+- 🏢 **Multi-tenancy built in** — per-resource tenant scoping with fail-closed guarantees; one tenant can never read or write another's rows.
+- ⚡ **Pluggable read-through caching** — in-memory or Redis, per-resource TTLs, never-expire mode, automatic write-invalidation, tenant-safe keys, and a `Cache-Control` bust header.
+- 🔐 **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action permissions; and `filterable`/`sortable`/`selectable`/`writable` flags enforced on every request.
+- 🧪 **Type-safe & battle-tested** — strict TypeScript, ESM, ships full `.d.ts`; hundreds of unit tests plus real-database + Redis integration tests in CI.
+
+## Current Support
+
+| Layer          | Supported                                                                     |
+| -------------- | ----------------------------------------------------------------------------- |
+| HTTP server    | Express 4/5, Fastify, HyperExpress, Ultimate Express                          |
+| ORM / database | Prisma 7 + Postgres, MySQL, MariaDB, SQL Server, SQLite, MongoDB, CockroachDB |
+| Auth           | API key, JWT/Bearer, Passport + JWT                                           |
+| Caching        | Pluggable read-through cache (in-memory default; bring Redis, etc.)           |
+
+Every HTTP adapter is interchangeable and behaves identically — same routes, status codes,
+error-body shape, and content negotiation — so you can switch frameworks without touching
+your resource definitions, auth, or query logic. See
+[README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md) for per-framework usage.
+
+The same is true across databases: the dynamic query-builder endpoint and all CRUD compile
+to portable Prisma Client calls (never raw SQL), so the **same client request behaves
+identically on every database** — switch engines by changing only the Prisma `provider`. The
+integration suite runs unchanged against Postgres, MySQL, and SQLite in CI to keep that honest.
+
+> **Roadmap** — This project welcomes community-written adapters for Drizzle, Sequelize, etc.
+
+## Install
+
+```bash
+pnpm add @edium/halifax
+pnpm add express @prisma/client
+```
+
+## Quick Start
+
+```ts
+import express from 'express'
+import { PrismaClient } from '@prisma/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+import {
+  PrismaAdapter,
+  ApiKeyAuthStrategy,
+  createExpressCrudRouter,
+  type ResourceDefinition
+} from '@edium/halifax'
+
+const prisma = new PrismaClient({ adapter: new PrismaPg(process.env.DATABASE_URL!) })
+
+const posts: ResourceDefinition = {
+  name: 'Post',
+  routePrefix: 'posts',
+  defaultLimit: 50,
+  maxLimit: 200,
+  fields: [
+    { name: 'id', filterable: true, sortable: true },
+    { name: 'title', filterable: true, sortable: true, writable: true },
+    { name: 'content', writable: true },
+    { name: 'published', filterable: true, writable: true }
+  ],
+  permissions: {
+    allowUpdateMany: false,
+    allowDeleteMany: false
+  },
+  repository: new PrismaAdapter({ delegate: prisma.post })
+}
+
+const app = express()
+app.use(express.json())
+app.use(
+  '/api/v1',
+  createExpressCrudRouter([posts], { authStrategy: new ApiKeyAuthStrategy(process.env.API_KEY!) })
+)
+app.listen(3000)
+```
+
+## Documentation
+
+| Guide                                                | Contents                                                                                      |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [README_AUTOCRUD.md](./README_AUTOCRUD.md)           | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes |
+| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) | Prisma 7 setup, `PrismaAdapter` options, capabilities, custom repositories                    |
+| [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md) | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters          |
+| [README_AUTH.md](./README_AUTH.md)                   | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, custom `authorize`      |
+| [README_MULTITENANCY.md](./README_MULTITENANCY.md)   | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour |
+| [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)   | Query-builder payload, comparisons, nested filters, portable Prisma execution                 |
+| [README_CACHE.md](./README_CACHE.md)                 | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header               |
+
+## Running Integration Tests
+
+The integration suite tests the full stack against a real PostgreSQL database.
+
+### 1. Start a Postgres container
+
+```bash
+docker run -d \
+  --name halifax-test-db \
+  --restart unless-stopped \
+  -e POSTGRES_USER=postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=halifax_test \
+  -p 5432:5432 \
+  postgres:17
+```
+
+### 2. Create `.env.test`
+
+```bash
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/halifax_test"
+```
+
+### 3. Run
+
+```bash
+pnpm test:integration
+```
+
+`globalSetup` runs `prisma generate` and `prisma db push` automatically before any test executes.
+
+### Subsequent runs
+
+```bash
+docker start halifax-test-db
+pnpm test:integration
+```
+
+### Tear down
+
+```bash
+docker stop halifax-test-db && docker rm halifax-test-db
+```

package/README_AUTH.md

@@ -0,0 +1,172 @@
+# Authentication
+
+Halifax auth is handled by an `AuthStrategy` injected at router creation time. The interface is:
+
+```ts
+interface AuthStrategy {
+  authenticate(req: HttpRequest): AuthContext | Promise<AuthContext>
+  authorize?(params: AuthorizeParams): boolean | Promise<boolean>
+}
+```
+
+`authenticate` runs on every request and returns an `AuthContext`. `authorize` is optional — when present it gates each action against the context. When absent, Halifax falls back to checking `requiredPermissions` directly against `auth.roles` and `auth.permissions`.
+
+## Built-in Strategies
+
+### `AllowAllAuthStrategy`
+
+No authentication — every request is admitted. For local development only.
+
+```ts
+import { AllowAllAuthStrategy } from '@edium/halifax'
+
+createExpressCrudRouter([resource], { authStrategy: new AllowAllAuthStrategy() })
+```
+
+### `ApiKeyAuthStrategy`
+
+Reads a header and compares it to a shared secret.
+
+```ts
+import { ApiKeyAuthStrategy } from '@edium/halifax'
+
+// Default header: x-api-key
+const authStrategy = new ApiKeyAuthStrategy(process.env.API_KEY ?? '')
+
+// Custom header name
+const authStrategy = new ApiKeyAuthStrategy(process.env.API_KEY ?? '', 'x-token')
+```
+
+Wrong or missing key → 403.
+
+### `JwtClaimsAuthStrategy`
+
+Extracts a Bearer token from `Authorization` and calls your verify callback. No Passport dependency.
+
+```ts
+import { JwtClaimsAuthStrategy } from '@edium/halifax'
+import { verify } from 'jsonwebtoken'
+
+export const authStrategy = new JwtClaimsAuthStrategy(async (token) => {
+  const payload = verify(token, process.env.JWT_SECRET!) as Record<string, unknown>
+  return {
+    isAuthenticated: true,
+    userId: payload.sub as string,
+    roles: (payload.roles ?? []) as string[],
+    permissions: (payload.permissions ?? []) as string[],
+    claims: payload
+  }
+})
+```
+
+Missing or non-Bearer `Authorization` header → 401. A verify callback that throws → 401.
+
+### `PassportSessionStrategy`
+
+Drop-in for apps that use Passport with session cookies (as opposed to JWT Bearer tokens). Passport's session middleware runs at the Express app level before Halifax, so `req.user` is already populated by the time Halifax sees the request. This strategy just reads it.
+
+**Prerequisites in your Express app (before mounting Halifax):**
+
+```ts
+import session from 'express-session'
+import passport from 'passport'
+
+app.use(session({ secret: process.env.SESSION_SECRET!, resave: false, saveUninitialized: false }))
+app.use(passport.initialize())
+app.use(passport.session())
+```
+
+**Usage:**
+
+```ts
+import { PassportSessionStrategy } from '@edium/halifax'
+
+// Default: reads id/sub → userId, roles, permissions from req.user
+export const authStrategy = new PassportSessionStrategy()
+
+// Custom mapping for non-standard user shapes
+export const authStrategy = new PassportSessionStrategy((user) => {
+  const u = user as { username: string; groups: string[] }
+  return { isAuthenticated: true, userId: u.username, roles: u.groups }
+})
+```
+
+No passport instance is passed — Halifax never calls `passport.authenticate()`. If `req.user` is absent (session expired, not logged in), the request is rejected with 401.
+
+### `PassportJwtStrategy`
+
+Drop-in for an existing Passport + `passport-jwt` setup.
+
+```ts
+import passport from 'passport'
+import { Strategy as JwtStrategy, ExtractJwt } from 'passport-jwt'
+import { PassportJwtStrategy } from '@edium/halifax'
+
+passport.use(
+  new JwtStrategy(
+    {
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKey: process.env.JWT_SECRET
+    },
+    (payload, done) => done(null, payload)
+  )
+)
+
+// Default: reads sub/id → userId, roles, permissions, full payload → claims
+export const authStrategy = new PassportJwtStrategy({ passport })
+
+// Custom payload mapping
+export const authStrategy = new PassportJwtStrategy({
+  passport,
+  mapUser: (user) => {
+    const u = user as { userId: string; role: string }
+    return { isAuthenticated: true, userId: u.userId, roles: [u.role] }
+  }
+})
+```
+
+## Per-Action Permission Requirements
+
+`requiredPermissions` on a resource maps each CRUD action to a list of roles or permission strings. The authenticated user must possess at least one entry from the list (matched against both `auth.roles` and `auth.permissions`).
+
+```ts
+const postResource: ResourceDefinition = {
+  ...
+  requiredPermissions: {
+    readMany:  ['posts.read'],
+    readOne:   ['posts.read'],
+    create:    ['posts.create'],
+    updateOne: ['posts.update'],
+    deleteOne: ['posts.delete'],
+  }
+}
+```
+
+Actions not listed in `requiredPermissions` are allowed for any authenticated user. If `authorize` is implemented on the strategy, it overrides this fallback entirely.
+
+## Custom `authorize` Logic
+
+Implement `authorize` on your strategy for full control:
+
+```ts
+class RoleBasedStrategy implements AuthStrategy {
+  authenticate(req) {
+    /* ... verify token ... */
+  }
+
+  authorize({ auth, action, resource, requiredPermissions }) {
+    if (auth.roles.includes('admin')) return true
+    return requiredPermissions.every((p) => auth.permissions.includes(p) || auth.roles.includes(p))
+  }
+}
+```
+
+## Environment Variables
+
+```bash
+API_KEY="your-api-key"
+# or
+JWT_SECRET="your-secret-key"
+# or
+SESSION_SECRET="your-secret-key"
+```

package/README_AUTOCRUD.md

@@ -0,0 +1,253 @@
+# Auto CRUD
+
+Halifax generates REST endpoints automatically from a `ResourceDefinition`. Define the resource once; the router registers the routes, validates inputs, enforces field-level security, and handles authentication and authorization.
+
+## Resource Definition
+
+```ts
+import type { ResourceDefinition } from '@edium/halifax'
+import { postRepository } from './repositories/post.js'
+
+export const postResource: ResourceDefinition = {
+  name: 'Post',
+  routePrefix: 'posts',
+  defaultLimit: 50, // applied when the caller omits ?limit=
+  maxLimit: 200, // requests above this are silently capped
+  fields: [
+    { name: 'id', filterable: true, sortable: true },
+    { name: 'title', filterable: true, sortable: true, writable: true },
+    { name: 'content', writable: true },
+    { name: 'published', filterable: true, writable: true },
+    { name: 'authorId', filterable: true },
+    { name: 'createdAt', filterable: false, sortable: true, selectable: true }
+  ],
+  relations: [{ name: 'author', includable: true }],
+  permissions: {
+    allowDeleteMany: false
+  },
+  requiredPermissions: {
+    readMany: ['posts.read'],
+    readOne: ['posts.read'],
+    create: ['posts.create'],
+    updateOne: ['posts.update'],
+    deleteOne: ['posts.delete']
+  },
+  repository: postRepository
+}
+```
+
+## Generated Routes
+
+Each `permissions` flag enables one route:
+
+| Flag                            | Method   | Path             |
+| ------------------------------- | -------- | ---------------- |
+| `allowReadMany`                 | `GET`    | `../posts`       |
+| `allowReadOne`                  | `GET`    | `../posts/:id`   |
+| `allowCreate`                   | `POST`   | `../posts`       |
+| `allowUpdateOne`                | `PATCH`  | `../posts/:id`   |
+| `allowUpdateMany`               | `PATCH`  | `../posts`       |
+| `allowUpsertOne`                | `PUT`    | `../posts/:id`   |
+| `allowDeleteOne`                | `DELETE` | `../posts/:id`   |
+| `allowDeleteMany`               | `DELETE` | `../posts`       |
+| `allowReadManyWithQueryBuilder` | `POST`   | `../posts/query` |
+
+All endpoint flags default to `true` — only set them explicitly to `false` to restrict access.
+
+## The `:id` Parameter
+
+`:id` accepts an **integer** (1–2,147,483,647), a **UUID** (RFC 4122, any version), or a **MongoDB ObjectId** (24 hex chars). The format is detected automatically — nothing to configure. Anything else returns 400.
+
+```
+GET /api/v1/posts/42
+GET /api/v1/posts/550e8400-e29b-41d4-a716-446655440000
+GET /api/v1/posts/507f1f77bcf86cd799439011
+```
+
+## Field Flags
+
+Each entry in `fields` accepts four optional boolean flags. All default to `true` — only set them explicitly to `false` to restrict access.
+
+| Flag         | Effect when `false`                                                   |
+| ------------ | --------------------------------------------------------------------- |
+| `filterable` | Rejects the field as a query-string filter (`?fieldName=value`) → 400 |
+| `sortable`   | Rejects the field in `?order=` and query-builder `orderBy` → 400      |
+| `selectable` | Rejects the field in `?fields=` and query-builder `fields` → 400      |
+| `writable`   | Silently strips the field from POST / PATCH request bodies            |
+
+Example — `role` is fully locked down; `createdAt` can be read and sorted but never written or filtered:
+
+```ts
+fields: [
+  { name: 'id', filterable: true, sortable: true, selectable: true },
+  { name: 'email', filterable: true, sortable: true, selectable: true, writable: true },
+  { name: 'role', filterable: false, sortable: false, selectable: false, writable: false },
+  { name: 'createdAt', filterable: false, sortable: true, selectable: true }
+]
+```
+
+## Pagination
+
+Set `defaultLimit` and `maxLimit` on the resource:
+
+```ts
+{
+  defaultLimit: 50,   // used when the caller omits ?limit=
+  maxLimit:     200,  // requests above this are silently capped to 200
+}
+```
+
+Neither is required. Without them, page size is unlimited and fully caller-controlled.
+
+## Query-String Filtering and Pagination
+
+```
+GET /api/v1/posts?limit=25&offset=0&order=-createdAt&published=true&fields=id,title
+```
+
+| Parameter       | Description                                                            |
+| --------------- | ---------------------------------------------------------------------- |
+| `limit`         | Page size. Capped by `maxLimit`; defaults to `defaultLimit` if set.    |
+| `offset`        | Number of rows to skip.                                                |
+| `order`         | Comma-separated field names. Prefix `-` for descending.                |
+| `fields`        | Comma-separated field names to include in the response.                |
+| `include`       | Comma-separated relation names to eager-load (e.g. `?include=author`). |
+| `<field>=value` | Exact-match filter on any `filterable` field.                          |
+
+Multiple values for a field filter produce an `IN` query:
+
+```
+GET /api/v1/posts?authorId=1,2,3
+```
+
+## Relation Includes
+
+Declare includable relations in the resource definition, then request them with `?include=`:
+
+```ts
+relations: [
+  { name: 'author', includable: true },
+  { name: 'comments', includable: false } // blocked
+]
+```
+
+```
+GET /api/v1/posts/42?include=author
+GET /api/v1/posts?include=author&limit=10
+```
+
+## Batch Create
+
+Send an array body to create multiple records in one request:
+
+```ts
+POST /
+  api /
+  v1 /
+  posts[({ title: 'First', published: false }, { title: 'Second', published: true })]
+```
+
+Returns 201. Whether the created records are returned depends on the repository's `supportsCreateManyReturn` capability (see [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md)).
+
+## HTTP Headers
+
+### Content Negotiation (Accept → 406)
+
+All routes check the `Accept` header. Requests that explicitly exclude `application/json` receive **406 Not Acceptable**. Requests with no `Accept` header, `*/*`, or `application/*` proceed normally.
+
+```
+Accept: application/json     ✓
+Accept: */*                  ✓
+Accept: application/json, text/html;q=0.5  ✓
+(no header)                  ✓
+Accept: text/html            → 406
+```
+
+### Content Type (Content-Type → 415)
+
+Requests with a body (`POST`, `PATCH`, `PUT`, `DELETE`) must use `Content-Type: application/json`. Any other value returns **415 Unsupported Media Type**.
+
+```
+Content-Type: application/json          ✓
+Content-Type: application/json; utf-8   ✓
+(no header, no body)                    ✓
+Content-Type: text/plain                → 415
+Content-Type: application/x-www-form-urlencoded  → 415
+```
+
+### Method Not Allowed (405)
+
+If a resource has at least one method enabled, all other methods on that path return **405 Method Not Allowed** with an `Allow` response header listing the permitted methods.
+
+```
+# Resource has allowReadMany + allowCreate only:
+GET    /api/v1/posts   → 200
+POST   /api/v1/posts   → 201
+PUT    /api/v1/posts   → 405  Allow: GET, POST
+DELETE /api/v1/posts   → 405  Allow: GET, POST
+```
+
+### X-Correlation-ID
+
+If the request includes an `X-Correlation-ID` header, the same value is echoed back in the response. Use this to correlate log entries across services.
+
+```
+# Request
+X-Correlation-ID: 550e8400-e29b-41d4-a716-446655440000
+
+# Response includes:
+X-Correlation-ID: 550e8400-e29b-41d4-a716-446655440000
+```
+
+### Idempotency-Key (POST create)
+
+Pass an `Idempotency-Key` header on POST create requests. The key is forwarded to the repository via `CreateOptions.idempotencyKey` — repositories that support idempotent creation can use it to deduplicate concurrent or retried requests.
+
+```
+POST /api/v1/posts
+Idempotency-Key: my-client-generated-uuid
+```
+
+The router itself does not enforce uniqueness; deduplication is the repository's responsibility.
+
+## Filter Depth Controls
+
+The `?where` / query-builder `children` filter lets callers nest conditions. To prevent abuse, nesting is capped at depth **4** by default. Set `maxFilterDepth` on the resource to override:
+
+```ts
+{
+  maxFilterDepth: 1 // only one level of children allowed
+}
+```
+
+Requests that exceed the limit receive **400 VALIDATION_ERROR**.
+
+## Error Response Shape
+
+All errors follow the same envelope — an `errors` array where each item has a machine-readable `code` and a human-readable `message`:
+
+```json
+{
+  "errors": [
+    {
+      "code": "VALIDATION_ERROR",
+      "message": "Field(s) not filterable: role."
+    }
+  ]
+}
+```
+
+| Status | Code                     | Error class                 | Typical cause                                                                                        |
+| ------ | ------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 400    | `BAD_REQUEST`            | `BadRequestError`           | Malformed `:id` — not an integer (1–2147483647) or UUID                                              |
+| 401    | `UNAUTHORIZED`           | `AuthenticationError`       | Missing or invalid auth token                                                                        |
+| 403    | `FORBIDDEN`              | `AuthorizationError`        | Authenticated but lacks required permission                                                          |
+| 404    | `NOT_FOUND`              | `NotFoundError`             | Record not found                                                                                     |
+| 405    | `METHOD_NOT_ALLOWED`     | `MethodNotAllowedError`     | HTTP method not enabled for this resource                                                            |
+| 406    | `NOT_ACCEPTABLE`         | `NotAcceptableError`        | `Accept` header excludes `application/json`                                                          |
+| 415    | `UNSUPPORTED_MEDIA_TYPE` | `UnsupportedMediaTypeError` | Request body is not `application/json`                                                               |
+| 422    | `UNPROCESSABLE_ENTITY`   | `UnprocessableEntityError`  | Semantic validation failure — unknown field, invalid filter, sort/select restriction, depth exceeded |
+| 500    | `INTERNAL_ERROR`         | `ServerError`               | Repository misconfigured or unhandled internal error                                                 |
+| 501    | `NOT_IMPLEMENTED`        | `NotImplementedError`       | Repository does not support this operation                                                           |
+
+When extra context is available (e.g. Prisma error details), a `details` field is included in the error item.