@dereekb/firebase 13.2.2 → 13.3.1

package/src/lib/client/function/function.factory.d.ts

@@ -1,40 +1,106 @@
 import { type ClassLikeType, type Getter, type Maybe } from '@dereekb/util';
 import { type Functions, type HttpsCallableOptions } from 'firebase/functions';
 import { type FirebaseFunctionMap, type FirebaseFunctionTypeMap } from './function';
+/**
+ * Per-function configuration for creating `HttpsCallable` instances, allowing
+ * custom `HttpsCallableOptions` (e.g., timeout) per function key.
+ */
 export interface FirebaseFunctionTypeConfig {
     readonly options?: HttpsCallableOptions;
 }
+/**
+ * Maps each function key in a {@link FirebaseFunctionTypeMap} to its optional configuration.
+ */
 export type FirebaseFunctionTypeConfigMap<M extends FirebaseFunctionTypeMap> = {
     readonly [K in keyof M]: Maybe<FirebaseFunctionTypeConfig>;
 };
 /**
- * Used for building a FirebaseFunctionMap<M> for a specific Functions instance.
+ * Factory that creates a {@link FirebaseFunctionMap} for a given `Functions` instance.
+ *
+ * Call this with a live `Functions` instance to get a map of typed callable functions
+ * ready to invoke.
  */
 export type FirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap> = (functionsInstance: Functions) => FirebaseFunctionMap<M>;
+/**
+ * Creates a {@link FirebaseFunctionMapFactory} from a configuration map.
+ *
+ * Each key in the config map becomes an `HttpsCallable` function wrapped with {@link directDataHttpsCallable}
+ * for direct data access. Per-key options (e.g., timeout) are applied if provided.
+ *
+ * @param configMap - maps function keys to their optional configuration
+ *
+ * @example
+ * ```ts
+ * const factory = firebaseFunctionMapFactory<MyFunctionTypeMap>({
+ *   createUser: { options: { timeout: 30000 } },
+ *   deleteUser: null
+ * });
+ * const functions = factory(getFunctions());
+ * const result = await functions.createUser({ name: 'Alice' });
+ * ```
+ */
 export declare function firebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap>(configMap: FirebaseFunctionTypeConfigMap<M>): FirebaseFunctionMapFactory<M>;
+/**
+ * String key used to identify a function group in the app-level functions map.
+ */
 export type FirebaseFunctionMapKey = string;
+/**
+ * Lazy getter that also carries metadata about the function group's type and key.
+ *
+ * The `_type` property holds the class constructor for type identification (used by injection),
+ * and `_key` holds the string key in the app-level {@link FirebaseFunctionsMap}.
+ */
 export type FirebaseFunctionGetter<T> = Getter<T> & {
     _type: ClassLikeType<T>;
     _key: FirebaseFunctionMapKey;
 };
 /**
- * Map of all firebase functions in the app.
+ * Top-level map of all function groups in the app. Each key represents a logical function group
+ * (e.g., `'notificationFunctions'`, `'developmentFunctions'`) mapped to its {@link FirebaseFunctionTypeMap}.
  */
 export type FirebaseFunctionsMap = {
     readonly [key: FirebaseFunctionMapKey]: FirebaseFunctionTypeMap;
 };
+/**
+ * Configuration map for building a {@link LazyFirebaseFunctions} instance.
+ * Each entry pairs a class type (for DI identification) with a factory function.
+ */
 export type FirebaseFunctionsConfigMap<M extends FirebaseFunctionsMap> = {
     readonly [K in keyof M]: FirebaseFunctionsConfigMapEntry<M[K]>;
 };
