@dereekb/firebase-server 13.2.2 → 13.3.1

package/src/lib/firestore/driver.accessor.transaction.d.ts

@@ -2,7 +2,11 @@ import { type DocumentReference, type DocumentSnapshot, type Transaction as Goog
 import { type Observable } from 'rxjs';
 import { type WithFieldValue, type UpdateData, type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type FirestoreDocumentContext, FirestoreDocumentContextType, type FirestoreDocumentUpdateParams, type FirestoreDataConverter, type DocumentData, type FirestoreAccessorIncrementUpdate, type FirestoreAccessorArrayUpdate } from '@dereekb/firebase';
 /**
- * FirestoreDocumentDataAccessor implementation for a transaction.
+ * Google Cloud Firestore implementation of {@link FirestoreDocumentDataAccessor} that executes
+ * all operations within a Firestore {@link Transaction}.
+ *
+ * Reads performed through this accessor are included in the transaction's read set, ensuring
+ * consistency. Writes are committed atomically when the transaction completes.
  */
 export declare class TransactionFirestoreDocumentDataAccessor<T> implements FirestoreDocumentDataAccessor<T> {
     private readonly _transaction;
@@ -22,12 +26,29 @@ export declare class TransactionFirestoreDocumentDataAccessor<T> implements Fire
     update(data: UpdateData<object>, params?: FirestoreDocumentUpdateParams): Promise<void>;
 }
 /**
- * Creates a new FirestoreDocumentDataAccessorFactory for a Transaction.
+ * Creates a {@link FirestoreDocumentDataAccessorFactory} that produces transaction-backed accessors.
+ *
+ * All accessors share the same transaction, so reads and writes participate in the same
+ * atomic operation.
  *
- * @param transaction
- * @returns
+ * @param transaction - The Google Cloud Transaction to execute operations within.
+ *
+ * @example
+ * ```typescript
+ * await firestore.runTransaction(async (transaction) => {
+ *   const factory = transactionAccessorFactory<User>(transaction);
+ *   const accessor = factory.accessorFor(userDocRef);
+ *   const snapshot = await accessor.get();
+ *   await accessor.update({ name: 'Updated' });
+ * });
+ * ```
  */
 export declare function transactionAccessorFactory<T>(transaction: GoogleCloudTransaction): FirestoreDocumentDataAccessorFactory<T>;
+/**
+ * A {@link FirestoreDocumentContext} backed by a Google Cloud {@link Transaction}.
+ *
+ * All document accessors created from this context operate within the same transaction.
+ */
 export declare class TransactionFirestoreDocumentContext<T> implements FirestoreDocumentContext<T> {
     private readonly _transaction;
     readonly contextType = FirestoreDocumentContextType.TRANSACTION;
@@ -35,4 +56,7 @@ export declare class TransactionFirestoreDocumentContext<T> implements Firestore
     constructor(transaction: GoogleCloudTransaction);
     get transaction(): GoogleCloudTransaction;
 }
+/**
+ * Creates a {@link TransactionFirestoreDocumentContext} wrapping the given transaction.
+ */
 export declare function transactionDocumentContext<T>(transaction: GoogleCloudTransaction): TransactionFirestoreDocumentContext<T>;

package/src/lib/firestore/driver.d.ts

@@ -1,3 +1,17 @@
 import { type FirestoreDrivers } from '@dereekb/firebase';
+/**
+ * Alias for {@link FirestoreDrivers} specific to the Google Cloud Firestore (server) implementation.
+ */
 export type GoogleCloudFirestoreDrivers = FirestoreDrivers;
+/**
+ * Creates a complete set of {@link FirestoreDrivers} for Google Cloud Firestore (Admin SDK).
+ *
+ * Bundles the server-side accessor driver and query driver, identified as `@google-cloud/firestore`.
+ *
+ * @example
+ * ```typescript
+ * const drivers = googleCloudFirestoreDrivers();
+ * const context = firestoreContextFactory(drivers);
+ * ```
+ */
 export declare function googleCloudFirestoreDrivers(): GoogleCloudFirestoreDrivers;

package/src/lib/firestore/driver.query.d.ts

@@ -1,6 +1,31 @@
 import { type Query as GoogleCloudQuery } from '@google-cloud/firestore';
 import { type FullFirestoreQueryConstraintHandlersMapping, type FirestoreQueryConstraintFunctionsDriver, type FirestoreQueryDriver } from '@dereekb/firebase';
+/**
+ * Server-side query builder type, aliasing the Google Cloud Firestore {@link Query}.
+ */
 export type FirestoreServerQueryBuilder<T = any> = GoogleCloudQuery<T>;
+/**
+ * Maps each abstract query constraint type to its Google Cloud Firestore implementation.
+ *
+ * Used by {@link firestoreClientQueryConstraintFunctionsDriver} to build the server-side query driver.
+ */
 export declare const FIRESTORE_CLIENT_QUERY_CONSTRAINT_HANDLER_MAPPING: FullFirestoreQueryConstraintHandlersMapping<FirestoreServerQueryBuilder>;
+/**
+ * Creates a {@link FirestoreQueryConstraintFunctionsDriver} for the Google Cloud Firestore server SDK.
+ *
+ * Translates abstract query constraints into Google Cloud Firestore query builder calls.
+ */
 export declare function firestoreClientQueryConstraintFunctionsDriver(): FirestoreQueryConstraintFunctionsDriver;
+/**
+ * Creates a complete {@link FirestoreQueryDriver} for Google Cloud Firestore (Admin SDK).
+ *
+ * Supports query execution (getDocs), document counting (countDocs), and real-time
+ * streaming (streamDocs) via `onSnapshot`. Transaction-aware reads are supported
+ * through the optional transaction parameter in `getDocs`.
+ *
+ * @example
+ * ```typescript
+ * const queryDriver = googleCloudFirestoreQueryDriver();
+ * ```
+ */
 export declare function googleCloudFirestoreQueryDriver(): FirestoreQueryDriver;

package/src/lib/firestore/increment.d.ts

@@ -1,8 +1,18 @@
 import { type UpdateData, type FirestoreAccessorIncrementUpdate } from '@dereekb/firebase';
 /**
- * Creates UpdateData corresponding to the input increment update.
+ * Converts a {@link FirestoreAccessorIncrementUpdate} into Firestore {@link UpdateData} using
+ * Google Cloud Firestore's {@link FieldValue.increment}.
  *
- * @param input
- * @returns
+ * Each field in the input maps to an atomic increment operation. Null/undefined values default to 0.
+ *
+ * @param input - The increment specification mapping field names to numeric deltas.
+ *
+ * @example
+ * ```typescript
+ * const updateData = firestoreServerIncrementUpdateToUpdateData<Stats>({
+ *   viewCount: 1,
+ *   likeCount: -1
+ * });
+ * ```
  */
 export declare function firestoreServerIncrementUpdateToUpdateData<T extends object>(input: FirestoreAccessorIncrementUpdate<T>): UpdateData<T>;

package/src/lib/firestore/snapshot/index.d.ts

@@ -1 +1 @@
-export * from './snapshot.field';
+export * from './snapshot.field.encrypt';

package/src/lib/firestore/snapshot/{snapshot.field.d.ts → snapshot.field.encrypt.d.ts}

@@ -1,44 +1,30 @@
-import { type Maybe, type Getter, type GetterOrValue } from '@dereekb/util';
+import { type GetterOrValue, type Maybe } from '@dereekb/util';
 import { type FirestoreModelFieldMapFunctionsConfig } from '@dereekb/firebase';
 /**
- * The source for the encryption secret.
+ * Configuration for a required encrypted Firestore field.
  *
- * - If a string, it is used directly as the hex-encoded key (64 hex chars = 32 bytes).
- * - If a Getter, it is called each time to retrieve the key (useful for rotation or lazy loading).
- * - If an object with `env`, the key is read from the specified environment variable.
- */
-export type FirestoreEncryptedFieldSecretSource = string | Getter<string> | {
-    env: string;
-};
-/**
- * Configuration for encrypted Firestore fields.
- *
- * @template T - The JSON-serializable value type stored in the model.
+ * @template T - The JSON-serializable value type.
  */
 export interface FirestoreEncryptedFieldConfig<T> {
     /**
-     * The encryption secret source.
-     *
-     * Expects a 64-character hex string representing a 32-byte AES-256 key.
+     * Secret source for the encryption key.
      */
-    readonly secret: FirestoreEncryptedFieldSecretSource;
+    readonly secret: GetterOrValue<string>;
     /**
-     * Default model value when the Firestore data is null/undefined.
+     * Default value when the field is missing from Firestore.
      */
-    readonly default?: GetterOrValue<T>;
+    readonly default: GetterOrValue<T>;
 }
 /**
- * Configuration for optional encrypted Firestore fields.
+ * Configuration for an optional encrypted Firestore field.
  *
- * @template T - The JSON-serializable value type stored in the model.
+ * @template T - The JSON-serializable value type.
  */
 export interface OptionalFirestoreEncryptedFieldConfig<T> {
     /**
-     * The encryption secret source.
-     *
-     * Expects a 64-character hex string representing a 32-byte AES-256 key.
+     * Secret source for the encryption key.
      */
-    readonly secret: FirestoreEncryptedFieldSecretSource;
+    readonly secret: GetterOrValue<string>;
 }
 /**
  * Creates a Firestore field mapping that encrypts/decrypts a JSON-serializable value
@@ -50,7 +36,7 @@ export interface OptionalFirestoreEncryptedFieldConfig<T> {
  * @example
  * ```typescript
  * const jwksField = firestoreEncryptedField<JWKSet>({
- *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' },
+ *   secret: process.env['FIRESTORE_ENCRYPTION_KEY']!,
  *   default: () => ({ keys: [] })
  * });
  * ```
@@ -69,7 +55,7 @@ export declare function firestoreEncryptedField<T>(config: FirestoreEncryptedFie
  * @example
  * ```typescript
  * const optionalSecretField = optionalFirestoreEncryptedField<OAuthClientSecret>({
- *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' }
+ *   secret: process.env['FIRESTORE_ENCRYPTION_KEY']!
  * });
  * ```
  *

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

@@ -1,35 +1,51 @@
 import { type DocumentDataWithIdAndKey, type FirestoreDocument, type FirestoreDocumentData } from '@dereekb/firebase';
 import { type CallableContext } from '../type';
+/**
+ * Asserts that the callable context contains auth data with a valid UID.
+ *
+ * @throws {HttpsError} Throws unauthenticated error if no auth data is present.
+ *
+ * @example
+ * ```typescript
+ * assertContextHasAuth(context);
+ * // Safe to access context.auth.uid
+ * ```
+ */
 export declare function assertContextHasAuth(context: CallableContext): void;
 /**
- * Attempts to load data from the document. A modelNotAvailableError is thrown if the snapshot data is null/undefined (the document does not exist).
+ * Loads the snapshot data from a Firestore document, throwing if the document does not exist.
+ *
+ * @param document - The Firestore document to load data from.
+ * @param message - Optional custom error message.
+ * @throws {HttpsError} Throws a {@link modelNotAvailableError} (404) if the document has no data.
  *
- * @param document
- * @param message
- * @returns
+ * @example
+ * ```typescript
+ * const userData = await assertSnapshotData(userDocument);
+ * ```
  */
 export declare function assertSnapshotData<D extends FirestoreDocument<any>>(document: D, message?: string): Promise<FirestoreDocumentData<D>>;
 /**
- * Convenience function for assertSnapshotData that also attaches the id and key of the document to the data.
+ * Loads snapshot data and attaches the document's `id` and `key` to the result.
+ *
+ * Combines {@link assertSnapshotData} with {@link setIdAndKeyFromKeyIdRefOnDocumentData}.
  *
- * @param document
- * @param message
- * @returns
+ * @param document - The Firestore document to load data from.
+ * @param message - Optional custom error message.
+ * @throws {HttpsError} Throws a {@link modelNotAvailableError} (404) if the document has no data.
  */
 export declare function assertSnapshotDataWithKey<D extends FirestoreDocument<any>>(document: D, message?: string): Promise<DocumentDataWithIdAndKey<FirestoreDocumentData<D>>>;
 /**
- * Asserts that the document exists. A modelNotAvailableError is thrown if the document does not exist.
+ * Asserts that the Firestore document exists without loading its data.
  *
- * @param document
- * @param message
- * @returns
+ * @param document - The Firestore document to check.
+ * @param message - Optional custom error message.
+ * @throws {HttpsError} Throws a {@link modelNotAvailableError} (404) if the document does not exist.
  */
 export declare function assertDocumentExists<D extends FirestoreDocument<any>>(document: D, message?: string): Promise<void>;
 /**
- * Error thrown by assertDocumentExists().
+ * Creates a {@link modelNotAvailableError} for the given document's model type.
  *
- * @param document
- * @param message
- * @returns
+ * Used by {@link assertDocumentExists} and other assertion functions.
  */
 export declare function documentModelNotAvailableError(document: Pick<FirestoreDocument<any>, 'modelType'>, message?: string): import("firebase-functions/https").HttpsError;

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

@@ -1,4 +1,30 @@
 import { type CallableContext } from '../type';
+/**
+ * A {@link CallableContext} narrowed to guarantee that `auth` data is present.
+ *
+ * Used as the base context type for authenticated function handlers throughout `@dereekb/firebase-server`.
+ */
 export type CallableContextWithAuthData<R extends CallableContext = CallableContext> = Omit<R, 'auth'> & Required<Pick<R, 'auth'>>;
+/**
+ * Type guard that checks whether the given callable context contains authenticated user data (non-null auth with a uid).
+ *
+ * @example
+ * ```typescript
+ * if (isContextWithAuthData(context)) {
+ *   console.log(context.auth.uid);
+ * }
+ * ```
+ */
 export declare function isContextWithAuthData<R extends CallableContext>(context: CallableContext): context is CallableContextWithAuthData<R>;
+/**
+ * Asserts that the callable context contains authenticated user data.
+ *
+ * @throws {HttpsError} Throws an unauthenticated error if auth data is missing.
+ *
+ * @example
+ * ```typescript
+ * assertIsContextWithAuthData(context);
+ * // context.auth is now guaranteed to be present
+ * ```
+ */
 export declare function assertIsContextWithAuthData<R extends CallableContext>(context: CallableContext): asserts context is CallableContextWithAuthData<R>;

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

@@ -1,5 +1,20 @@
 import { type ThrowErrorFunction } from '@dereekb/util';
 import type * as admin from 'firebase-admin';
+/**
+ * Error code for when a phone number is already registered in Firebase Auth.
+ */
 export declare const PHONE_NUMBER_ALREADY_EXISTS_ERROR_CODE = "PHONE_NUMBER_ALREADY_EXISTS";
+/**
+ * Creates a precondition conflict (409) error indicating the phone number already exists.
+ */
 export declare function phoneNumberAlreadyExistsError(): import("firebase-functions/https").HttpsError;
+/**
+ * Handles Firebase Auth errors by mapping known error codes to typed HTTP errors.
+ *
+ * Currently maps `auth/phone-number-already-exists` to a 409 conflict error.
+ * Unknown error codes are forwarded to the optional handler.
+ *
+ * @param e - The caught error.
+ * @param handleUnknownCode - Optional handler for Firebase errors with unrecognized codes.
+ */
 export declare function handleFirebaseAuthError(e: unknown, handleUnknownCode?: ThrowErrorFunction<admin.FirebaseError>): never | void;

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

@@ -2,33 +2,62 @@ import { type ErrorMessageOrPartialServerError, type ServerError, type StringErr
 import type * as admin from 'firebase-admin';
 import { type FirebaseErrorCode } from '@dereekb/firebase';
 import { HttpsError } from 'firebase-functions/https';
+/**
+ * Creates an unauthenticated {@link HttpsError} indicating the request context has no auth data.
+ */
 export declare function unauthenticatedContextHasNoAuthData(): HttpsError;
+/**
+ * Creates an unauthenticated {@link HttpsError} indicating the request context has no user UID.
+ */
 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}. */
 export declare function unauthenticatedError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const FORBIDDEN_ERROR_CODE = "FORBIDDEN";
+/** Creates a forbidden (403) {@link HttpsError}. */
 export declare function forbiddenError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const PERMISSION_DENIED_ERROR_CODE = "PERMISSION_DENIED";
+/** Creates a permission-denied (403) {@link HttpsError}. */
 export declare function permissionDeniedError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const NOT_FOUND_ERROR_CODE = "NOT_FOUND";
+/** Creates a not-found (404) {@link HttpsError}. */
 export declare function notFoundError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const MODEL_NOT_AVAILABLE_ERROR_CODE = "MODEL_NOT_AVAILABLE";
+/** Creates a model-not-available (404) {@link HttpsError}, used when a Firestore document does not exist. */
 export declare function modelNotAvailableError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const BAD_REQUEST_ERROR_CODE = "BAD_REQUEST";
+/** Creates a bad-request (400) {@link HttpsError}. */
 export declare function badRequestError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const CONFLICT_ERROR_CODE = "CONFLICT";
+/** Creates a precondition-conflict (409) {@link HttpsError}. */
 export declare function preconditionConflictError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const ALREADY_EXISTS_ERROR_CODE = "ALREADY_EXISTS";
+/** Creates an already-exists (409) {@link HttpsError}. */
 export declare function alreadyExistsError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const UNAVAILABLE_ERROR_CODE = "UNAVAILABLE";
+/** Creates an unavailable (503) {@link HttpsError}. */
 export declare function unavailableError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE = "UNAVAILABLE_OR_DEACTIVATED_FUNCTION";
+/** Creates an unimplemented (501) {@link HttpsError} for deactivated or unavailable functions. */
 export declare function unavailableOrDeactivatedFunctionError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
 export declare const INTERNAL_SERVER_ERROR_CODE = "INTERNAL_ERROR";
+/** Creates an internal-error (500) {@link HttpsError}. */
 export declare function internalServerError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
+/**
+ * Discriminator for the type of Firebase server error encountered.
+ */
 export type FirebaseServerErrorInfoType = 'httpsError' | 'firebaseError' | 'unknown';
 /**
- * Server error information
+ * Structured information extracted from a caught Firebase server error.
+ *
+ * Provides typed access to the original error, Firebase error codes, and any
+ * embedded {@link ServerError} details from {@link HttpsError} instances.
  */
 export interface FirebaseServerErrorInfo {
     /**
@@ -60,16 +89,51 @@ export interface FirebaseServerErrorInfo {
      */
     readonly firebaseError?: admin.FirebaseError;
 }
+/**
+ * Type guard for Firebase {@link HttpsError} instances.
+ */
 export declare function isFirebaseHttpsError(input: unknown | HttpsError): input is HttpsError;
+/**
+ * Type guard for Firebase Admin {@link admin.FirebaseError} instances.
+ */
 export declare function isFirebaseError(input: unknown | admin.FirebaseError): input is admin.FirebaseError;
 /**
- * Creates a FirebaseServerErrorInfo from the input.
+ * Analyzes a caught error and extracts structured Firebase error information.
+ *
+ * Classifies the error as an {@link HttpsError}, {@link admin.FirebaseError}, or unknown,
+ * and extracts any embedded error codes and {@link ServerError} details.
  *
- * @param e
- * @returns
+ * @param e - The caught error to analyze.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someFirebaseOperation();
+ * } catch (e) {
+ *   const info = firebaseServerErrorInfo(e);
+ *   if (info.serverErrorCode === 'MODEL_NOT_AVAILABLE') { ... }
+ * }
+ * ```
  */
 export declare function firebaseServerErrorInfo(e: unknown): FirebaseServerErrorInfo;
+/**
+ * Returns a tuple of [firebaseErrorCode, errorInfo] for pattern-matching on Firebase error codes.
+ */
 export declare function firebaseServerErrorInfoCodePair(e: unknown): [FirebaseErrorCode | undefined, FirebaseServerErrorInfo];
+/**
+ * Returns a tuple of [serverError, errorInfo] for pattern-matching on embedded server error details.
+ */
 export declare function firebaseServerErrorInfoServerErrorPair(e: unknown): [ServerError | undefined, FirebaseServerErrorInfo];
+/**
+ * Returns a tuple of [serverErrorCode, errorInfo] for pattern-matching on server error string codes.
+ */
 export declare function firebaseServerErrorInfoServerErrorCodePair(e: unknown): [StringErrorCode | undefined, FirebaseServerErrorInfo];
+/**
+ * Handles a caught error if it is a Firebase Admin error, passing it to the given handler function.
+ *
+ * If the error is not a Firebase error (no `code` property), this is a no-op.
+ *
+ * @param e - The caught error.
+ * @param handleFirebaseErrorFn - Handler that receives the typed {@link admin.FirebaseError}.
+ */
 export declare function handleFirebaseError(e: unknown, handleFirebaseErrorFn: ThrowErrorFunction<admin.FirebaseError>): never | void;

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

@@ -1,14 +1,26 @@
-import { type ClassType, type Getter } from '@dereekb/util';
+import { type ClassType, type Getter, type WebsitePath } from '@dereekb/util';
 import { type INestApplication, type INestApplicationContext, type NestApplicationOptions, type Provider } from '@nestjs/common';
 import express from 'express';
 import type * as admin from 'firebase-admin';
 import { type StorageBucketId } from '@dereekb/firebase';
-import { type ServerEnvironmentConfig } from '@dereekb/nestjs';
+import { type FirebaseServerEnvironmentConfig } from '../env/env.config';
+import { type GlobalRoutePrefixConfig } from './middleware/globalprefix';
+/**
+ * A running NestJS server instance backed by Express, paired with a lazy promise getter for the NestJS application context.
+ */
 export interface NestServer {
     readonly server: express.Express;
     readonly nest: NestAppPromiseGetter;
 }
+/**
+ * Lazy getter that returns a promise resolving to the initialized NestJS application context.
+ */
 export type NestAppPromiseGetter = Getter<Promise<INestApplicationContext>>;
+/**
+ * Manages the lifecycle of a NestJS server instance for Firebase Cloud Functions.
+ *
+ * Caches the server per Firebase app name so repeated invocations reuse the same instance.
+ */
 export interface NestServerInstance<T> {
     /**
      * Root module class of the app.
@@ -19,7 +31,7 @@ export interface NestServerInstance<T> {
      *
      * If already initialized the server will not be initialized again.
      */
-    initNestServer(firebaseApp: admin.app.App, env?: NestServerEnvironmentConfig): NestServer;
+    initNestServer(firebaseApp: admin.app.App, env?: NestFirebaseServerEnvironmentConfig): NestServer;
     /**
      * Terminates the nest server for the input app.
      *
@@ -27,9 +39,26 @@ export interface NestServerInstance<T> {
      */
     removeNestServer(firebaseApp: admin.app.App): Promise<boolean>;
 }
-export declare class FirebaseNestServerRootModule {
-}
+/** @deprecated Use `FirebaseNestServerRootModule` from `./app.module` instead. */
+export { FirebaseNestServerRootModule } from './app.module';
+/**
+ * Optional hook to customize the NestJS application after creation but before initialization.
+ */
 export type ConfigureNestServerInstanceFunction = (nestApp: INestApplication) => INestApplication | void;
+/**
+ * Configuration for creating a {@link NestServerInstance}, including the root module class,
+ * global providers, middleware toggles, storage defaults, and app-level options.
+ *
+ * @example
+ * ```typescript
+ * const instance = nestServerInstance({
+ *   moduleClass: AppModule,
+ *   appCheckEnabled: true,
+ *   globalApiRoutePrefix: '/api',
+ *   configureWebhooks: true
+ * });
+ * ```
+ */
 export interface NestServerInstanceConfig<T> {
     /**
      * Module to instantiate.
@@ -66,17 +95,32 @@ export interface NestServerInstanceConfig<T> {
      */
     readonly applicationOptions?: NestApplicationOptions;
     /**
-     * Global routing prefix.
+     * Global routing prefix or options.
      *
      * Example: '/api'
      */
-    readonly globalApiRoutePrefix?: string;
+    readonly globalApiRoutePrefix?: WebsitePath | GlobalRoutePrefixConfig;
     /**
      * Optional configuration function
      */
     readonly configureNestServerInstance?: ConfigureNestServerInstanceFunction;
 }
-export interface NestServerEnvironmentConfig {
-    readonly environment: ServerEnvironmentConfig;
+export interface NestFirebaseServerEnvironmentConfig {
+    readonly environment: FirebaseServerEnvironmentConfig;
 }
+/** @deprecated Use NestFirebaseServerEnvironmentConfig instead. */
+export type NestServerEnvironmentConfig = NestFirebaseServerEnvironmentConfig;
+/**
+ * Creates a {@link NestServerInstance} that manages NestJS server lifecycle within Firebase Cloud Functions.
+ *
+ * The returned instance caches servers by Firebase app name, so calling `initNestServer` multiple
+ * times with the same app reuses the existing server. The factory wires up Firebase Admin,
+ * environment config, storage, AppCheck middleware, and webhook routes based on the config.
+ *
+ * @example
+ * ```typescript
+ * const instance = nestServerInstance({ moduleClass: AppModule, appCheckEnabled: true });
+ * const { server } = instance.initNestServer(firebaseApp, { environment: envConfig });
+ * ```
+ */
 export declare function nestServerInstance<T>(config: NestServerInstanceConfig<T>): NestServerInstance<T>;

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

@@ -0,0 +1,90 @@
+import { type ArrayOrValue, type ClassType, type Getter, type Maybe, type WebsitePath } from '@dereekb/util';
+import { type DynamicModule, type Provider } from '@nestjs/common';
+import { type StorageBucketId } from '@dereekb/firebase';
+import { type FirebaseServerEnvironmentConfig } from '../env/env.config';
+import { GlobalRoutePrefixConfig } from './middleware/globalprefix';
+import type * as admin from 'firebase-admin';
+export declare class FirebaseNestServerRootModule {
+}
+/**
+ * Configuration for building the shared NestJS root module used by both
+ * production (`nestServerInstance`) and test (`firebaseAdminNestContextWithFixture`) setups.
+ *
+ * This ensures both environments use the same provider assembly logic so they don't drift apart.
+ */
+export interface NestServerRootModuleConfig {
+    /**
+     * Module(s) to import into the root module.
+     */
+    readonly modules: ArrayOrValue<ClassType | DynamicModule>;
+    /**
+     * Getter for the Firebase Admin app instance.
+     * When provided, the `FIREBASE_APP_TOKEN` is made available globally.
+     */
+    readonly firebaseAppGetter?: Maybe<Getter<admin.app.App>>;
+    /**
+     * Additional providers to include globally.
+     */
+    readonly additionalProviders?: Provider[];
+    /**
+     * Environment configuration. When provided, injects env tokens via `firebaseServerEnvTokenProviders`.
+     */
+    readonly envConfig?: FirebaseServerEnvironmentConfig;
+    /**
+     * Whether to configure `FirebaseServerEnvService` / `ServerEnvironmentService`.
+     * Defaults to true when `envConfig` is provided.
+     */
+    readonly configureEnvService?: boolean;
+    /**
+     * Default storage bucket ID.
+     */
+    readonly defaultStorageBucket?: StorageBucketId;
+    /**
+     * Whether to force using the storage bucket.
+     */
+    readonly forceStorageBucket?: boolean;
+    /**
+     * Global route prefix configuration.
+     * The `GlobalRoutePrefixConfig` token is always provided (empty object when no config given).
+     */
+    readonly globalApiRoutePrefix?: WebsitePath | GlobalRoutePrefixConfig;
+    /**
+     * Whether to add the webhook middleware module.
+     */
+    readonly configureWebhooks?: boolean;
+    /**
+     * Whether to add the AppCheck middleware module.
+     * Defaults to false (production code sets this to true via `appCheckEnabled`).
+     */
+    readonly appCheckEnabled?: boolean;
+}
+/**
+ * Result of {@link buildNestServerRootModule}.
+ */
+export interface NestServerRootModuleResult {
+    /**
+     * The fully configured DynamicModule (global: true) containing
+     * all providers and imports.
+     */
+    readonly rootModule: DynamicModule;
+    /**
+     * The resolved `GlobalRoutePrefixConfig`. Callers that create
+     * an `INestApplication` can use this to call `setGlobalPrefix()`.
+     */
+    readonly globalApiRoutePrefixConfig: Maybe<GlobalRoutePrefixConfig>;
+}
+/**
+ * Builds the shared root `DynamicModule` used by both production and test setups.
+ *
+ * Assembles:
+ * - Firebase app token provider
+ * - Environment token providers and env service bindings
+ * - Additional providers
+ * - Storage bucket provider
+ * - `GlobalRoutePrefixConfig` token
+ * - Optional webhook and AppCheck middleware modules
+ *
+ * @param config - Shared configuration
+ * @returns The root module and resolved prefix config
+ */
+export declare function buildNestServerRootModule(config: NestServerRootModuleConfig): NestServerRootModuleResult;