@edium/halifax 2.0.0 → 2.2.0

package/dist/core/crudRouter.js

@@ -1,57 +1,25 @@
 import { AllowAllAuthStrategy } from '../auth/AuthStrategy.js';
 import { createCachingRepository, InMemoryCacheStore } from '../core/cache/index.js';
-import { HttpError } from '../errors/HttpError.js';
-import { MethodNotAllowedError } from '../errors/MethodNotAllowedError.js';
-import { NotAcceptableError } from '../errors/NotAcceptableError.js';
-import { NotFoundError } from '../errors/NotFoundError.js';
-import { NotImplementedError } from '../errors/NotImplementedError.js';
-import { UnprocessableEntityError } from '../errors/UnprocessableEntityError.js';
-import { UnsupportedMediaTypeError } from '../errors/UnsupportedMediaTypeError.js';
+import { generateOpenApiSpec, generateDocsHtml } from '../openapi/index.js';
 import { defaultCrudPermissions } from '../core/types.js';
-import { parseListOptions } from '../core/queryString.js';
-import { validateAdvancedQuery, validateId, isValidUuid, isValidObjectId } from '../core/validation.js';
 import { ServerError } from '../errors/ServerError.js';
 import { AuthorizationError } from '../errors/AuthorizationError.js';
-/**
- * Parses and validates a raw `:id` route parameter.
- * @param raw - The raw string value from `req.params.id`.
- * @returns A parsed integer for numeric IDs, or the original string for UUID / ObjectId keys.
- * @throws {@link BadRequestError} when the value is not a valid integer, UUID, or ObjectId.
- */
-function parseId(raw) {
-    validateId(raw);
-    // UUID and Mongo ObjectId keys are passed through as strings; only numeric ids are parsed.
-    if (typeof raw === 'string' && (isValidUuid(raw) || isValidObjectId(raw)))
-        return raw;
-    return typeof raw === 'string' ? parseInt(raw, 10) : raw;
-}
-/**
- * Strips non-writable fields from a request body and rejects unknown fields with a 422.
- * Operates on a {@link normalizeResource | normalized} resource, whose fields carry explicit
- * `writable` booleans (permissive by default; the primary key protected). Fields with
- * `writable: false` are silently dropped.
- * @param resource - The normalized resource definition.
- * @param data - The raw request body key-value map.
- * @returns A new object containing only writable fields.
- * @throws {@link UnprocessableEntityError} when the body contains keys not defined on the resource.
- */
-function filterWritableFields(resource, data) {
-    const fields = resource.fields ?? [];
-    const knownFields = new Set(fields.map((f) => f.name));
-    const unknownFields = Object.keys(data).filter((key) => !knownFields.has(key));
-    if (unknownFields.length) {
-        throw new UnprocessableEntityError(`Unknown field(s): ${unknownFields.join(', ')}.`);
-    }
-    return Object.fromEntries(Object.entries(data).filter(([key]) => {
-        const field = fields.find((f) => f.name === key);
-        return field?.writable !== false;
-    }));
-}
+import { MethodNotAllowedError } from '../errors/MethodNotAllowedError.js';
+import { normalizeError, sendError, wantsCacheBust } from '../core/handlerUtils.js';
+import { mergeFieldDefinitions } from '../core/fields.js';
+import { registerCreate } from '../core/handlers/create.js';
+import { registerReadMany } from '../core/handlers/readMany.js';
+import { registerReadOne } from '../core/handlers/readOne.js';
+import { registerQuery } from '../core/handlers/query.js';
+import { registerUpdateOne } from '../core/handlers/updateOne.js';
+import { registerUpdateMany } from '../core/handlers/updateMany.js';
+import { registerUpsertOne } from '../core/handlers/upsertOne.js';
+import { registerDeleteOne } from '../core/handlers/deleteOne.js';
+import { registerDeleteMany } from '../core/handlers/deleteMany.js';
+export { normalizeError };
 /**
  * Derives a human-readable resource name from a route prefix when none is given:
  * de-kebabs/de-snakes and title-cases each word (`'blog-posts'` → `'Blog Posts'`).
- * @param routePrefix - The resource's URL path segment.
- * @returns A title-cased display name.
  */
 function deriveResourceName(routePrefix) {
     return (routePrefix
@@ -61,27 +29,13 @@ function deriveResourceName(routePrefix) {
         .join(' ') || routePrefix);
 }
 /**
- * Resolves the effective field list for a resource. When the repository exposes a field
- * schema it forms the base, and the resource's own `fields` are merged over it **by name**
- * as sparse overrides (entries with no matching base field are added). When the repository
- * exposes no schema, the resource's `fields` are the authoritative list.
- *
- * Every resolved field gets explicit, permissive defaults — `filterable`/`sortable`/
- * `selectable`/`writable` default to `true` — except the primary key, which is non-writable
- * unless a field entry explicitly sets `writable: true`.
- *
- * @param resource - The raw resource definition.
- * @param idField - The repository's primary-key field name (protected from writes).
- * @returns The fully-resolved field list.
+ * Resolves the effective field list for a resource. Merges the repository's field schema
+ * with the resource's own `fields` as sparse overrides. Applies permissive defaults for all
+ * flags except the primary key, which is non-writable unless explicitly opted in.
  * @throws {@link ServerError} when neither the repository nor the resource provides any fields.
  */
 function resolveFields(resource, idField) {
-    const byName = new Map();
-    for (const field of resource.repository?.fields ?? [])
-        byName.set(field.name, { ...field });
-    for (const override of resource.fields ?? [])
-        byName.set(override.name, { ...byName.get(override.name), ...override });
-    const merged = [...byName.values()];
+    const merged = mergeFieldDefinitions(resource);
     if (merged.length === 0) {
         throw new ServerError(`Resource '${resource.name ?? resource.routePrefix}' has no fields. Provide 'fields', ` +
             `or construct its repository with a model so the schema can be derived.`);
@@ -92,13 +46,15 @@ function resolveFields(resource, idField) {
         sortable: field.sortable !== false,
         selectable: field.selectable !== false,
         // Permissive by default — but the primary key is protected: writable only when opted in.
-        writable: field.name === idField ? field.writable === true : field.writable !== false
+        writable: field.name === idField ? field.writable === true : field.writable !== false,
+        ...(field.type !== undefined ? { type: field.type } : {}),
+        ...(field.format !== undefined ? { format: field.format } : {}),
+        ...(field.readRoles?.length ? { readRoles: field.readRoles } : {}),
+        ...(field.writeRoles?.length ? { writeRoles: field.writeRoles } : {})
     }));
 }
 /**
  * Merges the repository's relation schema with the resource's own relations, by name.
- * @param resource - The raw resource definition.
- * @returns The resolved relation list (may be empty).
  */
 function resolveRelations(resource) {
     const byName = new Map();
@@ -109,12 +65,9 @@ function resolveRelations(resource) {
     return [...byName.values()];
 }
 /**
- * Produces a fully-resolved resource: `name` filled in (derived from `routePrefix` when
- * omitted), and `fields`/`relations` resolved from the repository schema + the resource's
- * own (override) entries. Every downstream router stage operates on this normalized form,
- * so defaults live in exactly one place.
- * @param resource - The raw resource definition supplied by the caller.
- * @returns A normalized resource with guaranteed `name` and resolved `fields`/`relations`.
+ * Produces a fully-resolved resource: `name` filled in, and `fields`/`relations` resolved
+ * from the repository schema + the resource's own entries. Every downstream stage operates
+ * on this normalized form so defaults live in exactly one place.
  */
 function normalizeResource(resource) {
     const idField = resource.repository?.idField ?? 'id';
@@ -125,89 +78,17 @@ function normalizeResource(resource) {
         relations: resolveRelations(resource)
     };
 }
-/** Maps HTTP status codes to machine-readable error code strings. */
-const statusCodeMap = {
-    400: 'BAD_REQUEST',
-    401: 'UNAUTHORIZED',
-    403: 'FORBIDDEN',
-    404: 'NOT_FOUND',
-    405: 'METHOD_NOT_ALLOWED',
-    406: 'NOT_ACCEPTABLE',
-    415: 'UNSUPPORTED_MEDIA_TYPE',
-    422: 'UNPROCESSABLE_ENTITY',
-    501: 'NOT_IMPLEMENTED'
-};
-/**
- * Converts any thrown value to a structured `{ status, code, message, details }` object.
- * {@link HttpError} subclasses preserve their status; all other errors become 500.
- * @param error - The caught value to normalise (may be any type).
- * @returns A plain object with `status`, `code`, `message`, and optional `details`.
- */
-export function normalizeError(error) {
-    if (error instanceof HttpError) {
-        return {
-            status: error.status,
-            code: statusCodeMap[error.status] ?? 'INTERNAL_ERROR',
-            message: error.message,
-            details: error.details
-        };
-    }
-    if (error instanceof Error) {
-        return { status: 500, code: 'INTERNAL_ERROR', message: 'Internal server error' };
-    }
-    return { status: 500, code: 'INTERNAL_ERROR', message: 'Internal server error' };
-}
-/**
- * Serialises a caught error and writes it as a JSON `{ errors: [...] }` response.
- * @param error - The caught value to serialise.
- * @param res - The response object to write to.
- */
-async function sendError(error, res) {
-    const { status, code, message, details } = normalizeError(error);
-    const item = { code, message };
-    if (details !== undefined)
-        item['details'] = details;
-    await res.status(status).json({ errors: [item] });
-}
 /**
- * Runs the auth strategy for `action` and throws {@link AuthorizationError} when not allowed.
- * @param req - The incoming HTTP request.
- * @param resource - The resource being accessed (used to look up required permissions).
- * @param action - The CRUD action being performed.
- * @param authStrategy - The active auth strategy.
- * @returns The resolved {@link AuthContext} (so callers can derive the tenant scope from it).
+ * Resolves the effective envelope key. A non-empty string enables wrapping; `null`, `undefined`,
+ * and `''` all mean "no envelope".
  */
-async function authorizeRequest(req, resource, action, authStrategy) {
-    const auth = await authStrategy.authenticate(req);
-    const requiredPermissions = resource.requiredPermissions?.[action] ?? [];
-    if (authStrategy.authorize) {
-        const allowed = await authStrategy.authorize({
-            auth,
-            action,
-            resource,
-            requiredPermissions,
-            req
-        });
-        if (!allowed)
-            throw new AuthorizationError();
-        return auth;
-    }
-    if (requiredPermissions.length) {
-        const permissions = new Set(auth.permissions ?? []);
-        const roles = new Set(auth.roles ?? []);
-        const allowed = requiredPermissions.every((permission) => permissions.has(permission) || roles.has(permission));
-        if (!allowed)
-            throw new AuthorizationError();
-    }
-    return auth;
+function normalizeEnvelope(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
 }
 /**
- * Determines the column a resource is tenant-scoped on, applying this precedence:
+ * Determines the column a resource is tenant-scoped on, with this precedence:
  * explicit `resource.tenant` (or `false` to opt out) → auto-detect the API's default
  * tenant field when the resource actually has it → otherwise unscoped (global).
- * @param resource - The resource being inspected.
- * @param tenant - The API-wide tenant options, or `undefined` when tenancy is off.
- * @returns The tenant field name, or `null` when the resource is not scoped.
  */
 function effectiveTenantField(resource, tenant) {
     if (!tenant)
@@ -221,87 +102,14 @@ function effectiveTenantField(resource, tenant) {
 }
 /** Matches a safe SQL identifier — tenant fields are interpolated into SQL on bulk paths. */
 const safeIdentifier = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-/**
- * Reads a single header value by name (case-insensitive).
- * @param req - The incoming HTTP request.
- * @param name - Header name to look up (case-insensitive).
- * @returns The header value as a string, or `undefined` when absent.
- */
-function getHeaderValue(req, name) {
-    const raw = req.headers[name.toLowerCase()] ?? req.headers[name];
-    const value = Array.isArray(raw) ? raw[0] : raw;
-    return typeof value === 'string' ? value : undefined;
-}
-/**
- * Decides whether the request asks to bypass (bust) the cache. For the standard
- * `Cache-Control` header this means a `no-cache`/`no-store` directive; for any custom
- * bust header, mere presence (with a non-empty value) triggers a refresh.
- * @param req - The incoming HTTP request.
- * @param header - The configured bust header name.
- * @returns `true` when the cache should be force-refreshed for this request.
- */
-function wantsCacheBust(req, header) {
-    const value = getHeaderValue(req, header);
-    if (!value)
-        return false;
-    if (header.toLowerCase() === 'cache-control')
-        return /no-cache|no-store/i.test(value);
-    return true;
-}
-/**
- * Throws {@link UnsupportedMediaTypeError} when a body-carrying request uses a non-JSON Content-Type.
- * @param req - The incoming HTTP request to check.
- */
-function checkContentType(req) {
-    if (!['POST', 'PATCH', 'PUT', 'DELETE'].includes(req.method.toUpperCase()))
-        return;
-    const contentType = getHeaderValue(req, 'content-type') ?? '';
-    if (contentType && !contentType.includes('application/json')) {
-        throw new UnsupportedMediaTypeError();
-    }
-}
-/**
- * Throws {@link NotAcceptableError} when the client's Accept header excludes `application/json`.
- * @param req - The incoming HTTP request to check.
- */
-function checkAcceptHeader(req) {
-    const accept = getHeaderValue(req, 'accept') ?? '';
-    if (accept &&
-        !accept.includes('*/*') &&
-        !accept.includes('application/*') &&
-        !accept.includes('application/json')) {
-        throw new NotAcceptableError();
-    }
-}
-/**
- * Wraps a route handler with Content-Type / Accept checks, error serialisation,
- * and `X-Correlation-ID` echo-back.
- * @param handler - The inner async route handler to wrap.
- * @returns A new handler with pre/post-processing applied.
- */
-function wrap(handler) {
-    return async (req, res) => {
-        const correlationId = getHeaderValue(req, 'x-correlation-id');
-        if (correlationId)
-            res.setHeader?.('X-Correlation-ID', correlationId);
-        try {
-            checkContentType(req);
-            checkAcceptHeader(req);
-            await handler(req, res);
-        }
-        catch (error) {
-            await sendError(error, res);
-        }
-    };
-}
 /**
  * Registers all CRUD routes for every resource on the given HTTP server.
  *
  * Routes are controlled by `resource.permissions` merged with {@link defaultCrudPermissions}.
  *
- * @param server - The HTTP server adapter to register routes on (e.g. {@link ExpressHttpServer}).
+ * @param server - The HTTP server adapter to register routes on.
  * @param resources - Resource definitions to wire up as CRUD endpoints.
- * @param options - Auth strategy and query-builder path overrides.
+ * @param options - Auth strategy, tenant config, envelope, caching, and OpenAPI overrides.
  */
 export function registerCrudApi(server, resources, options = {}) {
     const authStrategy = options.authStrategy ?? new AllowAllAuthStrategy();
@@ -314,12 +122,12 @@ export function registerCrudApi(server, resources, options = {}) {
         const repository = rawResource.repository;
         if (!repository)
             throw new ServerError(`Resource '${rawResource.name ?? rawResource.routePrefix}' does not define a repository.`);
-        // Resolve name + field/relation schema once, here, so every downstream stage (validation,
-        // write-filtering, tenant auto-detection, cache namespace) works off a single source of
-        // truth with all defaults already applied.
+        // Resolve name + field/relation schema once so every downstream stage works off a single
+        // source of truth with all defaults already applied.
         const resource = normalizeResource(rawResource);
-        // Resolve tenancy once at registration and fail closed on misconfiguration, so a
-        // scoped resource can never be silently served unscoped at request time.
+        // Per-resource envelope wins over API-wide default, including an explicit null/''.
+        const envelope = normalizeEnvelope(resource.envelope !== undefined ? resource.envelope : options.envelope);
+        // Resolve tenancy once at registration and fail closed on misconfiguration.
         const tenantField = effectiveTenantField(resource, options.tenant);
         if (tenantField) {
             if (!safeIdentifier.test(tenantField))
@@ -328,21 +136,12 @@ export function registerCrudApi(server, resources, options = {}) {
                 throw new ServerError(`Resource '${resource.name}' is tenant-scoped on '${tenantField}' but its repository ` +
                     `does not implement withScope(). Refusing to serve it unscoped.`);
         }
-        // Effective cache TTL: an explicit `cache: false` disables; otherwise per-resource config
-        // wins over the API-wide default. `0` means "never expire" (so `undefined` = no caching).
+        // Effective cache TTL: explicit `cache: false` disables; per-resource config wins over
+        // API-wide default. `0` means "never expire" (so `undefined` = no caching).
         const cacheTtl = resource.cache === false
             ? undefined
             : (resource.cache?.ttlSeconds ?? options.cache?.ttlSeconds);
         const cachingEnabled = cacheTtl !== undefined;
-        /**
-         * Wraps a repository in the read-through cache when caching is enabled for this resource.
-         * The namespace embeds the resource name and tenant key, so one tenant can never read
-         * another's cached rows. `bust` (from the cache-bust header) force-refreshes this request.
-         * @param repo - The (possibly tenant-scoped) repository for this request.
-         * @param scopeKey - Stable key for the current tenant scope (or `'global'`).
-         * @param bust - Whether the caller requested a cache-busting refresh.
-         * @returns The repository, cache-wrapped when caching is enabled.
-         */
         const withCache = (repo, scopeKey, bust) => cachingEnabled
             ? createCachingRepository(repo, {
                 store: cacheStore,
@@ -351,12 +150,6 @@ export function registerCrudApi(server, resources, options = {}) {
                 bust
             })
             : repo;
-        /**
-         * Returns the repository to use for this request: the tenant-scoped clone when the
-         * resource is scoped, or the bare repository otherwise — wrapped in the read-through
-         * cache when enabled. Throws 403 in strict mode (the default) when a scoped resource
-         * cannot resolve a tenant for the caller.
-         */
         const resolveRepo = async (req, auth) => {
             const bust = cachingEnabled && wantsCacheBust(req, bustHeader);
             if (!tenantField || !options.tenant)
@@ -371,127 +164,27 @@ export function registerCrudApi(server, resources, options = {}) {
         };
         const permissions = { ...defaultCrudPermissions, ...resource.permissions };
         const basePath = `/${resource.routePrefix}`;
-        if (permissions.allowCreate) {
-            server.registerRoute('POST', basePath, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'create', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                const idempotencyKey = getHeaderValue(req, 'idempotency-key');
-                const createOptions = idempotencyKey ? { idempotencyKey } : undefined;
-                const items = (Array.isArray(req.body) ? req.body : [req.body]).map((item) => filterWritableFields(resource, item));
-                if (items.length === 1) {
-                    const result = await repo.createOne(items[0], createOptions);
-                    await res.status(201).json(result);
-                    return;
-                }
-                const results = await repo.createMany(items, createOptions);
-                await res.status(201).json(results);
-            }));
-        }
-        if (permissions.allowReadMany) {
-            server.registerRoute('GET', basePath, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'readMany', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                const listOptions = parseListOptions(req.query, resource);
-                const results = await repo.getMany(listOptions);
-                await res.status(200).json(results);
-            }));
-        }
-        if (permissions.allowReadManyWithQueryBuilder) {
-            server.registerRoute('POST', `${basePath}/${queryBuilderPath}`, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'readManyWithQueryBuilder', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                if (!repo.executeQuery)
-                    throw new NotImplementedError('This resource does not support the query builder.');
-                const body = (req.body ?? {});
-                const query = { ...body };
-                validateAdvancedQuery(resource, query);
-                const results = await repo.executeQuery(query);
-                await res.status(200).json(results);
-            }));
-        }
-        if (permissions.allowReadOne) {
-            server.registerRoute('GET', `${basePath}/:id`, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'readOne', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                const id = parseId(req.params['id']);
-                const listOptions = parseListOptions(req.query, resource);
-                const result = await repo.getOne(id, {
-                    fields: listOptions.fields,
-                    include: listOptions.include
-                });
-                if (!result)
-                    throw new NotFoundError();
-                await res.status(200).json(result);
-            }));
-        }
-        if (permissions.allowUpdateOne) {
-            server.registerRoute('PATCH', `${basePath}/:id`, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'updateOne', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                const id = parseId(req.params['id']);
-                const body = filterWritableFields(resource, req.body);
-                const result = await repo.updateOne(id, body);
-                if (!result)
-                    throw new NotFoundError();
-                await res.status(200).json(result);
-            }));
-        }
-        if (permissions.allowUpdateMany) {
-            server.registerRoute('PATCH', basePath, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'updateMany', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                if (!repo.updateMany)
-                    throw new NotImplementedError('This resource does not support updateMany.');
-                const { update, ...queryBody } = (req.body ?? {});
-                const filteredUpdate = filterWritableFields(resource, (update ?? {}));
-                if (!Object.keys(filteredUpdate).length)
-                    throw new UnprocessableEntityError('updateMany requires at least one writable field in the update payload.');
-                const query = { ...queryBody };
-                validateAdvancedQuery(resource, query);
-                if (!query.where?.length)
-                    throw new UnprocessableEntityError('updateMany requires at least one WHERE filter to prevent unintended bulk updates.');
-                const result = await repo.updateMany(query, filteredUpdate);
-                await res.status(200).json(result);
-            }));
-        }
-        if (permissions.allowUpsertOne) {
-            server.registerRoute('PUT', `${basePath}/:id`, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'upsertOne', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                if (!repo.upsertOne)
-                    throw new NotImplementedError('This resource does not support upsert.');
-                const id = parseId(req.params['id']);
-                const body = filterWritableFields(resource, req.body);
-                const result = await repo.upsertOne(id, body);
-                await res.status(200).json(result);
-            }));
-        }
-        if (permissions.allowDeleteOne) {
-            server.registerRoute('DELETE', `${basePath}/:id`, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'deleteOne', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                const id = parseId(req.params['id']);
-                const deleted = await repo.deleteOne(id);
-                if (!deleted)
-                    throw new NotFoundError();
-                await res.status(200).json({ deleted: true });
-            }));
-        }
-        if (permissions.allowDeleteMany) {
-            server.registerRoute('DELETE', basePath, wrap(async (req, res) => {
-                const auth = await authorizeRequest(req, resource, 'deleteMany', authStrategy);
-                const repo = await resolveRepo(req, auth);
-                if (!repo.deleteMany)
-                    throw new NotImplementedError('This resource does not support deleteMany.');
-                const body = (req.body ?? {});
-                const query = { ...body };
-                validateAdvancedQuery(resource, query);
-                if (!query.where?.length)
-                    throw new UnprocessableEntityError('deleteMany requires at least one WHERE filter to prevent unintended bulk deletes.');
-                const result = await repo.deleteMany(query);
-                await res.status(200).json(result);
-            }));
-        }
+        // Cast to the widest usable type once so every handler can call hooks without generics.
+        const hooks = resource.hooks;
+        const handlerCtx = { resource, authStrategy, envelope, hooks, resolveRepo };
+        if (permissions.allowCreate)
+            registerCreate(server, basePath, handlerCtx);
+        if (permissions.allowReadMany)
+            registerReadMany(server, basePath, handlerCtx);
+        if (permissions.allowReadManyWithQueryBuilder)
+            registerQuery(server, basePath, queryBuilderPath, handlerCtx);
+        if (permissions.allowReadOne)
+            registerReadOne(server, basePath, handlerCtx);
+        if (permissions.allowUpdateOne)
+            registerUpdateOne(server, basePath, handlerCtx);
+        if (permissions.allowUpdateMany)
+            registerUpdateMany(server, basePath, handlerCtx);
+        if (permissions.allowUpsertOne)
+            registerUpsertOne(server, basePath, handlerCtx);
+        if (permissions.allowDeleteOne)
+            registerDeleteOne(server, basePath, handlerCtx);
+        if (permissions.allowDeleteMany)
+            registerDeleteMany(server, basePath, handlerCtx);
         // 405 fallbacks — only registered when at least one method exists for the path
         const baseMethods = [
             ...(permissions.allowReadMany ? ['GET'] : []),
@@ -524,4 +217,41 @@ export function registerCrudApi(server, resources, options = {}) {
             });
         }
     });
