@dereekb/firebase-server 13.2.2 → 13.3.1

package/src/lib/nest/middleware/appcheck.middleware.d.ts

@@ -1,28 +1,58 @@
 import { type NestMiddleware } from '@nestjs/common';
 import { type Request } from 'firebase-functions/v2/https';
 import { type Response } from 'express';
-import { type Maybe } from '@dereekb/util';
-import { GlobalRoutePrefixConfig } from './globalprefix';
+import { type SlashPath, type Maybe } from '@dereekb/util';
+/**
+ * Configuration for `FirebaseAppCheckMiddleware`.
+ *
+ * Controls which paths are excluded from AppCheck verification at the
+ * middleware consumer level via `.forRoutes()` and `.exclude()`.
+ */
+export declare abstract class FirebaseAppCheckMiddlewareConfig {
+    /**
+     * Whether to protect webhook paths under the global route prefix.
+     *
+     * When false (default), paths like `/api/webhook/*` are excluded from AppCheck.
+     *
+     * Defaults to false, otherwise webhook calls would be rejected.
+     */
+    readonly protectGlobalWebhooksPath?: boolean;
+    /**
+     * Whether to protect paths outside the global route prefix.
+     *
+     * When false (default), only paths under the global prefix (e.g., `/api/*`) are protected.
+     * Paths like `/.well-known/*` or `/oidc/*` are not checked.
+     *
+     * Defaults to false, otherwise non-global paths would be rejected.
+     */
+    readonly protectNonGlobalPaths?: boolean;
+    /**
+     * Additional path patterns to protect with AppCheck verification.
+     *
+     * Each entry is a path prefix (e.g., '/health') that will be added
+     * to the protected routes. The global route prefix itself (e.g., '/api')
+     * is not allowed as a value since it is always protected.
+     *
+     * Defaults to an empty array.
+     */
+    readonly protectedPaths?: SlashPath[];
+}
 /**
  * Middleware that verifies the X-Firebase-AppCheck header using admin.
  *
- * It ignores all webhook paths by default.
+ * Route-level exclusions (webhooks, non-global paths, custom paths) are
+ * handled by `ConfigureFirebaseAppCheckMiddlewareModule` via `.forRoutes()`
+ * and `.exclude()`. This middleware only checks the per-request `skipAppCheck`
+ * flag (set by the `@SkipAppCheck()` decorator) at runtime.
  */
 export declare class FirebaseAppCheckMiddleware implements NestMiddleware {
-    private readonly globalRoutePrefixConfig?;
     private readonly logger;
-    private readonly _ignoredWebhookPath;
-    constructor(globalRoutePrefixConfig?: Maybe<GlobalRoutePrefixConfig>);
-    use(req: Request, res: Response, next: (error?: Error | unknown) => void): Promise<void>;
-    isIgnoredRequest(req: Request): boolean;
-    isIgnoredPath(path: string): boolean;
+    use(req: Request, _res: Response, next: (error?: Error | unknown) => void): Promise<void>;
 }
 /**
- * Verifies the AppCheck parameter. If it fails, a value is returned.
+ * Verifies the `X-Firebase-AppCheck` header using Firebase Admin AppCheck.
  *
- * @param req
- * @param res
- * @param next
- * @returns
+ * @param req - The incoming request to verify.
+ * @returns A {@link ForbiddenException} if verification fails, or `undefined` if it passes.
  */
 export declare function verifyAppCheckInRequest(req: Request): Promise<Maybe<Error>>;

package/src/lib/nest/middleware/appcheck.module.d.ts

@@ -1,8 +1,17 @@
 import { type MiddlewareConsumer } from '@nestjs/common';
+import { FirebaseAppCheckMiddlewareConfig } from './appcheck.middleware';
+import { GlobalRoutePrefixConfig } from './globalprefix';
 /**
- * Convenience class that mirrors the ConfigureAppCheckMiddlewareModule class in @dereekb/nestjs, but for Firebase apps.
+ * Middleware module that configures `FirebaseAppCheckMiddleware` route coverage
+ * based on `FirebaseAppCheckMiddlewareConfig` and `GlobalRoutePrefixConfig`.
+ *
+ * Uses `.forRoutes()` and `.exclude()` to control which paths require AppCheck,
+ * so the middleware itself only needs to handle the per-request `skipAppCheck` flag.
  */
 export declare class ConfigureFirebaseAppCheckMiddlewareModule {
+    private readonly globalRoutePrefixConfig?;
+    private readonly config?;
     private readonly logger;
+    constructor(globalRoutePrefixConfig?: GlobalRoutePrefixConfig | undefined, config?: FirebaseAppCheckMiddlewareConfig | undefined);
     configure(consumer: MiddlewareConsumer): void;
 }

