@dereekb/firebase-server 13.2.1 → 13.3.0

package/oidc/src/lib/service/oidc.encryption.service.d.ts

@@ -0,0 +1,53 @@
+import { type OidcEntryClientId } from '@dereekb/firebase';
+import { OidcModuleConfig } from '../oidc.config';
+import { type SelectiveFieldEncryptor, type StringEncryptionProvider, type JsonSerializableObject } from '@dereekb/util';
+import type { AdapterPayload } from 'oidc-provider';
+/**
+ * Adapter payload fields that contain sensitive values and are selectively encrypted at rest.
+ *
+ * - `client_secret`: OAuth client secret (present on Client entries)
+ * - `registration_access_token`: DCR access token (present on Client entries)
+ */
+export declare const OIDC_ENCRYPTED_PAYLOAD_FIELDS: readonly ["client_secret", "registration_access_token"];
+/**
+ * Union of adapter payload field names that are selectively encrypted.
+ */
+export type OidcEncryptedPayloadField = (typeof OIDC_ENCRYPTED_PAYLOAD_FIELDS)[number];
+/**
+ * Loosely-typed adapter payload with known sensitive fields.
+ */
+export interface OidcClientPayload {
+    client_id: OidcEntryClientId;
+    client_secret?: string;
+    registration_access_token?: string;
+    [key: string]: unknown;
+}
+/**
+ * Selective field encryptor for oidc-provider adapter and client payloads.
+ *
+ * Both adapter payloads and client payloads share the same encrypted fields,
+ * so a single encryptor type is used for both.
+ */
+export type OidcAdapterPayloadEncryptor = SelectiveFieldEncryptor<AdapterPayload, OidcEncryptedPayloadField>;
+/**
+ * Centralized encryption service for OIDC payload fields.
+ *
+ * Provides a single {@link StringEncryptionProvider} and pre-built selective field encryptors
+ * for both the oidc-provider adapter payloads and client CRUD payloads. This avoids
+ * duplicating encryption setup across {@link OidcService}, the adapter factory, and
+ * the OIDC model server actions.
+ */
+export declare class OidcEncryptionService {
+    readonly provider: StringEncryptionProvider;
+    readonly adapterPayloadEncryptor: OidcAdapterPayloadEncryptor;
+    constructor(config: OidcModuleConfig);
+    /**
+     * Encrypts sensitive fields in an adapter payload and returns it as a {@link JsonSerializableObject}
+     * suitable for storing directly in Firestore.
+     */
+    encryptAdapterPayload(payload: AdapterPayload): JsonSerializableObject;
+    /**
+     * Decrypts sensitive fields in a Firestore-stored payload object back to an {@link AdapterPayload}.
+     */
+    decryptAdapterPayload(payload: JsonSerializableObject): AdapterPayload;
+}

package/oidc/src/lib/service/oidc.interaction.service.d.ts

@@ -0,0 +1,44 @@
+import type { Request, Response } from 'express';
+import type { Interaction, InteractionResults, Grant } from 'oidc-provider';
+import { type OidcInteractionUid } from '@dereekb/firebase';
+import { OidcClientService } from './oidc.client.service';
+import { OidcService } from './oidc.service';
+/**
+ * Service for handling OIDC interactions.
+ */
+export declare class OidcInteractionService {
+    private readonly oidcService;
+    private readonly clientService;
+    constructor(oidcService: OidcService, clientService: OidcClientService);
+    /**
+     * Loads the interaction details for a given request/response pair.
+     *
+     * Requires the oidc-provider interaction cookie to be present on the request.
+     */
+    getInteractionDetails(req: Request, res: Response): Promise<Interaction>;
+    /**
+     * Finds an interaction by its UID directly from the adapter store.
+     *
+     * Bypasses the cookie-based lookup used by `provider.interactionDetails()`.
+     * This is necessary when the interaction cookie is scoped to a different path
+     * (e.g., the frontend) and is not sent with backend API requests.
+     *
+     * @throws {Error} When the interaction is not found or has expired.
+     */
+    findInteractionByUid(uid: OidcInteractionUid): Promise<Interaction>;
+    /**
+     * Completes an interaction by UID without requiring the interaction cookie.
+     *
+     * Looks up the interaction directly by UID, applies the result, saves it,
+     * and returns the `returnTo` URL for the client to redirect to.
+     *
+     * @returns The `returnTo` URL that the client should redirect to.
+     */
+    finishInteractionByUid(uid: OidcInteractionUid, result: InteractionResults, options?: {
+        mergeWithLastSubmission?: boolean;
+    }): Promise<string>;
+    /**
+     * Finds an existing grant by ID, or creates a new one.
+     */
+    findOrCreateGrant(grantId: string | undefined, accountId: string, clientId: string): Promise<Grant>;
+}