+/**
+ * Tuple of `[ClassType, FactoryFunction]` for a single function group entry.
+ */
 export type FirebaseFunctionsConfigMapEntry<M extends FirebaseFunctionTypeMap> = [ClassLikeType, FirebaseFunctionMapFactory<M>];
 /**
- * Factory function for creating a FirebaseFunctionsMap for a given Functions instance.
+ * Factory that creates a {@link LazyFirebaseFunctions} map for a given `Functions` instance.
  */
 export type LazyFirebaseFunctionsFactory<M extends FirebaseFunctionsMap> = (functions: Functions) => LazyFirebaseFunctions<M>;
 /**
- * Map of FirebaseFunctionGetter values that are lazy-loaded via the getter.
+ * Map of lazy-loaded function groups. Each group is a {@link FirebaseFunctionGetter} that
+ * defers initialization until first access via `cachedGetter`, avoiding unnecessary
+ * `httpsCallable` instantiation for unused function groups.
  */
 export type LazyFirebaseFunctions<M extends FirebaseFunctionsMap> = {
     readonly [K in keyof M]: FirebaseFunctionGetter<FirebaseFunctionMap<M[K]>>;
 };
+/**
+ * Creates a {@link LazyFirebaseFunctionsFactory} from a config map of function groups.
+ *
+ * Each function group is lazily initialized on first access using `cachedGetter`,
+ * so `httpsCallable` instances are only created when actually needed.
+ *
+ * @param configMap - maps each function group key to its `[ClassType, Factory]` tuple
+ *
+ * @example
+ * ```ts
+ * const factory = lazyFirebaseFunctionsFactory<AppFunctionsMap>({
+ *   notificationFunctions: [NotificationFunctions, notificationFunctionMapFactory],
+ *   developmentFunctions: [DevelopmentFunctions, devFunctionMapFactory]
+ * });
+ *
+ * const lazyFns = factory(getFunctions());
+ * const notifFns = lazyFns.notificationFunctions(); // initialized on first call
+ * ```
+ */
 export declare function lazyFirebaseFunctionsFactory<M extends FirebaseFunctionsMap, C extends FirebaseFunctionsConfigMap<M> = FirebaseFunctionsConfigMap<M>>(configMap: C): LazyFirebaseFunctionsFactory<M>;

package/src/lib/client/function/model.function.factory.d.ts

@@ -6,23 +6,47 @@ import { type FirebaseFunctionTypeMap, type FirebaseFunctionMap, type FirebaseFu
 import { type FirebaseFunctionTypeConfigMap } from './function.factory';
 import { type OnCallCreateModelResult } from '../../common/model/function';
 /**
- * Used to specify which function to direct requests to.
+ * String identifier that routes a CRUD request to a specific sub-handler within a model's
+ * CRUD function. For example, a model's `update` might have specifiers like `'status'` or `'config'`
+ * to target different update behaviors.
  */
 export type ModelFirebaseCrudFunctionSpecifier = string;
 /**
- * Provides a reference to a ModelFirebaseCrudFunctionSpecifier if available.
+ * Optional reference to a {@link ModelFirebaseCrudFunctionSpecifier}, used to route CRUD requests
+ * to a specific sub-handler.
  */
 export type ModelFirebaseCrudFunctionSpecifierRef = {
     readonly specifier?: ModelFirebaseCrudFunctionSpecifier;
 };
+/**
+ * Generic CRUD function for a Firestore model. Wraps {@link FirebaseFunction} with model-specific input/output types.
+ */
 export type ModelFirebaseCrudFunction<I, O = void> = FirebaseFunction<I, O>;
+/**
+ * Create function for a model. Returns {@link OnCallCreateModelResult} containing the created document's key by default.
+ */
 export type ModelFirebaseCreateFunction<I, O extends OnCallCreateModelResult = OnCallCreateModelResult> = ModelFirebaseCrudFunction<I, O>;
+/** Read function for a model, returning the read data. */
 export type ModelFirebaseReadFunction<I, O> = ModelFirebaseCrudFunction<I, O>;
+/** Update function for a model. Returns void by default. */
 export type ModelFirebaseUpdateFunction<I, O = void> = ModelFirebaseCrudFunction<I, O>;
+/** Delete function for a model. Returns void by default. */
 export type ModelFirebaseDeleteFunction<I, O = void> = ModelFirebaseCrudFunction<I, O>;
+/**
+ * Maps each model type (from a {@link FirestoreModelIdentity}) to its CRUD function type configuration.
+ *
+ * Each entry defines which CRUD operations (create, read, update, delete) are available for
+ * that model type, along with optional specifiers for sub-operations.
+ */
 export type ModelFirebaseCrudFunctionTypeMap<T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
     [K in FirestoreModelTypes<T>]: ModelFirebaseCrudFunctionTypeMapEntry;
 };
