@dereekb/firebase-server 13.2.1 → 13.3.0

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

@@ -4,14 +4,46 @@ import { type TransformAndValidateFunctionResultFactory, type TransformAndValida
  * Context used for building FirebaseServerActions. It contains references to reusable factories.
  */
 export type FirebaseServerActionsContext = FirebaseServerActionsTransformContext;
+/**
+ * Abstract base class for {@link FirebaseServerActionsContext} implementations.
+ *
+ * Subclass this when you need to provide the transform and validation factories
+ * from an injected source (e.g., a NestJS provider) rather than constructing them inline.
+ */
 export declare abstract class AbstractFirebaseServerActionsContext implements FirebaseServerActionsContext {
     abstract readonly firebaseServerActionTransformFactory: TransformAndValidateObjectFactory;
     abstract readonly firebaseServerActionTransformFunctionFactory: TransformAndValidateFunctionResultFactory<unknown>;
 }
+/**
+ * Options for creating a {@link FirebaseServerActionsContext}.
+ */
 export type FirebaseServerActionsContextOptions = FirebaseServerActionsTransformFactoryOptions;
+/**
+ * Creates a {@link FirebaseServerActionsContext} with the default transform and validation factories.
+ *
+ * @example
+ * ```ts
+ * const context = firebaseServerActionsContext({ logError: true });
+ * ```
+ *
+ * @param options - Optional configuration for error logging behavior.
+ * @returns A fully configured actions context.
+ */
 export declare function firebaseServerActionsContext(options?: FirebaseServerActionsContextOptions): FirebaseServerActionsContext;
+/**
+ * Callback invoked when a validation error occurs during request transformation.
+ * Receives the error details object for logging or telemetry purposes.
+ */
 export type FirebaseServerActionsTransformFactoryLogErrorFunction = (details: object) => void;
+/**
+ * Configuration for validation error logging. Pass `true` to use the default console logger,
+ * `false` to suppress logging entirely, or a custom function for application-specific logging.
+ */
 export type FirebaseServerActionsTransformFactoryLogErrorFunctionInput = FirebaseServerActionsTransformFactoryLogErrorFunction | boolean;
+/**
+ * Default error logger that writes validation error details to the console.
+ * Used when `logError` is `true` or omitted in the factory options.
+ */
 export declare const defaultFirebaseServerActionsTransformFactoryLogErrorFunction: FirebaseServerActionsTransformFactoryLogErrorFunction;
 /**
  * Context used for transforming content.
@@ -20,11 +52,31 @@ export interface FirebaseServerActionsTransformContext {
     readonly firebaseServerActionTransformFactory: TransformAndValidateObjectFactory;
     readonly firebaseServerActionTransformFunctionFactory: TransformAndValidateFunctionResultFactory;
 }
+/**
+ * Options for creating a {@link FirebaseServerActionsTransformContext}.
+ */
 export type FirebaseServerActionsTransformContextOptions = FirebaseServerActionsTransformFactoryOptions;
+/**
+ * Creates a {@link FirebaseServerActionsTransformContext} with both the object transform factory
+ * and the function result transform factory configured from the same options.
+ *
+ * @param options - Optional configuration for error logging behavior.
+ * @returns A transform context with both factory types ready to use.
+ */
 export declare function firebaseServerActionsTransformContext(options?: FirebaseServerActionsTransformContextOptions): FirebaseServerActionsTransformContext;
+/**
+ * Error code used in server error responses for ArkType validation failures.
+ * Clients can check for this code to distinguish validation errors from other bad-request errors.
+ */
 export declare const FIREBASE_SERVER_VALIDATION_ERROR_CODE = "VALIDATION_ERROR";
 /**
- * Creates a server error object from ArkType validation errors.
+ * Creates a structured server error object from ArkType validation errors.
+ *
+ * The returned object is suitable for embedding in HTTP error responses. Use {@link firebaseServerValidationError}
+ * instead if you need a throwable `HttpsError`.
+ *
+ * @param validationErrors - The ArkType validation errors to convert.
+ * @returns A plain object with a message, error code, and validation summary.
  */
 export declare function firebaseServerValidationServerError(validationErrors: ArkErrors): {
     message: string;
@@ -34,10 +86,41 @@ export declare function firebaseServerValidationServerError(validationErrors: Ar
     };
 };
 /**
- * Creates a new badRequestError with the validation error details as the response data.
+ * Creates a throwable `badRequestError` wrapping ArkType validation errors.
+ *
+ * This is the preferred way to reject requests with invalid input data in Firebase server actions.
+ *
+ * @param validationErrors - The ArkType validation errors to wrap.
+ * @returns A throwable error suitable for Firebase callable function responses.
  */
 export declare function firebaseServerValidationError(validationErrors: ArkErrors): import("firebase-functions/https").HttpsError;
+/**
+ * Options for configuring the transform and validation factory used by Firebase server actions.
+ */
 export interface FirebaseServerActionsTransformFactoryOptions {
+    /**
+     * Controls whether and how validation errors are logged.
+     *
+     * - `true` or omitted: uses the default console logger.
+     * - `false`: suppresses all validation error logging.
+     * - A function: uses the provided function for custom logging.
+     */
     readonly logError?: FirebaseServerActionsTransformFactoryLogErrorFunctionInput;
 }
+/**
+ * Creates a {@link TransformAndValidateObjectFactory} that validates incoming data using ArkType
+ * and throws a `badRequestError` on validation failure.
+ *
+ * Validation errors are optionally logged before the error is thrown, controlled by the `logError` option.
+ *
+ * @example
+ * ```ts
+ * const transformFactory = firebaseServerActionsTransformFactory({ logError: true });
+ * const transform = transformFactory(myArkTypeSchema);
+ * const validated = await transform(rawInput);
+ * ```
+ *
+ * @param options - Optional configuration for error logging behavior.
+ * @returns A factory that creates type-safe transform functions from ArkType schemas.
+ */
 export declare function firebaseServerActionsTransformFactory(options?: FirebaseServerActionsTransformFactoryOptions): TransformAndValidateObjectFactory;

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

@@ -2,17 +2,63 @@ import { type INestApplicationContext } from '@nestjs/common';
 import { type CallableRequest } from 'firebase-functions/v2/https';
 import { type CallableContextWithAuthData } from '../../function/context';
 import { type OnCallWithNestContextRequest } from './call';
+/**
+ * Augments a request type with a reference to the raw {@link INestApplicationContext}.
+ *
+ * This is the lowest-level nest integration type -- most handlers should prefer {@link NestContextRequest}
+ * which provides a typed, domain-specific context instead of the raw application context.
+ *
+ * @typeParam R - The base request type to augment.
+ */
 export type NestApplicationContextRequest<R> = R & {
     readonly nestApplication: INestApplicationContext;
 };
+/**
+ * Simple reference wrapper holding a typed nest context object.
+ *
+ * @typeParam N - The nest context type.
+ */
 export type NestRef<N> = {
     readonly nest: N;
 };
+/**
+ * Augments a request type with a typed nest context. This is the primary request shape used by
+ * nest-integrated Firebase function handlers throughout the codebase.
+ *
+ * @typeParam N - The nest context type, typically an application-specific context class.
+ * @typeParam R - The base request type to augment.
+ */
 export type NestContextRequest<N, R> = R & {
     readonly nest: N;
 };
+/**
+ * Creates a new request object with the typed nest context spread into it.
+ *
+ * Unlike {@link injectNestApplicationContextIntoRequest}, this attaches a domain-specific context rather
+ * than the raw NestJS application context.
+ *
+ * @param nest - The typed nest context to attach.
+ * @param request - The base request to augment.
+ * @returns A new object combining the request properties with the nest context.
+ */
 export declare function injectNestIntoRequest<N, R>(nest: N, request: R): NestContextRequest<N, R>;
+/**
+ * Creates a new request object with the raw {@link INestApplicationContext} spread into it.
+ *
+ * This is typically used at the outermost layer of function wiring before a {@link MakeNestContext}
+ * factory converts it into a typed context via {@link injectNestIntoRequest}.
+ *
+ * @param nestContext - The NestJS application context to attach.
+ * @param request - The base request to augment.
+ * @returns A new object combining the request properties with the application context.
+ */
 export declare function injectNestApplicationContextIntoRequest<R>(nestContext: INestApplicationContext, request: R): NestApplicationContextRequest<R>;
+/**
+ * A Firebase v2 {@link CallableRequest} augmented with a typed nest context.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam I - The callable request input data type.
+ */
 export type NestContextCallableRequest<N, I> = NestContextRequest<N, CallableRequest<I>>;
 /**
  * Equivalent to OnCallWithNestContextRequest

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

@@ -1,6 +1,12 @@
 import { type Minutes, type PromiseOrValue } from '@dereekb/util';
 import { type MakeNestContext, type NestApplicationFunctionFactory } from '../nest.provider';
 import { type NestApplicationContextRequest, type NestContextRequest } from './nest';
+/**
+ * Configuration for scheduled Firebase functions, supporting both cron expressions and human-readable schedules.
+ *
+ * At least one of `cron` or `schedule` must be provided. If `cron` is a number, it is interpreted as
+ * a repeating interval in minutes and converted to a cron expression automatically.
+ */
 export interface OnScheduleConfig {
     /**
      * Scheduled time in a cron-tab format.
@@ -39,23 +45,66 @@ export interface OnScheduleConfig {
      */
     readonly maxDoublings?: number;
 }
+/**
+ * Request object passed to scheduled function handlers, containing the platform-specific schedule event context.
+ *
+ * @typeParam S - The schedule event type (e.g., `scheduler.ScheduledEvent` for v2).
+ */
 export interface OnScheduleRequest<S> {
     readonly scheduleContext?: S;
 }
+/**
+ * Request type for scheduled functions that receive the raw {@link INestApplicationContext}.
+ *
+ * @typeParam S - The schedule event type.
+ */
 export type OnScheduleWithNestApplicationRequest<S = unknown> = NestApplicationContextRequest<OnScheduleRequest<S>>;
 /**
  * Scheduled function that is passed an INestApplicationContext in addition to the OnScheduleRequest object.
  */
 export type OnScheduleWithNestApplication<S = unknown> = (request: OnScheduleWithNestApplicationRequest<S>) => PromiseOrValue<void>;
+/**
+ * Request type for scheduled functions that receive a typed nest context.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam S - The schedule event type.
+ */
 export type OnScheduleWithNestContextRequest<N, S = unknown> = NestContextRequest<N, OnScheduleRequest<S>>;
 /**
  * Scheduled function that is passed an arbitrary nest context object in addition to the OnScheduleRequest object.
  */
 export type OnScheduleWithNestContext<N, S = unknown> = (request: OnScheduleWithNestContextRequest<N, S>) => PromiseOrValue<void>;
+/**
+ * Mutates the application-level schedule request to attach a typed nest context.
+ *
+ * This is the schedule-function equivalent of {@link setNestContextOnRequest} for callable functions.
+ *
+ * @param makeNestContext - Factory that creates the typed context from the application context.
+ * @param request - The application-level schedule request to augment.
+ * @returns The same request object, now typed with the nest context attached.
+ */
 export declare function setNestContextOnScheduleRequest<N, S>(makeNestContext: MakeNestContext<N>, request: OnScheduleWithNestApplicationRequest<S>): OnScheduleWithNestContextRequest<N, S>;
+/**
+ * A scheduled Firebase function augmented with metadata for testing and introspection.
+ *
+ * The `_runNow` method allows triggering the scheduled function outside of its cron schedule,
+ * which is useful for testing or manual invocation. The `_schedule` field exposes the resolved
+ * schedule configuration.
+ *
+ * @typeParam F - The base Firebase function type (e.g., `scheduler.ScheduleFunction`).
+ */
 export type NestApplicationScheduleConfiguredFunction<F extends object = object> = F & {
     _runNow(): PromiseOrValue<void>;
     readonly _schedule: OnScheduleConfig;
 };
+/**
+ * Factory that creates a {@link NestApplicationScheduleConfiguredFunction} from a {@link NestApplicationPromiseGetter}.
+ *
+ * @typeParam F - The base Firebase function type.
+ */
 export type NestApplicationScheduleConfiguredFunctionFactory<F extends object = object> = NestApplicationFunctionFactory<NestApplicationScheduleConfiguredFunction<F>>;
+/**
+ * A map of named scheduled functions, keyed by function name. Useful for registering
+ * multiple scheduled functions as a group (e.g., in a module's function map).
+ */
 export type NestApplicationScheduleConfiguredFunctionMap = Record<string, NestApplicationScheduleConfiguredFunction>;

package/src/lib/nest/function/v2/blocking.d.ts

@@ -3,9 +3,32 @@ import { type MakeNestContext, type NestApplicationFunctionFactory } from '../..
 import { type NestContextRequest } from '../nest';
 import { type BlockingFunction } from 'firebase-functions/v1';
 import { type BlockingOptions, type beforeUserCreated } from 'firebase-functions/identity';
+/**
+ * The response type returned by a `beforeUserCreated` blocking function handler.
+ *
+ * Derived from the Firebase SDK's `beforeUserCreated` handler signature to stay in sync
+ * with upstream type changes.
+ */
 export type BeforeCreateResponse = MaybeSo<Awaited<ReturnType<Parameters<typeof beforeUserCreated>[1]>>>;
+/**
+ * Request type for blocking function handlers that include a typed nest context alongside the blocking event.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam E - The blocking event type (e.g., `AuthBlockingEvent`).
+ */
 export type BlockingFunctionNestContextRequest<N, E extends object> = NestContextRequest<N, E>;
+/**
+ * A raw blocking function handler that receives the Firebase event and optionally returns a response
+ * to modify the authentication flow (e.g., setting custom claims or blocking sign-in).
+ *
+ * @typeParam E - The blocking event type.
+ * @typeParam O - The optional return type that can modify the auth flow.
+ */
 export type BlockingFunctionHandler<E extends object, O> = (event: E) => PromiseOrValue<O | void>;
+/**
+ * Ref that holds a reference to the underlying {@link BlockingFunctionHandler}, enabling
+ * direct invocation in tests without going through the Firebase trigger machinery.
+ */
 export type BlockingFunctionHandlerRef<E extends object, O> = {
     __handler: BlockingFunctionHandler<E, O>;
 };
@@ -13,22 +36,69 @@ export type BlockingFunctionHandlerRef<E extends object, O> = {
  * BlockingFunction extension that also contains the handler and typing info.
  */
 export type BlockingFunctionWithHandler<E extends object, O> = BlockingFunction & BlockingFunctionHandlerRef<E, O>;
+/**
+ * A {@link BlockingFunction} that may or may not have a handler ref attached. Used as the return type
+ * of builder functions where the handler attachment is optional.
+ */
 export type BlockingFunctionMaybeWithHandler<E extends object, O> = BlockingFunction & Partial<BlockingFunctionHandlerRef<E, O>>;
+/**
+ * Abstraction over Firebase blocking function constructors (e.g., `beforeUserCreated`, `beforeUserSignedIn`).
+ *
+ * Supports both the options-less and options-with overloads, allowing the same builder pattern
+ * to work with any blocking function type.
+ *
+ * @typeParam E - The blocking event type.
+ * @typeParam O - The optional return type.
+ */
 export interface BlockingFunctionBuilder<E extends object, O> {
     (handler: (event: E) => PromiseOrValue<O | void>): BlockingFunction;
     (opts: BlockingOptions, handler: (event: E) => PromiseOrValue<O | void>): BlockingFunction;
 }
 /**
- * Creates a BlockingFunctionWithHandler from the input.
+ * Creates a {@link BlockingFunctionWithHandler} by invoking the builder and attaching the handler ref.
+ *
+ * The attached `__handler` enables direct handler invocation in tests without triggering
+ * the full Firebase blocking function infrastructure.
+ *
+ * @example
+ * ```ts
+ * const fn = makeBlockingFunctionWithHandler(
+ *   beforeUserCreated,
+ *   (event) => ({ displayName: event.data.email?.split('@')[0] }),
+ *   { accessToken: true }
+ * );
+ * // In tests: fn.__handler(mockEvent)
+ * ```
  *
- * @param blockingFunctionBuilder
- * @param handler
- * @returns
+ * @param blockingFunctionBuilder - The Firebase blocking function constructor (e.g., `beforeUserCreated`).
+ * @param handler - The handler logic to execute on each event.
+ * @param opts - Optional {@link BlockingOptions} passed to the builder.
+ * @returns A {@link BlockingFunctionWithHandler} with the handler accessible via `__handler`.
  */
 export declare function makeBlockingFunctionWithHandler<E extends object, O>(blockingFunctionBuilder: BlockingFunctionBuilder<E, O>, handler: BlockingFunctionHandler<E, O>, opts?: Maybe<BlockingOptions>): BlockingFunctionWithHandler<E, O>;
+/**
+ * A blocking function handler that receives the event augmented with a typed nest context.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam E - The blocking event type.
+ * @typeParam O - The optional return type.
+ */
 export type NestContextBlockingFunctionHandler<N, E extends object, O> = (request: BlockingFunctionNestContextRequest<N, E>) => PromiseOrValue<O | void>;
+/**
+ * Builder that wraps a {@link NestContextBlockingFunctionHandler} into a raw {@link BlockingFunctionHandler}
+ * by injecting the nest context into each event before delegation.
+ */
 export type NestContextBlockingFunctionHandlerBuilder<N, E extends object, O> = (handler: NestContextBlockingFunctionHandler<N, E, O>) => BlockingFunctionHandler<E, O>;
+/**
+ * Builder function that receives a {@link NestContextBlockingFunctionHandlerBuilder} and uses it
+ * to construct a complete {@link BlockingFunctionMaybeWithHandler}, typically by calling
+ * {@link makeBlockingFunctionWithHandler} internally.
+ */
 export type BlockingFunctionHandlerWithNestContextBuilder<N, E extends object, O> = (nest: NestContextBlockingFunctionHandlerBuilder<N, E, O>) => BlockingFunctionMaybeWithHandler<E, O>;
+/**
+ * Utility type that infers the correct {@link BlockingFunctionHandlerWithNestContextBuilder} type
+ * from a given {@link BlockingFunctionBuilder}, preserving the event and output type parameters.
+ */
 export type BlockingFunctionHandlerWithNestContextBuilderForBuilder<N, B extends BlockingFunctionBuilder<any, any>> = B extends BlockingFunctionBuilder<infer E, infer O> ? BlockingFunctionHandlerWithNestContextBuilder<N, E, O> : never;
 /**
  * Factory produced by BlockingFunctionHandlerWithNestContextFactory.
@@ -39,10 +109,24 @@ export type NestApplicationBlockingFunctionFactory<E extends object, O> = NestAp
  */
 export type BlockingFunctionHandlerWithNestContextFactory<N> = <E extends object, O>(fn: BlockingFunctionHandlerWithNestContextBuilder<N, E, O>) => NestApplicationBlockingFunctionFactory<E, O>;
 /**
- * Creates a BlockingFunctionHandlerWithNestContextFactory.
+ * Creates a {@link BlockingFunctionHandlerWithNestContextFactory} that wires up the NestJS application
+ * context injection for blocking functions (e.g., `beforeUserCreated`, `beforeUserSignedIn`).
+ *
+ * The returned factory lazily resolves the NestJS application on each invocation, injects the
+ * typed context into the event, and delegates to the handler.
+ *
+ * @example
+ * ```ts
+ * const factory = blockingFunctionHandlerWithNestContextFactory(makeMyContext);
+ * const beforeCreate = factory<AuthBlockingEvent, BeforeCreateResponse>((nestHandler) =>
+ *   makeBlockingFunctionWithHandler(beforeUserCreated, nestHandler((request) => {
+ *     // request.nest is the typed context
+ *     return { displayName: 'new-user' };
+ *   }))
+ * );
+ * ```
  *
- * @param appFactory
- * @param makeNestContext
- * @returns
+ * @param makeNestContext - Factory that creates the typed context from the NestJS application context.
+ * @returns A factory for creating nest-context-aware blocking function handlers.
  */
 export declare function blockingFunctionHandlerWithNestContextFactory<N>(makeNestContext: MakeNestContext<N>): BlockingFunctionHandlerWithNestContextFactory<N>;

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

@@ -3,7 +3,10 @@ import { type CallableHttpFunction } from '../../../function/type';
 import { type MakeNestContext, type NestApplicationFunctionFactory } from '../../nest.provider';
 import { type OnCallWithNestApplication, type OnCallWithNestContext } from '../call';
 /**
- * A NestApplicationFunctionFactory for a CallableHttpFunction.
+ * A {@link NestApplicationFunctionFactory} that produces a typed {@link CallableHttpFunction}.
+ *
+ * @typeParam I - The expected input data type for the callable request.
+ * @typeParam O - The return type of the callable function.
  */
 export type NestApplicationCallableHttpFunctionFactory<I = unknown, O = unknown> = NestApplicationFunctionFactory<CallableHttpFunction<I, O>>;
 /**
@@ -11,10 +14,23 @@ export type NestApplicationCallableHttpFunctionFactory<I = unknown, O = unknown>
  */
 export type OnCallHandlerWithNestApplicationFactory = <I = unknown, O = unknown>(fn: OnCallWithNestApplication<I, O>, opts?: https.CallableOptions<I>) => NestApplicationCallableHttpFunctionFactory<I, O>;
 /**
- * Creates a factory for generating OnCallWithNestApplication (firebase-functions v2) functions.
+ * Creates an {@link OnCallHandlerWithNestApplicationFactory} that registers Firebase v2 callable functions
+ * with automatic NestJS application context injection.
+ *
+ * The `defaultOpts` are merged with per-function options, allowing shared configuration (e.g., CORS settings,
+ * memory allocation) to be set once at the factory level.
+ *
+ * @example
+ * ```ts
+ * const callFactory = onCallHandlerWithNestApplicationFactory({ cors: true });
+ * const myFunction = callFactory<InputType, OutputType>(
+ *   (request) => request.nestApplication.get(MyService).handle(request.data),
+ *   { memory: '256MiB' }
+ * );
+ * ```
  *
- * @param opts
- * @returns
+ * @param defaultOpts - Default {@link https.CallableOptions} applied to all functions created by this factory.
+ * @returns A factory that creates nest-application-aware callable functions.
  */
 export declare function onCallHandlerWithNestApplicationFactory(defaultOpts?: https.CallableOptions): OnCallHandlerWithNestApplicationFactory;
 /**
@@ -22,10 +38,24 @@ export declare function onCallHandlerWithNestApplicationFactory(defaultOpts?: ht
  */
 export type OnCallHandlerWithNestContextFactory<C> = <I = unknown, O = unknown>(fn: OnCallWithNestContext<C, I, O>, opts?: https.CallableOptions<I>) => NestApplicationCallableHttpFunctionFactory<I, O>;
 /**
- * Creates a factory for generating OnCallWithNestContext functions with a nest context object that is generated by the input function.
+ * Creates an {@link OnCallHandlerWithNestContextFactory} that builds on an existing
+ * {@link OnCallHandlerWithNestApplicationFactory} by additionally injecting a typed nest context.
+ *
+ * This is the standard way to create callable functions that receive a domain-specific context
+ * (e.g., `MyApiNestContext`) rather than the raw NestJS application context.
+ *
+ * @example
+ * ```ts
+ * const appFactory = onCallHandlerWithNestApplicationFactory();
+ * const contextFactory = onCallHandlerWithNestContextFactory(appFactory, makeMyContext);
+ * const myFunction = contextFactory<InputType, OutputType>((request) => {
+ *   // request.nest is MyApiNestContext
+ *   return request.nest.someService.handle(request.data);
+ * });
+ * ```
  *
- * @param appFactory
- * @param makeNestContext
- * @returns
+ * @param appFactory - The base application-level callable factory.
+ * @param makeNestContext - Factory that creates the typed context from the application context.
+ * @returns A factory that creates typed-context-aware callable functions.
  */
 export declare function onCallHandlerWithNestContextFactory<C>(appFactory: OnCallHandlerWithNestApplicationFactory, makeNestContext: MakeNestContext<C>): OnCallHandlerWithNestContextFactory<C>;

package/src/lib/nest/function/v2/event.d.ts

@@ -2,15 +2,63 @@ import { type PromiseOrValue } from '@dereekb/util';
 import { type CloudEvent, type CloudFunction } from 'firebase-functions/v2';
 import { type MakeNestContext, type NestApplicationFunctionFactory } from '../../nest.provider';
 import { type NestContextRequest } from '../nest';
+/**
+ * Request type for cloud event handlers that include a typed nest context alongside the cloud event.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam E - The specific {@link CloudEvent} subtype.
+ */
 export type CloudEventNestContextRequest<N, E extends CloudEvent<any>> = NestContextRequest<N, E>;
+/**
+ * A raw handler for a Firebase v2 {@link CloudEvent}.
+ *
+ * @typeParam E - The specific cloud event subtype.
+ * @typeParam O - The return type (typically `void` for event handlers).
+ */
 export type CloudEventHandler<E extends CloudEvent<any>, O = unknown> = (event: E) => PromiseOrValue<O>;
+/**
+ * Abstraction over Firebase v2 cloud event function constructors (e.g., `onDocumentWritten`, `onObjectFinalized`).
+ *
+ * This enables the same factory pattern to work with any event-triggered function type.
+ *
+ * @typeParam E - The specific cloud event subtype.
+ * @typeParam O - The return type.
+ */
 export interface CloudFunctionBuilder<E extends CloudEvent<any>, O = unknown> {
     (handler: (event: E) => PromiseOrValue<O>): CloudFunction<E>;
 }
+/**
+ * A cloud event handler that receives the event augmented with a typed nest context.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam E - The specific cloud event subtype.
+ * @typeParam O - The return type.
+ */
 export type NestContextCloudEventHandler<N, E extends CloudEvent<any>, O = unknown> = (request: CloudEventNestContextRequest<N, E>) => PromiseOrValue<O>;
+/**
+ * Builder that wraps a {@link NestContextCloudEventHandler} into a raw {@link CloudEventHandler}
+ * by injecting the nest context into each event before delegation.
+ */
 export type NestContextCloudEventHandlerBuilder<N, E extends CloudEvent<any>, O = unknown> = (handler: NestContextCloudEventHandler<N, E, O>) => CloudEventHandler<E, O>;
+/**
+ * Convenience alias for a {@link NestContextCloudEventHandler} where the event data type is specified
+ * directly rather than as a full {@link CloudEvent} subtype.
+ *
+ * @typeParam N - The nest context type.
+ * @typeParam I - The cloud event data type.
+ * @typeParam O - The return type.
+ */
 export type NestContextCloudEventHandlerWithData<N, I, O = unknown> = NestContextCloudEventHandler<N, CloudEvent<I>, O>;
+/**
+ * Builder function that receives a {@link NestContextCloudEventHandlerBuilder} and uses it
+ * to construct a complete {@link CloudFunction}, typically by calling the Firebase event
+ * function constructor (e.g., `onDocumentWritten`) with the wrapped handler.
+ */
 export type CloudEventHandlerWithNestContextBuilder<N, E extends CloudEvent<any>, O = unknown> = (nest: NestContextCloudEventHandlerBuilder<N, E, O>) => CloudFunction<E>;
+/**
+ * Utility type that infers the correct {@link CloudEventHandlerWithNestContextBuilder} type
+ * from a given {@link CloudFunctionBuilder}, preserving the event and output type parameters.
+ */
 export type CloudEventHandlerWithNestContextBuilderForBuilder<N, B extends CloudFunctionBuilder<any, any>> = B extends CloudFunctionBuilder<infer E, infer O> ? CloudEventHandlerWithNestContextBuilder<N, E, O> : never;
 /**
  * Factory produced by CloudEventHandlerWithNestContextFactory.
@@ -21,10 +69,25 @@ export type NestApplicationCloudEventFunctionFactory<E extends CloudEvent<any>>
  */
 export type CloudEventHandlerWithNestContextFactory<N> = <E extends CloudEvent<any>, O = unknown>(fn: CloudEventHandlerWithNestContextBuilder<N, E, O>) => NestApplicationCloudEventFunctionFactory<E>;
 /**
- * Creates a CloudEventHandlerWithNestContextFactory.
+ * Creates a {@link CloudEventHandlerWithNestContextFactory} that wires up NestJS application context
+ * injection for Firebase v2 event-triggered functions.
+ *
+ * The returned factory lazily resolves the NestJS application on each event, injects the typed
+ * context, and delegates to the handler. This is the event-triggered equivalent of
+ * {@link onCallHandlerWithNestContextFactory} for callable functions.
+ *
+ * @example
+ * ```ts
+ * const factory = cloudEventHandlerWithNestContextFactory(makeMyContext);
+ * const onWrite = factory<DocumentEvent, void>((nestHandler) =>
+ *   onDocumentWritten('path/{id}', nestHandler((request) => {
+ *     // request.nest is the typed context
+ *     request.nest.myService.handleWrite(request.data);
+ *   }))
+ * );
+ * ```
  *
- * @param appFactory
- * @param makeNestContext
- * @returns
+ * @param makeNestContext - Factory that creates the typed context from the NestJS application context.
+ * @returns A factory for creating nest-context-aware event function handlers.
  */
 export declare function cloudEventHandlerWithNestContextFactory<N>(makeNestContext: MakeNestContext<N>): CloudEventHandlerWithNestContextFactory<N>;

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

@@ -7,21 +7,52 @@ import { type ScheduleOptions } from 'firebase-functions/v2/scheduler';
  * Configuration options for OnScheduleHandlerWithNestApplicationFactory that extends the base OnScheduleConfig with the gen 2 ScheduleOptions.
  */
 export type OnScheduleConfigWithGlobalOptions = OnScheduleConfig & Omit<ScheduleOptions, 'schedule'>;
+/**
+ * Creates an {@link OnScheduleWithNestApplicationRequest} by combining the NestJS application context
+ * with an optional scheduler event. Used internally by schedule handler factories to build the
+ * request object passed to schedule function handlers.
+ *
+ * @param nestApplication - The initialized NestJS application context.
+ * @param scheduleContext - The optional Firebase scheduler event, absent when invoked via `_runNow()`.
+ * @returns A request object ready for schedule function handlers.
+ */
 export declare function makeOnScheduleHandlerWithNestApplicationRequest(nestApplication: INestApplicationContext, scheduleContext?: scheduler.ScheduledEvent): OnScheduleWithNestApplicationRequest<scheduler.ScheduledEvent>;
+/**
+ * A {@link NestApplicationScheduleConfiguredFunctionFactory} specialized for Firebase v2 schedule functions.
+ */
 export type NestApplicationScheduleFunctionFactory = NestApplicationScheduleConfiguredFunctionFactory<scheduler.ScheduleFunction>;
 /**
- * Factory function for generating a NestApplicationFunctionFactory for a HttpsFunctions/Runnable firebase function.
+ * Factory function that creates a {@link NestApplicationScheduleFunctionFactory} from a schedule configuration
+ * and an {@link OnScheduleWithNestApplication} handler.
+ *
+ * Produced by {@link onScheduleHandlerWithNestApplicationFactory}.
  */
 export type OnScheduleHandlerWithNestApplicationFactory = (schedule: OnScheduleConfigWithGlobalOptions, fn: OnScheduleWithNestApplication<scheduler.ScheduledEvent>) => NestApplicationScheduleFunctionFactory;
 /**
- * Creates a factory for generating OnCallWithNestApplication functions.
+ * Creates an {@link OnScheduleHandlerWithNestApplicationFactory} for Firebase v2 scheduled functions.
  *
- * @param nestAppPromiseGetter
- * @returns
+ * The factory resolves `cron` values (including numeric minute intervals) into cron expressions,
+ * merges base and per-function schedule options, and attaches `_runNow` and `_schedule` metadata
+ * to the resulting function for testing and introspection.
+ *
+ * @example
+ * ```ts
+ * const scheduleFactory = onScheduleHandlerWithNestApplicationFactory({ timeoutSeconds: 60 });
+ * const dailyCleanup = scheduleFactory(
+ *   { cron: '0 2 * * *', timezone: 'America/New_York' },
+ *   (request) => request.nestApplication.get(CleanupService).run()
+ * );
+ * ```
+ *
+ * @param baseScheduleConfig - Optional default schedule options merged into every function created by this factory.
+ * @returns A factory for creating nest-application-aware scheduled functions.
  */
 export declare function onScheduleHandlerWithNestApplicationFactory(baseScheduleConfig?: OnScheduleConfigWithGlobalOptions): OnScheduleHandlerWithNestApplicationFactory;
 /**
- * Factory function for generating HttpsFunctions/Runnable firebase function that returns the value from the input OnCallWithNestContext function.
+ * Factory function that creates a {@link NestApplicationScheduleFunctionFactory} from a schedule configuration
+ * and an {@link OnScheduleWithNestContext} handler that receives a typed nest context.
+ *
+ * Produced by {@link onScheduleHandlerWithNestContextFactory}.
  */
 export type OnScheduleHandlerWithNestContextFactory<N> = (schedule: OnScheduleConfigWithGlobalOptions, fn: OnScheduleWithNestContext<N, scheduler.ScheduledEvent>) => NestApplicationScheduleFunctionFactory;
 /**

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

@@ -1,4 +1,5 @@
 export * from './auth';
+export * from './controller';
 export * from './development';
 export * from './env';
 export * from './firebase';
@@ -7,5 +8,7 @@ export * from './function';
 export * from './middleware';
 export * from './model';
 export * from './storage';
+export * from './app.module';
 export * from './app';
 export * from './nest.provider';
+export * from './nest.provider.server';

package/src/lib/nest/middleware/appcheck.d.ts

@@ -1,4 +1,9 @@
 import { type Request } from 'express';
+/**
+ * Extended Express request with an optional flag to skip AppCheck verification.
+ *
+ * Set by the {@link SkipAppCheck} decorator to bypass verification for specific routes.
+ */
 export interface AppCheckRequest extends Request {
     skipAppCheck?: boolean;
 }