@dereekb/firebase-server 13.6.17 → 13.7.0

package/src/lib/nest/controller/model/model.api.get.service.d.ts

@@ -0,0 +1,73 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
+import { type INestApplicationContext } from '@nestjs/common';
+import { ModelApiDispatchConfig } from './model.api.dispatch';
+import { type FirebaseServerAuthData } from '../auth.context.server';
+/**
+ * Maximum number of keys allowed in a multi-read request.
+ */
+export declare const MAX_MODEL_ACCESS_MULTI_READ_KEYS = 50;
+/**
+ * Result of a single document access read.
+ */
+export interface ModelAccessReadResult {
+    readonly key: FirestoreModelKey;
+    readonly data: unknown;
+}
+/**
+ * Result of a multi-document access read.
+ */
+export interface ModelAccessMultiReadResult {
+    readonly results: ModelAccessReadResult[];
+    readonly errors: ModelAccessReadError[];
+}
+/**
+ * Error for a single document in a multi-read request.
+ */
+export interface ModelAccessReadError {
+    readonly key: FirestoreModelKey;
+    readonly message: string;
+    readonly code?: string;
+}
+/**
+ * Service for direct document reads using the `useModel()` permission-checking pattern.
+ *
+ * Unlike the dispatch service (which goes through callModel handlers), this service
+ * reads documents directly from Firestore via {@link AbstractFirebaseNestContext.useModel},
+ * enforcing `'read'` role permissions per document.
+ */
+export declare class ModelApiGetService {
+    private readonly _nestContext;
+    constructor(config: ModelApiDispatchConfig, nestApplication: INestApplicationContext);
+    /**
+     * Reads a single document by model type and key with permission checking.
+     *
+     * @param modelType - The Firestore model type string (e.g., 'profile', 'guestbook').
+     * @param key - The full Firestore model key (e.g., 'pr/abc123').
+     * @param auth - The authenticated user's auth data from the request.
+     * @returns The document key and data.
+     * @throws Permission or not-found errors from useModel.
+     */
+    readDocument(modelType: FirestoreModelType, key: FirestoreModelKey, auth: Maybe<FirebaseServerAuthData>): Promise<ModelAccessReadResult>;
+    /**
+     * Reads multiple documents of the same model type with permission checking.
+     *
+     * Individual document errors (not-found, forbidden) are captured per-key
+     * and returned in the errors array rather than throwing.
+     *
+     * @param modelType - The Firestore model type string.
+     * @param keys - Array of Firestore model keys (max {@link MAX_MODEL_ACCESS_MULTI_READ_KEYS}).
+     * @param auth - The authenticated user's auth data from the request.
+     * @returns Results and errors for each requested key.
+     */
+    readDocuments(modelType: FirestoreModelType, keys: FirestoreModelKey[], auth: Maybe<FirebaseServerAuthData>): Promise<ModelAccessMultiReadResult>;
+    /**
+     * Builds an {@link AuthDataRef} compatible with `useModel()` from the HTTP request auth.
+     *
+     * Uses the same synthetic auth pattern as {@link ModelApiDispatchService.dispatch}.
+     *
+     * @param auth - The Firebase server auth data from the HTTP request, or undefined for unauthenticated requests.
+     * @returns An object containing a synthetic {@link AuthData} for use with `useModel()`, or undefined auth.
+     */
+    private _makeAuthRef;
+}

package/src/lib/nest/controller/model/model.api.module.d.ts

@@ -0,0 +1,32 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type ClassType } from '@dereekb/util';
+/**
+ * Configuration for {@link modelApiModuleMetadata}.
+ */
+export interface ModelApiModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Module that exports the required dependencies.
+     *
+     * Must provide {@link ModelApiDispatchConfig} so the dispatch service
+     * can access the callModel function and nest context factory.
+     */
+    readonly dependencyModule: ClassType;
+}
+/**
+ * Generates NestJS module metadata for the Model API controller.
+ *
+ * Follows the same pattern as {@link oidcModuleMetadata} — takes a dependency module
+ * that provides the required tokens, and returns a complete module metadata object.
+ *
+ * @param metadataConfig - Configuration including the dependency module.
+ * @returns NestJS module metadata with the Model API controller, dispatch service, and app context provider.
+ *
+ * @example
+ * ```typescript
+ * @Module(modelApiModuleMetadata({
+ *   dependencyModule: DemoModelApiDependencyModule
+ * }))
+ * export class DemoModelApiModule {}
+ * ```
+ */
+export declare function modelApiModuleMetadata(metadataConfig: ModelApiModuleMetadataConfig): ModuleMetadata;

