@dereekb/firebase-server 13.2.2 → 13.3.0

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

@@ -11,19 +11,45 @@ export declare const FIREBASE_AUTH_TOKEN: InjectionToken;
  */
 export declare class FirebaseServerAuthModule {
 }
+/**
+ * Simplified provider config that receives only the Firebase Admin Auth instance.
+ */
 export type ProvideFirebaseServerAuthServiceSimple<T extends FirebaseServerAuthService> = Pick<FactoryProvider<T>, 'provide'> & {
     useFactory: (auth: admin.auth.Auth) => T;
 };
+/**
+ * Provider config for a custom {@link FirebaseServerAuthService} implementation — either a full factory
+ * provider or a simplified one that only needs the Auth instance.
+ */
 export type ProvideFirebaseServerAuthService<T extends FirebaseServerAuthService> = FactoryProvider<T> | ProvideFirebaseServerAuthServiceSimple<T>;
+/**
+ * Creates NestJS provider entries for a custom {@link FirebaseServerAuthService} implementation.
+ *
+ * Returns two providers: the concrete service and an alias that maps
+ * `FirebaseServerAuthService` to the concrete token, enabling injection by the abstract type.
+ *
+ * @example
+ * ```typescript
+ * const providers = provideFirebaseServerAuthService({
+ *   provide: MyAuthService,
+ *   useFactory: (auth) => new MyAuthService(auth)
+ * });
+ * ```
+ */
 export declare function provideFirebaseServerAuthService<T extends FirebaseServerAuthService>(provider: ProvideFirebaseServerAuthService<T>): [ProvideFirebaseServerAuthService<T>, Provider<T>];
 export interface FirebaseServerAuthModuleMetadataConfig<T extends FirebaseServerAuthService> extends AdditionalModuleMetadata {
     readonly serviceProvider: ProvideFirebaseServerAuthService<T>;
 }
 /**
- * Convenience function used to generate ModuleMetadata for an app's Auth related modules and FirebaseServerAuthService provider.
+ * Generates NestJS {@link ModuleMetadata} for an app's auth module, including the {@link FirebaseServerAuthModule}
+ * import and the custom {@link FirebaseServerAuthService} provider.
  *
- * @param provide
- * @param useFactory
- * @returns
+ * @example
+ * ```typescript
+ * @Module(firebaseServerAuthModuleMetadata({
+ *   serviceProvider: { provide: MyAuthService, useFactory: (auth) => new MyAuthService(auth) }
+ * }))
+ * export class AppAuthModule {}
+ * ```
  */
 export declare function firebaseServerAuthModuleMetadata<T extends FirebaseServerAuthService>(config: FirebaseServerAuthModuleMetadataConfig<T>): ModuleMetadata;

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

@@ -2,13 +2,51 @@ import { type UserRelated } from '@dereekb/firebase';
 import { type ArrayOrValue, type AuthRole } 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.
+ *
+ * @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;
+/**
+ * Checks whether the caller has admin privileges in the request.
+ */
 export declare function isAdminInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>): boolean;
+/**
+ * Asserts that the caller is either an admin or is targeting their own user record.
+ *
+ * If the request data contains a `uid` that differs from the caller's auth UID, admin status is required.
+ *
+ * @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;
+/**
+ * Checks whether the caller is an admin or is targeting their own user record in the request data.
+ *
+ * @param requireUid - If true, a UID must be present in the request data.
+ */
 export declare function isAdminOrTargetUserInRequestData<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I extends Partial<UserRelated> = Partial<UserRelated>>(request: NestContextCallableRequestWithOptionalAuth<N, I>, requireUid?: boolean): boolean;
+/**
+ * Asserts that the caller has signed the Terms of Service.
+ *
+ * @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;
+/**
+ * Checks whether the caller has signed the Terms of Service.
+ */
 export declare function hasSignedTosInRequest<N extends AbstractFirebaseNestContext<any, any> = AbstractFirebaseNestContext<any, any>, I = unknown>(request: NestContextCallableRequestWithOptionalAuth<N, I>): boolean;
