@dereekb/firebase-server 13.4.1 → 13.4.2

package/src/lib/nest/model/analytics.details.d.ts

@@ -62,19 +62,33 @@ export interface OnCallModelFunctionAnalyticsDetails<R = any, O = any> {
  * @typeParam I - The input/request data type.
  */
 export interface OnCallAnalyticsContext<I = any> {
-    /** The CRUD operation type (e.g., `'create'`, `'update'`). */
+    /**
+     * The CRUD operation type (e.g., `'create'`, `'update'`).
+     */
     readonly call: OnCallFunctionType;
-    /** The model type being operated on (e.g., `'guestbook'`). */
+    /**
+     * The model type being operated on (e.g., `'guestbook'`).
+     */
     readonly modelType: FirestoreModelType;
-    /** Optional operation specifier for variant handlers. */
+    /**
+     * Optional operation specifier for variant handlers.
+     */
     readonly specifier: Maybe<ModelFirebaseCrudFunctionSpecifier>;
-    /** The Firebase Auth UID of the calling user. */
+    /**
+     * The Firebase Auth UID of the calling user.
+     */
     readonly uid?: FirebaseAuthUserId;
-    /** The full Firebase Auth context. */
+    /**
+     * The full Firebase Auth context.
+     */
     readonly auth?: AuthData;
-    /** The typed request data. */
+    /**
+     * The typed request data.
+     */
     readonly data?: I;
-    /** The full NestContext callable request with auth and specifier. */
+    /**
+     * The full NestContext callable request with auth and specifier.
+     */
     readonly request: NestContextCallableRequestWithAuth<unknown, I> & ModelFirebaseCrudFunctionSpecifierRef;
 }
 /**

package/src/lib/nest/model/analytics.emit.d.ts

@@ -32,6 +32,9 @@ export type OnCallAnalyticsEmitterInstance = (lifecycle: OnCallModelAnalyticsEve
  * emitter('triggered').sendEventType('Handler Starting');
  * emitter('success').sendEvent('Widget Created', { id: result.id });
  * ```
+ *
+ * @param config - The service and context to bind to the emitter factory.
+ * @returns A factory function that creates lifecycle-stage-specific emitters.
  */
 export declare function onCallAnalyticsEmitterInstance(config: OnCallAnalyticsEmitterInstanceConfig): OnCallAnalyticsEmitterInstance;
 /**

package/src/lib/nest/model/analytics.handler.d.ts

@@ -11,25 +11,45 @@ import { type Maybe } from '@dereekb/util';
  * Consumed by {@link OnCallModelAnalyticsService} and forwarded to provider-specific listeners.
  */
 export interface OnCallModelAnalyticsEvent {
-    /** The event name describing what happened (e.g., `'Guestbook Created'`). */
+    /**
+     * The event name describing what happened (e.g., `'Guestbook Created'`).
+     */
     readonly event: string;
-    /** The lifecycle stage at which this event was emitted. */
+    /**
+     * The lifecycle stage at which this event was emitted.
+     */
     readonly lifecycle: 'triggered' | 'success' | 'error' | 'complete';
-    /** The CRUD operation type (e.g., `'create'`, `'update'`, `'delete'`). */
+    /**
+     * The CRUD operation type (e.g., `'create'`, `'update'`, `'delete'`).
+     */
     readonly call: OnCallFunctionType;
-    /** The model type being operated on (e.g., `'guestbook'`, `'profile'`). */
+    /**
+     * The model type being operated on (e.g., `'guestbook'`, `'profile'`).
+     */
     readonly modelType: FirestoreModelType;
-    /** Optional operation specifier for variant handlers (e.g., `'subscribeToNotifications'`). */
+    /**
+     * Optional operation specifier for variant handlers (e.g., `'subscribeToNotifications'`).
+     */
     readonly specifier?: Maybe<ModelFirebaseCrudFunctionSpecifier>;
-    /** The Firebase Auth UID of the calling user, if authenticated. */
+    /**
+     * The Firebase Auth UID of the calling user, if authenticated.
+     */
     readonly uid?: Maybe<FirebaseAuthUserId>;
-    /** The full Firebase Auth context, if available. */
+    /**
+     * The full Firebase Auth context, if available.
+     */
     readonly auth?: Maybe<AuthData>;
-    /** The raw request object passed to the handler. */
+    /**
+     * The raw request object passed to the handler.
+     */
     readonly request?: Maybe<unknown>;
-    /** Custom key-value properties attached by lifecycle callbacks. */
+    /**
+     * Custom key-value properties attached by lifecycle callbacks.
+     */
     readonly properties?: Maybe<Record<string, any>>;
-    /** The error object, if this event was emitted during the `'error'` lifecycle stage. */
+    /**
+     * The error object, if this event was emitted during the `'error'` lifecycle stage.
+     */
     readonly error?: Maybe<unknown>;
 }
 /**

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

@@ -106,19 +106,31 @@ export interface OnCallApiDetailsRef {
 }
 /**
  * Whether the details are specifier-level (has specifiers map).
+ *
+ * @param details - The API details to check.
+ * @returns True if the details contain a specifiers map.
  */
 export declare function isOnCallModelTypeApiDetails(details: OnCallApiDetails): details is OnCallModelTypeApiDetails;
 /**
  * Whether the details are CRUD-model-level (has modelTypes map).
+ *
+ * @param details - The API details to check.
+ * @returns True if the details contain a modelTypes map.
  */
 export declare function isOnCallCrudModelApiDetails(details: OnCallApiDetails): details is OnCallCrudModelApiDetails;
 /**
  * Whether the details are handler-level (leaf node — no specifiers or modelTypes).
+ *
+ * @param details - The API details to check.
+ * @returns True if the details are handler-level (no specifiers or modelTypes).
  */
 export declare function isOnCallHandlerApiDetails(details: OnCallApiDetails): details is OnCallModelFunctionApiDetails;
 /**
  * Whether the specifier-level details represent a true specifier (multiple sub-operations)
  * vs a wrapped direct handler (`isSpecifier: false`, details under `_`).
+ *
+ * @param details - The specifier-level API details to check.
+ * @returns True if the details represent a true specifier with multiple sub-operations.
  */
 export declare function isActualSpecifier(details: OnCallModelTypeApiDetails): boolean;
 /**
@@ -177,16 +189,25 @@ export interface WithApiDetailsConfig<F extends (...args: any[]) => any> extends
  *   fn: async (request) => { ... }
  * });
  * ```
+ *
+ * @param config - The API details configuration including the handler function.
+ * @returns The handler function with _apiDetails attached.
  */
 export declare function withApiDetails<F extends (...args: any[]) => any>(config: WithApiDetailsConfig<F>): F & OnCallModelFunctionApiDetailsRef;
 /**
  * Reads _apiDetails from a function if present.
+ *
+ * @param fn - The function or object that may carry _apiDetails.
+ * @returns The API details if present, otherwise undefined.
  */
 export declare function readApiDetails(fn: Maybe<OnCallApiDetailsRef>): Maybe<OnCallApiDetails>;
 /**
  * Aggregates _apiDetails from a specifier handler config object.
  *
  * Returns OnCallModelTypeApiDetails if any handlers have _apiDetails, otherwise undefined.
+ *
+ * @param config - Map of specifier keys to handler functions.
+ * @returns Aggregated specifier-level API details, or undefined if no handlers have _apiDetails.
  */
 export declare function aggregateSpecifierApiDetails(config: {
     readonly [key: string]: Maybe<OnCallApiDetailsRef>;
@@ -195,6 +216,9 @@ export declare function aggregateSpecifierApiDetails(config: {
  * Aggregates _apiDetails from a model type map (used by onCallCreateModel, etc.).
  *
  * Returns OnCallCrudModelApiDetails if any handlers have _apiDetails, otherwise undefined.
+ *
+ * @param map - Map of model type strings to handler functions.
+ * @returns Aggregated CRUD-model-level API details, or undefined if no handlers have _apiDetails.
  */
 export declare function aggregateCrudModelApiDetails(map: {
     readonly [key: string]: Maybe<OnCallApiDetailsRef>;
@@ -203,6 +227,9 @@ export declare function aggregateCrudModelApiDetails(map: {
  * Aggregates _apiDetails from the top-level call model map.
  *
  * Returns OnCallModelApiDetails if any CRUD handlers have _apiDetails, otherwise undefined.
+ *
+ * @param map - Map of call type strings to CRUD handler functions.
+ * @returns Aggregated model-level API details, or undefined if no handlers have _apiDetails.
  */
 export declare function aggregateModelApiDetails(map: {
     readonly [key: string]: Maybe<OnCallApiDetailsRef>;
@@ -275,8 +302,14 @@ export declare function getModelApiDetails(callModelFn: Maybe<OnCallApiDetailsRe
 /**
  * Resolves leaf-level analytics details from the aggregated _apiDetails tree.
  *
- * Walks: call → modelType → specifier (if specifier-level), then reads the `analytics`
+ * Walks: call -> modelType -> specifier (if specifier-level), then reads the `analytics`
  * field from the handler-level {@link OnCallModelFunctionApiDetails}.
+ *
+ * @param apiDetails - The top-level aggregated API details.
+ * @param call - The CRUD operation type to look up.
+ * @param modelType - The Firestore model type to look up.
+ * @param specifier - Optional specifier key for variant handlers.
+ * @returns The analytics details for the resolved handler, or undefined.
  */
 export declare function resolveAnalyticsFromApiDetails(apiDetails: OnCallModelApiDetails, call: OnCallFunctionType, modelType: FirestoreModelType, specifier?: ModelFirebaseCrudFunctionSpecifier): Maybe<OnCallModelFunctionAnalyticsDetails>;
 /**

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

@@ -55,10 +55,15 @@ export interface OnCallModelConfig {
 export declare function onCallModel(map: OnCallModelMap, config?: OnCallModelConfig): OnCallWithNestContext<unknown, OnCallTypedModelParams> & OnCallApiDetailsRef;
 /**
  * Creates a bad-request error indicating the `call` field was missing from the request payload.
+ *
+ * @returns A bad-request error with CALL_TYPE_MISSING_ERROR code.
  */
 export declare function onCallModelMissingCallTypeError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates a bad-request error indicating the provided `call` type is not recognized.
+ *
+ * @param call - The unrecognized call type string.
+ * @returns A bad-request error with UNKNOWN_CALL_TYPE_ERROR code.
  */
 export declare function onCallModelUnknownCallTypeError(call: OnCallFunctionType): import("firebase-functions/https").HttpsError;
 /**
@@ -82,13 +87,21 @@ export type OnCallWithCallTypeModelMap<N, T extends FirestoreModelIdentity = Fir
  * @typeParam N - The NestJS context type.
  */
 export interface OnCallWithCallTypeModelConfig<N> {
-    /** The call type string (e.g., 'create', 'read') passed through to assertions. */
+    /**
+     * The call type string (e.g., 'create', 'read') passed through to assertions.
+     */
     readonly callType: string;
-    /** The CRUD category used by {@link AssertModelCrudRequestFunction}. */
+    /**
+     * The CRUD category used by {@link AssertModelCrudRequestFunction}.
+     */
     readonly crudType: AssertModelCrudRequestFunctionContextCrudType;
-    /** Optional assertion run before the model handler; throw to reject. */
+    /**
+     * Optional assertion run before the model handler; throw to reject.
+     */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallTypedModelParams>;
-    /** Error factory invoked when the requested model type has no handler in the map. */
+    /**
+     * Error factory invoked when the requested model type has no handler in the map.
+     */
     readonly throwOnUnknownModelType: (modelType: FirestoreModelType) => Error;
 }
 /**
@@ -97,6 +110,9 @@ export interface OnCallWithCallTypeModelConfig<N> {
  * Dispatches to the correct model-type handler from the map, enforces auth requirements,
  * runs pre-assertions, and aggregates API details from all handlers for MCP introspection.
  *
+ * @param map - Maps model type strings to their handler functions.
+ * @param config - Configuration including call type, crud type, and error factory.
+ * @returns A callable function that dispatches to the correct model-type handler.
  * @internal Not intended for direct use outside the model CRUD module.
  */
 export declare function _onCallWithCallTypeFunction<N>(map: OnCallWithCallTypeModelMap<N>, config: OnCallWithCallTypeModelConfig<N>): OnCallWithAuthAwareNestContext<N, OnCallTypedModelParams, unknown> & OnCallApiDetailsRef;

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

@@ -61,7 +61,9 @@ export type OnCallCreateModelMap<N, T extends FirestoreModelIdentity = Firestore
  * Configuration for {@link onCallCreateModel}.
  */
 export interface OnCallCreateModelConfig<N> {
-    /** Optional assertion run before the create handler; throw to reject. */
+    /**
+     * Optional assertion run before the create handler; throw to reject.
+     */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallCreateModelParams>;
 }
 /**
@@ -85,5 +87,8 @@ export interface OnCallCreateModelConfig<N> {
 export declare function onCallCreateModel<N>(map: OnCallCreateModelMap<N>, config?: OnCallCreateModelConfig<N>): OnCallWithNestContext<N, OnCallCreateModelParams, OnCallCreateModelResult>;
 /**
  * Creates a bad-request error indicating the requested model type is not valid for creation.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
  */
 export declare function createModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/model/crud.assert.function.d.ts

@@ -18,13 +18,21 @@ export type AssertModelCrudRequestFunctionContextCrudType = 'call' | 'create' |
  * @typeParam I - The input data type of the request.
  */
 export interface AssertModelCrudRequestFunctionContext<N, I = unknown> {
-    /** The original callable request including the NestJS context and caller data. */
+    /**
+     * The original callable request including the NestJS context and caller data.
+     */
     readonly request: NestContextCallableRequest<N, I>;
-    /** The CRUD call type string (e.g., 'create', 'read'). */
+    /**
+     * The CRUD call type string (e.g., 'create', 'read').
+     */
     readonly call: OnCallFunctionType;
-    /** The Firestore model type being targeted (e.g., 'profile', 'guestbook'). */
+    /**
+     * The Firestore model type being targeted (e.g., 'profile', 'guestbook').
+     */
     readonly modelType: FirestoreModelType;
-    /** The optional sub-operation specifier (e.g., 'username', 'fromUpload'). */
+    /**
+     * The optional sub-operation specifier (e.g., 'username', 'fromUpload').
+     */
     readonly specifier: Maybe<string>;
 }
 /**

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

@@ -50,7 +50,9 @@ export type OnCallDeleteModelMap<N, T extends FirestoreModelIdentity = Firestore
  * Configuration for {@link onCallDeleteModel}.
  */
 export interface OnCallDeleteModelConfig<N> {
-    /** Optional assertion run before the delete handler; throw to reject. */
+    /**
+     * Optional assertion run before the delete handler; throw to reject.
+     */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallDeleteModelParams>;
 }
 /**
@@ -74,5 +76,8 @@ export interface OnCallDeleteModelConfig<N> {
 export declare function onCallDeleteModel<N>(map: OnCallDeleteModelMap<N>, config?: OnCallDeleteModelConfig<N>): OnCallWithNestContext<N, OnCallDeleteModelParams, unknown>;
 /**
  * Creates a bad-request error indicating the requested model type is not valid for deletion.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
  */
 export declare function deleteModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

package/src/lib/nest/model/permission.error.d.ts

@@ -6,6 +6,9 @@ import { type FirebaseDoesNotExistErrorContextErrorFunction, type FirebasePermis
  * which the client can use to display a meaningful "not found" message. Intended to be
  * passed to Firebase permission/existence checking utilities as the
  * {@link FirebaseDoesNotExistErrorContextErrorFunction} callback.
+ *
+ * @param firebaseContextGrantedModelRoles - The granted model roles context containing the document reference.
+ * @returns A model-not-available HTTP error.
  */
 export declare const nestFirebaseDoesNotExistError: FirebaseDoesNotExistErrorContextErrorFunction;
 /**
@@ -14,5 +17,9 @@ export declare const nestFirebaseDoesNotExistError: FirebaseDoesNotExistErrorCon
  * Returns a "forbidden" HTTP error including the document key, model type, and the roles
  * that were required but not granted. Intended to be passed to Firebase permission checking
  * utilities as the {@link FirebasePermissionErrorContextErrorFunction} callback.
+ *
+ * @param firebaseContextGrantedModelRoles - The granted model roles context containing the document reference.
+ * @param roles - The roles that were required but not granted.
+ * @returns A forbidden HTTP error.
  */
 export declare const nestFirebaseForbiddenPermissionError: FirebasePermissionErrorContextErrorFunction;

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

@@ -52,7 +52,9 @@ export type OnCallReadModelMap<N, T extends FirestoreModelIdentity = FirestoreMo
  * Configuration for {@link onCallReadModel}.
  */
 export interface OnCallReadModelConfig<N> {
-    /** Optional assertion run before the read handler; throw to reject. */
+    /**
+     * Optional assertion run before the read handler; throw to reject.
+     */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallReadModelParams>;
 }
 /**
@@ -76,5 +78,8 @@ export interface OnCallReadModelConfig<N> {
 export declare function onCallReadModel<N>(map: OnCallReadModelMap<N>, config?: OnCallReadModelConfig<N>): OnCallWithNestContext<N, OnCallReadModelParams, unknown>;
 /**
  * Creates a bad-request error indicating the requested model type is not valid for reading.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
  */
 export declare function readModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

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

@@ -76,5 +76,8 @@ export declare function onCallSpecifierHandler<N, I = any, O = any>(config: OnCa
 /**
  * Creates a bad-request error indicating the provided specifier is not recognized
  * by the current model CRUD handler.
+ *
+ * @param specifier - The unrecognized specifier string.
+ * @returns A bad-request error with UNKNOWN_SPECIFIER_ERROR code.
  */
 export declare function unknownModelCrudFunctionSpecifierError(specifier: ModelFirebaseCrudFunctionSpecifier): import("firebase-functions/https").HttpsError;

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

@@ -50,7 +50,9 @@ export type OnCallUpdateModelMap<N, T extends FirestoreModelIdentity = Firestore
  * Configuration for {@link onCallUpdateModel}.
  */
 export interface OnCallUpdateModelConfig<N> {
-    /** Optional assertion run before the update handler; throw to reject. */
+    /**
+     * Optional assertion run before the update handler; throw to reject.
+     */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallUpdateModelParams>;
 }
 /**
@@ -77,5 +79,8 @@ export interface OnCallUpdateModelConfig<N> {
 export declare function onCallUpdateModel<N>(map: OnCallUpdateModelMap<N>, config?: OnCallUpdateModelConfig<N>): OnCallWithNestContext<N, OnCallUpdateModelParams, unknown>;
 /**
  * Creates a bad-request error indicating the requested model type is not valid for updating.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with UNKNOWN_TYPE_ERROR code.
  */
 export declare function updateModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

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

@@ -28,9 +28,17 @@ export declare abstract class AbstractNestContext {
     private readonly _nestApplication;
     constructor(nestApplication: INestApplicationContext);
     /**
+     * Returns the NestJS application context.
+     *
      * @deprecated use nestApplication instead.
+     * @returns The NestJS application context.
      */
     get nest(): INestApplicationContext;
+    /**
+     * Returns the NestJS application context.
+     *
+     * @returns The NestJS application context.
+     */
     get nestApplication(): INestApplicationContext;
 }
 /**
@@ -67,6 +75,7 @@ export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseM
      *
      * @param auth - The request's auth data reference.
      * @param buildFn - Optional builder to customize the context.
+     * @returns A model context with auth, app, and error factories.
      */
     makeModelContext(auth: AuthDataRef, buildFn?: BuildFunction<FirebaseAppModelContext<A>>): FirebaseAppModelContext<A>;
     /**
@@ -75,6 +84,7 @@ export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseM
      *
      * @param context - The request's auth data reference.
      * @param buildFn - Optional builder to customize the model context.
+     * @returns An in-context models service scoped to the given auth context.
      */
     model(context: AuthDataRef, buildFn?: BuildFunction<FirebaseAppModelContext<A>>): InContextFirebaseModelsService<Y>;
     useModel<T extends FirebaseModelsServiceTypes<Y>, O>(type: T, select: UseModelInput<FirebaseAppModelContext<A>, Y, T, O>): Promise<O>;

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

@@ -28,6 +28,7 @@ export declare class FirebaseServerStorageContextModule {
  * Creates a NestJS provider that configures the default storage bucket ID.
  *
  * @param input - A bucket ID string or full factory config object.
+ * @returns A NestJS provider for the storage context factory config token.
  * @throws Error if `defaultBucketId` is empty.
  *
  * @example
@@ -44,6 +45,8 @@ export type ProvideFirebaseServerStorageServiceSimple<T extends FirebaseServerSt
 };
 /**
  * Returns the default provider config that creates a standard {@link FirebaseServerStorageService}.
+ *
+ * @returns The default provider configuration for FirebaseServerStorageService.
  */
 export declare function defaultProvideFirebaseServerStorageServiceSimple(): ProvideFirebaseServerStorageServiceSimple<FirebaseServerStorageService>;
 export type ProvideFirebaseServerStorageService<T extends FirebaseServerStorageService> = FactoryProvider<T> | ProvideFirebaseServerStorageServiceSimple<T>;
@@ -52,6 +55,9 @@ export type ProvideFirebaseServerStorageService<T extends FirebaseServerStorageS
  *
  * If the provider token differs from `FirebaseServerStorageService`, an alias provider is added
  * so the service can also be injected by the abstract type.
+ *
+ * @param provider - The storage service provider configuration.
+ * @returns An array of NestJS providers for the storage service.
  */
 export declare function provideFirebaseServerStorageService<T extends FirebaseServerStorageService = FirebaseServerStorageService>(provider: ProvideFirebaseServerStorageService<T>): Provider<T>[];
 export interface FirebaseServerStorageModuleMetadataConfig<T extends FirebaseServerStorageService = FirebaseServerStorageService> extends AdditionalModuleMetadata {
@@ -61,6 +67,9 @@ export interface FirebaseServerStorageModuleMetadataConfig<T extends FirebaseSer
  * Generates NestJS {@link ModuleMetadata} for an app's storage module, including the
  * {@link FirebaseServerStorageContextModule} import and the storage service provider.
  *
+ * @param config - Optional configuration including a custom service provider and additional module metadata.
+ * @returns NestJS module metadata ready to be passed to the `@Module()` decorator.
+ *
  * @example
  * ```typescript
  * @Module(firebaseServerStorageModuleMetadata())

package/src/lib/storage/driver.accessor.d.ts

@@ -3,10 +3,18 @@ import { type SlashPathFolder } from '@dereekb/util';
 import { type GetFilesOptions, type Storage as GoogleCloudStorage, type File as GoogleCloudFile, type FileMetadata, type Bucket } from '@google-cloud/storage';
 /**
  * Resolves a Google Cloud Storage {@link Bucket} from a {@link StoragePath}.
+ *
+ * @param storage - the Google Cloud Storage client instance.
+ * @param path - the storage path containing the bucket ID.
+ * @returns The resolved Google Cloud Storage bucket.
  */
 export declare function googleCloudStorageBucketForStorageFilePath(storage: GoogleCloudStorage, path: StoragePath): Bucket;
 /**
  * Resolves a Google Cloud Storage {@link GoogleCloudFile} from a {@link StoragePath}.
+ *
+ * @param storage - the Google Cloud Storage client instance.
+ * @param path - the storage path containing bucket ID and file path.
+ * @returns The resolved Google Cloud Storage file reference.
  */
 export declare function googleCloudStorageFileForStorageFilePath(storage: GoogleCloudStorage, path: StoragePath): GoogleCloudFile;
 /**
@@ -15,6 +23,10 @@ export declare function googleCloudStorageFileForStorageFilePath(storage: Google
 export type GoogleCloudStorageAccessorFile = FirebaseStorageAccessorFile<GoogleCloudFile> & Required<Pick<FirebaseStorageAccessorFile<GoogleCloudFile>, 'uploadStream' | 'getStream'>>;
 /**
  * Converts Google Cloud Storage {@link FileMetadata} into the normalized {@link StorageMetadata} format.
+ *
+ * @param file - the Google Cloud Storage file reference.
+ * @param metadata - the raw file metadata from the Google Cloud SDK.
+ * @returns Normalized storage metadata.
  */
 export declare function googleCloudFileMetadataToStorageMetadata(file: GoogleCloudFile, metadata: FileMetadata): StorageMetadata;
 /**
@@ -22,6 +34,10 @@ export declare function googleCloudFileMetadataToStorageMetadata(file: GoogleClo
  * and ACL operations for a single file in Google Cloud Storage.
  *
  * Handles emulator-specific edge cases (e.g., signing errors, atomic move fallback).
+ *
+ * @param storage - the Google Cloud Storage client instance.
+ * @param storagePath - the storage path identifying the file's bucket and path.
+ * @returns A file accessor with CRUD, streaming, and ACL operations.
  */
 export declare function googleCloudStorageAccessorFile(storage: GoogleCloudStorage, storagePath: StoragePath): GoogleCloudStorageAccessorFile;
 /**
@@ -49,11 +65,17 @@ export declare const googleCloudStorageListFilesResultFactory: import("@dereekb/
 /**
  * Creates a {@link GoogleCloudStorageAccessorFolder} that supports checking folder existence
  * and listing files/subfolders with pagination.
+ *
+ * @param storage - the Google Cloud Storage client instance.
+ * @param storagePath - the storage path identifying the folder's bucket and prefix.
+ * @returns A folder accessor with existence checking and listing operations.
  */
 export declare function googleCloudStorageAccessorFolder(storage: GoogleCloudStorage, storagePath: StoragePath): GoogleCloudStorageAccessorFolder;
 /**
  * Creates a {@link FirebaseStorageAccessorDriver} for Google Cloud Storage (Admin SDK).
  *
+ * @returns A server-side storage accessor driver for Google Cloud Storage.
+ *
  * @example
  * ```typescript
  * const driver = googleCloudStorageFirebaseStorageAccessorDriver();

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

@@ -8,6 +8,8 @@ export type GoogleCloudFirebaseStorageDrivers = FirebaseStorageDrivers;
  *
  * Bundles the server-side storage accessor driver, identified as `@google-cloud/storage`.
  *
+ * @returns A complete set of storage drivers for server-side usage.
+ *
  * @example
  * ```typescript
  * const drivers = googleCloudFirebaseStorageDrivers();

package/src/lib/storage/storage.d.ts

@@ -12,6 +12,7 @@ export declare const googleCloudFirebaseStorageContextFactory: FirebaseStorageCo
  * Storage wrapper and the raw Google Cloud Storage SDK.
  *
  * @param storage - The Firebase Admin Storage instance.
+ * @returns The underlying Google Cloud Storage client.
  *
  * @example
  * ```typescript

package/test/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.4.1",
+  "version": "13.4.2",
   "peerDependencies": {
-    "@dereekb/analytics": "13.4.1",
-    "@dereekb/date": "13.4.1",
-    "@dereekb/firebase": "13.4.1",
-    "@dereekb/firebase-server": "13.4.1",
-    "@dereekb/model": "13.4.1",
-    "@dereekb/nestjs": "13.4.1",
-    "@dereekb/rxjs": "13.4.1",
-    "@dereekb/util": "13.4.1",
+    "@dereekb/analytics": "13.4.2",
+    "@dereekb/date": "13.4.2",
+    "@dereekb/firebase": "13.4.2",
+    "@dereekb/firebase-server": "13.4.2",
+    "@dereekb/model": "13.4.2",
+    "@dereekb/nestjs": "13.4.2",
+    "@dereekb/rxjs": "13.4.2",
+    "@dereekb/util": "13.4.2",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.16",
@@ -21,7 +21,7 @@
     "make-error": "^1.3.0"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.4.1"
+    "@dereekb/nestjs": "13.4.2"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/index.cjs.js

@@ -49,7 +49,8 @@ var zohoAccessTokenSystemStateEmbeddedTokenConverter = firebase.firestoreSubObje
  * Loads the {@link SystemStateDocument} that stores {@link ZohoAccessTokenSystemStateData},
  * using {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} as the document ID.
  *
- * @param accessor - the document accessor for the SystemState collection
+ * @param accessor - the document accessor for the SystemState collection.
+ * @returns The SystemState document for the Zoho access token data.
  *
  * @example
  * ```ts
@@ -267,7 +268,8 @@ function _ts_generator(thisArg, body) {
  * Tokens are stored in a single {@link SystemState} document (type {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE})
  * and token updates/clears use Firestore transactions for concurrency safety.
  *
- * @param systemStateCollection - the Firestore collection for system state documents
+ * @param systemStateCollection - the Firestore collection for system state documents.
+ * @returns A cache service backed by Firestore system state documents.
  *
  * @example
  * ```ts
@@ -282,7 +284,7 @@ function _ts_generator(thisArg, body) {
             var cache = {
                 loadCachedToken: function loadCachedToken() {
                     return _async_to_generator(function() {
-                        var document, existingData, result, _ref, _existingData_data, tokensArray;
+                        var document, existingData, result, tokensArray;
                         return _ts_generator(this, function(_state) {
                             switch(_state.label){
                                 case 0:
@@ -295,7 +297,7 @@ function _ts_generator(thisArg, body) {
                                     existingData = _state.sent();
                                     result = null;
                                     if (existingData != null) {
-                                        tokensArray = (_ref = existingData === null || existingData === void 0 ? void 0 : (_existingData_data = existingData.data) === null || _existingData_data === void 0 ? void 0 : _existingData_data.tokens) !== null && _ref !== void 0 ? _ref : [];
+                                        tokensArray = existingData.data.tokens;
                                         result = tokensArray.find(function(x) {
                                             return x.key === serviceKey;
                                         });
@@ -318,7 +320,7 @@ function _ts_generator(thisArg, body) {
                                         4,
                                         systemStateCollection.firestoreContext.runTransaction(function(transaction) {
                                             return _async_to_generator(function() {
-                                                var _ref, _existingData_data, documentInTransaction, existingData, existingTokens, tokens, templateOrUpdate;
+                                                var _ref, documentInTransaction, existingData, existingTokens, tokens, templateOrUpdate;
                                                 return _ts_generator(this, function(_state) {
                                                     switch(_state.label){
                                                         case 0:
@@ -329,7 +331,7 @@ function _ts_generator(thisArg, body) {
                                                             ];
                                                         case 1:
                                                             existingData = _state.sent();
-                                                            existingTokens = (_ref = existingData === null || existingData === void 0 ? void 0 : (_existingData_data = existingData.data) === null || _existingData_data === void 0 ? void 0 : _existingData_data.tokens) !== null && _ref !== void 0 ? _ref : [];
+                                                            existingTokens = (_ref = existingData === null || existingData === void 0 ? void 0 : existingData.data.tokens) !== null && _ref !== void 0 ? _ref : [];
                                                             tokens = // filter any potential old token for this service key
                                                             _to_consumable_array(existingTokens.filter(function(x) {
                                                                 return x.key !== serviceKey;