package/src/lib/nest/model/analytics.handler.d.ts

@@ -71,6 +71,8 @@ export declare const ON_CALL_MODEL_ANALYTICS_SERVICE: InjectionToken<OnCallModel
  *
  * Used as the default fallback by {@link OnCallModelAnalyticsResolver} when no analytics
  * service is registered.
+ *
+ * @returns An {@link OnCallModelAnalyticsService} that discards all analytics events.
  */
 export declare function noopOnCallModelAnalyticsService(): OnCallModelAnalyticsService;
 /**

package/src/lib/nest/model/api.details.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type OnCallFunctionType, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier } from '@dereekb/firebase';
+import { type OnCallFunctionType, type OnCallTypedModelParams, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier } from '@dereekb/firebase';
 import { type OnCallModelFunctionAnalyticsDetails } from './analytics.details';
 /**
  * Reference to a type that can produce a JSON Schema representation.
@@ -11,10 +11,41 @@ import { type OnCallModelFunctionAnalyticsDetails } from './analytics.details';
 export interface JsonSchemaRef {
     toJsonSchema(options?: object): object;
 }
+/**
+ * A natural language summary of an MCP tool operation result.
+ */
+export type McpToolResponseSummary = string;
+/**
+ * Minimal structural type for MCP tool response content.
+ *
+ * Mirrors the shape of MCP SDK's CallToolResult without importing the SDK directly,
+ * so api.details.ts remains dependency-free.
+ */
+export interface McpToolResponseContent {
+    readonly content: ReadonlyArray<McpToolResponseContentBlock>;
+    readonly structuredContent?: unknown;
+    readonly isError?: boolean;
+}
+/**
+ * A single content block in an MCP tool response.
+ */
+export interface McpToolResponseContentBlock {
+    readonly type: string;
+    readonly text?: string;
+    readonly mimeType?: string;
+    readonly data?: string;
+}
 /**
  * MCP-specific customization for a model function.
  *
  * When omitted, defaults are auto-generated from the handler's position in the call model tree.
+ *
+ * Response formatting uses a tiered system:
+ * - **Tier 1 (default)**: Auto-generated summary from the result shape. No config needed.
+ * - **Tier 2**: Provide {@link summarizeResponse} to return a natural language string. The framework wraps it into MCP content + structuredContent automatically.
+ * - **Tier 3**: Provide {@link formatResponse} for complete control over the MCP response content blocks.
+ *
+ * Resolution order: formatResponse > summarizeResponse > auto-generated default.
  */
 export interface OnCallModelFunctionMcpDetails {
     /**
@@ -25,6 +56,27 @@ export interface OnCallModelFunctionMcpDetails {
      * Custom tool name override.
      */
     readonly name?: string;
+    /**
+     * Tier 2 response formatter: returns a natural language summary string.
+     *
+     * The framework wraps the string into a text content block and attaches the raw result
+     * as structuredContent automatically.
+     *
+     * @param result - The handler's return value.
+     * @param params - The OnCallTypedModelParams that were dispatched.
+     * @returns A human-readable summary of the operation result.
+     */
+    readonly summarizeResponse?: (result: unknown, params: OnCallTypedModelParams) => McpToolResponseSummary;
+    /**
+     * Tier 3 response formatter: complete control over the MCP tool response.
+     *
+     * When provided, takes precedence over {@link summarizeResponse} and the auto-generated default.
+     *
+     * @param result - The handler's return value.
+     * @param params - The OnCallTypedModelParams that were dispatched.
+     * @returns The full MCP tool response content.
+     */
+    readonly formatResponse?: (result: unknown, params: OnCallTypedModelParams) => McpToolResponseContent;
 }
 /**
  * API details metadata for a single model call handler function.

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

@@ -5,13 +5,13 @@ import { type AssertModelCrudRequestFunctionContextCrudType, type AssertModelCru
 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
+ * Maps call type strings (e.g., 'create', 'read', 'update', 'delete', 'query') to their
  * corresponding handler functions.
  *
- * Used by {@link onCallModel} to dispatch incoming requests to the correct CRUD handler.
+ * Used by {@link onCallModel} to dispatch incoming requests to the correct handler.
  */
 export type OnCallModelMap = {
-    readonly [call: OnCallFunctionType]: OnCallWithNestContext<any, OnCallTypedModelParams>;
+    readonly [call: OnCallFunctionType]: OnCallWithNestContext<any, OnCallTypedModelParams<any>>;
 };
 /**
  * Configuration for {@link onCallModel}.
@@ -51,7 +51,8 @@ export interface OnCallModelConfig {
  *   create: onCallCreateModel({ profile: createProfile, guestbook: createGuestbook }),
  *   read: onCallReadModel({ profile: readProfile }),
  *   update: onCallUpdateModel({ profile: updateProfile }),
- *   delete: onCallDeleteModel({ guestbook: deleteGuestbook })
+ *   delete: onCallDeleteModel({ guestbook: deleteGuestbook }),
+ *   query: onCallQueryModel({ profile: queryProfiles })
  * });
  * ```
  */