+/**
+ * Asserts that the caller has all of the specified auth roles.
+ *
+ * @param authRoles - One or more roles that must all be present.
+ * @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;
+/**
+ * Checks whether 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;
 /**
  * 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/auth.context.server.d.ts

@@ -0,0 +1,27 @@
+import { type AuthData } from '../../type';
+import { type Request } from 'express';
+/**
+ * Minimum auth data shape shared by all server-side auth contexts.
+ *
+ * Both Firebase's {@link AuthData} and OAuth auth contexts satisfy this interface.
+ */
+export interface FirebaseServerAuthData extends AuthData {
+    /**
+     * The authenticated user's UID.
+     */
+    readonly uid: string;
+}
+/**
+ * Extends Express Request with an `auth` field for authenticated requests.
+ *
+ * Generic over the auth context type, constrained to {@link FirebaseServerAuthData}
+ * so all auth contexts guarantee at least a `uid`.
+ *
+ * @typeParam A - The auth context type. Defaults to {@link FirebaseServerAuthData}.
+ */
+export interface FirebaseServerAuthenticatedRequest<A extends FirebaseServerAuthData = FirebaseServerAuthData> extends Request {
+    /**
+     * The auth in this request. Should not be changed.
+     */
+    readonly auth?: A;
+}

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

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

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

@@ -5,14 +5,30 @@ import { type NestApplicationScheduleConfiguredFunctionMap } from '../function/s
 import { type OnCallHandlerWithNestContextFactory } from '../function/v2/call';
 import { type AbstractFirebaseNestContext } from '../nest.provider';
 import { type OnCallDevelopmentFunctionMap } from './development.function';
+/**
+ * Configuration for {@link firebaseServerDevFunctions}.
+ *
+ * Controls whether development endpoints are active, what operations they expose,
+ * and whether they require authentication. In production, set `enabled: false`
+ * to replace dev endpoints with a stub that returns an "unavailable" error.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam S - The schedule function map type.
+ */
 export interface FirebaseServerDevFunctionsConfig<N extends AbstractFirebaseNestContext<any, any>, S extends NestApplicationScheduleConfiguredFunctionMap> {
+    /** When false, dev endpoints return an "unavailable" error instead of executing. */
     readonly enabled: boolean;
     /**
      * Whether or not to require an auth context when calling dev functions. True by default.
+     *
+     * Set to false only in local development where authentication is unavailable.
      */
     readonly secure?: boolean;
+    /** Getter for the NestJS application promise, used to bootstrap the context. */
     readonly nest: NestAppPromiseGetter;
+    /** Map of specifier keys to developer utility functions. */
     readonly developerFunctionsMap: OnCallDevelopmentFunctionMap<N>;
+    /** Factory that wraps a handler function with NestJS context resolution. */
     readonly onCallFactory: OnCallHandlerWithNestContextFactory<N>;
     /**
      * Whether or not to disable adding the dev schedule function. False by default.
@@ -23,7 +39,36 @@ export interface FirebaseServerDevFunctionsConfig<N extends AbstractFirebaseNest
      */
     readonly allScheduledFunctions?: S;
 }
+/**
+ * The output of {@link firebaseServerDevFunctions}, containing the `dev` callable function
+ * keyed by {@link RUN_DEV_FUNCTION_APP_FUNCTION_KEY}.
+ *
+ * Spread this into your Firebase Functions exports to register the dev endpoint.
+ */
 export interface FirebaseServerDevFunctions {
     readonly [RUN_DEV_FUNCTION_APP_FUNCTION_KEY]: RunnableHttpFunction<OnCallDevelopmentParams> | CallableHttpFunction<OnCallDevelopmentParams>;
 }
