@edium/halifax 1.0.0 → 2.1.0

package/dist/adapters/orm/prisma/createPrismaResources.js

@@ -3,7 +3,7 @@ import { toRoutePrefix } from './helpers.js';
 /**
  * Creates resource definitions for Prisma models based on the provided schema and options.
  * @param prismaClient An instance of the Prisma client to be used for database operations.
- * @param schema  An array of model definitions, where each model includes its name, optional database name, and fields.
+ * @param schema  An array of model definitions, where each model includes its name and fields.
  * @param options An optional configuration object that allows customization of the generated resources, including model-specific options, default limits, and permissions.
  * @returns An array of resource definitions that can be used to set up API endpoints or other data access layers based on the Prisma models.
  */
@@ -13,13 +13,10 @@ export function createPrismaResources(prismaClient, schema, options = {}) {
         .filter((model) => !options.models?.[model.name]?.exclude)
         .map((model) => {
         const modelOpts = options.models?.[model.name] ?? {};
-        const tableName = modelOpts.tableName ?? model.dbName ?? model.name;
         const routePrefix = modelOpts.routePrefix ?? toRoutePrefix(model.name);
         const delegateKey = model.name.charAt(0).toLowerCase() + model.name.slice(1);
         const adapter = new PrismaAdapter({
             delegate: client[delegateKey],
-            client: client,
-            tableName,
             ...(options.idField !== undefined && { idField: options.idField }),
             ...(options.returnCreated !== undefined && { returnCreated: options.returnCreated }),
             model
@@ -27,13 +24,21 @@ export function createPrismaResources(prismaClient, schema, options = {}) {
         const resource = {
             name: model.name,
             routePrefix,
-            tableName,
             fields: adapter.fields,
             repository: adapter,
             permissions: { ...options.permissions, ...modelOpts.permissions }
         };
         if (adapter.relations?.length)
             resource.relations = adapter.relations;
+        // Tenant scoping: an explicit per-model setting wins (including `false` to opt out);
+        // otherwise auto-detect by the global tenant field when the model actually has it.
+        if (modelOpts.tenant !== undefined) {
+            resource.tenant = modelOpts.tenant;
+        }
+        else if (options.tenantField &&
+            adapter.fields.some((f) => f.name === options.tenantField)) {
+            resource.tenant = { field: options.tenantField };
+        }
         if (modelOpts.requiredPermissions)
             resource.requiredPermissions = modelOpts.requiredPermissions;
         const defaultLimit = modelOpts.defaultLimit ?? options.defaultLimit;
@@ -48,4 +53,3 @@ export function createPrismaResources(prismaClient, schema, options = {}) {
         return resource;
     });
 }
-//# sourceMappingURL=createPrismaResources.js.map

package/dist/adapters/orm/prisma/helpers.d.ts

@@ -24,4 +24,3 @@ export declare function toOrderBy(orderBy?: ListOptions['orderBy']): Array<Recor
  * @returns The route prefix, e.g., 'user-profiles'.
  */
 export declare function toRoutePrefix(modelName: string): string;
-//# sourceMappingURL=helpers.d.ts.map

package/dist/adapters/orm/prisma/helpers.js

@@ -42,4 +42,3 @@ export function toRoutePrefix(modelName) {
         return kebab + 'es';
     return kebab + 's';
 }
-//# sourceMappingURL=helpers.js.map

package/dist/adapters/orm/prisma/index.d.ts

@@ -1,4 +1,3 @@
-export type { PrismaDelegate, PrismaNativeClient, PrismaAdapterOptions, CreatePrismaResourcesOptions } from './types.js';
+export type { PrismaDelegate, PrismaAdapterOptions, CreatePrismaResourcesOptions } from './types.js';
 export { PrismaAdapter } from './PrismaAdapter.js';
 export { createPrismaResources } from './createPrismaResources.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/adapters/orm/prisma/index.js

@@ -1,3 +1,2 @@
 export { PrismaAdapter } from './PrismaAdapter.js';
 export { createPrismaResources } from './createPrismaResources.js';
-//# sourceMappingURL=index.js.map

package/dist/adapters/orm/prisma/types.d.ts

@@ -1,4 +1,4 @@
-import type { ModelSchema, ModelResourceOptions, CrudPermissions } from '../../../core/types.js';
+import type { ModelSchema, ModelResourceOptions, CrudPermissions, TenantScope } from '../../../core/types.js';
 /**
  * Minimal Prisma delegate interface needed for CRUD operations. This is not a full Prisma client,
  * but only the methods required by the adapter. The actual Prisma client will have more methods
@@ -23,19 +23,18 @@ export interface PrismaDelegate {
         count: number;
     }>;
 }
-/** Minimal Prisma client interface needed for raw SQL execution. */
-export interface PrismaNativeClient {
-    $queryRawUnsafe?<T = unknown>(query: string, ...values: unknown[]): Promise<T>;
-    $executeRawUnsafe?<T = unknown>(query: string, ...values: unknown[]): Promise<T>;
-}
 /** Construction options for {@link PrismaAdapter}. */
 export interface PrismaAdapterOptions {
     delegate: PrismaDelegate;
-    client?: PrismaNativeClient;
     idField?: string;
-    tableName?: string;
     returnCreated?: boolean;
     model?: ModelSchema;
+    /**
+     * Tenant constraint bound to this adapter instance. Set indirectly via
+     * {@link PrismaAdapter.withScope}; when present, every operation is confined to
+     * `scope.value` on `scope.field`. Leave undefined for unscoped (global) access.
+     */
+    scope?: TenantScope;
 }
 /** Global options for {@link createPrismaResources}. */
 export interface CreatePrismaResourcesOptions {
@@ -45,5 +44,11 @@ export interface CreatePrismaResourcesOptions {
     maxLimit?: number;
     idField?: string;
     returnCreated?: boolean;
+    /**
+     * Tenant column to scope on. Every generated resource that has a scalar field with
+     * this name is marked tenant-scoped on it (`resource.tenant = { field }`), unless the
+     * model overrides or opts out via {@link ModelResourceOptions.tenant}. Pair this with
+     * the API-level `tenant` option (the value resolver) to enforce isolation.
+     */
+    tenantField?: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/adapters/orm/prisma/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/auth/AuthStrategy.d.ts

@@ -187,12 +187,3 @@ export declare class PassportSessionStrategy implements AuthStrategy {
      */
     authorize(params: AuthorizeParams): boolean;
 }
-/** @deprecated Use {@link AuthStrategy} instead. */
-export type AuthProvider = AuthStrategy;
-/** @deprecated Use {@link AllowAllAuthStrategy} instead. */
-export declare const AllowAllAuthProvider: typeof AllowAllAuthStrategy;
-/** @deprecated Use {@link ApiKeyAuthStrategy} instead. */
-export declare const ApiKeyAuthProvider: typeof ApiKeyAuthStrategy;
-/** @deprecated Use {@link JwtClaimsAuthStrategy} instead. */
-export declare const PermissionAuthProvider: typeof JwtClaimsAuthStrategy;
-//# sourceMappingURL=AuthStrategy.d.ts.map

package/dist/auth/AuthStrategy.js

@@ -218,10 +218,3 @@ export class PassportSessionStrategy {
         return params.requiredPermissions.every((p) => permissions.has(p) || roles.has(p));
     }
 }
-/** @deprecated Use {@link AllowAllAuthStrategy} instead. */
-export const AllowAllAuthProvider = AllowAllAuthStrategy;
-/** @deprecated Use {@link ApiKeyAuthStrategy} instead. */
-export const ApiKeyAuthProvider = ApiKeyAuthStrategy;
-/** @deprecated Use {@link JwtClaimsAuthStrategy} instead. */
-export const PermissionAuthProvider = JwtClaimsAuthStrategy;
-//# sourceMappingURL=AuthStrategy.js.map

package/dist/core/cache/CacheStore.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pluggable cache backend. The default is `InMemoryCacheStore`; supply your own
+ * (Redis, Memcached, etc.) via the API's cache options to share a cache across processes.
+ * All methods may be async so network-backed stores fit the same contract.
+ */
+export interface CacheStore {
+    /**
+     * Read a cached value.
+     * @param key - Cache key.
+     * @returns The stored value, or `undefined` when absent or expired.
+     */
+    get(key: string): Promise<unknown> | unknown;
+    /**
+     * Write a cached value.
+     * @param key - Cache key.
+     * @param value - Value to store.
+     * @param ttlSeconds - Time-to-live in seconds. Omit/`undefined` (or `0`) for no expiry.
+     */
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void> | void;
+    /**
+     * Delete a cached value.
+     * @param key - Cache key to remove.
+     */
+    delete(key: string): Promise<void> | void;
+}

package/dist/core/cache/CacheStore.js

@@ -0,0 +1 @@
+export {};

package/dist/core/cache/createCachingRepository.d.ts

@@ -0,0 +1,39 @@
+import type { Repository } from '../../core/types.js';
+import type { CacheStore } from './CacheStore.js';
+/** Options for {@link createCachingRepository}. */
+export interface CachingRepositoryOptions {
+    /** Backing cache store. */
+    store: CacheStore;
+    /** Time-to-live for cached reads, in seconds. `0` means **never expire** (cache forever). */
+    ttlSeconds: number;
+    /**
+     * Key namespace for this repository — must be unique per (resource, tenant) so one
+     * tenant can never read another's cached rows. The router builds this from the resource
+     * name and the resolved tenant scope value.
+     */
+    namespace: string;
+    /**
+     * When `true`, reads bypass the cache lookup, fetch fresh from the underlying repository,
+     * and overwrite the cached entry. Set per-request from the cache-bust header so a client
+     * can force-refresh on demand. Writes still invalidate as usual.
+     */
+    bust?: boolean;
+}
+/**
+ * Wraps a {@link Repository} with read-through caching and write invalidation.
+ *
+ * - **Reads** (`getOne`, `getMany`, `executeQuery`) are cached under a versioned key.
+ * - **Writes** (`createOne/Many`, `updateOne/Many`, `upsertOne`, `deleteOne/Many`) bump the
+ *   namespace version, so every previously-cached read for this resource/tenant is instantly
+ *   stale (old keys simply fall out by TTL — no scan needed, which keeps Redis cheap).
+ *
+ * Caching sits at the repository layer, *below* the router's auth checks, so every request
+ * is still authenticated and authorized — only the database round-trip is skipped. Optional
+ * methods are only exposed when the wrapped repository implements them, so the router's
+ * capability probing (`if (!repo.executeQuery) …`) keeps working.
+ *
+ * @param repo - The repository to wrap (already tenant-scoped by the caller, if applicable).
+ * @param options - Cache store, TTL, namespace, and optional bust flag.
+ * @returns A repository with the same surface as `repo`, plus caching.
+ */
+export declare function createCachingRepository<TRecord, TCreate, TUpdate>(repo: Repository<TRecord, TCreate, TUpdate>, options: CachingRepositoryOptions): Repository<TRecord, TCreate, TUpdate>;

package/dist/core/cache/createCachingRepository.js

@@ -0,0 +1,116 @@
+/** Produces a deterministic string for a value so equal queries hash to the same key. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+        .join(',')}}`;
+}
+/**
+ * Wraps a {@link Repository} with read-through caching and write invalidation.
+ *
+ * - **Reads** (`getOne`, `getMany`, `executeQuery`) are cached under a versioned key.
+ * - **Writes** (`createOne/Many`, `updateOne/Many`, `upsertOne`, `deleteOne/Many`) bump the
+ *   namespace version, so every previously-cached read for this resource/tenant is instantly
+ *   stale (old keys simply fall out by TTL — no scan needed, which keeps Redis cheap).
+ *
+ * Caching sits at the repository layer, *below* the router's auth checks, so every request
+ * is still authenticated and authorized — only the database round-trip is skipped. Optional
+ * methods are only exposed when the wrapped repository implements them, so the router's
+ * capability probing (`if (!repo.executeQuery) …`) keeps working.
+ *
+ * @param repo - The repository to wrap (already tenant-scoped by the caller, if applicable).
+ * @param options - Cache store, TTL, namespace, and optional bust flag.
+ * @returns A repository with the same surface as `repo`, plus caching.
+ */
+export function createCachingRepository(repo, options) {
+    const { store, ttlSeconds, namespace, bust = false } = options;
+    const versionKey = `${namespace}:__ver`;
+    const readVersion = async () => {
+        const v = await store.get(versionKey);
+        return typeof v === 'number' ? v : 0;
+    };
+    const bumpVersion = async () => {
+        await store.set(versionKey, (await readVersion()) + 1);
+    };
+    const keyFor = async (op, payload) => `${namespace}:v${await readVersion()}:${op}:${stableStringify(payload)}`;
+    const cachedRead = async (op, payload, run) => {
+        const key = await keyFor(op, payload);
+        // A cache-bust request skips the lookup and force-refreshes the entry.
+        if (!bust) {
+            const hit = await store.get(key);
+            if (hit !== undefined)
+                return hit;
+        }
+        const value = await run();
+        await store.set(key, value, ttlSeconds);
+        return value;
+    };
+    const wrapped = {
+        ...(repo.capabilities ? { capabilities: repo.capabilities } : {}),
+        getOne(id, getOptions) {
+            return cachedRead('getOne', { id, getOptions }, () => repo.getOne(id, getOptions));
+        },
+        getMany(listOptions) {
+            return cachedRead('getMany', listOptions ?? {}, () => repo.getMany(listOptions));
+        },
+        async createOne(data, createOptions) {
+            const result = await repo.createOne(data, createOptions);
+            await bumpVersion();
+            return result;
+        },
+        async createMany(data, createOptions) {
+            const result = await repo.createMany(data, createOptions);
+            await bumpVersion();
+            return result;
+        },
+        async updateOne(id, data) {
+            const result = await repo.updateOne(id, data);
+            await bumpVersion();
+            return result;
+        },
+        async deleteOne(id) {
+            const result = await repo.deleteOne(id);
+            await bumpVersion();
+            return result;
+        }
+    };
+    // Optional methods: only expose (and invalidate) when the underlying repository has them,
+    // so the router's `if (!repo.x)` capability checks behave identically to an uncached repo.
+    if (repo.executeQuery) {
+        wrapped.executeQuery = (query) => cachedRead('query', query, () => repo.executeQuery(query));
+    }
+    if (repo.updateMany) {
+        wrapped.updateMany = async (query, data) => {
+            const result = await repo.updateMany(query, data);
+            await bumpVersion();
+            return result;
+        };
+    }
+    if (repo.upsertOne) {
+        wrapped.upsertOne = async (id, data) => {
+            const result = await repo.upsertOne(id, data);
+            await bumpVersion();
+            return result;
+        };
+    }
+    if (repo.deleteMany) {
+        wrapped.deleteMany = async (query) => {
+            const result = await repo.deleteMany(query);
+            await bumpVersion();
+            return result;
+        };
+    }
+    if (repo.withScope) {
+        wrapped.withScope = (scope) => createCachingRepository(repo.withScope(scope), {
+            store,
+            ttlSeconds,
+            bust,
+            namespace: `${namespace}:${String(scope.value)}`
+        });
+    }
+    return wrapped;
+}

package/dist/core/cache/in-memory/InMemoryCacheStore.d.ts

@@ -0,0 +1,19 @@
+import type { CacheStore } from '../CacheStore.js';
+/**
+ * Default in-process {@link CacheStore} backed by a `Map`, with per-entry TTL.
+ *
+ * Suitable for single-process deployments and tests. For multi-instance deployments,
+ * inject a shared store (e.g. `RedisCacheStore`) instead so cache and invalidation are
+ * consistent across processes.
+ */
+export declare class InMemoryCacheStore implements CacheStore {
+    private readonly now;
+    private readonly map;
+    /**
+     * @param now - Clock function (ms epoch). Injectable for tests; defaults to `Date.now`.
+     */
+    constructor(now?: () => number);
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttlSeconds?: number): void;
+    delete(key: string): void;
+}

package/dist/core/cache/in-memory/InMemoryCacheStore.js

@@ -0,0 +1,34 @@
+/**
+ * Default in-process {@link CacheStore} backed by a `Map`, with per-entry TTL.
+ *
+ * Suitable for single-process deployments and tests. For multi-instance deployments,
+ * inject a shared store (e.g. `RedisCacheStore`) instead so cache and invalidation are
+ * consistent across processes.
+ */
+export class InMemoryCacheStore {
+    now;
+    map = new Map();
+    /**
+     * @param now - Clock function (ms epoch). Injectable for tests; defaults to `Date.now`.
+     */
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== null && entry.expiresAt <= this.now()) {
+            this.map.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlSeconds) {
+        const expiresAt = ttlSeconds && ttlSeconds > 0 ? this.now() + ttlSeconds * 1000 : null;
+        this.map.set(key, { value, expiresAt });
+    }
+    delete(key) {
+        this.map.delete(key);
+    }
+}

package/dist/core/cache/index.d.ts

@@ -0,0 +1,5 @@
+export * from './CacheStore.js';
+export * from './createCachingRepository.js';
+export * from './in-memory/InMemoryCacheStore.js';
+export * from './redis/RedisLikeClient.js';
+export * from './redis/RedisCacheStore.js';

package/dist/core/cache/index.js

@@ -0,0 +1,5 @@
+export * from './CacheStore.js';
+export * from './createCachingRepository.js';
+export * from './in-memory/InMemoryCacheStore.js';
+export * from './redis/RedisLikeClient.js';
+export * from './redis/RedisCacheStore.js';

package/dist/core/cache/redis/RedisCacheStore.d.ts

@@ -0,0 +1,28 @@
+import type { CacheStore } from '../CacheStore.js';
+import type { RedisLikeClient } from './RedisLikeClient.js';
+/**
+ * A {@link CacheStore} backed by Redis, for sharing cache and invalidation across processes
+ * and instances. Values are JSON-serialised; TTL maps to Redis `EX` (a TTL of `0`/omitted
+ * stores the key with no expiry).
+ *
+ * ```ts
+ * import { createClient } from 'redis'
+ * const client = createClient({ url: process.env.REDIS_URL })
+ * await client.connect()
+ * const store = new RedisCacheStore(client, { keyPrefix: 'halifax:' })
+ * ```
+ */
+export declare class RedisCacheStore implements CacheStore {
+    private readonly client;
+    private readonly prefix;
+    /**
+     * @param client - A connected Redis client matching {@link RedisLikeClient}.
+     * @param options - Optional `keyPrefix` prepended to every key (namespacing a shared Redis).
+     */
+    constructor(client: RedisLikeClient, options?: {
+        keyPrefix?: string;
+    });
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/core/cache/redis/RedisCacheStore.js

@@ -0,0 +1,42 @@
+/**
+ * A {@link CacheStore} backed by Redis, for sharing cache and invalidation across processes
+ * and instances. Values are JSON-serialised; TTL maps to Redis `EX` (a TTL of `0`/omitted
+ * stores the key with no expiry).
+ *
+ * ```ts
+ * import { createClient } from 'redis'
+ * const client = createClient({ url: process.env.REDIS_URL })
+ * await client.connect()
+ * const store = new RedisCacheStore(client, { keyPrefix: 'halifax:' })
+ * ```
+ */
+export class RedisCacheStore {
+    client;
+    prefix;
+    /**
+     * @param client - A connected Redis client matching {@link RedisLikeClient}.
+     * @param options - Optional `keyPrefix` prepended to every key (namespacing a shared Redis).
+     */
+    constructor(client, options = {}) {
+        this.client = client;
+        this.prefix = options.keyPrefix ?? '';
+    }
+    async get(key) {
+        const raw = await this.client.get(this.prefix + key);
+        if (raw === null || raw === undefined)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    async set(key, value, ttlSeconds) {
+        const payload = JSON.stringify(value);
+        if (ttlSeconds && ttlSeconds > 0) {
+            await this.client.set(this.prefix + key, payload, { EX: ttlSeconds });
+        }
+        else {
+            await this.client.set(this.prefix + key, payload);
+        }
+    }
+    async delete(key) {
+        await this.client.del(this.prefix + key);
+    }
+}

package/dist/core/cache/redis/RedisLikeClient.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The slice of a Redis client {@link RedisCacheStore} uses. It is intentionally tiny and
+ * duck-typed so any client matching it works (`redis` v4, etc.) without Halifax depending on
+ * a specific Redis package. (`redis` v4: `get` / `set(key, val, { EX })` / `del` all match.)
+ */
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        EX?: number;
+    }): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+}

package/dist/core/cache/redis/RedisLikeClient.js

@@ -0,0 +1 @@
+export {};

package/dist/core/crudRouter.d.ts

@@ -1,14 +1,80 @@
-import { type AuthStrategy } from '../auth/AuthStrategy.js';
+import { type AuthContext, type AuthStrategy } from '../auth/AuthStrategy.js';
+import { type CacheStore } from '../core/cache/index.js';
 import { type ResourceDefinition } from '../core/types.js';
-import type { HttpServer } from '../core/types.js';
+import type { HttpRequest, HttpServer } from '../core/types.js';
+/** Context handed to {@link TenantOptions.resolveId} for the current request. */
+export interface TenantResolveContext {
+    /** The resolved authentication context for the request. */
+    auth: AuthContext;
+    /** The incoming HTTP request. */
+    req: HttpRequest;
+    /** The resource being accessed. */
+    resource: ResourceDefinition;
+}
+/**
+ * Configures multi-tenant isolation for the whole API. When set, every resource that
+ * is tenant-scoped (see {@link ResourceDefinition.tenant}) has all of its reads, writes,
+ * and bulk operations confined to the tenant value returned by {@link TenantOptions.resolveId}.
+ */
+export interface TenantOptions {
+    /**
+     * Resolve the tenant key the current caller is bound to (e.g. their company id),
+     * derived from the authenticated session/token — never from client-supplied input.
+     * Return `null`/`undefined` to signal "no tenant"; combined with {@link TenantOptions.strict}
+     * this either denies the request (default) or serves it unscoped.
+     * @param ctx - The auth context, request, and resource being accessed.
+     * @returns The tenant key, or null/undefined when none applies.
+     */
+    resolveId: (ctx: TenantResolveContext) => unknown | Promise<unknown>;
+    /**
+     * Default tenant column name used to auto-detect scoping: any resource that has a
+     * field with this name (and no explicit {@link ResourceDefinition.tenant}) is scoped
+     * on it. Defaults to `'tenantId'`.
+     */
+    field?: string;
+    /**
+     * Fail-closed switch. When `true` (the default), a tenant-scoped resource whose
+     * {@link TenantOptions.resolveId} returns no value rejects the request with 403 rather
+     * than serving unscoped data. Only set to `false` if you deliberately allow
+     * cross-tenant ("god mode") access for callers with no tenant.
+     */
+    strict?: boolean;
+}
 /** Options for {@link registerCrudApi} / {@link createExpressCrudRouter}. */
 export interface CrudApiOptions {
     /** Auth strategy used for all routes. Defaults to {@link AllowAllAuthStrategy}. */
     authStrategy?: AuthStrategy;
-    /** Path segment for the query-builder POST route (default: `'query-builder'`). */
+    /** Multi-tenant isolation config. When omitted, no tenant scoping is applied. */
+    tenant?: TenantOptions;
+    /** Path segment for the query-builder POST route (default: `'query'`). */
     queryBuilderPath?: string;
-    /** Path for the query-builder preview route (default: `'/query-builder/preview'`). */
-    previewQueryBuilderPath?: string;
+    /**
+     * Wrap every success response body under a single key (e.g. `'data'` → `{ "data": <body> }`)
+     * for all resources. Per-resource {@link ResourceDefinition.envelope} takes precedence.
+     * Error responses are never enveloped. Omit (or set `null`/`''`) for bare bodies — the
+     * default, and backward compatible.
+     */
+    envelope?: string | null;
+    /**
+     * API-wide read-through caching. Provide a `store` (defaults to an in-process
+     * {@link InMemoryCacheStore}) and/or a default `ttlSeconds` applied to every resource that
+     * doesn't set its own {@link ResourceDefinition.cache}. Per-resource config takes precedence.
+     */
+    cache?: {
+        /** Backing cache store shared by all resources. Defaults to an in-process store. */
+        store?: CacheStore;
+        /**
+         * Default TTL (seconds) applied to all resources lacking their own cache config.
+         * `0` means never expire; omit to leave caching off by default.
+         */
+        ttlSeconds?: number;
+        /**
+         * Request header that force-refreshes the cache for that request. Defaults to
+         * `'Cache-Control'` (busts when the value contains `no-cache`/`no-store`). Set a custom
+         * header name to bust whenever that header is present with any value.
+         */
+        bustHeader?: string;
+    };
 }
 /**
  * Converts any thrown value to a structured `{ status, code, message, details }` object.
@@ -26,11 +92,9 @@ export declare function normalizeError(error: unknown): {
  * Registers all CRUD routes for every resource on the given HTTP server.
  *
  * Routes are controlled by `resource.permissions` merged with {@link defaultCrudPermissions}.
- * A global query-builder preview endpoint is also registered at `previewQueryBuilderPath`.
  *
  * @param server - The HTTP server adapter to register routes on (e.g. {@link ExpressHttpServer}).
  * @param resources - Resource definitions to wire up as CRUD endpoints.
- * @param options - Auth strategy, query-builder path overrides, and preview path overrides.
+ * @param options - Auth strategy and query-builder path overrides.
  */
 export declare function registerCrudApi(server: HttpServer, resources: ResourceDefinition[], options?: CrudApiOptions): void;
-//# sourceMappingURL=crudRouter.d.ts.map