package/oidc/src/lib/service/oidc.jwks.service.d.ts

@@ -0,0 +1,105 @@
+import { type AES256GCMEncryptionSecretSource } from '@dereekb/nestjs';
+import { type FirebaseStorageAccessorFile } from '@dereekb/firebase';
+import { type JwksKey, type JsonWebKeyWithKid } from '../model/jwks/jwks';
+import { type WebsiteUrlWithPrefix, type Maybe } from '@dereekb/util';
+import { OidcServerFirestoreCollections } from '../model/model';
+/**
+ * Result of {@link JwksService.generateKeyPair}.
+ */
+export interface GenerateKeyPairResult {
+    /** The stored Firestore document data (private key is encrypted). */
+    readonly jwksKey: JwksKey;
+    /** The unencrypted private JWK, ready for use as a signing key. */
+    readonly signingKey: JsonWebKeyWithKid;
+}
+export declare abstract class JwksServiceConfig {
+    /**
+     * Encryption secret for private key storage.
+     *
+     * Supports all `AES256GCMEncryptionSecretSource` formats:
+     * direct hex string, getter function, or environment variable reference.
+     */
+    abstract readonly encryptionSecret: AES256GCMEncryptionSecretSource;
+    /**
+     * Maximum age of a rotated key (in seconds) before it is retired.
+     * Defaults to 30 days (2592000).
+     */
+    abstract readonly rotatedKeyMaxAge?: number;
+    /**
+     * If true, the JWKS will be written to storage when keys are rotated, if enabled.
+     *
+     * Defaults to true if `serveJwksFromStorage` is defined.
+     */
+    abstract readonly enableSaveJwksToStorage?: boolean;
+    /**
+     * If true, this flag signals to the rest of the system that the JWKS will be served from storage.
+     *
+     * Defaults to true if `enableSaveJwksToStorage` is true.
+     */
+    abstract readonly serveJwksFromStorage?: boolean;
+}
+/**
+ * If provided, the JwksService will write the JWKS to this file when keys are rotated.
+ */
+export declare abstract class JwksServiceStorageConfig {
+    /**
+     * If provided, the JWKS will be written to this file when keys are rotated.
+     */
+    abstract readonly jwksStorageAccessorFile?: Maybe<FirebaseStorageAccessorFile>;
+}
+export declare const DEFAULT_ROTATED_KEY_MAX_AGE: number;
+export declare class JwksService {
+    private readonly config;
+    private readonly collections;
+    private readonly storageConfig?;
+    private readonly _jwksStoragePublicUrl;
+    private readonly rotatedKeyMaxAge;
+    /**
+     * Whether the JWKS is served from a public storage URL rather than the built-in endpoint.
+     */
+    readonly serveJwksFromStorage: boolean;
+    /**
+     * Whether the JWKS should be saved to storage when keys are rotated.
+     */
+    readonly saveJwksToStorage: boolean;
+    constructor(config: JwksServiceConfig, collections: OidcServerFirestoreCollections, storageConfig?: Maybe<JwksServiceStorageConfig>);
+    private get jwksKeyCollection();
+    /**
+     * Generates a new RS256 key pair and stores it in Firestore.
+     * The private key is encrypted at rest using AES-256-GCM.
+     *
+     * Returns both the stored {@link JwksKey} and the unencrypted private JWK
+     * so callers can use the signing key immediately without a decryption round-trip.
+     */
+    generateKeyPair(): Promise<GenerateKeyPairResult>;
+    /**
+     * Returns the currently active signing key's private JWK.
+     */
+    getActiveSigningKey(): Promise<JsonWebKeyWithKid | undefined>;
+    /**
+     * Returns the public URL for the JWKS stored in Cloud Storage, if configured.
+     *
+     * This call will also initialize/rotate the keys in the datastore and sync them
+     * to the cloud if they are currently not available.
+     *
+     * Returns undefined if storage is not configured or `serveJwksFromStorage` is false.
+     * Returns null if an error occured while trying to setup.
+     */
+    getJwksStoragePublicUrl(): Promise<Maybe<WebsiteUrlWithPrefix>>;
+    /**
+     * Returns the public JWKS (all non-retired keys) by querying Firestore.
+     */
+    getLatestPublicJwks(): Promise<{
+        keys: JsonWebKeyWithKid[];
+    }>;
+    /**
+     * Rotates keys: marks the current active key as rotated and generates a new active key.
+     */
+    rotateKeys(): Promise<JwksKey>;
+    private _initializeKeysAndCloud;
+    private _syncKeysToCloud;
+    /**
+     * Retires rotated keys whose expiresAt has passed.
+     */
+    retireExpiredKeys(): Promise<number>;
+}