+/**
+ * Creates the development callable function bundle for a Firebase + NestJS server.
+ *
+ * When `enabled` is true, wires together the developer function map, optionally
+ * includes the scheduled-function runner, and wraps everything in the NestJS context.
+ * When `enabled` is false, returns a stub that throws an "unavailable" error.
+ *
+ * @param config - Controls which dev functions are exposed and how they are secured.
+ * @returns An object with the `dev` function, ready to be spread into Firebase exports.
+ *
+ * @example
+ * ```typescript
+ * const devFunctions = firebaseServerDevFunctions({
+ *   enabled: environment.dev,
+ *   nest: getNestApp,
+ *   developerFunctionsMap: { initData: initDataFunction },
+ *   onCallFactory: myOnCallFactory,
+ *   allScheduledFunctions: scheduledFunctions
+ * });
+ *
+ * export const { dev } = devFunctions;
+ * ```
+ */
 export declare function firebaseServerDevFunctions<N extends AbstractFirebaseNestContext<any, any>, S extends NestApplicationScheduleConfiguredFunctionMap>(config: FirebaseServerDevFunctionsConfig<N, S>): FirebaseServerDevFunctions;

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

@@ -1,9 +1,27 @@
 import { type NestContextCallableRequest } from '../function/nest';
+/**
+ * Context passed to a {@link AssertDevelopmentRequestFunction} before a development
+ * function handler executes.
+ *
+ * Provides the original request and the specifier identifying which dev function
+ * is being called, enabling assertions to gate access on a per-function basis.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type of the request.
+ */
 export interface AssertDevelopmentRequestFunctionContext<N, I = unknown> {
+    /** The original callable request including the NestJS context and caller data. */
     readonly request: NestContextCallableRequest<N, I>;
+    /** The development function specifier string identifying which dev operation was requested. */
     readonly specifier: string;
 }
 /**
- * Function that asserts something given the input request.
+ * Pre-assertion hook invoked before a development function handler executes.
+ *
+ * Throw an error to reject the request. Useful for restricting which development
+ * functions are accessible in certain environments or to specific callers.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type of the request.
  */
 export type AssertDevelopmentRequestFunction<N, I = unknown> = (context: AssertDevelopmentRequestFunctionContext<N, I>) => void;

package/src/lib/nest/development/development.function.d.ts

