@dereekb/firebase-server 13.6.16 → 13.7.0

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.6.16",
+  "version": "13.7.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.6.16",
-    "@dereekb/date": "13.6.16",
-    "@dereekb/firebase": "13.6.16",
-    "@dereekb/firebase-server": "13.6.16",
-    "@dereekb/model": "13.6.16",
-    "@dereekb/nestjs": "13.6.16",
-    "@dereekb/rxjs": "13.6.16",
-    "@dereekb/util": "13.6.16",
-    "@dereekb/zoho": "13.6.16",
+    "@dereekb/analytics": "13.7.0",
+    "@dereekb/date": "13.7.0",
+    "@dereekb/firebase": "13.7.0",
+    "@dereekb/firebase-server": "13.7.0",
+    "@dereekb/model": "13.7.0",
+    "@dereekb/nestjs": "13.7.0",
+    "@dereekb/rxjs": "13.7.0",
+    "@dereekb/util": "13.7.0",
+    "@dereekb/zoho": "13.7.0",
     "@nestjs/common": "^11.1.17",
     "@nestjs/config": "^4.0.3",
     "express": "^5.0.0",

package/oidc/src/lib/middleware/oauth-auth.module.d.ts

@@ -1,4 +1,4 @@
-import { type MiddlewareConsumer } from '@nestjs/common';
+import { type INestApplication } from '@nestjs/common';
 import { type SlashPath } from '@dereekb/util';
 /**
  * Configuration for `OidcAuthBearerTokenMiddleware` route protection.
@@ -6,12 +6,6 @@ import { type SlashPath } from '@dereekb/util';
  * Works in reverse of `FirebaseAppCheckMiddlewareConfig`: instead of protecting
  * all routes and ignoring some, this only protects explicitly specified paths.
  * Routes under the global API prefix (protected by AppCheck) are excluded.
- *
- * @example
- * ```ts
- * // Provide in your module:
- * { provide: OidcAuthMiddlewareConfig, useValue: { protectedPaths: ['/mcp'] } }
- * ```
  */
 export declare abstract class OidcAuthMiddlewareConfig {
     /**
@@ -24,27 +18,26 @@ export declare abstract class OidcAuthMiddlewareConfig {
     readonly protectedPaths: SlashPath[];
 }
 /**
- * Middleware module that applies OAuth bearer token verification
- * to paths specified in `OidcAuthMiddlewareConfig`.
+ * Applies OAuth bearer token verification as global Express middleware on
+ * the given NestJS application.
  *
- * Only protects explicitly listed paths — all other routes pass through.
- * This is the inverse of `ConfigureFirebaseAppCheckMiddlewareModule`, which
- * protects everything and ignores specific paths.
+ * Resolves `OidcService` and `OidcAuthMiddlewareConfig` from the app's DI container,
+ * then registers an Express middleware that verifies bearer tokens for the configured
+ * protected paths and attaches auth data to `req.auth`.
+ *
+ * This is an alternative to {@link ConfigureOidcAuthMiddlewareModule} for cases where
+ * NestJS module scoping makes the module approach impractical.
+ *
+ * @param nestApp - The NestJS application instance used to resolve dependencies and register the middleware.
  *
  * @example
  * ```ts
- * @Module({
- *   imports: [ConfigureOidcAuthMiddlewareModule],
- *   providers: [
- *     { provide: OidcAuthMiddlewareConfig, useValue: { protectedPaths: ['/mcp'] } }
- *   ]
- * })
- * export class AppModule {}
+ * export const APP_NEST_SERVER_CONFIG: NestServerInstanceConfig<AppModule> = {
+ *   moduleClass: AppModule,
+ *   configureNestServerInstance: (nestApp) => {
+ *     applyOidcAuthMiddleware(nestApp);
+ *   }
+ * };
  * ```
  */
-export declare class ConfigureOidcAuthMiddlewareModule {
-    private readonly config?;
-    private readonly logger;
-    constructor(config?: OidcAuthMiddlewareConfig | undefined);
-    configure(consumer: MiddlewareConsumer): void;
-}
+export declare function applyOidcAuthMiddleware(nestApp: INestApplication): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.6.16",
+  "version": "13.7.0",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -43,15 +43,15 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/analytics": "13.6.16",
-    "@dereekb/date": "13.6.16",
-    "@dereekb/dbx-core": "13.6.16",
-    "@dereekb/firebase": "13.6.16",
-    "@dereekb/model": "13.6.16",
-    "@dereekb/nestjs": "13.6.16",
-    "@dereekb/rxjs": "13.6.16",
-    "@dereekb/util": "13.6.16",
-    "@dereekb/zoho": "13.6.16",
+    "@dereekb/analytics": "13.7.0",
+    "@dereekb/date": "13.7.0",
+    "@dereekb/dbx-core": "13.7.0",
+    "@dereekb/firebase": "13.7.0",
+    "@dereekb/model": "13.7.0",
+    "@dereekb/nestjs": "13.7.0",
+    "@dereekb/rxjs": "13.7.0",
+    "@dereekb/util": "13.7.0",
+    "@dereekb/zoho": "13.7.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.17",
@@ -71,6 +71,7 @@
     "nanoid": "^5.1.7",
     "oidc-provider": "^9.7.0",
     "rxjs": "^7.8.0",
+    "supertest": "^7.2.2",
     "ts-essentials": "^10.0.0"
   },
   "module": "./index.esm.js"