package/oidc/src/lib/service/oidc.service.d.ts

@@ -0,0 +1,55 @@
+import type Provider from 'oidc-provider';
+import { type Configuration } from 'oidc-provider';
+import { OidcModuleConfig } from '../oidc.config';
+import { JwksService } from './oidc.jwks.service';
+import { OidcAccountService } from './oidc.account.service';
+import { OidcServerFirestoreCollections } from '../model';
+import { OidcEncryptionService } from './oidc.encryption.service';
+import { OidcProviderConfigService } from './oidc.config.service';
+import { type OidcEntryClientId, type OidcEntryOAuthClientPayloadData } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+import { type OidcAuthData } from './oidc.auth';
+/**
+ * Core OIDC service that wraps the oidc-provider instance and exposes
+ * typed methods for interaction handling, provider initialization, and JWKS management.
+ */
+export declare class OidcService {
+    private readonly config;
+    private readonly providerConfigService;
+    private readonly jwksService;
+    private readonly accountService;
+    private readonly collections;
+    private readonly encryptionService;
+    private readonly _getProvider;
+    constructor(config: OidcModuleConfig, providerConfigService: OidcProviderConfigService, jwksService: JwksService, accountService: OidcAccountService, collections: OidcServerFirestoreCollections, encryptionService: OidcEncryptionService);
+    /**
+     * Returns the oidc-provider instance, initializing it on first access.
+     */
+    getProvider(): Promise<Provider>;
+    /**
+     * Verifies an opaque access token and returns the {@link OidcAuthData}.
+     *
+     * Uses the provider's `AccessToken` model to look up the token and extract
+     * the account ID, scope, and client ID.
+     *
+     * @param token - The opaque access token string.
+     * @returns The auth context, or `undefined` if the token is invalid or expired.
+     */
+    verifyAccessToken(rawToken: string): Promise<OidcAuthData | undefined>;
+    /**
+     * Finds a client payload by ID directly from the adapter store.
+     *
+     * @param clientId - The client's document/adapter entry ID.
+     * @returns The client payload data, or `undefined` if not found.
+     */
+    findClientPayload(clientId: OidcEntryClientId): Promise<Maybe<OidcEntryOAuthClientPayloadData>>;
+    /**
+     * Builds the oidc-provider {@link Configuration} options that are spread into
+     * `new Provider(issuer, { ...options })`.
+     *
+     * Does NOT include `adapter`, `findAccount`, or `jwks` — those require async
+     * setup and are handled by {@link OidcService}.
+     */
+    buildProviderConfiguration(cookieKeys: string[]): Configuration;
+    private _buildProvider;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.2.1",
+  "version": "13.3.0",
   "exports": {
     "./test": {
       "module": "./test/index.esm.js",
@@ -26,6 +26,12 @@
       "import": "./model/index.cjs.mjs",
       "default": "./model/index.cjs.js"
     },
+    "./oidc": {
+      "module": "./oidc/index.esm.js",
+      "types": "./oidc/index.d.ts",
+      "import": "./oidc/index.cjs.mjs",
+      "default": "./oidc/index.cjs.js"
+    },
     "./package.json": "./package.json",
     ".": {
       "module": "./index.esm.js",
@@ -37,14 +43,14 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/date": "13.2.1",
-    "@dereekb/dbx-core": "13.2.1",
-    "@dereekb/firebase": "13.2.1",
-    "@dereekb/model": "13.2.1",
-    "@dereekb/nestjs": "13.2.1",
-    "@dereekb/rxjs": "13.2.1",
-    "@dereekb/util": "13.2.1",
-    "@dereekb/zoho": "13.2.1",
+    "@dereekb/date": "13.3.0",
+    "@dereekb/dbx-core": "13.3.0",
+    "@dereekb/firebase": "13.3.0",
+    "@dereekb/model": "13.3.0",
+    "@dereekb/nestjs": "13.3.0",
+    "@dereekb/rxjs": "13.3.0",
+    "@dereekb/util": "13.3.0",
+    "@dereekb/zoho": "13.3.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.0.0",

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

@@ -1,7 +1,27 @@
 import { type FirebaseAuthToken } from '@dereekb/firebase';
 import type * as admin from 'firebase-admin';
 import { type AuthData } from '../type';
-export interface AuthDataRef {
-    readonly auth?: AuthData;
+/**
+ * Reference to optional {@link AuthData} from a Firebase callable function request.
+ *
+ * Used by {@link FirebaseServerAuthService.authContextInfo} to build auth context
+ * from callable function requests where the caller may or may not be authenticated.
+ */
+export interface AuthDataRef<T extends AuthData = AuthData> {
+    readonly auth?: T;
 }
+/**
+ * Converts a Firebase Admin {@link admin.auth.DecodedIdToken} into a normalized {@link FirebaseAuthToken}.
+ *
+ * Maps Firebase Admin token fields (snake_case) to the application's token interface (camelCase),
+ * including email, phone, and sign-in timestamps.
+ *
+ * @param token - The decoded ID token from Firebase Admin Auth.
+ *
+ * @example
+ * ```typescript
+ * const decodedToken = await admin.auth().verifyIdToken(idToken);
+ * const authToken = firebaseAuthTokenFromDecodedIdToken(decodedToken);
+ * ```
+ */
 export declare function firebaseAuthTokenFromDecodedIdToken(token: admin.auth.DecodedIdToken): FirebaseAuthToken;

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

@@ -16,6 +16,11 @@ import { type CallableContext } from '../type';
  * ```
  */
 export declare const DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR: import("@dereekb/util").NumberFactory;
+/**
+ * Identifies a Firebase Auth user by UID within a server-side auth context.
+ *
+ * Base interface for {@link FirebaseServerAuthUserContext} and {@link FirebaseServerAuthContext}.
+ */
 export interface FirebaseServerAuthUserIdentifierContext {
     /**
      * UID of the user for this context.

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

@@ -13,7 +13,8 @@ export declare class FirebaseServerAuthNewUserSendSetupDetailsThrottleError exte
     constructor(lastSentAt: Date);
 }
 /**
- * Thrown by sendSetupDetails() if the user was recently sent details.
+ * Thrown by sendSetupDetails() if the user has already been sent setup details
+ * and the `sendSetupDetailsOnce` option was enabled.
  */
 export declare class FirebaseServerAuthNewUserSendSetupDetailsSendOnceError extends BaseError {
     constructor();

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

@@ -1,8 +1,20 @@
 import { type Maybe } from '@dereekb/util';
 import type * as admin from 'firebase-admin';
 /**
- * Awaits the load result from the input promise. If it encounters a FIREBASE_AUTH_USER_NOT_FOUND_ERROR, then returns undefined. Throws the error otherwise.
- * @param promise
- * @returns
+ * Safely awaits a Firebase Admin Auth user lookup, returning `undefined` instead of throwing
+ * when the user is not found.
+ *
+ * Any error other than {@link FIREBASE_AUTH_USER_NOT_FOUND_ERROR} is re-thrown.
+ *
+ * @param promise - A promise resolving to a UserRecord (e.g., from `auth.getUser(uid)`).
+ * @returns The user record, or `undefined` if the user does not exist.
+ *
+ * @example
+ * ```typescript
+ * const user = await getAuthUserOrUndefined(admin.auth().getUser(uid));
+ * if (user) {
+ *   console.log(user.email);
+ * }
+ * ```
  */
 export declare function getAuthUserOrUndefined(promise: Promise<admin.auth.UserRecord>): Promise<Maybe<admin.auth.UserRecord>>;

package/src/lib/env/env.config.d.ts

@@ -0,0 +1,42 @@
+import { type InjectionToken, type Provider } from '@nestjs/common';
+import { type ServerEnvironmentConfig } from '@dereekb/nestjs';
+/**
+ * Extension of ServerEnvironmentConfig for Firebase server applications.
+ *
+ * Requires appUrl to be provided.
+ */
+export interface FirebaseServerEnvironmentConfig extends ServerEnvironmentConfig {
+    readonly appUrl: string;
+}
+/**
+ * Token to access a configured FirebaseServerEnvironmentServiceConfig for the app.
+ */
+export declare const FIREBASE_SERVER_ENV_TOKEN: InjectionToken;
+/**
+ * Creates a NestJS provider that binds the given config to the {@link FIREBASE_SERVER_ENV_TOKEN} injection token.
+ *
+ * @param env - The Firebase server environment configuration.
+ *
+ * @example
+ * ```typescript
+ * const provider = firebaseServerEnvTokenProvider({ appUrl: 'https://myapp.com', ... });
+ * ```
+ */
+export declare function firebaseServerEnvTokenProvider<T extends FirebaseServerEnvironmentConfig = FirebaseServerEnvironmentConfig>(env: T): Provider;
+/**
+ * Creates NestJS providers that bind the given config to both {@link FIREBASE_SERVER_ENV_TOKEN}
+ * and the base {@link SERVER_ENV_TOKEN} from `@dereekb/nestjs`.
+ *
+ * Use this when the NestJS app needs the config accessible via either token.
+ *
+ * @param env - The Firebase server environment configuration.
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   providers: [...firebaseServerEnvTokenProviders(myEnvConfig)]
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare function firebaseServerEnvTokenProviders<T extends FirebaseServerEnvironmentConfig = FirebaseServerEnvironmentConfig>(env: T): Provider[];

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

@@ -1,13 +1,30 @@
+import { type Maybe, type WebsiteUrlDetails } from '@dereekb/util';
 /**
  * Reference to a FirebaseServerEnvService
  */
 export interface FirebaseServerEnvServiceRef<S extends FirebaseServerEnvService = FirebaseServerEnvService> {
     readonly envService: S;
 }
+/**
+ * Abstract service providing Firebase server environment information such as deployment stage,
+ * feature flags, and app URL.
+ *
+ * Implementations are typically injected via {@link FIREBASE_SERVER_ENV_TOKEN} and
+ * backed by a {@link FirebaseServerEnvironmentConfig}.
+ */
 export declare abstract class FirebaseServerEnvService {
+    /** Whether the server is running in a test/CI environment. */
     abstract readonly isTestingEnv: boolean;
+    /** Whether the server is running in production. */
     abstract readonly isProduction: boolean;
+    /** Whether the server is running in a staging environment. */
     abstract readonly isStaging: boolean;
+    /** Whether developer/debug tools are enabled for this environment. */
     abstract readonly developerToolsEnabled: boolean;
+    /** Whether the development scheduler (for cron-like tasks) is enabled. */
     abstract readonly developmentSchedulerEnabled: boolean;
+    /** The application's public URL, if configured. */
+    abstract readonly appUrl: Maybe<string>;
+    /** Parsed URL details for the application URL. */
+    abstract readonly appUrlDetails: Maybe<WebsiteUrlDetails>;
 }

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

@@ -1 +1,2 @@
+export * from './env.config';
 export * from './env.service';

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

@@ -1,8 +1,16 @@
 import { type UpdateData, type FirestoreAccessorArrayUpdate } from '@dereekb/firebase';
 /**
- * Creates UpdateData corresponding to the input array update.
+ * Converts a {@link FirestoreAccessorArrayUpdate} into Firestore {@link UpdateData} using
+ * Google Cloud Firestore's {@link FieldValue.arrayUnion} and {@link FieldValue.arrayRemove}.
  *
- * @param input
- * @returns
+ * @param input - The array update specification with `union` and/or `remove` field maps.
+ *
+ * @example
+ * ```typescript
+ * const updateData = firestoreServerArrayUpdateToUpdateData<User>({
+ *   union: { tags: ['new-tag'] },
+ *   remove: { tags: ['old-tag'] }
+ * });
+ * ```
  */
 export declare function firestoreServerArrayUpdateToUpdateData<T extends object>(input: FirestoreAccessorArrayUpdate<T>): UpdateData<T>;

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

@@ -2,7 +2,11 @@ import { type DocumentReference, type WriteBatch as GoogleCloudWriteBatch, type
 import { type Observable } from 'rxjs';
 import { type WithFieldValue, type FirestoreDocumentContext, FirestoreDocumentContextType, type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type FirestoreDocumentDeleteParams, type FirestoreDocumentUpdateParams, type UpdateData, type DocumentData, type FirestoreDataConverter, type FirestoreAccessorIncrementUpdate, type FirestoreAccessorArrayUpdate } from '@dereekb/firebase';
 /**
- * FirestoreDocumentDataAccessor implementation for a batch.
+ * Google Cloud Firestore implementation of {@link FirestoreDocumentDataAccessor} that queues
+ * all write operations (create, set, update, delete) into a {@link WriteBatch}.
+ *
+ * Writes are not committed until the batch is explicitly committed. Read operations
+ * (get, exists) bypass the batch and read directly from Firestore.
  */
 export declare class WriteBatchFirestoreDocumentDataAccessor<T> implements FirestoreDocumentDataAccessor<T> {
     readonly documentRef: DocumentReference<T>;
@@ -21,12 +25,28 @@ export declare class WriteBatchFirestoreDocumentDataAccessor<T> implements Fires
     update(data: UpdateData<object>, params?: FirestoreDocumentUpdateParams): Promise<void>;
 }
 /**
- * Creates a new FirestoreDocumentDataAccessorFactory for a Batch.
+ * Creates a {@link FirestoreDocumentDataAccessorFactory} that produces batch-backed accessors.
+ *
+ * All accessors created from this factory share the same {@link WriteBatch}, so committing
+ * the batch applies all queued writes atomically.
  *
- * @param batch
- * @returns
+ * @param writeBatch - The Google Cloud WriteBatch to queue operations into.
+ *
+ * @example
+ * ```typescript
+ * const batch = firestore.batch();
+ * const factory = writeBatchAccessorFactory<User>(batch);
+ * const accessor = factory.accessorFor(userDocRef);
+ * await accessor.set({ name: 'Alice' });
+ * await batch.commit();
+ * ```
  */
 export declare function writeBatchAccessorFactory<T>(writeBatch: GoogleCloudWriteBatch): FirestoreDocumentDataAccessorFactory<T>;
+/**
+ * A {@link FirestoreDocumentContext} backed by a Google Cloud {@link WriteBatch}.
+ *
+ * All document accessors created from this context queue writes into the same batch.
+ */
 export declare class WriteBatchFirestoreDocumentContext<T> implements FirestoreDocumentContext<T> {
     private readonly _batch;
     readonly contextType = FirestoreDocumentContextType.BATCH;
@@ -34,4 +54,7 @@ export declare class WriteBatchFirestoreDocumentContext<T> implements FirestoreD
     constructor(batch: GoogleCloudWriteBatch);
     get batch(): GoogleCloudWriteBatch;
 }
+/**
+ * Creates a {@link WriteBatchFirestoreDocumentContext} wrapping the given batch.
+ */
 export declare function writeBatchDocumentContext<T>(batch: GoogleCloudWriteBatch): WriteBatchFirestoreDocumentContext<T>;

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

@@ -5,7 +5,50 @@ interface DocRefForPathInput {
 interface CollectionRefForPathInput {
     readonly collection: (path: string) => CollectionReference;
 }
+/**
+ * Resolves a Firestore {@link CollectionReference} from a starting point and optional additional path segments.
+ *
+ * Supports nested subcollection paths by processing segments in pairs (doc ID, collection name).
+ *
+ * @param start - A Firestore object that can resolve collection paths (e.g., Firestore instance, DocumentReference).
+ * @param path - The initial collection path.
+ * @param pathSegments - Optional pairs of [docId, collectionName] for subcollection traversal.
+ * @throws Error if pathSegments length is odd (segments must come in pairs).
+ *
+ * @example
+ * ```typescript
+ * const ref = collectionRefForPath<User>(firestore, 'users');
+ * const subRef = collectionRefForPath<Comment>(firestore, 'users', ['user123', 'comments']);
+ * ```
+ */
 export declare function collectionRefForPath<T>(start: CollectionRefForPathInput, path: string, pathSegments?: string[]): CollectionReference<T>;
+/**
+ * Resolves a Firestore {@link DocumentReference} from a starting point, optional document path, and additional path segments.
+ *
+ * If no path is provided, auto-generates a document ID. Supports nested subcollection
+ * traversal via path segment pairs.
+ *
+ * @param start - A Firestore object that can resolve document paths (e.g., CollectionReference).
+ * @param path - Optional document ID or path within the collection.
+ * @param pathSegments - Optional pairs of [collectionName, docId] for subcollection traversal.
+ *
+ * @example
+ * ```typescript
+ * const ref = docRefForPath<User>(usersCollection, 'user123');
+ * const autoRef = docRefForPath<User>(usersCollection); // auto-generated ID
+ * ```
+ */
 export declare function docRefForPath<T>(start: DocRefForPathInput, path?: string, pathSegments?: string[]): DocumentReference<T>;
+/**
+ * Creates a {@link FirestoreAccessorDriver} for Google Cloud Firestore (Admin SDK).
+ *
+ * Implements document/collection resolution, transaction/batch factories, and context factories
+ * using the `@google-cloud/firestore` library.
+ *
+ * @example
+ * ```typescript
+ * const accessorDriver = googleCloudFirestoreAccessorDriver();
+ * ```
+ */
 export declare function googleCloudFirestoreAccessorDriver(): FirestoreAccessorDriver;
 export {};

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

@@ -1,6 +1,12 @@
 import { type DocumentReference, type WriteResult as GoogleCloudWriteResult, type DocumentSnapshot } from '@google-cloud/firestore';
 import { type Observable } from 'rxjs';
 import { type WithFieldValue, type UpdateData, type FirestoreDocumentContext, type FirestoreDocumentDataAccessor, type FirestoreDocumentDataAccessorFactory, type FirestoreDocumentDeleteParams, type FirestoreDocumentUpdateParams, type SetOptions, type FirestoreDataConverter, type DocumentData, type FirestoreAccessorIncrementUpdate, type FirestoreAccessorArrayUpdate } from '@dereekb/firebase';
+/**
+ * Default Google Cloud Firestore implementation of {@link FirestoreDocumentDataAccessor}.
+ *
+ * Performs all operations directly against the Firestore document reference without
+ * batching or transactional context. Supports real-time streaming via `onSnapshot`.
+ */
 export declare class DefaultFirestoreDocumentDataAccessor<T> implements FirestoreDocumentDataAccessor<T> {
     private readonly _documentRef;
     constructor(documentRef: DocumentReference<T>);
@@ -16,5 +22,19 @@ export declare class DefaultFirestoreDocumentDataAccessor<T> implements Firestor
     arrayUpdate(data: FirestoreAccessorArrayUpdate<T>, params?: FirestoreDocumentUpdateParams): Promise<GoogleCloudWriteResult>;
     update(data: UpdateData<object>, params?: FirestoreDocumentUpdateParams): Promise<GoogleCloudWriteResult>;
 }
+/**
+ * Creates a {@link FirestoreDocumentDataAccessorFactory} that produces default (non-batched, non-transactional) accessors.
+ *
+ * @example
+ * ```typescript
+ * const factory = defaultFirestoreAccessorFactory<User>();
+ * const accessor = factory.accessorFor(userDocRef);
+ * ```
+ */
 export declare function defaultFirestoreAccessorFactory<T>(): FirestoreDocumentDataAccessorFactory<T>;
+/**
+ * Creates a {@link FirestoreDocumentContext} with no special execution context (no batch, no transaction).
+ *
+ * Operations performed through this context execute immediately against Firestore.
+ */
 export declare function defaultFirestoreDocumentContext<T>(): FirestoreDocumentContext<T>;