@@ -3,18 +3,57 @@ import { type OnCallDevelopmentParams, type DevelopmentFirebaseFunctionSpecifier
 import { type OnCallWithNestContext } from '../function/call';
 import { type NestContextCallableRequest } from '../function/nest';
 import { type AssertDevelopmentRequestFunction } from './development.assert.function';
+/**
+ * A single development function handler.
+ *
+ * Receives the NestJS context request with unwrapped inner data and the specifier
+ * identifying which dev operation was requested.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type.
+ * @typeParam O - The output type.
+ */
 export type OnCallDevelopmentFunction<N, I = unknown, O = unknown> = (request: NestContextCallableRequest<N, I> & DevelopmentFirebaseFunctionSpecifierRef) => PromiseOrValue<O>;
+/**
+ * Maps specifier strings to development function handlers.
+ *
+ * Each key is a specifier that clients pass in the `specifier` field of
+ * {@link OnCallDevelopmentParams} to invoke a specific dev operation.
+ *
+ * @typeParam N - The NestJS context type.
+ */
 export type OnCallDevelopmentFunctionMap<N> = {
     readonly [key: string]: OnCallDevelopmentFunction<N, any, any>;
 };
+/**
+ * Configuration for {@link onCallDevelopmentFunction}.
+ *
+ * @typeParam N - The NestJS context type.
+ */
 export interface OnCallDevelopmentConfig<N> {
+    /** Optional assertion run before the dev handler; throw to reject the request. */
     readonly preAssert?: AssertDevelopmentRequestFunction<N, OnCallDevelopmentParams>;
 }
 /**
- * Creates a OnCallWithAuthorizedNestContext function for creating a model.
+ * Factory that creates a callable function dispatching to development utility handlers.
+ *
+ * Incoming requests carry a `specifier` field that selects the appropriate handler
+ * from the provided map. The inner `data` payload is unwrapped and forwarded to the handler.
  *
- * @param map
- * @returns
+ * @param map - Maps specifier strings to development function handlers.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function that dispatches to the correct dev handler by specifier.
+ *
+ * @example
+ * ```typescript
+ * const devFunction = onCallDevelopmentFunction<DemoNestContext>({
+ *   initData: initDataFunction,
+ *   resetData: resetDataFunction
+ * });
+ * ```
  */
 export declare function onCallDevelopmentFunction<N>(map: OnCallDevelopmentFunctionMap<N>, config?: OnCallDevelopmentConfig<N>): OnCallWithNestContext<N, OnCallDevelopmentParams>;
+/**
+ * Creates a bad-request error indicating the provided development function specifier is not recognized.
+ */
 export declare function developmentUnknownSpecifierError(specifier: DevelopmentFirebaseFunctionSpecifier): import("firebase-functions/https").HttpsError;

package/src/lib/nest/development/development.schedule.function.d.ts

@@ -1,7 +1,36 @@
 import { type ScheduledFunctionDevelopmentFirebaseFunctionParams, type ScheduledFunctionDevelopmentFirebaseFunctionResult } from '@dereekb/firebase';
 import { type NestApplicationScheduleConfiguredFunctionMap } from '../function/schedule';
 import { type OnCallDevelopmentFunction } from './development.function';
+/**
+ * Configuration for {@link makeScheduledFunctionDevelopmentFunction}.
+ */
 export interface MakeScheduledFunctionDevelopmentFunctionConfig {
+    /** The complete map of registered scheduled functions that can be triggered manually. */
     readonly allScheduledFunctions: NestApplicationScheduleConfiguredFunctionMap;
 }
+/**
+ * Creates a development function that allows manually triggering or listing scheduled functions.
+ *
+ * Supports two operation types:
+ * - `'run'` - Executes a scheduled function by name via its `_runNow()` method.
+ * - `'list'` - Returns a list of all available scheduled function names.
+ *
+ * This is intended for development and testing environments where you need to
+ * trigger scheduled jobs on demand without waiting for their cron schedule.
+ *
+ * @param config - Provides the map of all scheduled functions available for manual execution.
+ * @returns A development function handler compatible with {@link OnCallDevelopmentFunctionMap}.
+ *
+ * @example
+ * ```typescript
+ * const scheduleDev = makeScheduledFunctionDevelopmentFunction({
+ *   allScheduledFunctions: myScheduledFunctions
+ * });
+ *
+ * // Register it in the dev function map:
+ * const devFunctions: OnCallDevelopmentFunctionMap<MyContext> = {
+ *   [SCHEDULED_FUNCTION_DEV_FUNCTION_SPECIFIER]: scheduleDev
+ * };
+ * ```
+ */
 export declare function makeScheduledFunctionDevelopmentFunction(config: MakeScheduledFunctionDevelopmentFunctionConfig): OnCallDevelopmentFunction<unknown, ScheduledFunctionDevelopmentFirebaseFunctionParams, ScheduledFunctionDevelopmentFirebaseFunctionResult>;

package/src/lib/nest/development/development.schedule.function.error.d.ts

@@ -1,6 +1,27 @@
+/**
+ * Error code used when a 'run' request is missing the target function name.
+ */
 export declare const NO_RUN_NAME_SPECIFIED_FOR_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_CODE = "NO_RUN_NAME_SPECIFIED_FOR_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION";
+/**
+ * Creates a bad-request error for when the caller sends a 'run' command
+ * without specifying which scheduled function to execute.
+ */
 export declare function noRunNameSpecifiedForScheduledFunctionDevelopmentFunction(): import("firebase-functions/https").HttpsError;
+/**
+ * Error code used when the requested scheduled function name does not exist in the function map.
+ */
 export declare const UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE = "UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME";
+/**
+ * Creates a bad-request error for when the requested scheduled function name
+ * is not found in the registered function map.
+ */
 export declare function unknownScheduledFunctionDevelopmentFunctionName(name: unknown): import("firebase-functions/https").HttpsError;
+/**
+ * Error code used when the request `type` field is neither 'run' nor 'list'.
+ */
 export declare const UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE = "UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE";
+/**
+ * Creates a bad-request error for when the request `type` field does not match
+ * any supported operation ('run' or 'list').
+ */
 export declare function unknownScheduledFunctionDevelopmentFunctionType(type: unknown): import("firebase-functions/https").HttpsError;

package/src/lib/nest/env/env.service.d.ts

@@ -1,8 +1,17 @@
 import { ServerEnvironmentService } from '@dereekb/nestjs';
 import { type FirebaseServerEnvService } from '../../env/env.service';
+import { type Maybe, type WebsiteUrlDetails } from '@dereekb/util';
+/**
+ * Default NestJS injectable implementation of {@link FirebaseServerEnvService}.
+ *
+ * Extends {@link ServerEnvironmentService} from `@dereekb/nestjs` and adds
+ * Firebase-specific environment properties like `appUrl` and `developmentSchedulerEnabled`.
+ */
 export declare class DefaultFirebaseServerEnvService extends ServerEnvironmentService implements FirebaseServerEnvService {
+    private readonly _appUrlDetails;
     /**
      * Enabled when not in production and not in a testing environment.
      */
     get developmentSchedulerEnabled(): boolean;
+    get appUrlDetails(): Maybe<WebsiteUrlDetails>;
 }

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

@@ -1,4 +1,20 @@
 import { type AsyncDecisionFunction } from '@dereekb/util';
 import { type NestAppPromiseGetter } from '../app';
+/**
+ * Creates an async decision function that resolves to `true` if the NestJS app is running in production.
+ *
+ * Useful for conditionally enabling production-only Cloud Functions (e.g., scheduled tasks).
+ *
+ * @example
+ * ```typescript
+ * const isProduction = nestAppIsProductionEnvironment(nestAppGetter);
+ * if (await isProduction()) { ... }
+ * ```
+ */
 export declare function nestAppIsProductionEnvironment(nest: NestAppPromiseGetter): AsyncDecisionFunction<void>;
+/**
+ * Creates an async decision function that resolves to `true` if the development scheduler is enabled.
+ *
+ * The development scheduler is enabled in non-production, non-testing environments.
+ */
 export declare function nestAppHasDevelopmentSchedulerEnabled(nest: NestAppPromiseGetter): AsyncDecisionFunction<void>;

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

@@ -1,7 +1,19 @@
 import type * as admin from 'firebase-admin';
 import { type FactoryProvider, type InjectionToken } from '@nestjs/common';
 /**
- * Nest Injection Token to access the
+ * NestJS injection token for the Firebase Admin {@link admin.app.App} instance.
+ *
+ * Injected globally by {@link nestServerInstance} during server initialization.
  */
 export declare const FIREBASE_APP_TOKEN: InjectionToken;
+/**
+ * Creates a NestJS {@link FactoryProvider} that binds a Firebase Admin app getter to {@link FIREBASE_APP_TOKEN}.
+ *
+ * @param useFactory - Factory function returning the Firebase Admin app instance.
+ *
+ * @example
+ * ```typescript
+ * const provider = firebaseServerAppTokenProvider(() => admin.app());
+ * ```
+ */
 export declare function firebaseServerAppTokenProvider(useFactory: () => admin.app.App): FactoryProvider<admin.app.App>;

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

@@ -19,26 +19,42 @@ export declare class FirebaseServerFirestoreModule {
  */
 export declare class FirebaseServerFirestoreContextModule {
 }
+/**
+ * Factory function that creates an app's Firestore collections instance from a {@link FirestoreContext}.
+ */
 export type ProvideAppFirestoreCollectionsFactory<T> = (context: FirestoreContext) => T;
+/**
+ * Configuration for providing an app's Firestore collections class via NestJS DI.
+ */
 export interface ProvideAppFirestoreCollectionsConfig<T> {
     provide: ClassLikeType<T>;
     useFactory: ProvideAppFirestoreCollectionsFactory<T>;
 }
 /**
- * Used to configure a Nestjs provider for a FirestoreCollections-type object that is initialized with a FirestoreContext.
+ * Creates a NestJS provider that initializes a Firestore collections instance from the app's {@link FirestoreContext}.
  *
- * @param type
- * @param useFactory
- * @returns
+ * @example
+ * ```typescript
+ * const [provider] = provideAppFirestoreCollections({
+ *   provide: DemoFirestoreCollections,
+ *   useFactory: (context) => new DemoFirestoreCollections(context)
+ * });
+ * ```
  */
 export declare function provideAppFirestoreCollections<T>({ provide, useFactory }: ProvideAppFirestoreCollectionsConfig<T>): [Provider<T>];
 export interface ProvideAppFirestoreModuleMetadataConfig<T> extends ProvideAppFirestoreCollectionsConfig<T>, Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
 }
 /**
- * Convenience function used to generate ModuleMetadata for an app's Firestore related modules and an appFirestoreCollection
+ * Generates NestJS {@link ModuleMetadata} for an app's Firestore module, including the
+ * {@link FirebaseServerFirestoreContextModule} import and the app's collections provider.
  *
- * @param provide
- * @param useFactory
- * @returns
+ * @example
+ * ```typescript
+ * @Module(appFirestoreModuleMetadata({
+ *   provide: DemoFirestoreCollections,
+ *   useFactory: (context) => new DemoFirestoreCollections(context)
+ * }))
+ * export class AppFirestoreModule {}
+ * ```
  */
 export declare function appFirestoreModuleMetadata<T>(config: ProvideAppFirestoreModuleMetadataConfig<T>): ModuleMetadata;

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

@@ -2,31 +2,89 @@ import { type PromiseOrValue } from '@dereekb/util';
 import { type CallableRequest } from 'firebase-functions/v2/https';
 import { type NestApplicationContextRequest, type NestContextCallableRequest, type NestContextCallableRequestWithAuth } from './nest';
 import { type MakeNestContext } from '../nest.provider';
+/**
+ * Request type for callable functions that receive an {@link INestApplicationContext} alongside the Firebase callable request data.
+ *
+ * @typeParam I - The expected input data type for the callable request.
+ */
 export type OnCallWithNestApplicationRequest<I> = NestApplicationContextRequest<CallableRequest<I>>;
 /**
  * Runnable function that is passed an INestApplicationContext in addition to the usual data/context provided by firebase.
  */
 export type OnCallWithNestApplication<I = unknown, O = unknown> = (request: OnCallWithNestApplicationRequest<I>) => PromiseOrValue<O>;
+/**
+ * Request type for callable functions that receive a typed nest context object alongside the Firebase callable request data.
+ *
+ * @typeParam N - The nest context type, typically an application-specific context class.
+ * @typeParam I - The expected input data type for the callable request.
+ */
 export type OnCallWithNestContextRequest<N, I> = NestContextCallableRequest<N, I>;
 /**
  * Runnable function that is passed an arbitrary nest context object in addition to the usual data/context provided by firebase.
  */
 export type OnCallWithNestContext<N, I = unknown, O = unknown> = (request: OnCallWithNestContextRequest<N, I>) => PromiseOrValue<O>;
+/**
+ * Mutates the application-level request to attach a typed nest context, converting it to an {@link OnCallWithNestContextRequest}.
+ *
+ * This bridges the gap between the raw NestJS application context and the domain-specific context object
+ * used by callable function handlers.
+ *
+ * @param makeNestContext - Factory that creates the typed context from the application context.
+ * @param request - The application-level callable request to augment.
+ * @returns The same request object, now typed with the nest context attached.
+ */
 export declare function setNestContextOnRequest<N, I>(makeNestContext: MakeNestContext<N>, request: OnCallWithNestApplicationRequest<I>): OnCallWithNestContextRequest<N, I>;
+/**
+ * Callable function handler that requires authenticated requests. The request's auth data is guaranteed to be present.
+ *
+ * Use {@link inAuthContext} to wrap this handler with runtime auth assertion, or use {@link assertRequestRequiresAuthForFunction}
+ * to check auth requirements dynamically.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam I - The expected input data type.
+ * @typeParam O - The return type.
+ */
 export type OnCallWithAuthorizedNestContext<N, I = unknown, O = unknown> = ((request: NestContextCallableRequestWithAuth<N, I>) => PromiseOrValue<O>) & {
     readonly _requiresAuth?: true;
 };
+/**
+ * Callable function handler that explicitly does not require authentication.
+ *
+ * Created via {@link optionalAuthContext} to flag a handler as accepting unauthenticated requests.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam I - The expected input data type.
+ * @typeParam O - The return type.
+ */
 export type OnCallWithOptionalAuthorizedNestContext<N, I = unknown, O = unknown> = OnCallWithNestContext<N, I, O> & {
     readonly _requireAuth: false;
 };
 /**
- * Wraps the input OnCallWithNestContext function to flag it as optional to have auth data.
+ * Wraps the input {@link OnCallWithNestContext} function to flag it as not requiring authentication.
  *
- * @param fn
- * @returns
+ * By default, callable functions with auth-aware nest context require auth. Use this wrapper to
+ * explicitly opt out of that requirement for endpoints that should be publicly accessible.
+ *
+ * @example
+ * ```ts
+ * const handler = optionalAuthContext<MyContext, Input, Output>((request) => {
+ *   // request.auth may be undefined
+ *   return doSomething(request);
+ * });
+ * ```
+ *
+ * @param fn - The callable function handler to wrap.
+ * @returns A new handler flagged with `_requireAuth: false`.
  */
 export declare function optionalAuthContext<N, I, O>(fn: OnCallWithNestContext<N, I, O>): OnCallWithOptionalAuthorizedNestContext<N, I, O>;
+/**
+ * Union type representing a callable function handler that may or may not require authentication,
+ * determined at runtime by the {@link OnCallWithAuthAwareNestRequireAuthRef._requireAuth} flag.
+ */
 export type OnCallWithAuthAwareNestContext<N, I = unknown, O = unknown> = (OnCallWithAuthorizedNestContext<N, I, O> | OnCallWithOptionalAuthorizedNestContext<N, I, O>) & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Ref interface used to determine whether a callable function handler requires authentication at runtime.
+ */
 export interface OnCallWithAuthAwareNestRequireAuthRef {
     /**
      * If false, auth is not required.
@@ -43,9 +101,20 @@ export interface OnCallWithAuthAwareNestRequireAuthRef {
  */
 export declare function assertRequestRequiresAuthForFunction(fn: OnCallWithAuthAwareNestRequireAuthRef, request: OnCallWithNestContextRequest<any, any>): void;
 /**
- * Creates an OnCallWithNestContext wrapper that validates the input CallableContext to assert the context has auth data before entering the function.
+ * Wraps an {@link OnCallWithAuthorizedNestContext} handler to enforce authentication at runtime.
  *
- * @param fn
- * @returns
+ * The wrapper calls {@link assertIsContextWithAuthData} before invoking the handler, ensuring that
+ * unauthenticated requests are rejected with an appropriate error before reaching handler logic.
+ *
+ * @example
+ * ```ts
+ * const secureHandler = inAuthContext<MyContext, Input, Output>((request) => {
+ *   // request.auth is guaranteed to be defined here
+ *   return processAuthenticatedRequest(request);
+ * });
+ * ```
+ *
+ * @param fn - The authorized handler to wrap with auth assertion.
+ * @returns A general {@link OnCallWithNestContext} handler that asserts auth before delegating.
  */
 export declare function inAuthContext<N, I, O>(fn: OnCallWithAuthorizedNestContext<N, I, O>): OnCallWithNestContext<N, I, O>;