package/src/lib/nest/middleware/globalprefix.d.ts

@@ -1,7 +1,35 @@
-import { type Maybe } from '@dereekb/util';
+import { type MaybeSo, type Maybe } from '@dereekb/util';
+import { type INestApplication } from '@nestjs/common';
 /**
- * Can be injected to retrieve information about the global prefix configured for the app.
+ * Configuration options accepted by NestJS `setGlobalPrefix()`, with all properties made required (non-optional).
+ *
+ * Derived from the second parameter of {@link INestApplication.setGlobalPrefix}.
  */
-export declare abstract class GlobalRoutePrefixConfig {
+export type NestGlobalRoutePrefixConfig = MaybeSo<Parameters<INestApplication['setGlobalPrefix']>[1]>;
+/**
+ * Route exclusion patterns from {@link NestGlobalRoutePrefixConfig}.
+ *
+ * Used to specify routes that should bypass the global prefix (e.g., webhook endpoints, health checks).
+ */
+export type NestGlobalRoutePrefixConfigExclude = NestGlobalRoutePrefixConfig['exclude'];
+/**
+ * Injectable configuration that exposes the global route prefix and exclusion rules for the NestJS application.
+ *
+ * Provided at the module level so that middleware, guards, and other components can read the prefix
+ * without coupling to the bootstrap code. Used by {@link buildNestServerRootModule} to wire up the prefix
+ * consistently across production and test environments.
+ *
+ * @see https://docs.nestjs.com/faq/global-prefix
+ */
+export declare abstract class GlobalRoutePrefixConfig implements NestGlobalRoutePrefixConfig {
+    /**
+     * The global API route prefix applied to all controllers (e.g., `"api"`).
+     *
+     * When set, all controller routes are mounted under this prefix unless explicitly excluded.
+     */
     readonly globalApiRoutePrefix?: Maybe<string>;
+    /**
+     * Routes excluded from the global prefix, such as webhook endpoints or health checks.
+     */
+    readonly exclude?: NestGlobalRoutePrefixConfig['exclude'];
 }

package/src/lib/nest/middleware/index.d.ts

@@ -1,6 +1,7 @@
 export * from './appcheck';
+export * from './globalprefix';
 export * from './appcheck.middleware';
 export * from './appcheck.module';
 export * from './appcheck.decorator';
 export * from './rawbody.middleware';
-export * from './webhook';
+export * from './webhook.module';

package/src/lib/nest/middleware/rawbody.middleware.d.ts

@@ -1,6 +1,12 @@
 import { type NestMiddleware } from '@nestjs/common';
 import { type Request } from 'firebase-functions/v2/https';
 import { type Response } from 'express';
+/**
+ * Middleware that replaces `req.body` with `req.rawBody` for routes that need the unparsed request body.
+ *
+ * Used by webhook routes to support signature verification (e.g., Stripe, Mailgun) where
+ * the raw body must match the signed payload exactly.
+ */
 export declare class FirebaseRawBodyMiddleware implements NestMiddleware {
     use(req: Request, res: Response, next: () => void): void;
 }

package/src/lib/nest/model/call.model.function.d.ts

@@ -4,28 +4,94 @@ import { type OnCallWithAuthAwareNestContext, type OnCallWithAuthAwareNestRequir
 import { type AssertModelCrudRequestFunctionContextCrudType, type AssertModelCrudRequestFunction } from './crud.assert.function';
 import { type NestContextCallableRequest } from '../function/nest';
 import { type OnCallApiDetailsRef } from './api.details';
+/**
+ * Maps CRUD call type strings (e.g., 'create', 'read', 'update', 'delete') to their
+ * corresponding handler functions.
+ *
+ * Used by {@link onCallModel} to dispatch incoming requests to the correct CRUD handler.
+ */
 export type OnCallModelMap = {
     readonly [call: OnCallFunctionType]: OnCallWithNestContext<any, OnCallTypedModelParams>;
 };
+/**
+ * Configuration for {@link onCallModel}.
+ *
+ * Allows injecting a pre-assertion hook that runs before any CRUD handler is invoked,
+ * useful for cross-cutting concerns like rate limiting or feature flags.
+ */
 export interface OnCallModelConfig {
+    /**
+     * Optional assertion function invoked before dispatching to the CRUD handler.
+     * Throw to reject the request.
+     */
     readonly preAssert?: AssertModelCrudRequestFunction<unknown, OnCallTypedModelParams>;
 }
 /**
- * Creates a OnCallWithAuthorizedNestContext function for creating a model.
+ * Top-level factory that creates a single callable function dispatching to CRUD operations.
  *
- * @param map
- * @returns
+ * Incoming requests carry a `call` field (e.g., 'create', 'read') that selects the
+ * appropriate handler from the provided map. API details from all handlers are aggregated
+ * for MCP tool generation.
+ *
+ * @param map - Maps call type strings to their CRUD handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function that dispatches to the correct CRUD handler, with aggregated {@link OnCallApiDetailsRef._apiDetails}.
+ *
+ * @example
+ * ```typescript
+ * const callModel = onCallModel({
+ *   create: onCallCreateModel({ profile: createProfile, guestbook: createGuestbook }),
+ *   read: onCallReadModel({ profile: readProfile }),
+ *   update: onCallUpdateModel({ profile: updateProfile }),
+ *   delete: onCallDeleteModel({ guestbook: deleteGuestbook })
+ * });
+ * ```
  */
 export declare function onCallModel(map: OnCallModelMap, config?: OnCallModelConfig): OnCallWithNestContext<unknown, OnCallTypedModelParams> & OnCallApiDetailsRef;
+/**
+ * Creates a bad-request error indicating the `call` field was missing from the request payload.
+ */
 export declare function onCallModelMissingCallTypeError(): import("firebase-functions/https").HttpsError;
+/**
+ * Creates a bad-request error indicating the provided `call` type is not recognized.
+ */
 export declare function onCallModelUnknownCallTypeError(call: OnCallFunctionType): import("firebase-functions/https").HttpsError;
+/**
+ * Maps Firestore model type strings to their handler functions for a single CRUD operation.
+ *
+ * Each handler receives the NestContext request and an optional specifier, and may
+ * declare whether it requires authentication via {@link OnCallWithAuthAwareNestRequireAuthRef}.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining which model type keys are valid.
+ */
 export type OnCallWithCallTypeModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
     readonly [K in FirestoreModelTypes<T>]?: ((request: NestContextCallableRequest<N, any> & ModelFirebaseCrudFunctionSpecifierRef) => PromiseOrValue<any>) & OnCallWithAuthAwareNestRequireAuthRef;
 };
+/**
+ * Internal configuration for {@link _onCallWithCallTypeFunction}.
+ *
+ * Shared by the CRUD-specific factories (create, read, update, delete) to avoid
+ * duplicating dispatch and assertion logic.
+ *
+ * @typeParam N - The NestJS context type.
+ */
 export interface OnCallWithCallTypeModelConfig<N> {
+    /** The call type string (e.g., 'create', 'read') passed through to assertions. */
     readonly callType: string;
+    /** The CRUD category used by {@link AssertModelCrudRequestFunction}. */
     readonly crudType: AssertModelCrudRequestFunctionContextCrudType;
+    /** Optional assertion run before the model handler; throw to reject. */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallTypedModelParams>;
+    /** Error factory invoked when the requested model type has no handler in the map. */
     readonly throwOnUnknownModelType: (modelType: FirestoreModelType) => Error;
 }
+/**
+ * Internal factory used by the CRUD-specific wrappers ({@link onCallCreateModel}, {@link onCallReadModel}, etc.).
+ *
+ * Dispatches to the correct model-type handler from the map, enforces auth requirements,
+ * runs pre-assertions, and aggregates API details from all handlers for MCP introspection.
+ *
+ * @internal Not intended for direct use outside the model CRUD module.
+ */
 export declare function _onCallWithCallTypeFunction<N>(map: OnCallWithCallTypeModelMap<N>, config: OnCallWithCallTypeModelConfig<N>): OnCallWithAuthAwareNestContext<N, OnCallTypedModelParams, unknown> & OnCallApiDetailsRef;

package/src/lib/nest/model/create.model.function.d.ts

@@ -3,21 +3,87 @@ import { type FirestoreModelType, type FirestoreModelIdentity, type FirestoreMod
 import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
 import { type NestContextCallableRequestWithOptionalAuth, type NestContextCallableRequestWithAuth } from '../function/nest';
 import { type AssertModelCrudRequestFunction } from './crud.assert.function';
+/**
+ * Request type for model create handlers that require authentication.
+ *
+ * Combines the authenticated NestJS context with the optional CRUD function specifier,
+ * allowing handlers to access both auth data and identify sub-operations.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the create operation.
+ */
 export type OnCallCreateModelRequest<N, I = unknown> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model create handler function that requires an authenticated caller.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the create operation.
+ * @typeParam O - The output type returned on success.
+ */
 export type OnCallCreateModelFunctionWithAuth<N, I = unknown, O = unknown> = ((request: OnCallCreateModelRequest<N, I>) => PromiseOrValue<O>) & {
     readonly _requiresAuth?: true;
 };
+/**
+ * Request type for model create handlers that allow unauthenticated callers.
+ */
 export type OnCallCreateModelRequestWithOptionalAuth<N, I = unknown> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model create handler function that does not require authentication.
+ *
+ * Useful for public-facing creation endpoints such as anonymous sign-up flows.
+ */
 export type OnCallCreateModelFunctionWithOptionalAuth<N, I = unknown, O = unknown> = ((request: OnCallCreateModelRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
     readonly _requireAuth: false;
 };
+/**
+ * Standard model create handler requiring auth (the common case).
+ */
 export type OnCallCreateModelFunction<N, I = unknown, O extends OnCallCreateModelResult = OnCallCreateModelResult> = OnCallCreateModelFunctionWithAuth<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Union of auth-required and optional-auth create handlers.
+ *
+ * Used in {@link OnCallCreateModelMap} so both variants can be registered side by side.
+ */
 export type OnCallCreateModelFunctionAuthAware<N, I = unknown, O extends OnCallCreateModelResult = OnCallCreateModelResult> = OnCallCreateModelFunction<N, I, O> | OnCallCreateModelFunctionWithOptionalAuth<N, I, O>;
+/**
+ * Maps Firestore model type strings to their create handler functions.
+ *
+ * Pass this map to {@link onCallCreateModel} to register all model types
+ * that support creation through the call model system.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining valid model type keys.
+ */
 export type OnCallCreateModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
     readonly [K in FirestoreModelTypes<T>]?: OnCallCreateModelFunctionAuthAware<N, any, OnCallCreateModelResult>;
 };
+/**
+ * Configuration for {@link onCallCreateModel}.
+ */
 export interface OnCallCreateModelConfig<N> {
+    /** Optional assertion run before the create handler; throw to reject. */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallCreateModelParams>;
 }
+/**
+ * Factory that creates a callable function handling model creation for multiple model types.
+ *
+ * Dispatches to the correct handler based on the `modelType` field in the request,
+ * enforces auth requirements per handler, and aggregates API details for MCP introspection.
+ *
+ * @param map - Maps model type strings to their create handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'create' CRUD operation.
+ *
+ * @example
+ * ```typescript
+ * const createHandler = onCallCreateModel<DemoNestContext>({
+ *   profile: createProfile,
+ *   guestbook: createGuestbook
+ * });
+ * ```
+ */
 export declare function onCallCreateModel<N>(map: OnCallCreateModelMap<N>, config?: OnCallCreateModelConfig<N>): OnCallWithNestContext<N, OnCallCreateModelParams, OnCallCreateModelResult>;
+/**
+ * Creates a bad-request error indicating the requested model type is not valid for creation.
+ */
 export declare function createModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/model/crud.assert.function.d.ts

@@ -1,14 +1,40 @@
 import { type Maybe } from '@dereekb/util';
 import { type NestContextCallableRequest } from '../function/nest';
 import { type OnCallFunctionType } from '@dereekb/firebase';
+/**
+ * Discriminator for the category of CRUD operation being asserted.
+ *
+ * Used by {@link AssertModelCrudRequestFunction} to let assertions branch on operation type,
+ * enabling cross-cutting rules like "block all deletes for archived models."
+ */
 export type AssertModelCrudRequestFunctionContextCrudType = 'call' | 'create' | 'read' | 'update' | 'delete';
+/**
+ * Context passed to a {@link AssertModelCrudRequestFunction} before a CRUD handler executes.
+ *
+ * Provides the original request alongside routing metadata (call type, model type, specifier)
+ * so assertions can make fine-grained decisions without parsing the raw request.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type of the request.
+ */
 export interface AssertModelCrudRequestFunctionContext<N, I = unknown> {
+    /** The original callable request including the NestJS context and caller data. */
     readonly request: NestContextCallableRequest<N, I>;
+    /** The CRUD call type string (e.g., 'create', 'read'). */
     readonly call: OnCallFunctionType;
+    /** The Firestore model type being targeted (e.g., 'profile', 'guestbook'). */
     readonly modelType: string;
+    /** The optional sub-operation specifier (e.g., 'username', 'fromUpload'). */
     readonly specifier: Maybe<string>;
 }
 /**
- * Function that asserts something given the input request.
+ * Pre-assertion hook invoked before a model CRUD handler executes.
+ *
+ * Throw an error to reject the request. Useful for cross-cutting concerns such as
+ * feature flags, rate limiting, or role-based access restrictions that apply
+ * across multiple model types or operations.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type of the request.
  */
 export type AssertModelCrudRequestFunction<N, I = unknown> = (context: AssertModelCrudRequestFunctionContext<N, I>) => void;

package/src/lib/nest/model/delete.model.function.d.ts

@@ -3,21 +3,76 @@ import { type FirestoreModelType, type FirestoreModelIdentity, type FirestoreMod
 import { type NestContextCallableRequestWithOptionalAuth, type NestContextCallableRequestWithAuth } from '../function/nest';
 import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
 import { type AssertModelCrudRequestFunction } from './crud.assert.function';
+/**
+ * Request type for model delete handlers that require authentication.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the delete operation.
+ */
 export type OnCallDeleteModelRequest<N, I = unknown> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model delete handler function that requires an authenticated caller.
+ */
 export type OnCallDeleteModelFunctionWithAuth<N, I = unknown, O = void> = ((request: OnCallDeleteModelRequest<N, I>) => PromiseOrValue<O>) & {
     readonly _requiresAuth?: true;
 };
+/**
+ * Request type for model delete handlers that allow unauthenticated callers.
+ */
 export type OnCallDeleteModelRequestWithOptionalAuth<N, I = unknown> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model delete handler function that does not require authentication.
+ */
 export type OnCallDeleteModelFunctionWithOptionalAuth<N, I = unknown, O = void> = ((request: OnCallDeleteModelRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
     readonly _requireAuth: false;
 };
+/**
+ * Standard model delete handler requiring auth (the common case).
+ */
 export type OnCallDeleteModelFunction<N, I = unknown, O = void> = OnCallDeleteModelFunctionWithAuth<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Union of auth-required and optional-auth delete handlers.
+ */
 export type OnCallDeleteModelFunctionAuthAware<N, I = unknown, O = void> = OnCallDeleteModelFunction<N, I, O> | OnCallDeleteModelFunctionWithOptionalAuth<N, I, O>;
+/**
+ * Maps Firestore model type strings to their delete handler functions.
+ *
+ * Pass this map to {@link onCallDeleteModel} to register all model types
+ * that support deletion through the call model system.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining valid model type keys.
+ */
 export type OnCallDeleteModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
     readonly [K in FirestoreModelTypes<T>]?: OnCallDeleteModelFunctionAuthAware<N, any, any>;
 };
+/**
+ * Configuration for {@link onCallDeleteModel}.
+ */
 export interface OnCallDeleteModelConfig<N> {
+    /** Optional assertion run before the delete handler; throw to reject. */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallDeleteModelParams>;
 }
+/**
+ * Factory that creates a callable function handling model deletion for multiple model types.
+ *
+ * Dispatches to the correct handler based on the `modelType` field in the request,
+ * enforces auth requirements per handler, and aggregates API details for MCP introspection.
+ *
+ * @param map - Maps model type strings to their delete handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'delete' CRUD operation.
+ *
+ * @example
+ * ```typescript
+ * const deleteHandler = onCallDeleteModel<DemoNestContext>({
+ *   guestbook: deleteGuestbook,
+ *   guestbookEntry: deleteGuestbookEntry
+ * });
+ * ```
+ */
 export declare function onCallDeleteModel<N>(map: OnCallDeleteModelMap<N>, config?: OnCallDeleteModelConfig<N>): OnCallWithNestContext<N, OnCallDeleteModelParams, unknown>;
+/**
+ * Creates a bad-request error indicating the requested model type is not valid for deletion.
+ */
 export declare function deleteModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/model/permission.error.d.ts

@@ -1,3 +1,18 @@
 import { type FirebaseDoesNotExistErrorContextErrorFunction, type FirebasePermissionErrorContextErrorFunction } from '@dereekb/firebase';
+/**
+ * NestJS-compatible error factory for when a Firestore document does not exist.
+ *
+ * Returns a "model not available" HTTP error including the document key and model type,
+ * which the client can use to display a meaningful "not found" message. Intended to be
+ * passed to Firebase permission/existence checking utilities as the
+ * {@link FirebaseDoesNotExistErrorContextErrorFunction} callback.
+ */
 export declare const nestFirebaseDoesNotExistError: FirebaseDoesNotExistErrorContextErrorFunction;
+/**
+ * NestJS-compatible error factory for when the caller lacks required roles on a Firestore document.
+ *
+ * Returns a "forbidden" HTTP error including the document key, model type, and the roles
+ * that were required but not granted. Intended to be passed to Firebase permission checking
+ * utilities as the {@link FirebasePermissionErrorContextErrorFunction} callback.
+ */
 export declare const nestFirebaseForbiddenPermissionError: FirebasePermissionErrorContextErrorFunction;

package/src/lib/nest/model/read.model.function.d.ts

@@ -3,21 +3,78 @@ import { type FirestoreModelType, type FirestoreModelIdentity, type FirestoreMod
 import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
 import { type NestContextCallableRequestWithAuth, type NestContextCallableRequestWithOptionalAuth } from '../function/nest';
 import { type AssertModelCrudRequestFunction } from './crud.assert.function';
+/**
+ * Request type for model read handlers that require authentication.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the read operation.
+ */
 export type OnCallReadModelRequest<N, I = unknown> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model read handler function that requires an authenticated caller.
+ */
 export type OnCallReadModelFunctionWithAuth<N, I = unknown, O = unknown> = ((request: OnCallReadModelRequest<N, I>) => PromiseOrValue<O>) & {
     readonly _requiresAuth?: true;
 };
+/**
+ * Request type for model read handlers that allow unauthenticated callers.
+ */
 export type OnCallReadModelRequestWithOptionalAuth<N, I = unknown> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model read handler function that does not require authentication.
+ *
+ * Useful for public-facing read endpoints such as listing public content.
+ */
 export type OnCallReadModelFunctionWithOptionalAuth<N, I = unknown, O = unknown> = ((request: OnCallReadModelRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
     readonly _requireAuth: false;
 };
+/**
+ * Standard model read handler requiring auth (the common case).
+ */
 export type OnCallReadModelFunction<N, I = unknown, O = unknown> = OnCallReadModelFunctionWithAuth<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Union of auth-required and optional-auth read handlers.
+ */
 export type OnCallReadModelFunctionAuthAware<N, I = unknown, O = unknown> = OnCallReadModelFunction<N, I, O> | OnCallReadModelFunctionWithOptionalAuth<N, I, O>;
+/**
+ * Maps Firestore model type strings to their read handler functions.
+ *
+ * Pass this map to {@link onCallReadModel} to register all model types
+ * that support reading through the call model system.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining valid model type keys.
+ */
 export type OnCallReadModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
     readonly [K in FirestoreModelTypes<T>]?: OnCallReadModelFunctionAuthAware<N, any, any>;
 };
+/**
+ * Configuration for {@link onCallReadModel}.
+ */
 export interface OnCallReadModelConfig<N> {
+    /** Optional assertion run before the read handler; throw to reject. */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallReadModelParams>;
 }
+/**
+ * Factory that creates a callable function handling model reads for multiple model types.
+ *
+ * Dispatches to the correct handler based on the `modelType` field in the request,
+ * enforces auth requirements per handler, and aggregates API details for MCP introspection.
+ *
+ * @param map - Maps model type strings to their read handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'read' CRUD operation.
+ *
+ * @example
+ * ```typescript
+ * const readHandler = onCallReadModel<DemoNestContext>({
+ *   profile: readProfile,
+ *   guestbook: readGuestbook
+ * });
+ * ```
+ */
 export declare function onCallReadModel<N>(map: OnCallReadModelMap<N>, config?: OnCallReadModelConfig<N>): OnCallWithNestContext<N, OnCallReadModelParams, unknown>;
+/**
+ * Creates a bad-request error indicating the requested model type is not valid for reading.
+ */
 export declare function readModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/model/specifier.function.d.ts

@@ -3,21 +3,78 @@ import { type Maybe, type PromiseOrValue } from '@dereekb/util';
 import { type NestContextCallableRequestWithOptionalAuth, type NestContextCallableRequestWithAuth } from '../function/nest';
 import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
 import { type OnCallApiDetailsRef } from './api.details';
+/**
+ * Request type for specifier-dispatched handlers that require authentication.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type.
+ */
 export type OnCallSpecifierHandlerNestContextRequest<N, I = unknown> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A specifier handler function that requires an authenticated caller.
+ */
 export type OnCallSpecifierHandlerFunctionWithAuth<N, I = unknown, O = unknown> = ((request: OnCallSpecifierHandlerNestContextRequest<N, I>) => PromiseOrValue<O>) & {
     readonly _requiresAuth?: true;
 };
+/**
+ * Request type for specifier-dispatched handlers that allow unauthenticated callers.
+ */
 export type OnCallSpecifierHandlerNestContextRequestWithOptionalAuth<N, I = unknown> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A specifier handler function that does not require authentication.
+ */
 export type OnCallSpecifierHandlerFunctionWithOptionalAuth<N, I = unknown, O = unknown> = ((request: OnCallSpecifierHandlerNestContextRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
     readonly _requireAuth: false;
 };
+/**
+ * Union of auth-required and optional-auth specifier handler functions.
+ *
+ * Each specifier handler within an {@link OnCallSpecifierHandlerConfig} may independently
+ * declare its own auth requirements.
+ */
 export type OnCallSpecifierHandlerFunction<N, I = unknown, O = void> = (OnCallSpecifierHandlerFunctionWithAuth<N, I, O> | OnCallSpecifierHandlerFunctionWithOptionalAuth<N, I, O>) & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Configuration object mapping specifier keys to handler functions.
+ *
+ * The special key `_` is the default handler invoked when no specifier (or the default
+ * specifier) is provided. Other keys correspond to named sub-operations on the same
+ * model type, allowing a single CRUD slot to support multiple behaviors.
+ *
+ * @typeParam N - The NestJS context type.
+ */
 export type OnCallSpecifierHandlerConfig<N> = {
     /**
-     * The default handler function.
+     * The default handler function, invoked when the specifier is `_` or omitted.
      */
     readonly _?: Maybe<OnCallSpecifierHandlerFunction<N, any, any>>;
     readonly [key: string]: Maybe<OnCallSpecifierHandlerFunction<N, any, any>>;
 };
+/**
+ * Factory that creates a handler dispatching to sub-operations based on a specifier string.
+ *
+ * Use this when a single model type + CRUD operation needs to support multiple behaviors
+ * (e.g., a profile update that can either update the default fields or change a username).
+ * The resulting function is marked `_requireAuth = false` because auth enforcement is
+ * delegated to each individual specifier handler.
+ *
+ * API details from all specifier handlers are aggregated into
+ * {@link OnCallSpecifierApiDetails} for MCP introspection.
+ *
+ * @param config - Maps specifier keys to their handler functions.
+ * @returns A callable function that dispatches by specifier, with aggregated API details.
+ *
+ * @example
+ * ```typescript
+ * const updateProfile = onCallSpecifierHandler<DemoNestContext>({
+ *   _: updateProfileDefault,
+ *   username: updateProfileUsername,
+ *   fromUpload: updateProfileFromUpload
+ * });
+ * ```
+ */
 export declare function onCallSpecifierHandler<N, I = any, O = any>(config: OnCallSpecifierHandlerConfig<N>): OnCallWithNestContext<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef & OnCallApiDetailsRef;
+/**
+ * Creates a bad-request error indicating the provided specifier is not recognized
+ * by the current model CRUD handler.
+ */
 export declare function unknownModelCrudFunctionSpecifierError(specifier: ModelFirebaseCrudFunctionSpecifier): import("firebase-functions/https").HttpsError;