+/**
+ * Entry for a single model type in a {@link ModelFirebaseCrudFunctionTypeMap}.
+ *
+ * Can be `null`/`undefined` (no CRUD functions for this model) or a partial record of
+ * create/read/update/delete configurations, each optionally with specifiers.
+ */
 export type ModelFirebaseCrudFunctionTypeMapEntry = MaybeNot | Partial<ModelFirebaseCrudFunctionCreateTypeConfig & ModelFirebaseCrudFunctionReadTypeConfig & ModelFirebaseCrudFunctionUpdateTypeConfig & ModelFirebaseCrudFunctionDeleteTypeConfig>;
 export type ModelFirebaseCrudFunctionTypeMapEntryWithReturnType<I = unknown, O = unknown> = [I, O];
 export type ModelFirebaseCrudFunctionTypeSpecifierConfig = Record<string | number, unknown | ModelFirebaseCrudFunctionTypeMapEntryWithReturnType>;
@@ -38,14 +62,23 @@ export type ModelFirebaseCrudFunctionUpdateTypeConfig = {
 export type ModelFirebaseCrudFunctionDeleteTypeConfig = {
     readonly delete: unknown | ModelFirebaseCrudFunctionTypeSpecifierConfig;
 };
+/**
+ * Default specifier string (`'_'`) used when a CRUD operation has specifiers but one
+ * should map to the base function name without a specifier suffix.
+ */
 export declare const MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER_DEFAULT = "_";
 export type ModelFirebaseCrudFunctionSpecifierDefault = typeof MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER_DEFAULT;
+/**
+ * Separator character (`','`) used to split multiple specifier keys in a config string.
+ * For example, `'update:status,config'` defines two update specifiers: `status` and `config`.
+ */
 export declare const MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER_SPLITTER = ",";
 export type ModelFirebaseCrudFunctionSpecifierSplitter = typeof MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER_SPLITTER;
 /**
- * The configuration for a types map.
+ * Configuration map that defines which CRUD operations and specifiers to generate for each model type.
  *
- * The FirestoreModelIdentities that are allowed are passed too which add type checking to make sure we're passing the expected identities.
+ * The {@link FirestoreModelIdentity} type parameter `T` constrains which model type keys are
+ * valid, providing compile-time safety. Entries are string arrays like `['create', 'update:status,config']`.
  */
 export type ModelFirebaseCrudFunctionConfigMap<C extends ModelFirebaseCrudFunctionTypeMap<T>, T extends FirestoreModelIdentity> = NonNever<{
     [K in FirestoreModelTypes<T>]: C[K] extends null ? never : ModelFirebaseCrudFunctionConfigMapEntry<C[K]>;
@@ -72,16 +105,38 @@ export type ModelFirebaseCrudFunctionMapEntrySpecifierShort<MODEL extends string
     [SPECIFIER in keyof M as SPECIFIER extends string ? (CRUD extends string ? (SPECIFIER extends ModelFirebaseCrudFunctionSpecifierDefault ? CRUD : SPECIFIER) : never) : never]: ModelFirebaseCrudFunctionMapEntryFunction<M, SPECIFIER, CRUD>;
 };
 export declare type ModelFirebaseCrudFunctionMapEntryFunction<E extends unknown | ModelFirebaseCrudFunctionTypeSpecifierConfig, K extends keyof E, CRUD extends string> = E[K] extends ModelFirebaseCrudFunctionTypeMapEntryWithReturnType<infer I, infer O> ? ModelFirebaseCrudFunction<I, O> : CRUD extends 'create' ? ModelFirebaseCreateFunction<E[K]> : ModelFirebaseCrudFunction<E[K]>;
+/**
+ * Combined function map providing both custom functions ({@link FirebaseFunctionMap}) and
+ * auto-generated model CRUD functions ({@link ModelFirebaseCrudFunctionMap}).
+ */
 export type ModelFirebaseFunctionMap<M extends FirebaseFunctionTypeMap, C extends ModelFirebaseCrudFunctionTypeMap> = FirebaseFunctionMap<M> & ModelFirebaseCrudFunctionMap<C>;
 /**
- * Used for building a FirebaseFunctionMap<M> for a specific Functions instance.
+ * Factory that creates a {@link ModelFirebaseFunctionMap} for a given `Functions` instance.
  */
 export type ModelFirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap, U extends ModelFirebaseCrudFunctionTypeMap> = (functionsInstance: Functions) => ModelFirebaseFunctionMap<M, U>;
 /**
- * Creates a ModelFirebaseFunctionMapFactory for the input config that targets the "callModel" Firebase function.
+ * Creates a {@link ModelFirebaseFunctionMapFactory} that routes model CRUD operations through the
+ * single `callModel` Cloud Function endpoint.
+ *
+ * Rather than creating separate `HttpsCallable` instances for each CRUD operation, all model
+ * operations are multiplexed through a single Firebase function (identified by {@link CALL_MODEL_APP_FUNCTION_KEY}).
+ * The model type, CRUD operation, and optional specifier are encoded into the request parameters
+ * via {@link onCallTypedModelParamsFunction}.
+ *
+ * Custom (non-CRUD) functions from `configMap` get their own individual `HttpsCallable` instances.
+ *
+ * @param configMap - configuration for custom (non-CRUD) functions
+ * @param crudConfigMap - configuration for model CRUD functions with optional specifiers
  *
- * @param configMap
- * @param crudConfigMap
- * @returns
+ * @example
+ * ```ts
+ * const factory = callModelFirebaseFunctionMapFactory<CustomFnMap, CrudMap>(
+ *   { customFn: null },
+ *   { notification: ['create', 'update:status,config', 'delete'] }
+ * );
+ * const fns = factory(getFunctions());
+ * await fns.createNotification(data);
+ * await fns.updateNotificationStatus(data);
+ * ```
  */
 export declare function callModelFirebaseFunctionMapFactory<M extends FirebaseFunctionTypeMap, U extends ModelFirebaseCrudFunctionTypeMap>(configMap: FirebaseFunctionTypeConfigMap<M>, crudConfigMap: ModelFirebaseCrudFunctionConfigMap<U, FirestoreModelIdentity>): ModelFirebaseFunctionMapFactory<M, U>;

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

@@ -2,16 +2,109 @@ import { type FirebaseStorageAccessorDriver, type FirebaseStorageAccessorFile, t
 import { type StoragePath } from '../../common/storage/storage';
 import { type ListResult, type StorageReference, type FirebaseStorage as ClientFirebaseStorage } from 'firebase/storage';
 import { type ErrorInput, type Maybe } from '@dereekb/util';
+/**
+ * Checks whether an error is a Firebase Storage "object not found" error.
+ *
+ * Useful for distinguishing missing-file errors from other storage failures,
+ * e.g., to silently handle deletion of already-deleted files.
+ *
+ * @param input - the error or error message to check
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await deleteObject(ref);
+ * } catch (e) {
+ *   if (isFirebaseStorageObjectNotFoundError(e)) {
+ *     // file already deleted, safe to ignore
+ *   }
+ * }
+ * ```
+ */
 export declare function isFirebaseStorageObjectNotFoundError(input: Maybe<ErrorInput | string>): boolean;
+/**
+ * Creates a `StorageReference` from an abstract {@link StoragePath} using the client `firebase/storage` SDK.
+ *
+ * @param storage - the client Firebase Storage instance
+ * @param path - abstract storage path to resolve
+ */
 export declare function firebaseStorageRefForStorageFilePath(storage: ClientFirebaseStorage, path: StoragePath): StorageReference;
+/**
+ * Checks whether a file exists at the given `StorageReference` by attempting to read its metadata.
+ *
+ * Returns `true` if metadata is successfully retrieved, `false` for any error (including permission errors).
+ *
+ * @param ref - the storage reference to check
+ */
 export declare function firebaseStorageFileExists(ref: StorageReference): Promise<boolean>;
+/**
+ * Client-side specialization of {@link FirebaseStorageAccessorFile} using `StorageReference` as the native reference type.
+ */
 export type FirebaseStorageClientAccessorFile = FirebaseStorageAccessorFile<StorageReference>;
+/**
+ * Creates a client-side {@link FirebaseStorageAccessorFile} for a specific storage path.
+ *
+ * Provides all file operations (upload, download, metadata, delete, resumable upload) backed by
+ * the `firebase/storage` SDK. Resumable uploads expose an Observable stream of upload progress snapshots.
+ *
+ * @param storage - the client Firebase Storage instance
+ * @param storagePath - the abstract storage path for the file
+ *
+ * @example
+ * ```ts
+ * const file = firebaseStorageClientAccessorFile(storage, { bucketId: 'my-bucket', pathString: 'uploads/photo.jpg' });
+ * const url = await file.getDownloadUrl();
+ * ```
+ */
 export declare function firebaseStorageClientAccessorFile(storage: ClientFirebaseStorage, storagePath: StoragePath): FirebaseStorageClientAccessorFile;
+/**
+ * Client-side specialization of {@link FirebaseStorageAccessorFolder} using `StorageReference` as the native reference type.
+ */
 export type FirebaseStorageClientAccessorFolder = FirebaseStorageAccessorFolder<StorageReference>;
+/**
+ * Internal result wrapper for client-side storage list operations, holding the raw `ListResult`
+ * and the options used to produce it. Used by {@link firebaseStorageClientListFilesResultFactory}
+ * to support pagination and nested listing.
+ */
 export interface FirebaseStorageClientListResult {
     listResult: ListResult;
     options?: StorageListFilesOptions;
 }
+/**
+ * Pre-configured {@link storageListFilesResultFactory} for the client `firebase/storage` SDK.
+ *
+ * Handles pagination tokens, nested folder traversal, and mapping between Firebase `ListResult`
+ * items and the abstract {@link StorageListItemResult} interface.
+ */
 export declare const firebaseStorageClientListFilesResultFactory: import("../..").StorageListFilesResultFactory<ClientFirebaseStorage, FirebaseStorageClientListResult>;
+/**
+ * Creates a client-side {@link FirebaseStorageAccessorFolder} for a specific storage path.
+ *
+ * Supports existence checks, paginated file/folder listing, and recursive nested listing
+ * when `includeNestedResults` is enabled.
+ *
+ * @param storage - the client Firebase Storage instance
+ * @param storagePath - the abstract storage path for the folder
+ *
+ * @example
+ * ```ts
+ * const folder = firebaseStorageClientAccessorFolder(storage, { bucketId: 'my-bucket', pathString: 'uploads/' });
+ * const result = await folder.list({ maxResults: 10 });
+ * const files = result.files();
+ * ```
+ */
 export declare function firebaseStorageClientAccessorFolder(storage: ClientFirebaseStorage, storagePath: StoragePath): FirebaseStorageClientAccessorFolder;
+/**
+ * Creates the client-side {@link FirebaseStorageAccessorDriver} that maps the abstract storage
+ * accessor interface to the `firebase/storage` SDK.
+ *
+ * Provides file and folder accessor factories and default bucket resolution.
+ * Used internally by {@link firebaseStorageClientDrivers}.
+ *
+ * @example
+ * ```ts
+ * const driver = firebaseStorageClientAccessorDriver();
+ * const file = driver.file(storage, storagePath);
+ * ```
+ */
 export declare function firebaseStorageClientAccessorDriver(): FirebaseStorageAccessorDriver;

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

@@ -1,3 +1,18 @@
 import { type FirebaseStorageDrivers } from '../../common/storage/driver/driver';
+/**
+ * Client-side {@link FirebaseStorageDrivers} using the `firebase/storage` SDK.
+ */
 export type FirebaseStorageClientDrivers = FirebaseStorageDrivers;
+/**
+ * Creates the client-side {@link FirebaseStorageDrivers} that bind the abstract storage driver
+ * interfaces to the `firebase/storage` SDK (browser/client).
+ *
+ * Provides file and folder accessor operations for use with {@link clientFirebaseStorageContextFactory}.
+ *
+ * @example
+ * ```ts
+ * const drivers = firebaseStorageClientDrivers();
+ * const contextFactory = firebaseStorageContextFactory(drivers);
+ * ```
+ */
 export declare function firebaseStorageClientDrivers(): FirebaseStorageClientDrivers;

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

@@ -1,5 +1,14 @@
 import { type FirebaseStorageContextFactory } from '../../common/storage/context';
 /**
- * Creates a FirebaseStorageContextFactory that uses the client @firebase/storage package.
+ * Pre-configured {@link FirebaseStorageContextFactory} for client-side (browser) Firebase Storage usage.
+ *
+ * Wires the client Storage drivers (from the `firebase/storage` SDK) into the abstract
+ * {@link FirebaseStorageContextFactory} so that file and folder operations use the client-side implementation.
+ *
+ * @example
+ * ```ts
+ * const context = clientFirebaseStorageContextFactory(storage);
+ * const file = context.file({ bucketId: 'my-bucket', pathString: 'uploads/image.png' });
+ * ```
  */
 export declare const clientFirebaseStorageContextFactory: FirebaseStorageContextFactory;

package/src/lib/common/auth/auth.context.d.ts

@@ -1,13 +1,19 @@
 import { type AuthClaims, type AuthClaimsObject, type AuthRoleSet, type MappedUseFunction, type Maybe, type UseValue } from '@dereekb/util';
 import { type FirebaseAuthToken, type FirebaseAuthUserId } from './auth';
 /**
- * Provides a context containing FirebaseAuthContextInfo
+ * Context that optionally carries the current user's authentication state.
+ *
+ * Used throughout the Firebase model and permission system to determine what
+ * the current caller is authorized to do. A missing `auth` implies an unauthenticated request.
  */
 export interface FirebaseAuthContext {
     readonly auth?: Maybe<FirebaseAuthContextInfo>;
 }
 /**
- * Auth contextual information
+ * Resolved authentication information for the current request/context.
+ *
+ * Provides the user's UID, admin status, custom claims, and auth roles.
+ * Typically derived from a decoded Firebase ID token or the Firebase Admin SDK.
  */
 export interface FirebaseAuthContextInfo {
     /**
@@ -31,6 +37,15 @@ export interface FirebaseAuthContextInfo {
      */
     readonly token: FirebaseAuthToken;
 }
+/**
+ * {@link UseValue} wrapper for {@link FirebaseAuthContextInfo}.
+ */
 export type UseFirebaseAuthContextInfo<I extends FirebaseAuthContextInfo = FirebaseAuthContextInfo> = UseValue<I>;
+/**
+ * Extracts the {@link FirebaseAuthContextInfo} from a {@link FirebaseAuthContext}.
+ */
 export declare const useContextAuth: MappedUseFunction<FirebaseAuthContext, FirebaseAuthContextInfo>;
+/**
+ * Extracts the user UID directly from a {@link FirebaseAuthContext}.
+ */
 export declare const useContextAuthUid: MappedUseFunction<FirebaseAuthContext, FirebaseAuthUserId>;

package/src/lib/common/auth/auth.d.ts

@@ -1,23 +1,36 @@
 import { type ISO8601DateString, type Maybe, type PasswordString, type PhoneNumber, type WebsiteUrl } from '@dereekb/util';
 /**
- * Don't use passwords smaller tahn 6.
+ * Minimum password length enforced by Firebase Authentication.
+ *
+ * Firebase requires at least 6 characters for password-based auth.
  */
 export declare const FIREBASE_AUTH_PASSWORD_MIN_LENGTH = 6;
 /**
- * Passwords longer than 128 characters are not useful...
+ * Practical maximum password length for Firebase Authentication.
  *
- * (but they are allowed by Firebase. There is no posted upper limit)
+ * Firebase has no posted upper limit, but passwords beyond 128 characters provide diminishing security value.
  */
 export declare const FIREBASE_AUTH_PASSWORD_MAX_LENGTH = 128;
 /**
- * Firebase User Identifier (UID)
+ * Unique identifier for a Firebase Authentication user (the `uid` from Firebase Auth).
  */
 export type FirebaseAuthUserId = string;
+/**
+ * Contains a reference to a Firebase Auth user's UID.
+ */
 export interface FirebaseAuthUserIdRef {
     uid: FirebaseAuthUserId;
 }
 /**
- * Firebase Auth Token interface
+ * Raw encoded JWT for Firebase Auth.
+ *
+ * Corresponds with IdToken type in Firebase Auth.
+ */
+export type FirebaseAuthIdToken = string;
+/**
+ * Decoded Firebase Auth token information, containing user identity details from the authentication provider.
+ *
+ * These fields come from the Firebase Auth token and represent the user's current identity state.
  */
 export interface FirebaseAuthToken {
     readonly email?: Maybe<string>;
@@ -38,6 +51,11 @@ export interface FirebaseAuthToken {
      */
     readonly lastRefreshTime?: Maybe<ISO8601DateString>;
 }
+/**
+ * Extended auth details combining token information with user profile fields.
+ *
+ * Represents the full set of user identity data available from Firebase Authentication.
+ */
 export interface FirebaseAuthDetails extends FirebaseAuthToken, Readonly<FirebaseAuthUserIdRef> {
     readonly disabled?: Maybe<boolean>;
     readonly displayName?: Maybe<string>;
@@ -55,25 +73,36 @@ export type FirebaseAuthOwnershipKey = string;
 export type FirebaseAuthSetupPassword = PasswordString;
 export declare const FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY = "setupPassword";
 export declare const FIREBASE_SERVER_AUTH_CLAIMS_SETUP_LAST_COM_DATE_KEY = "setupCommunicationAt";
+/**
+ * Custom claims data set on a newly-created Firebase Auth user to enable out-of-band account setup.
+ *
+ * The setup password is included in the invitation link so the user can verify ownership
+ * without requiring an immediate sign-in flow.
+ */
 export interface FirebaseAuthNewUserClaimsData {
     /**
-     * Setup password
+     * One-time setup password embedded in the user's claims for account initialization.
      */
     readonly setupPassword: FirebaseAuthSetupPassword;
     /**
-     * Last setup communication time.
+     * ISO 8601 timestamp of the last setup-related communication (e.g., invitation email).
      */
     readonly setupCommunicationAt: ISO8601DateString;
 }
 export declare const FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY = "resetPassword";
 export declare const FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY = "resetCommunicationAt";
+/**
+ * Custom claims data set on a Firebase Auth user during a password reset flow.
+ *
+ * Similar to {@link FirebaseAuthNewUserClaimsData} but for reset scenarios.
+ */
 export interface FirebaseAuthResetUserPasswordClaimsData {
     /**
-     * Reset password
+     * One-time reset password embedded in the user's claims for password reset verification.
      */
     readonly resetPassword: FirebaseAuthSetupPassword;
     /**
-     * Last reset communication time.
+     * ISO 8601 timestamp of the last reset-related communication (e.g., reset email).
      */
     readonly resetCommunicationAt: ISO8601DateString;
 }

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

@@ -1,12 +1,37 @@
 import { type ReadableError } from '@dereekb/util';
 import { type FirebaseErrorCode } from '../error';
+/**
+ * Shape of a Firebase Authentication error, matching the error structure from the Firebase Auth SDK.
+ */
 export interface FirebaseAuthError {
     readonly code: FirebaseErrorCode;
     readonly name: string;
     readonly customData: unknown;
 }
+/** Error code when the user account is not found. */
 export declare const FIREBASE_AUTH_USER_NOT_FOUND_ERROR = "auth/user-not-found";
+/** Error code when the password is incorrect. */
 export declare const FIREBASE_AUTH_WRONG_PASSWORD = "auth/wrong-password";
+/** Error code for a network request error (client SDK). */
 export declare const FIREBASE_AUTH_NETWORK_REQUEST_ERROR = "auth/network-request-error";
+/** Error code for a failed network request (client SDK). */
 export declare const FIREBASE_AUTH_NETWORK_REQUEST_FAILED = "auth/network-request-failed";
+/**
+ * Converts a {@link FirebaseAuthError} into a user-friendly {@link ReadableError} with a human-readable message.
+ *
+ * Maps known error codes (wrong password, user not found, network errors) to contextual messages
+ * suitable for display in the UI.
+ *
+ * @param inputError - the Firebase Auth error to convert
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await signIn(email, password);
+ * } catch (e) {
+ *   const readable = firebaseAuthErrorToReadableError(e as FirebaseAuthError);
+ *   showToast(readable.message);
+ * }
+ * ```
+ */
 export declare function firebaseAuthErrorToReadableError(inputError: FirebaseAuthError): ReadableError;

package/src/lib/common/auth/auth.server.error.d.ts

@@ -1,8 +1,12 @@
 /**
- * Thrown by a dbx-firebase server function when the input context does not have the expected auth data on a Firebase function call.
+ * Error code used when a Firebase Cloud Function is called without any authentication context.
+ *
+ * Typically caught by middleware that validates auth before allowing the function to proceed.
  */
 export declare const DBX_FIREBASE_SERVER_NO_AUTH_ERROR_CODE = "NO_AUTH";
 /**
- * Thrown by a dbx-firebase server function when the input context does not have a user uid on a Firebase function call.
+ * Error code used when a Firebase Cloud Function has an auth context but is missing the user UID.
+ *
+ * This can happen with anonymous or malformed tokens.
  */
 export declare const DBX_FIREBASE_SERVER_NO_UID_ERROR_CODE = "NO_USER_UID";

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

@@ -1,23 +1,34 @@
 /**
- * Used to specify which function to direct requests to.
+ * Identifies a specific development function endpoint to route requests to.
+ *
+ * Used in dev/test environments to invoke specific server-side functions by name.
  */
 export type DevelopmentFirebaseFunctionSpecifier = string;
 /**
- * Provides a reference to a DevelopmentFirebaseFunctionSpecifier if available.
+ * Contains a reference to a {@link DevelopmentFirebaseFunctionSpecifier}.
  */
 export type DevelopmentFirebaseFunctionSpecifierRef = {
     specifier: DevelopmentFirebaseFunctionSpecifier;
 };
+/**
+ * Parameters for calling a development-only Firebase function via the `dev` endpoint.
+ *
+ * Routes the call to a specific function via `specifier` and passes arbitrary data.
+ */
 export interface OnCallDevelopmentParams<T = unknown> {
     specifier: string;
     data: T;
 }
 /**
- * Creates an OnCallDevelopmentParams
+ * Creates an {@link OnCallDevelopmentParams} envelope for a development function call.
+ *
+ * @param specifier - the development function to invoke
+ * @param data - the call payload
  *
- * @param modelType
- * @param data
- * @returns
+ * @example
+ * ```ts
+ * const params = onCallDevelopmentParams('resetDatabase', { confirm: true });
+ * ```
  */
 export declare function onCallDevelopmentParams<T>(specifier: string, data: T): OnCallDevelopmentParams<T>;
 /**