@dereekb/firebase 13.2.2 → 13.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.2.2",
+  "version": "13.3.0",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -17,10 +17,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "13.2.2",
-    "@dereekb/model": "13.2.2",
-    "@dereekb/rxjs": "13.2.2",
-    "@dereekb/util": "13.2.2",
+    "@dereekb/util": "13.3.0",
+    "@dereekb/date": "13.3.0",
+    "@dereekb/model": "13.3.0",
+    "@dereekb/rxjs": "13.3.0",
     "@firebase/rules-unit-testing": "5.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.0.0",

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

@@ -1,8 +1,23 @@
 import { type FirebaseError } from 'firebase/app';
 /**
- * Returns true if the input is seen as a client-side FirebaseError.
+ * Type guard that checks whether an error is a client-side {@link FirebaseError} from the `firebase/app` package.
  *
- * @param error
- * @returns
+ * Distinguishes client Firebase errors from server-side errors or generic errors by checking
+ * for the `FirebaseError` name and a string `code` property. Used by {@link convertHttpsCallableErrorToReadableError}
+ * to determine the appropriate error wrapping strategy.
+ *
+ * @param error - the value to check
+ * @returns `true` if the input matches the shape of a client-side `FirebaseError`
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await someFirebaseOperation();
+ * } catch (e) {
+ *   if (isClientFirebaseError(e)) {
+ *     console.log(e.code); // e.g., 'auth/user-not-found'
+ *   }
+ * }
+ * ```
  */
 export declare function isClientFirebaseError(error: any): error is FirebaseError;

package/src/lib/client/firestore/array.d.ts

@@ -1,9 +1,22 @@
 import { type FirestoreAccessorArrayUpdate } from '../../common/firestore/accessor/accessor';
 import { type UpdateData } from '../../common/firestore/types';
 /**
- * Creates UpdateData corresponding to the input array update.
+ * Converts a {@link FirestoreAccessorArrayUpdate} into Firestore `UpdateData` using the
+ * client-side `arrayUnion()` and `arrayRemove()` FieldValue sentinels.
  *
- * @param input
- * @returns
+ * Processes both `union` (add elements) and `remove` (delete elements) operations,
+ * spreading array values as individual arguments since Firestore does not allow nested arrays.
+ *
+ * @param input - object with `union` and/or `remove` maps from field names to arrays of values
+ * @returns Firestore `UpdateData` with `FieldValue.arrayUnion()`/`FieldValue.arrayRemove()` sentinels
+ *
+ * @example
+ * ```ts
+ * const updateData = firestoreClientArrayUpdateToUpdateData<MyModel>({
+ *   union: { tags: ['newTag'] },
+ *   remove: { tags: ['oldTag'] }
+ * });
+ * await updateDoc(docRef, updateData);
+ * ```
  */
 export declare function firestoreClientArrayUpdateToUpdateData<T extends object>(input: FirestoreAccessorArrayUpdate<T>): UpdateData<T>;

package/src/lib/client/firestore/driver.accessor.batch.d.ts