package/src/lib/function/error.d.ts

@@ -14,100 +14,83 @@ export declare function unauthenticatedContextHasNoAuthData(): HttpsError;
  * @returns A new unauthenticated {@link HttpsError} with the no-auth error code.
  */
 export declare function unauthenticatedContextHasNoUidError(): HttpsError;
-/**
- * Standard error code constants and factory functions for creating typed {@link HttpsError} instances.
- *
- * Each factory wraps the Firebase `HttpsError` with a consistent shape: an HTTP status code,
- * a string error code, and an optional {@link ServerError} detail object.
- */
-export declare const UNAUTHENTICATED_ERROR_CODE = "UNAUTHENTICATED";
 /**
  * Creates an unauthenticated (401) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new unauthenticated (401) {@link HttpsError}.
  */
-export declare function unauthenticatedError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const FORBIDDEN_ERROR_CODE = "FORBIDDEN";
+export declare function unauthenticatedError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates a forbidden (403) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new forbidden (403) {@link HttpsError}.
  */
-export declare function forbiddenError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const PERMISSION_DENIED_ERROR_CODE = "PERMISSION_DENIED";
+export declare function forbiddenError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates a permission-denied (403) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new permission-denied (403) {@link HttpsError}.
  */
-export declare function permissionDeniedError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const NOT_FOUND_ERROR_CODE = "NOT_FOUND";
+export declare function permissionDeniedError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates a not-found (404) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new not-found (404) {@link HttpsError}.
  */
-export declare function notFoundError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const MODEL_NOT_AVAILABLE_ERROR_CODE = "MODEL_NOT_AVAILABLE";
+export declare function notFoundError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates a model-not-available (404) {@link HttpsError}, used when a Firestore document does not exist.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new model-not-available (404) {@link HttpsError}.
  */
-export declare function modelNotAvailableError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const BAD_REQUEST_ERROR_CODE = "BAD_REQUEST";
+export declare function modelNotAvailableError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates a bad-request (400) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new bad-request (400) {@link HttpsError}.
  */
-export declare function badRequestError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const CONFLICT_ERROR_CODE = "CONFLICT";
+export declare function badRequestError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates a precondition-conflict (409) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new precondition-conflict (409) {@link HttpsError}.
  */
-export declare function preconditionConflictError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const ALREADY_EXISTS_ERROR_CODE = "ALREADY_EXISTS";
+export declare function preconditionConflictError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates an already-exists (409) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new already-exists (409) {@link HttpsError}.
  */
-export declare function alreadyExistsError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const UNAVAILABLE_ERROR_CODE = "UNAVAILABLE";
+export declare function alreadyExistsError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates an unavailable (503) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new unavailable (503) {@link HttpsError}.
  */
-export declare function unavailableError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE = "UNAVAILABLE_OR_DEACTIVATED_FUNCTION";
+export declare function unavailableError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates an unimplemented (501) {@link HttpsError} for deactivated or unavailable functions.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new unimplemented (501) {@link HttpsError}.
  */
-export declare function unavailableOrDeactivatedFunctionError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
-export declare const INTERNAL_SERVER_ERROR_CODE = "INTERNAL_ERROR";
+export declare function unavailableOrDeactivatedFunctionError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Creates an internal-error (500) {@link HttpsError}.
  *
  * @param messageOrError - Optional error message string or partial server error object.
  * @returns A new internal-error (500) {@link HttpsError}.
  */
-export declare function internalServerError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
+export declare function internalServerError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
 /**
  * Discriminator for the type of Firebase server error encountered.
  */

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>;
+}