@dereekb/firebase-server 13.6.17 → 13.8.0

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

@@ -1,11 +1,9 @@
-import { type ClassType, type Getter, type Maybe, type WebsitePath } from '@dereekb/util';
-import { type INestApplication, type INestApplicationContext, type NestApplicationOptions, type Provider } from '@nestjs/common';
+import { type ClassType, type Getter } from '@dereekb/util';
+import { type INestApplication, type INestApplicationContext, type NestApplicationOptions } from '@nestjs/common';
 import express from 'express';
 import type * as admin from 'firebase-admin';
-import { type StorageBucketId } from '@dereekb/firebase';
 import { type FirebaseServerEnvironmentConfig } from '../env/env.config';
-import { type GlobalRoutePrefixConfig } from './middleware/globalprefix';
-import { type NestServerAssetConfig } from './app.module';
+import { type NestServerRootModuleConfig } from './app.module';
 /**
  * A running NestJS server instance backed by Express, paired with a lazy promise getter for the NestJS application context.
  */
@@ -58,58 +56,19 @@ export type ConfigureNestServerInstanceFunction = (nestApp: INestApplication) =>
  * });
  * ```
  */
-export interface NestServerInstanceConfig<T> {
+export interface NestServerInstanceConfig<T> extends Omit<NestServerRootModuleConfig, 'firebaseAppGetter'> {
     /**
      * Module to instantiate.
      */
     readonly moduleClass: ClassType<T>;
-    /**
-     * Additional providers to provide globally.
-     */
-    readonly providers?: Provider<unknown>[];
-    /**
-     * Whether or not to configure FirebaseServerEnvService to be provided globally.
-     */
-    readonly configureEnvService?: boolean;
-    /**
-     * Whether or not to configure webhook usage.
-     *
-     * This will configure the webhook routes.
-     */
-    readonly configureWebhooks?: boolean;
-    /**
-     * Default storage bucket to use. If provided, overrides what the app uses in the default FirebaseServerStorageContextModule and default FirebaseStorageContext.
-     */
-    readonly defaultStorageBucket?: StorageBucketId;
-    /**
-     * Whether or not to force using the default storage bucket.
-     */
-    readonly forceStorageBucket?: boolean;
-    /**
-     * Whether or not to verify API calls with app check. Is true by default.
-     */
-    readonly appCheckEnabled?: boolean;
     /**
      * Additional nest application options.
      */
     readonly applicationOptions?: NestApplicationOptions;
-    /**
-     * Global routing prefix or options.
-     *
-     * Example: '/api'
-     */
-    readonly globalApiRoutePrefix?: WebsitePath | GlobalRoutePrefixConfig;
     /**
      * Optional configuration function
      */
     readonly configureNestServerInstance?: ConfigureNestServerInstanceFunction;
-    /**
-     * Optional asset loader configuration.
-     *
-     * When provided, configures the {@link AssetLoader} with the given settings.
-     * The AssetLoader is always provided globally regardless of this config.
-     */
-    readonly assets?: Maybe<NestServerAssetConfig>;
 }
 export interface NestFirebaseServerEnvironmentConfig {
     readonly environment: FirebaseServerEnvironmentConfig;

package/src/lib/nest/app.module.d.ts

@@ -41,7 +41,7 @@ export interface NestServerRootModuleConfig {
     /**
      * Module(s) to import into the root module.
      */
-    readonly modules: ArrayOrValue<ClassType | DynamicModule>;
+    readonly modules?: Maybe<ArrayOrValue<ClassType | DynamicModule>>;
     /**
      * Getter for the Firebase Admin app instance.
      * When provided, the `FIREBASE_APP_TOKEN` is made available globally.
@@ -50,7 +50,7 @@ export interface NestServerRootModuleConfig {
     /**
      * Additional providers to include globally.
      */
-    readonly additionalProviders?: Provider[];
+    readonly providers?: Provider[];
     /**
      * Environment configuration. When provided, injects env tokens via `firebaseServerEnvTokenProviders`.
      */
@@ -71,6 +71,8 @@ export interface NestServerRootModuleConfig {
     /**
      * Global route prefix configuration.
      * The `GlobalRoutePrefixConfig` token is always provided (empty object when no config given).
+     *
+     * Example: '/api'
      */
     readonly globalApiRoutePrefix?: WebsitePath | GlobalRoutePrefixConfig;
     /**

package/src/lib/nest/auth/auth.util.d.ts

@@ -1,14 +1,15 @@
 import { type UserRelated } from '@dereekb/firebase';
-import { type ArrayOrValue, type AuthRole } from '@dereekb/util';
+import { type ArrayOrValue, type AuthRole, type ErrorMessageOrPartialServerError, type Maybe } from '@dereekb/util';
 import { type NestContextCallableRequestWithOptionalAuth } from '../function/nest';
 import { type AbstractFirebaseNestContext } from '../nest.provider';
 /**
  * Asserts that the caller has admin privileges in the request.
  *
  * @param request - The callable request to check for admin privileges.
+ * @param messageOrError - Optional custom error message or partial server error for the forbidden response.
  * @throws {HttpsError} Throws forbidden (403) if the caller is not an admin.
  */
-export declare function assertIsAdminInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>): void;
+export declare function assertIsAdminInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>, messageOrError?: Maybe<ErrorMessageOrPartialServerError>): void;
 /**
  * Checks whether the caller has admin privileges in the request.
  *
@@ -23,10 +24,11 @@ export declare function isAdminInRequest<N extends AbstractFirebaseNestContext<a
  *
  * @param request - The callable request containing the target UID.
  * @param requireUid - If true, a UID must be present in the request data.
+ * @param messageOrError - Optional custom error message or partial server error for the forbidden response.
  * @returns The resolved target UID (from request data or auth).
  * @throws {HttpsError} Throws forbidden (403) if the caller is not authorized.
  */
-export declare function assertIsAdminOrTargetUserInRequestData<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I extends Partial<UserRelated> = Partial<UserRelated>>(request: NestContextCallableRequestWithOptionalAuth<N, I>, requireUid?: boolean): string | undefined;
+export declare function assertIsAdminOrTargetUserInRequestData<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I extends Partial<UserRelated> = Partial<UserRelated>>(request: NestContextCallableRequestWithOptionalAuth<N, I>, requireUid?: boolean, messageOrError?: Maybe<ErrorMessageOrPartialServerError>): string | undefined;
 /**
  * Checks whether the caller is an admin or is targeting their own user record in the request data.
  *
@@ -39,9 +41,10 @@ export declare function isAdminOrTargetUserInRequestData<N extends AbstractFireb
  * Asserts that the caller has signed the Terms of Service.
  *
  * @param request - The callable request to check for ToS status.
+ * @param messageOrError - Optional custom error message or partial server error for the forbidden response.
  * @throws {HttpsError} Throws forbidden (403) if ToS has not been signed.
  */
-export declare function assertHasSignedTosInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>): void;
+export declare function assertHasSignedTosInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>, messageOrError?: Maybe<ErrorMessageOrPartialServerError>): void;
 /**
  * Checks whether the caller has signed the Terms of Service.
  *
@@ -54,9 +57,10 @@ export declare function hasSignedTosInRequest<N extends AbstractFirebaseNestCont
  *
  * @param request - The callable request to check for auth roles.
  * @param authRoles - One or more roles that must all be present.
+ * @param messageOrError - Optional custom error message or partial server error for the forbidden response.
  * @throws {HttpsError} Throws forbidden (403) if any required role is missing.
  */
-export declare function assertHasRolesInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>, authRoles: ArrayOrValue<AuthRole>): void;
+export declare function assertHasRolesInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>, authRoles: ArrayOrValue<AuthRole>, messageOrError?: Maybe<ErrorMessageOrPartialServerError>): void;
 /**
  * Checks whether the caller has all of the specified auth roles.
  *
@@ -65,6 +69,68 @@ export declare function assertHasRolesInRequest<N extends AbstractFirebaseNestCo
  * @returns True if the caller has all of the specified auth roles.
  */
 export declare function hasAuthRolesInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>, authRoles: ArrayOrValue<AuthRole>): boolean;
+/**
+ * Configuration for {@link resolveAdminOnlyValue}.
+ *
+ * @typeParam T - The value type being resolved.
+ */
+export interface ResolveAdminOnlyValueConfig<N extends AbstractFirebaseNestContext<any, any>, I, T> {
+    /**
+     * The callable request to check for admin privileges.
+     */
+    readonly request: NestContextCallableRequestWithOptionalAuth<N, I>;
+    /**
+     * The raw input value from the request data. May be undefined if the caller didn't provide it.
+     */
+    readonly value?: Maybe<T>;
+    /**
+     * The default value to use when {@link value} is undefined and the caller is not an admin.
+     *
+     * Admins receive no default (undefined) so the query has no restriction.
+     */
+    readonly defaultValue?: Maybe<T>;
+    /**
+     * Predicate that returns true if the given resolved value is restricted to admins only.
+     *
+     * When this returns true and the caller is not an admin, a forbidden error is thrown.
+     *
+     * @param value - The resolved value to check.
+     * @returns True if the value requires admin privileges.
+     */
+    readonly isAdminOnlyValue: (value: Maybe<T>) => boolean;
+    /**
+     * Optional error message or partial server error to include in the forbidden error.
+     */
+    readonly messageOrError?: ErrorMessageOrPartialServerError;
+}
+/**
+ * Resolves a request parameter value with admin-aware defaulting and access control.
+ *
+ * For non-admins:
+ * - If the caller didn't provide a value, the {@link ResolveAdminOnlyValueConfig.defaultValue} is used.
+ * - If the resolved value is admin-only (per the predicate), a forbidden error is thrown.
+ *
+ * For admins:
+ * - If the caller didn't provide a value, undefined is returned (no restriction).
+ * - Any value is allowed.
+ *
+ * @param config - Configuration specifying the request, value, defaults, and admin-only predicate.
+ * @returns The resolved value, or undefined for admins who didn't provide a value.
+ * @throws {HttpsError} Throws forbidden (403) if a non-admin attempts to use an admin-only value.
+ *
+ * @example
+ * ```typescript
+ * // Non-admins can only query published=true; admins can query anything
+ * const published = resolveAdminOnlyValue({
+ *   request,
+ *   value: data.published,
+ *   defaultValue: true,
+ *   isAdminOnlyValue: (v) => v !== true,
+ *   messageOrError: { message: 'Users can only search published entries.' }
+ * });
+ * ```
+ */
+export declare function resolveAdminOnlyValue<N extends AbstractFirebaseNestContext<any, any>, I, T>(config: ResolveAdminOnlyValueConfig<N, I, T>): Maybe<T>;
 /**
  * Returns true if the claims have a FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY claims value, indicating they are a newly invited user.
  *

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

@@ -1 +1,2 @@
 export * from './auth.context.server';
+export * from './model';

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

@@ -0,0 +1,4 @@
+export * from './model.api.get.service';
+export * from './model.api.dispatch';
+export * from './model.api.controller';
+export * from './model.api.module';

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

@@ -0,0 +1,93 @@
+import { type Request } from 'express';
+import { type OnCallTypedModelParams, type FirestoreModelKey } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+import { ModelApiCallModelDispatchService } from './model.api.dispatch';
+import { ModelApiGetService } from './model.api.get.service';
+/**
+ * Body for multi-read POST requests on the `get` route.
+ */
+interface ModelAccessMultiReadBody {
+    readonly keys: string[];
+}
+/**
+ * REST API controller that exposes the callModel dispatch chain and direct document access via HTTP.
+ *
+ * Mounted at `model` — under the `/api` global prefix, routes become `/api/model/*`.
+ *
+ * Provides three access patterns:
+ * 1. **Direct dispatch**: `POST /api/model/call` with an {@link OnCallTypedModelParams} body.
+ * 2. **Document access**: `GET /api/model/:modelType/get?key=...` (single) or
+ *    `POST /api/model/:modelType/get` with `{ keys: [...] }` (multi) via `useModel()`.
+ * 3. **Path-based dispatch**: `POST|PUT /api/model/:modelType/:call/:specifier?` dispatches
+ *    to the callModel chain. `DELETE` is only allowed when the call segment is `'delete'`.
+ *    The call type comes from the path, not the HTTP method.
+ *
+ * Auth is provided by the OIDC bearer token middleware on the `req.auth` field.
+ */
+export declare class ModelApiController {
+    private readonly dispatchService;
+    private readonly accessService;
+    constructor(dispatchService: ModelApiCallModelDispatchService, accessService: ModelApiGetService);
+    /**
+     * Direct dispatch with full OnCallTypedModelParams body.
+     *
+     * This route MUST be declared before the catch-all to prevent NestJS
+     * from matching "call" as a modelType.
+     *
+     * @param body - The full {@link OnCallTypedModelParams} describing the model call to dispatch.
+     * @param req - The Express request containing auth credentials on `req.auth`.
+     * @returns The result of the dispatched model call.
+     */
+    directDispatch(body: OnCallTypedModelParams, req: Request): Promise<unknown>;
+    /**
+     * Reads a single document by model type and key via `useModel()` with `'read'` roles.
+     *
+     * The key is a full Firestore model key (e.g., `pr/abc123`), not just an ID.
+     *
+     * Declared before the catch-all `{*path}` route so NestJS matches this first.
+     *
+     * @param modelType - The model type identifier (e.g., 'pr', 'user').
+     * @param key - The full Firestore model key to read (e.g., `pr/abc123`).
+     * @param req - The Express request containing auth credentials on `req.auth`.
+     * @returns The document data for the requested model key.
+     */
+    getOne(modelType: string, key: Maybe<FirestoreModelKey>, req: Request): Promise<import("./model.api.get.service").ModelAccessReadResult>;
+    /**
+     * Reads multiple documents of the same model type via `useMultipleModels()` with `'read'` roles.
+     *
+     * Keys are full Firestore model keys. Maximum {@link MAX_MODEL_ACCESS_MULTI_READ_KEYS} keys per request.
+     *
+     * Declared before the catch-all `{*path}` route so NestJS matches this first.
+     *
+     * @param modelType - The model type identifier (e.g., 'pr', 'user').
+     * @param body - Request body containing the array of Firestore model keys to read.
+     * @param req - The Express request containing auth credentials on `req.auth`.
+     * @returns An object with `results` (document data array) and `errors` (per-key failures).
+     */
+    getMany(modelType: string, body: ModelAccessMultiReadBody, req: Request): Promise<import("./model.api.get.service").ModelAccessMultiReadResult>;
+    /**
+     * Catch-all handler for callModel dispatch via path.
+     *
+     * Path: `/api/model/:modelType/:call/:specifier?`
+     *
+     * The call type (create, read, update, delete, query, etc.) is determined by the
+     * path segment, not the HTTP method. POST and PUT are allowed for any call type.
+     * DELETE is only allowed when the call segment is `'delete'`.
+     *
+     * @param req - The Express request whose path segments encode modelType, call, and optional specifier.
+     * @returns The result of the dispatched model call.
+     */
+    handleDispatchRequest(req: Request): Promise<unknown>;
+    /**
+     * Parses modelType, call, and specifier from the wildcard path segments.
+     *
+     * Expected path format: `:modelType/:call/:specifier?`
+     *
+     * @param req - The Express request containing wildcard path params.
+     * @returns Parsed path components with modelType, call, and specifier (defaults to '_').
+     */
+    private _parsePath;
+    private _dispatch;
+    private _toHttpException;
+}
+export {};

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