+    if (options.openapi && options.openapi.enabled !== false) {
+        const specPath = options.openapi.specPath ?? '/openapi.json';
+        const docsPath = options.openapi.docsPath ?? '/docs';
+        const resolvedEnvelope = options.openapi.envelope ?? options.envelope ?? null;
+        const resolvedScheme = options.openapi.securityScheme ?? authStrategy.openApiScheme?.();
+        const openApiOpts = {
+            ...options.openapi,
+            envelope: resolvedEnvelope,
+            ...(resolvedScheme ? { securityScheme: resolvedScheme } : {})
+        };
+        const spec = generateOpenApiSpec(resources, openApiOpts);
+        const specJson = JSON.stringify(spec, null, 2);
+        const docsHtml = generateDocsHtml(specPath, docsPath);
+        const requireAuth = options.openapi.requireAuth === true;
+        server.registerRoute('GET', specPath, async (req, res) => {
+            try {
+                if (requireAuth)
+                    await authStrategy.authenticate(req);
+                res.setHeader?.('Content-Type', 'application/json');
+                res.send?.(specJson);
+            }
+            catch (error) {
+                await sendError(error, res);
+            }
+        });
+        server.registerRoute('GET', docsPath, async (req, res) => {
+            try {
+                if (requireAuth)
+                    await authStrategy.authenticate(req);
+                res.setHeader?.('Content-Type', 'text/html; charset=utf-8');
+                res.send?.(docsHtml);
+            }
+            catch (error) {
+                await sendError(error, res);
+            }
+        });
+    }
 }

package/dist/core/fields.d.ts

@@ -0,0 +1,8 @@
+import type { FieldDefinition, ResourceDefinition } from '../core/types.js';
+/**
+ * Merges a resource's field schema: repository fields are the base, and
+ * `resource.fields` entries are applied as sparse overrides (by name).
+ * Returns the raw merged list with no defaults applied — callers normalise
+ * the flags they care about on top of this.
+ */
+export declare function mergeFieldDefinitions(resource: ResourceDefinition): FieldDefinition[];

package/dist/core/fields.js

@@ -0,0 +1,14 @@
+/**
+ * Merges a resource's field schema: repository fields are the base, and
+ * `resource.fields` entries are applied as sparse overrides (by name).
+ * Returns the raw merged list with no defaults applied — callers normalise
+ * the flags they care about on top of this.
+ */
+export function mergeFieldDefinitions(resource) {
+    const byName = new Map();
+    for (const f of resource.repository?.fields ?? [])
+        byName.set(f.name, { ...f });
+    for (const f of resource.fields ?? [])
+        byName.set(f.name, { ...byName.get(f.name), ...f });
+    return [...byName.values()];
+}