@@ -2,7 +2,11 @@ import { type DocumentReference, type WriteBatch as FirebaseFirestoreWriteBatch
 import { type FirestoreDocumentContext, type UpdateData, type DocumentData, type WithFieldValue, FirestoreDocumentContextType, type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type SetOptions } from '../../common/firestore';
 import { DefaultFirestoreDocumentDataAccessor } from './driver.accessor.default';
 /**
- * FirestoreDocumentDataAccessor implementation for a batch.
+ * Client-side {@link FirestoreDocumentDataAccessor} that queues write operations into a Firestore `WriteBatch`.
+ *
+ * Extends {@link DefaultFirestoreDocumentDataAccessor} to override `delete`, `set`, and `update` so they
+ * add operations to the batch rather than executing immediately. Read operations (`get`, `stream`, `exists`)
+ * still execute directly against Firestore. The batch must be committed separately after all operations are queued.
  */
 export declare class WriteBatchFirestoreDocumentDataAccessor<T> extends DefaultFirestoreDocumentDataAccessor<T> implements FirestoreDocumentDataAccessor<T> {
     private readonly _batch;
@@ -13,12 +17,28 @@ export declare class WriteBatchFirestoreDocumentDataAccessor<T> extends DefaultF
     update(data: UpdateData<object>): Promise<void>;
 }
 /**
- * Creates a new FirestoreDocumentDataAccessorFactory for a Batch.
+ * Creates a {@link FirestoreDocumentDataAccessorFactory} that produces {@link WriteBatchFirestoreDocumentDataAccessor}
+ * instances bound to the given `WriteBatch`. All write operations from these accessors are queued
+ * into the same batch.
+ *
+ * @param writeBatch - the Firestore `WriteBatch` to queue operations into
  *
- * @param batch
- * @returns
+ * @example
+ * ```ts
+ * const batch = writeBatch(firestore);
+ * const factory = writeBatchAccessorFactory<MyModel>(batch);
+ * const accessor = factory.accessorFor(docRef);
+ * await accessor.set(data);
+ * await batch.commit();
+ * ```
  */
 export declare function writeBatchAccessorFactory<T>(writeBatch: FirebaseFirestoreWriteBatch): FirestoreDocumentDataAccessorFactory<T>;
+/**
+ * Client-side {@link FirestoreDocumentContext} that groups all document operations into a single `WriteBatch`.
+ *
+ * Provides accessors with {@link FirestoreDocumentContextType.BATCH} semantics — writes are queued
+ * and only applied when the batch is committed.
+ */
 export declare class WriteBatchFirestoreDocumentContext<T> implements FirestoreDocumentContext<T> {
     private readonly _batch;
     readonly contextType = FirestoreDocumentContextType.BATCH;
@@ -26,4 +46,15 @@ export declare class WriteBatchFirestoreDocumentContext<T> implements FirestoreD
     constructor(batch: FirebaseFirestoreWriteBatch);
     get batch(): FirebaseFirestoreWriteBatch;
 }
+/**
+ * Factory function that creates a {@link WriteBatchFirestoreDocumentContext} for the given batch.
+ *
+ * @param batch - the Firestore `WriteBatch` to use for all document operations
+ *
+ * @example
+ * ```ts
+ * const batch = writeBatch(firestore);
+ * const context = writeBatchDocumentContext<MyModel>(batch);
+ * ```
+ */
 export declare function writeBatchDocumentContext<T>(batch: FirebaseFirestoreWriteBatch): WriteBatchFirestoreDocumentContext<T>;

package/src/lib/client/firestore/driver.accessor.create.d.ts

@@ -1,3 +1,18 @@
 import { type FirestoreDocumentDataAccessor } from '../../common/firestore/accessor/accessor';
 import { type WithFieldValue, type WriteResult } from '../../common/firestore/types';
+/**
+ * Returns a function that creates a document only if it does not already exist.
+ *
+ * Used by client-side accessor implementations (default, transaction) as their `create()` method.
+ * Checks for document existence first, then calls `set()` if the document is absent.
+ *
+ * @param accessor - the accessor to perform the existence check and set operation on
+ * @throws {Error} When the document already exists at the reference path
+ *
+ * @example
+ * ```ts
+ * const create = createWithAccessor(accessor);
+ * await create({ name: 'New Item' }); // throws if document already exists
+ * ```
+ */
 export declare function createWithAccessor<T>(accessor: FirestoreDocumentDataAccessor<T>): (data: WithFieldValue<T>) => Promise<void | WriteResult>;

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

@@ -1,2 +1,17 @@
 import { type FirestoreAccessorDriver } from '../../common/firestore/driver/accessor';
+/**
+ * Creates a client-side {@link FirestoreAccessorDriver} that maps the abstract accessor interface
+ * to the `firebase/firestore` SDK functions (`doc`, `collection`, `collectionGroup`, `runTransaction`, `writeBatch`).
+ *
+ * This driver provides:
+ * - Document, collection, and subcollection reference factories
+ * - Transaction and write batch context factories for atomic operations
+ * - A default (non-transactional) document context
+ *
+ * @example
+ * ```ts
+ * const driver = firestoreClientAccessorDriver();
+ * // Used internally by firebaseFirestoreClientDrivers()
+ * ```
+ */
 export declare function firestoreClientAccessorDriver(): FirestoreAccessorDriver;

package/src/lib/client/firestore/driver.accessor.default.d.ts

@@ -1,6 +1,15 @@
 import { type DocumentReference, type DocumentSnapshot, type UpdateData, type WithFieldValue } from 'firebase/firestore';
 import { type Observable } from 'rxjs';
 import { type DocumentData, type FirestoreAccessorArrayUpdate, type FirestoreAccessorIncrementUpdate, type FirestoreDataConverter, type FirestoreDocumentContext, type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type SetOptions, type WriteResult } from '../../common/firestore';
+/**
+ * Default (non-transactional) client-side implementation of {@link FirestoreDocumentDataAccessor}.
+ *
+ * Wraps a single Firestore `DocumentReference` and provides CRUD operations, streaming,
+ * and field-level updates (increment, array union/remove) using the `firebase/firestore` SDK.
+ *
+ * Used as the base accessor class; {@link WriteBatchFirestoreDocumentDataAccessor} extends this
+ * to add batch write semantics.
+ */
 export declare class DefaultFirestoreDocumentDataAccessor<T> implements FirestoreDocumentDataAccessor<T> {
     private readonly _documentRef;
     constructor(documentRef: DocumentReference<T>);
@@ -16,5 +25,28 @@ export declare class DefaultFirestoreDocumentDataAccessor<T> implements Firestor
     arrayUpdate(data: FirestoreAccessorArrayUpdate<T>): Promise<void | WriteResult>;
     update(data: UpdateData<object>): Promise<void>;
 }
+/**
+ * Creates a {@link FirestoreDocumentDataAccessorFactory} that produces {@link DefaultFirestoreDocumentDataAccessor} instances
+ * for direct (non-batched, non-transactional) Firestore operations.
+ *
+ * @example
+ * ```ts
+ * const factory = defaultFirestoreAccessorFactory<MyModel>();
+ * const accessor = factory.accessorFor(documentRef);
+ * const snapshot = await accessor.get();
+ * ```
+ */
 export declare function defaultFirestoreAccessorFactory<T>(): FirestoreDocumentDataAccessorFactory<T>;
+/**
+ * Creates a default (non-transactional, non-batched) {@link FirestoreDocumentContext} for client-side use.
+ *
+ * The context type is {@link FirestoreDocumentContextType.NONE}, meaning operations execute immediately
+ * against Firestore without transaction or batch grouping.
+ *
+ * @example
+ * ```ts
+ * const context = defaultFirestoreDocumentContext<MyModel>();
+ * const accessor = context.accessorFactory.accessorFor(docRef);
+ * ```
+ */
 export declare function defaultFirestoreDocumentContext<T>(): FirestoreDocumentContext<T>;

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

@@ -2,7 +2,11 @@ import { type DocumentReference, type DocumentSnapshot, type Transaction as Fire
 import { type Observable } from 'rxjs';
 import { type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type FirestoreDocumentContext, FirestoreDocumentContextType, type SetOptions, type DocumentData, type FirestoreDataConverter, type WriteResult, type FirestoreAccessorIncrementUpdate, type FirestoreAccessorArrayUpdate } from '../../common/firestore';
 /**
- * FirestoreDocumentDataAccessor implementation for a transaction.
+ * Client-side {@link FirestoreDocumentDataAccessor} that executes all operations within a Firestore `Transaction`.
+ *
+ * Unlike the default accessor, reads and writes are all routed through the transaction object,
+ * providing atomic read-then-write semantics. The `stream()` method emits a single snapshot
+ * from the transactional read rather than a live stream.
  */
 export declare class TransactionFirestoreDocumentDataAccessor<T> implements FirestoreDocumentDataAccessor<T> {
     private readonly _transaction;
@@ -22,12 +26,28 @@ export declare class TransactionFirestoreDocumentDataAccessor<T> implements Fire
     update(data: UpdateData<object>): Promise<void>;
 }
 /**
- * Creates a new FirestoreDocumentDataAccessorFactory for a Transaction.
+ * Creates a {@link FirestoreDocumentDataAccessorFactory} that produces {@link TransactionFirestoreDocumentDataAccessor}
+ * instances bound to the given transaction. All operations from these accessors participate in the same transaction.
+ *
+ * @param transaction - the Firestore `Transaction` to bind operations to
  *
- * @param transaction
- * @returns
+ * @example
+ * ```ts
+ * await runTransaction(firestore, async (transaction) => {
+ *   const factory = transactionAccessorFactory<MyModel>(transaction);
+ *   const accessor = factory.accessorFor(docRef);
+ *   const snapshot = await accessor.get();
+ *   // ... modify and set
+ * });
+ * ```
  */
 export declare function transactionAccessorFactory<T>(transaction: FirebaseFirestoreTransaction): FirestoreDocumentDataAccessorFactory<T>;
+/**
+ * Client-side {@link FirestoreDocumentContext} that executes all document operations within a Firestore `Transaction`.
+ *
+ * Provides accessors with {@link FirestoreDocumentContextType.TRANSACTION} semantics — all reads are
+ * consistent and all writes are applied atomically when the transaction completes.
+ */
 export declare class TransactionFirestoreDocumentContext<T> implements FirestoreDocumentContext<T> {
     private readonly _transaction;
     readonly contextType = FirestoreDocumentContextType.TRANSACTION;
@@ -35,4 +55,15 @@ export declare class TransactionFirestoreDocumentContext<T> implements Firestore
     constructor(transaction: FirebaseFirestoreTransaction);
     get transaction(): FirebaseFirestoreTransaction;
 }
+/**
+ * Factory function that creates a {@link TransactionFirestoreDocumentContext} for the given transaction.
+ *
+ * @param transaction - the Firestore `Transaction` to use for all document operations
+ *
+ * @example
+ * ```ts
+ * const context = transactionDocumentContext<MyModel>(transaction);
+ * const accessor = context.accessorFactory.accessorFor(docRef);
+ * ```
+ */
 export declare function transactionDocumentContext<T>(transaction: FirebaseFirestoreTransaction): TransactionFirestoreDocumentContext<T>;

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

@@ -1,3 +1,19 @@
 import { type FirestoreDrivers } from '../../common/firestore/driver/driver';
+/**
+ * Client-side {@link FirestoreDrivers} using the `firebase/firestore` SDK.
+ */
 export type FirebaseFirestoreClientDrivers = FirestoreDrivers;
+/**
+ * Creates the client-side {@link FirestoreDrivers} that bind the abstract Firestore driver
+ * interfaces to the `firebase/firestore` SDK (browser/client).
+ *
+ * Provides accessor drivers (default, batch, transaction) and query drivers for use
+ * with {@link clientFirebaseFirestoreContextFactory}.
+ *
+ * @example
+ * ```ts
+ * const drivers = firebaseFirestoreClientDrivers();
+ * const contextFactory = firestoreContextFactory(drivers);
+ * ```
+ */
 export declare function firebaseFirestoreClientDrivers(): FirebaseFirestoreClientDrivers;

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

@@ -3,11 +3,47 @@ import { type QueryConstraint } from 'firebase/firestore';
 import { type FullFirestoreQueryConstraintHandlersMapping } from './../../common/firestore/query/constraint';
 import { type FirestoreQueryConstraintFunctionsDriver, type FirestoreQueryDriver } from '../../common/firestore/driver/query';
 import { type Query } from '../../common/firestore/types';
+/**
+ * Accumulates Firestore query constraints alongside the base query reference.
+ *
+ * Used internally by the client query driver to build up constraints before
+ * combining them into a final query via the `firebase/firestore` `query()` function.
+ */
 export interface FirebaseFirestoreQueryBuilder {
     readonly query: Query;
     readonly constraints: QueryConstraint[];
 }
+/**
+ * Appends one or more `QueryConstraint` values to the builder, returning a new builder instance.
+ *
+ * @param builder - current query builder state
+ * @param constraint - constraint(s) to append
+ */
 export declare function addConstraintToBuilder(builder: FirebaseFirestoreQueryBuilder, constraint: ArrayOrValue<QueryConstraint>): FirebaseFirestoreQueryBuilder;
+/**
+ * Maps each abstract {@link FirestoreQueryConstraintType} to its client-side `firebase/firestore`
+ * implementation. The `FIRESTORE_OFFSET_QUERY_CONSTRAINT_TYPE` is `undefined` because Firestore
+ * client SDK does not support offset-based pagination (server-only feature).
+ */
 export declare const FIRESTORE_CLIENT_QUERY_CONSTRAINT_HANDLER_MAPPING: FullFirestoreQueryConstraintHandlersMapping<FirebaseFirestoreQueryBuilder>;
+/**
+ * Creates a {@link FirestoreQueryConstraintFunctionsDriver} for the client `firebase/firestore` SDK.
+ *
+ * Converts abstract query constraints into `firebase/firestore` `QueryConstraint` objects
+ * and composes them into an executable `Query`.
+ */
 export declare function firebaseFirestoreQueryConstraintFunctionsDriver(): FirestoreQueryConstraintFunctionsDriver;
+/**
+ * Creates the client-side {@link FirestoreQueryDriver} that executes queries, counts, and streams
+ * using the `firebase/firestore` SDK.
+ *
+ * Note: Transactions are not supported for queries on the client; passing a `transaction` to `getDocs`
+ * will throw an error.
+ *
+ * @example
+ * ```ts
+ * const queryDriver = firebaseFirestoreQueryDriver();
+ * // Used internally by firebaseFirestoreClientDrivers()
+ * ```
+ */
 export declare function firebaseFirestoreQueryDriver(): FirestoreQueryDriver;

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

@@ -1,5 +1,15 @@
 import { type FirestoreContextFactory } from '../../common/firestore/context';
 /**
- * Creates a FirestoreContextFactory that uses the @firebase/firebase package.
+ * Pre-configured {@link FirestoreContextFactory} for client-side (browser) Firebase usage.
+ *
+ * Wires the client Firestore drivers (from the `firebase/firestore` SDK) into the abstract
+ * {@link FirestoreContextFactory} so that collections, documents, queries, and transactions
+ * all use the client-side Firestore implementation.
+ *
+ * @example
+ * ```ts
+ * const context = clientFirebaseFirestoreContextFactory(firestore);
+ * const collection = context.collection(myCollectionConfig);
+ * ```
  */
 export declare const clientFirebaseFirestoreContextFactory: FirestoreContextFactory;

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

@@ -1,9 +1,18 @@
 import { type UpdateData } from 'firebase/firestore';
 import { type FirestoreAccessorIncrementUpdate } from '../../common/firestore/accessor/accessor';
 /**
- * Creates UpdateData corresponding to the input increment update.
+ * Converts a {@link FirestoreAccessorIncrementUpdate} into Firestore `UpdateData` using the
+ * client-side `increment()` FieldValue sentinel.
  *
- * @param input
- * @returns
+ * Maps each field in the input to an `increment()` call, defaulting to 0 for `undefined` values.
+ *
+ * @param input - object mapping field names to their increment amounts
+ * @returns Firestore `UpdateData` with `FieldValue.increment()` sentinels
+ *
+ * @example
+ * ```ts
+ * const updateData = firestoreClientIncrementUpdateToUpdateData<MyModel>({ viewCount: 1, likeCount: -1 });
+ * await updateDoc(docRef, updateData);
+ * ```
  */
 export declare function firestoreClientIncrementUpdateToUpdateData<T extends object>(input: FirestoreAccessorIncrementUpdate<T>): UpdateData<T>;

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

@@ -1,14 +1,39 @@
 import { type Functions } from 'firebase/functions';
 import { type FirebaseFunctionTypeMap, type FirebaseFunctionMap } from './function';
 import { type FirebaseFunctionTypeConfigMap } from './function.factory';
+/**
+ * Type map for development-only Firebase functions.
+ */
 export type DevelopmentFirebaseFunctionTypeMap = FirebaseFunctionTypeMap;
 /**
- * The configuration for a types map.
+ * Configuration map for development functions, mapping each function key to optional config.
  */
 export type DevelopmentFirebaseFunctionConfigMap<M extends DevelopmentFirebaseFunctionTypeMap> = FirebaseFunctionTypeConfigMap<M>;
+/**
+ * Map of instantiated development Firebase callable functions.
+ */
 export type DevelopmentFirebaseFunctionMap<M extends DevelopmentFirebaseFunctionTypeMap> = FirebaseFunctionMap<M>;
 /**
- * Used for building a FirebaseFunctionMap<M> for a specific Functions instance.
+ * Factory that creates a {@link DevelopmentFirebaseFunctionMap} for a given `Functions` instance.
  */
 export type DevelopmentFirebaseFunctionMapFactory<M extends DevelopmentFirebaseFunctionTypeMap> = (functionsInstance: Functions) => DevelopmentFirebaseFunctionMap<M>;
+/**
+ * Creates a {@link DevelopmentFirebaseFunctionMapFactory} that routes all development function calls
+ * through the single `runDevFunction` Cloud Function endpoint (identified by {@link RUN_DEV_FUNCTION_APP_FUNCTION_KEY}).
+ *
+ * Similar to {@link callModelFirebaseFunctionMapFactory}, all development functions are multiplexed
+ * through a single endpoint. The function specifier and data are wrapped via {@link onCallDevelopmentParams}.
+ *
+ * @param configMap - maps each development function key to optional configuration
+ *
+ * @example
+ * ```ts
+ * const factory = developmentFirebaseFunctionMapFactory<DevFnMap>({
+ *   resetData: null,
+ *   seedDatabase: null
+ * });
+ * const devFns = factory(getFunctions());
+ * await devFns.resetData();
+ * ```
+ */
 export declare function developmentFirebaseFunctionMapFactory<M extends DevelopmentFirebaseFunctionTypeMap>(configMap: DevelopmentFirebaseFunctionConfigMap<M>): DevelopmentFirebaseFunctionMapFactory<M>;

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

@@ -1,7 +1,34 @@
 import { type ServerError, ServerErrorResponse, type ServerErrorResponseData } from '@dereekb/util';
 import { type FirebaseError } from 'firebase/app';
+/**
+ * Client-side representation of an error originating from a Firebase Cloud Function.
+ *
+ * Wraps a {@link FirebaseError} with structured server error details (status, message, code)
+ * extracted from the error's `details` property. Extends {@link ServerErrorResponse} for
+ * consistent error handling across the application.
+ *
+ * Typically created via {@link convertHttpsCallableErrorToReadableError} when an `HttpsCallable`
+ * invocation fails with a server-side error that includes structured details.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await callableFunction(data);
+ * } catch (e) {
+ *   if (e instanceof FirebaseServerError) {
+ *     console.log(e.code, e.message, e.firebaseError.code);
+ *   }
+ * }
+ * ```
+ */
 export declare class FirebaseServerError<T extends ServerErrorResponseData = ServerErrorResponseData> extends ServerErrorResponse<T> {
     readonly firebaseError: FirebaseError;
+    /**
+     * Creates a {@link FirebaseServerError} from a raw {@link FirebaseError}, extracting
+     * structured error details from the error's `details` property if available.
+     *
+     * @param error - the Firebase error from an `HttpsCallable` failure
+     */
     static fromFirebaseError(error: FirebaseError): FirebaseServerError;
     constructor(firebaseError: FirebaseError, serverError: ServerError<T>);
     get _error(): FirebaseError;

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

@@ -1,23 +1,68 @@
 import { type FactoryWithInput, type Maybe, type PromiseOrValue } from '@dereekb/util';
 import { type HttpsCallable } from 'firebase/functions';
+/**
+ * Configuration for mapping input/output values when wrapping an `HttpsCallable`.
+ *
+ * @template I - the external input type (what callers provide)
+ * @template O - the external output type (what callers receive)
+ * @template A - the internal input type (what the callable expects)
+ * @template B - the internal output type (what the callable returns)
+ */
 export interface MapHttpsCallable<I, O, A, B> {
+    /** Transforms the caller's input into the format expected by the underlying callable. */
     readonly mapInput?: FactoryWithInput<PromiseOrValue<A>, Maybe<I>>;
+    /** Transforms the callable's raw output into the format returned to callers. */
     readonly mapOutput?: FactoryWithInput<PromiseOrValue<O>, Maybe<B>>;
 }
 /**
- * Maps input and output values when using HttpsCallable.
+ * Wraps an `HttpsCallable` with input/output transformations and error conversion.
+ *
+ * Supports both standard mode (returns `HttpsCallableResult<O>`) and direct-data mode
+ * (returns just `O`) depending on the `directData` parameter. Errors from the callable
+ * are converted to readable errors via {@link convertHttpsCallableErrorToReadableError}.
  *
- * @param callable
- * @param wrap
- * @returns
+ * @param callable - the underlying Firebase `HttpsCallable` to wrap
+ * @param wrap - input/output mapping functions
+ * @param directData - when `true`, returns the unwrapped data instead of `HttpsCallableResult`
+ *
+ * @example
+ * ```ts
+ * const wrapped = mapHttpsCallable(httpsCallable(functions, 'myFn'), {
+ *   mapInput: (params) => ({ ...params, timestamp: Date.now() }),
+ *   mapOutput: (result) => result?.items ?? []
+ * }, true);
+ * const items = await wrapped({ query: 'test' });
+ * ```
  */
 export declare function mapHttpsCallable<I, O, A, B = unknown>(callable: HttpsCallable<A, B>, wrap: MapHttpsCallable<I, O, A, B>): HttpsCallable<I, O>;
 export declare function mapHttpsCallable<I, O, A, B = unknown>(callable: HttpsCallable<A, B>, wrap: MapHttpsCallable<I, O, A, B>, directData: false): HttpsCallable<I, O>;
 export declare function mapHttpsCallable<I, O, A, B = unknown>(callable: HttpsCallable<A, B>, wrap: MapHttpsCallable<I, O, A, B>, directData: true): DirectDataHttpsCallable<HttpsCallable<I, O>>;
 export declare function mapHttpsCallable<I, O, A, B = unknown>(callable: HttpsCallable<A, B>, wrap: MapHttpsCallable<I, O, A, B>, directData?: boolean): HttpsCallable<I, O> | DirectDataHttpsCallable<HttpsCallable<I, O>>;
 /**
- * Wraps an HttpsCallable value so it returns only the data from the result, rather than an object with data attached.
+ * Unwraps an `HttpsCallable` so it returns the response data directly (`O`) instead of
+ * `HttpsCallableResult<O>`. Simplifies consumption when only the data payload is needed.
  */
 export type DirectDataHttpsCallable<C extends HttpsCallable<any, any>> = C extends HttpsCallable<infer I, infer O> ? (data?: I | null) => Promise<O> : never;
+/**
+ * Wraps an `HttpsCallable` to return the data payload directly, stripping the `HttpsCallableResult` wrapper.
+ *
+ * Errors are converted to readable errors via {@link convertHttpsCallableErrorToReadableError}.
+ *
+ * @param callable - the `HttpsCallable` to wrap
+ *
+ * @example
+ * ```ts
+ * const fn = directDataHttpsCallable(httpsCallable<Input, Output>(functions, 'myFn'));
+ * const output: Output = await fn(input);
+ * ```
+ */
 export declare function directDataHttpsCallable<I, O, C extends HttpsCallable<I, O> = HttpsCallable<I, O>>(callable: C): DirectDataHttpsCallable<C>;
+/**
+ * Converts errors from `HttpsCallable` calls into more readable error types.
+ *
+ * If the error is a client-side {@link FirebaseError} with `details`, wraps it as a {@link FirebaseServerError}
+ * to preserve server-side error context. Otherwise, converts it to a generic readable error via `toReadableError`.
+ *
+ * @param error - the caught error from an `HttpsCallable` invocation
+ */
 export declare function convertHttpsCallableErrorToReadableError(error: unknown): unknown;