@@ -0,0 +1,73 @@
+import { type Maybe } from '@dereekb/util';
+import { type OnCallTypedModelParams } from '@dereekb/firebase';
+import { type INestApplicationContext } from '@nestjs/common';
+import { type Request } from 'express';
+import { type OnCallWithNestContext } from '../../function/call';
+import { type OnCallApiDetailsRef, type ModelApiDetailsResult } from '../../model/api.details';
+import { type MakeNestContext } from '../../nest.provider';
+import { type FirebaseServerAuthData } from '../auth.context.server';
+/**
+ * The combined type of the function returned by onCallModel() with _apiDetails attached.
+ */
+export type OnCallModelFnWithApiDetails = OnCallWithNestContext<unknown, OnCallTypedModelParams> & OnCallApiDetailsRef;
+/**
+ * Abstract injectable config token for the Model API dispatch layer.
+ *
+ * Downstream apps provide this by creating a concrete provider that references
+ * their onCallModel() return value and MakeNestContext factory.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   provide: ModelApiDispatchConfig,
+ *   useValue: {
+ *     callModelFn: demoCallModelFn,
+ *     makeNestContext: mapDemoApiNestContext
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class ModelApiDispatchConfig {
+    /**
+     * The onCallModel() return value with _apiDetails attached.
+     */
+    readonly callModelFn: OnCallModelFnWithApiDetails;
+    /**
+     * Factory to create typed nest context from INestApplicationContext.
+     */
+    readonly makeNestContext: MakeNestContext<unknown>;
+}
+/**
+ * Injection token for providing the NestJS application context to the dispatch service.
+ *
+ * The app module metadata factory creates a provider for this token
+ * using the module's own INestApplicationContext.
+ */
+export declare const MODEL_API_NEST_APPLICATION_CONTEXT = "MODEL_API_NEST_APPLICATION_CONTEXT";
+/**
+ * Service that bridges HTTP/MCP requests to the callModel dispatch chain.
+ *
+ * Builds a synthetic {@link CallableRequest} from the HTTP request auth and body,
+ * injects the NestJS application context and typed nest context, then invokes
+ * the callModel function.
+ */
+export declare class ModelApiCallModelDispatchService {
+    private readonly config;
+    private readonly nestApplication;
+    constructor(config: ModelApiDispatchConfig, nestApplication: INestApplicationContext);
+    /**
+     * Dispatch to the callModel chain.
+     *
+     * @param params - The typed model params (call, modelType, specifier, data).
+     * @param auth - The authenticated user's auth data from the OIDC middleware.
+     * @param rawRequest - The raw Express request.
+     * @returns The handler's return value.
+     */
+    dispatch(params: OnCallTypedModelParams, auth: Maybe<FirebaseServerAuthData>, rawRequest: Request): Promise<unknown>;
+    /**
+     * Returns the model-first API details view, or undefined if no handlers have _apiDetails.
+     *
+     * @returns The aggregated API details describing all registered model call handlers, or undefined if unavailable.
+     */
+    getApiDetails(): Maybe<ModelApiDetailsResult>;
+}

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;