@@ -95,7 +96,9 @@ export interface OnCallWithCallTypeModelConfig<N> {
      */
     readonly callType: string;
     /**
-     * The CRUD category used by {@link AssertModelCrudRequestFunction}.
+     * The operation category used by {@link AssertModelCrudRequestFunction}.
+     *
+     * One of: 'call', 'create', 'read', 'update', 'delete', 'query'.
      */
     readonly crudType: AssertModelCrudRequestFunctionContextCrudType;
     /**

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

@@ -89,6 +89,6 @@ export declare function onCallCreateModel<N>(map: OnCallCreateModelMap<N>, confi
  * Creates a bad-request error indicating the requested model type is not valid for creation.
  *
  * @param modelType - The unrecognized model type string.
- * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
  */
 export declare function createModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

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

@@ -7,7 +7,7 @@ import { type OnCallFunctionType, type FirestoreModelType } from '@dereekb/fireb
  * 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';
+export type AssertModelCrudRequestFunctionContextCrudType = 'call' | 'create' | 'read' | 'update' | 'delete' | 'query';
 /**
  * Context passed to a {@link AssertModelCrudRequestFunction} before a CRUD handler executes.
  *

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

@@ -78,6 +78,6 @@ export declare function onCallDeleteModel<N>(map: OnCallDeleteModelMap<N>, confi
  * Creates a bad-request error indicating the requested model type is not valid for deletion.
  *
  * @param modelType - The unrecognized model type string.
- * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
  */
 export declare function deleteModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

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

@@ -9,3 +9,4 @@ export * from './create.model.function';
 export * from './read.model.function';
 export * from './update.model.function';
 export * from './delete.model.function';
+export * from './query.model.function';

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

@@ -0,0 +1,207 @@
+import { type Maybe, type PromiseOrValue } from '@dereekb/util';
+import { type FirestoreModelType, type FirestoreModelIdentity, type FirestoreModelTypes, type OnCallQueryModelParams, type OnCallQueryModelRequestParams, type OnCallQueryModelResult, type ModelFirebaseCrudFunctionSpecifierRef, type FirestoreModelKey, type FirestoreCollectionLike, type FirestoreQueryConstraint, type DocumentSnapshot, type QueryDocumentSnapshot } from '@dereekb/firebase';
+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 query handlers that require authentication.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the query operation. Must extend {@link OnCallQueryModelRequestParams}.
+ */
+export type OnCallQueryModelRequest<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model query handler function that requires an authenticated caller.
+ */
+export type OnCallQueryModelFunctionWithAuth<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = ((request: OnCallQueryModelRequest<N, I>) => PromiseOrValue<O>) & {
+    readonly _requiresAuth?: true;
+};
+/**
+ * Request type for model query handlers that allow unauthenticated callers.
+ */
+export type OnCallQueryModelRequestWithOptionalAuth<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model query handler function that does not require authentication.
+ *
+ * Useful for public-facing query endpoints such as listing public content.
+ */
+export type OnCallQueryModelFunctionWithOptionalAuth<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = ((request: OnCallQueryModelRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
+    readonly _requireAuth: false;
+};
+/**
+ * Standard model query handler requiring auth (the common case).
+ */
+export type OnCallQueryModelFunction<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = OnCallQueryModelFunctionWithAuth<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Union of auth-required and optional-auth query handlers.
+ */
+export type OnCallQueryModelFunctionAuthAware<N, I extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams, O = unknown> = OnCallQueryModelFunction<N, I, O> | OnCallQueryModelFunctionWithOptionalAuth<N, I, O>;
+/**
+ * Maps Firestore model type strings to their query handler functions.
+ *
+ * Pass this map to {@link onCallQueryModel} to register all model types
+ * that support querying through the call model system.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining valid model type keys.
+ */
+export type OnCallQueryModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
+    readonly [K in FirestoreModelTypes<T>]?: OnCallQueryModelFunctionAuthAware<N, any, any>;
+};
+/**
+ * Configuration for {@link onCallQueryModel}.
+ */
+export interface OnCallQueryModelConfig<N> {
+    /**
+     * Optional assertion run before the query handler; throw to reject.
+     */
+    readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallQueryModelParams>;
+}
+/**
+ * Factory that creates a callable function handling model queries 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.
+ *
+ * Query handlers receive filter/pagination params in the request data and should return
+ * an {@link OnCallQueryModelResult} with paginated results. Use {@link executeOnCallQuery}
+ * within handlers to handle cursor pagination automatically.
+ *
+ * @param map - Maps model type strings to their query handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'query' call type.
+ *
+ * @example
+ * ```typescript
+ * const queryHandler = onCallQueryModel<DemoNestContext>({
+ *   profile: queryProfiles,
+ *   guestbook: queryGuestbooks
+ * });
+ *
+ * // Register as the 5th call type in onCallModel:
+ * const callModel = onCallModel({
+ *   create: onCallCreateModel({ ... }),
+ *   read: onCallReadModel({ ... }),
+ *   update: onCallUpdateModel({ ... }),
+ *   delete: onCallDeleteModel({ ... }),
+ *   query: queryHandler
+ * });
+ * ```
+ */
+export declare function onCallQueryModel<N>(map: OnCallQueryModelMap<N>, config?: OnCallQueryModelConfig<N>): OnCallWithNestContext<N, OnCallQueryModelParams, unknown>;
+/**
+ * Creates a bad-request error indicating the requested model type is not valid for querying.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
+ */
+export declare function queryModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates a bad-request error indicating the cursor document key is invalid or inaccessible.
+ *
+ * @param cursorDocumentKey - The cursor document key that failed to resolve.
+ * @returns A bad-request error with {@link BAD_DOCUMENT_QUERY_CURSOR_ERROR_CODE} code.
+ */
+export declare function queryModelBadCursorError(cursorDocumentKey: Maybe<FirestoreModelKey>): import("firebase-functions/https").HttpsError;
+/**
+ * Configuration for {@link executeOnCallQuery}.
+ *
+ * @typeParam T - The Firestore document data type.
+ * @typeParam R - The mapped result type for each document. Defaults to T.
+ */
+export interface ExecuteOnCallQueryConfig<T, R = T> {
+    /**
+     * The query request params containing limit and cursorDocumentKey.
+     */
+    readonly params: OnCallQueryModelRequestParams;
+    /**
+     * The Firestore collection to query against.
+     *
+     * Used for building queries (via {@link FirestoreQueryFactory}).
+     */
+    readonly collection: FirestoreCollectionLike<T>;
+    /**
+     * Loads and permission-checks the cursor document when {@link OnCallQueryModelRequestParams.cursorDocumentKey} is provided.
+     *
+     * This function must verify that the caller has read access to the cursor document.
+     * Typically implemented using `nest.useModel()` which enforces permission checking.
+     * Must return the document's snapshot for use with `startAfter`.
+     *
+     * If the cursor document does not exist or the caller lacks permission, this function
+     * should throw an appropriate error (e.g., forbidden or not-found).
+     *
+     * @param cursorDocumentKey - The Firestore model key of the cursor document.
+     * @returns A promise resolving to the cursor document's snapshot.
+     *
+     * @example
+     * ```typescript
+     * loadCursorDocument: async (key) => {
+     *   const doc = await nest.useModel('guestbook', {
+     *     request,
+     *     key,
+     *     roles: 'read',
+     *     use: (x) => x.document
+     *   });
+     *   return doc.accessor.get();
+     * }
+     * ```
+     */
+    readonly loadCursorDocument: (cursorDocumentKey: FirestoreModelKey) => PromiseOrValue<DocumentSnapshot<T>>;
+    /**
+     * Builds query constraints to apply to the query.
+     *
+     * Return where/orderBy constraints here. Do NOT add limit or startAfter —
+     * those are managed by {@link executeOnCallQuery} automatically.
+     *
+     * @returns Array of query constraints to apply. May be async if constraints depend on external data.
+     */
+    readonly buildConstraints: () => PromiseOrValue<FirestoreQueryConstraint[]>;
+    /**
+     * Optional maximum items per page override. Defaults to {@link MAX_ON_CALL_QUERY_MODEL_LIMIT}.
+     *
+     * The effective limit is: `min(params.limit ?? DEFAULT, maxLimit)`.
+     */
+    readonly maxLimit?: number;
+    /**
+     * Optional transform applied to each document snapshot's data before returning.
+     *
+     * Defaults to `snapshot.data()`.
+     */
+    readonly mapResult?: (snapshot: QueryDocumentSnapshot<T>) => R;
+}
+/**
+ * Executes a paginated query using cursor-based pagination.
+ *
+ * Handles the mechanics of:
+ * - Clamping the page limit to the configured maximum
+ * - Resolving the cursor document key to a snapshot for `startAfter`
+ * - Fetching one extra document to detect whether more results exist
+ * - Building the {@link OnCallQueryModelResult} with cursorDocumentKey and hasMore
+ *
+ * @example
+ * ```typescript
+ * export const queryGuestbooks: DemoQueryModelFunction<QueryGuestbooksParams, OnCallQueryModelResult<Guestbook>> = async (request) => {
+ *   const { nest, data } = request;
+ *   return executeOnCallQuery({
+ *     params: data,
+ *     collection: nest.demoFirestoreCollections.guestbookCollection,
+ *     loadCursorDocument: async (key) => {
+ *       const doc = await nest.useModel('guestbook', { request, key, roles: 'read', use: (x) => x.document });
+ *       return doc.accessor.get();
+ *     },
+ *     buildConstraints: () => {
+ *       const constraints: FirestoreQueryConstraint[] = [];
+ *       if (data.published != null) {
+ *         constraints.push(where('published', '==', data.published));
+ *       }
+ *       constraints.push(orderBy('name', 'asc'));
+ *       return constraints;
+ *     }
+ *   });
+ * };
+ * ```
+ *
+ * @param config - Query configuration including collection, constraints, and pagination params.
+ * @returns Paginated query result with cursor for the next page.
+ */
+export declare function executeOnCallQuery<T, R = T>(config: ExecuteOnCallQueryConfig<T, R>): Promise<OnCallQueryModelResult<R>>;

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

@@ -80,6 +80,6 @@ export declare function onCallReadModel<N>(map: OnCallReadModelMap<N>, config?:
  * Creates a bad-request error indicating the requested model type is not valid for reading.
  *
  * @param modelType - The unrecognized model type string.
- * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
  */
 export declare function readModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

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

@@ -81,6 +81,6 @@ export declare function onCallUpdateModel<N>(map: OnCallUpdateModelMap<N>, confi
  * Creates a bad-request error indicating the requested model type is not valid for updating.
  *
  * @param modelType - The unrecognized model type string.
- * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
  */
 export declare function updateModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/nest.provider.d.ts

@@ -87,6 +87,20 @@ export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseM
      * @returns An in-context models service scoped to the given auth context.
      */
     model(context: AuthDataRef, buildFn?: BuildFunction<FirebaseAppModelContext<A>>): InContextFirebaseModelsService<Y>;
+    /**
+     * Loads a model document by key, checks permissions against the requested roles,
+     * and optionally transforms the result via a `use` function.
+     *
+     * When called without a `use` function, returns the {@link ContextGrantedModelRolesReader}
+     * which provides access to the document and its granted roles.
+     *
+     * @throws Throws {@link nestFirebaseDoesNotExistError} if the document does not exist.
+     * @throws Throws {@link nestFirebaseForbiddenPermissionError} if the caller lacks the requested roles.
+     *
+     * @param type - The model type string (e.g., 'profile', 'guestbook').
+     * @param select - Selection params including key, roles, and optional use function.
+     * @returns The result of the `use` function, or the roles reader if no `use` function is provided.
+     */
     useModel<T extends FirebaseModelsServiceTypes<Y>, O>(type: T, select: UseModelInput<FirebaseAppModelContext<A>, Y, T, O>): Promise<O>;
     useModel<T extends FirebaseModelsServiceTypes<Y>>(type: T, select: UseModelInputForRolesReader<FirebaseAppModelContext<A>, Y, T>): Promise<FirebaseModelsServiceSelectionResultRolesReader<Y, T>>;
     /**
@@ -95,6 +109,11 @@ export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseM
      * Uses {@link performAsyncTasks} internally. The `use` function receives the array of
      * successful {@link ContextGrantedModelRolesReader} values and an array of failed items.
      *
+     * Individual documents that do not exist throw {@link nestFirebaseDoesNotExistError},
+     * and documents where the caller lacks the requested roles throw
+     * {@link nestFirebaseForbiddenPermissionError}. These errors are captured per-key
+     * and passed to the `use` function via the failure array (unless `throwOnFirstError` is true).
+     *
      * @param type - the model type to load
      * @param select - selection params including keys array, roles, and use function
      * @returns the result of the use function