@dereekb/firebase-server 13.2.2 → 13.3.0

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

@@ -3,21 +3,79 @@ import { type FirestoreModelType, type FirestoreModelIdentity, type FirestoreMod
 import { type OnCallWithAuthAwareNestRequireAuthRef, type OnCallWithNestContext } from '../function/call';
 import { type NestContextCallableRequestWithAuth, type NestContextCallableRequestWithOptionalAuth } from '../function/nest';
 import { type AssertModelCrudRequestFunction } from './crud.assert.function';
+/**
+ * Request type for model update handlers that require authentication.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam I - The input data type for the update operation.
+ */
 export type OnCallUpdateModelRequest<N, I = unknown> = NestContextCallableRequestWithAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model update handler function that requires an authenticated caller.
+ */
 export type OnCallUpdateModelFunctionWithAuth<N, I = unknown, O = void> = ((request: OnCallUpdateModelRequest<N, I>) => PromiseOrValue<O>) & {
     readonly _requiresAuth?: true;
 };
+/**
+ * Request type for model update handlers that allow unauthenticated callers.
+ */
 export type OnCallUpdateModelRequestWithOptionalAuth<N, I = unknown> = NestContextCallableRequestWithOptionalAuth<N, I> & ModelFirebaseCrudFunctionSpecifierRef;
+/**
+ * A model update handler function that does not require authentication.
+ */
 export type OnCallUpdateModelFunctionWithOptionalAuth<N, I = unknown, O = void> = ((request: OnCallUpdateModelRequestWithOptionalAuth<N, I>) => PromiseOrValue<O>) & {
     readonly _requireAuth: false;
 };
+/**
+ * Standard model update handler requiring auth (the common case).
+ */
 export type OnCallUpdateModelFunction<N, I = unknown, O = void> = OnCallUpdateModelFunctionWithAuth<N, I, O> & OnCallWithAuthAwareNestRequireAuthRef;
+/**
+ * Union of auth-required and optional-auth update handlers.
+ */
 export type OnCallUpdateModelFunctionAuthAware<N, I = unknown, O = void> = OnCallUpdateModelFunction<N, I, O> | OnCallUpdateModelFunctionWithOptionalAuth<N, I, O>;
+/**
+ * Maps Firestore model type strings to their update handler functions.
+ *
+ * Pass this map to {@link onCallUpdateModel} to register all model types
+ * that support updates through the call model system.
+ *
+ * @typeParam N - The NestJS context type.
+ * @typeParam T - The Firestore model identity constraining valid model type keys.
+ */
 export type OnCallUpdateModelMap<N, T extends FirestoreModelIdentity = FirestoreModelIdentity> = {
     readonly [K in FirestoreModelTypes<T>]?: OnCallUpdateModelFunctionAuthAware<N, any, any>;
 };
+/**
+ * Configuration for {@link onCallUpdateModel}.
+ */
 export interface OnCallUpdateModelConfig<N> {
+    /** Optional assertion run before the update handler; throw to reject. */
     readonly preAssert?: AssertModelCrudRequestFunction<N, OnCallUpdateModelParams>;
 }
+/**
+ * Factory that creates a callable function handling model updates for multiple model types.
+ *
+ * Dispatches to the correct handler based on the `modelType` field in the request,
+ * enforces auth requirements per handler, and aggregates API details for MCP introspection.
+ *
+ * @param map - Maps model type strings to their update handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'update' CRUD operation.
+ *
+ * @example
+ * ```typescript
+ * const updateHandler = onCallUpdateModel<DemoNestContext>({
+ *   profile: onCallSpecifierHandler({
+ *     _: updateProfileDefault,
+ *     username: updateProfileUsername
+ *   }),
+ *   guestbook: updateGuestbook
+ * });
+ * ```
+ */
 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.
+ */
 export declare function updateModelUnknownModelTypeError(modelType: FirestoreModelType): import("firebase-functions/https").HttpsError;

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

@@ -11,13 +11,14 @@ import { type FirebaseServerActionsContext } from './function/context';
  */
 export type NestApplicationPromiseGetter = Getter<Promise<INestApplicationContext>>;
 /**
- * Generates a function from the passed NestApplicationPromiseGetter/context.
+ * Factory type that creates a function from a {@link NestApplicationPromiseGetter}.
  *
- * This pattern is available to allow generating similar content for differenting contexts, such as production and testing.
+ * This pattern enables generating the same function shape for different contexts
+ * (e.g., production vs testing) by parameterizing on the Nest application source.
  */
 export type NestApplicationFunctionFactory<F> = (nestAppPromiseGetter: NestApplicationPromiseGetter) => F;
 /**
- * Getter for an INestApplicationContext promise. Nest should be initialized when the promise resolves.
+ * Factory function that creates a typed context from an initialized {@link INestApplicationContext}.
  */
 export type MakeNestContext<C> = (nest: INestApplicationContext) => C;
 /**
@@ -28,6 +29,11 @@ export declare abstract class AbstractNestContext {
     constructor(nest: INestApplicationContext);
     get nest(): INestApplicationContext;
 }
+/**
+ * Abstract class used for the top-level NestJS context for Firebase services.
+ *
+ * Your API implementation of this class is usually <AppPrefix>ApiNestContext (e.g. `DemoApiNestContext`).
+ */
 export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseModelsService<any, FirebaseAppModelContext<A>>> extends AbstractNestContext implements FirebaseServerEnvServiceRef, FirebaseServerAuthServiceRef, FirebaseServerStorageServiceRef {
     /**
      * FirebasePermissionErrorContextErrorFunction to use with makeModelContext().
@@ -51,28 +57,35 @@ export declare abstract class AbstractFirebaseNestContext<A, Y extends FirebaseM
     abstract get app(): A;
     get storageService(): FirebaseServerStorageService;
     /**
-     * Creates a FirebaseAppModelContext instance.
+     * Creates a {@link FirebaseAppModelContext} from request auth data.
+     *
+     * The context includes auth info, app reference, and error factories for permissions/existence checks.
      *
-     * @param auth
-     * @param buildFn
-     * @returns
+     * @param auth - The request's auth data reference.
+     * @param buildFn - Optional builder to customize the context.
      */
     makeModelContext(auth: AuthDataRef, buildFn?: BuildFunction<FirebaseAppModelContext<A>>): FirebaseAppModelContext<A>;
     /**
-     * Creates a InContextFirebaseModelsService given the input context and parameters.
+     * Creates an {@link InContextFirebaseModelsService} bound to the given auth context,
+     * enabling scoped model selection and permission checking.
      *
-     * @param context
-     * @param buildFn
-     * @returns
+     * @param context - The request's auth data reference.
+     * @param buildFn - Optional builder to customize the model 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>;
     useModel<T extends FirebaseModelsServiceTypes<Y>>(type: T, select: UseModelInputForRolesReader<FirebaseAppModelContext<A>, Y, T>): Promise<FirebaseModelsServiceSelectionResultRolesReader<Y, T>>;
 }
+/**
+ * Input for {@link AbstractFirebaseNestContext.useModel} when only a roles reader is needed (no custom use function).
+ */
 export type UseModelInputForRolesReader<C extends FirebaseModelServiceContext, Y extends FirebaseModelsService<any, C>, T extends FirebaseModelsServiceTypes<Y>> = Omit<UseFirebaseModelsServiceSelection<Y, T>, 'type' | 'context'> & {
     readonly request: AuthDataRef;
     readonly buildFn?: BuildFunction<C>;
 };
+/**
+ * Input for {@link AbstractFirebaseNestContext.useModel} with a custom use function that transforms the selection result.
+ */
 export type UseModelInput<C extends FirebaseModelServiceContext, Y extends FirebaseModelsService<any, C>, T extends FirebaseModelsServiceTypes<Y>, O> = UseModelInputForRolesReader<C, Y, T> & {
     readonly use: UseFirebaseModelsServiceSelectionUseFunction<Y, T, O>;
 };

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

@@ -0,0 +1,12 @@
+import { type AbstractFirebaseNestContext } from './nest.provider';
+/**
+ * Abstract class used for the top-level server NestJS context for server-only services.
+ *
+ * Your API implementation of this class is usually <AppPrefix>ApiServerNestContext (e.g. `DemoApiServerNestContext`).
+ */
+export declare abstract class AbstractServerFirebaseNestContext<C extends AbstractFirebaseNestContext<any, any>> {
+    private readonly _context;
+    constructor(c: C);
+    get context(): C;
+    get nest(): import("@nestjs/common").INestApplicationContext;
+}

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

@@ -24,21 +24,47 @@ export declare class FirebaseServerStorageModule {
  */
 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.
+ * @throws Error if `defaultBucketId` is empty.
+ *
+ * @example
+ * ```typescript
+ * const provider = firebaseServerStorageDefaultBucketIdTokenProvider('my-bucket-name');
+ * ```
+ */
 export declare function firebaseServerStorageDefaultBucketIdTokenProvider(input: StorageBucketId | FirebaseStorageContextFactoryConfig): Provider;
+/**
+ * Simplified provider config that receives only the {@link FirebaseStorageContext}.
+ */
 export type ProvideFirebaseServerStorageServiceSimple<T extends FirebaseServerStorageService> = Pick<FactoryProvider<T>, 'provide'> & {
     useFactory: (context: FirebaseStorageContext) => T;
 };
+/**
+ * Returns the default provider config that creates a standard {@link FirebaseServerStorageService}.
+ */
 export declare function defaultProvideFirebaseServerStorageServiceSimple(): ProvideFirebaseServerStorageServiceSimple<FirebaseServerStorageService>;
 export type ProvideFirebaseServerStorageService<T extends FirebaseServerStorageService> = FactoryProvider<T> | ProvideFirebaseServerStorageServiceSimple<T>;
+/**
+ * Creates NestJS provider entries for a {@link FirebaseServerStorageService} implementation.
+ *
+ * If the provider token differs from `FirebaseServerStorageService`, an alias provider is added
+ * so the service can also be injected by the abstract type.
+ */
 export declare function provideFirebaseServerStorageService<T extends FirebaseServerStorageService = FirebaseServerStorageService>(provider: ProvideFirebaseServerStorageService<T>): Provider<T>[];
 export interface FirebaseServerStorageModuleMetadataConfig<T extends FirebaseServerStorageService = FirebaseServerStorageService> extends AdditionalModuleMetadata {
     readonly serviceProvider?: ProvideFirebaseServerStorageService<T>;
 }
 /**
- * Convenience function used to generate ModuleMetadata for an app's Auth related modules and FirebaseServerStorageService provider.
+ * Generates NestJS {@link ModuleMetadata} for an app's storage module, including the
+ * {@link FirebaseServerStorageContextModule} import and the storage service provider.
  *
- * @param provide
- * @param useFactory
- * @returns
+ * @example
+ * ```typescript
+ * @Module(firebaseServerStorageModuleMetadata())
+ * export class AppStorageModule {}
+ * ```
  */
 export declare function firebaseServerStorageModuleMetadata<T extends FirebaseServerStorageService = FirebaseServerStorageService>(config?: FirebaseServerStorageModuleMetadataConfig<T>): ModuleMetadata;

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

@@ -1,11 +1,32 @@
 import { type FirebaseStorageAccessorDriver, type FirebaseStorageAccessorFile, type FirebaseStorageAccessorFolder, type StoragePath, type StorageMetadata, type StorageBucketId } from '@dereekb/firebase';
 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}.
+ */
 export declare function googleCloudStorageBucketForStorageFilePath(storage: GoogleCloudStorage, path: StoragePath): Bucket;
+/**
+ * Resolves a Google Cloud Storage {@link GoogleCloudFile} from a {@link StoragePath}.
+ */
 export declare function googleCloudStorageFileForStorageFilePath(storage: GoogleCloudStorage, path: StoragePath): GoogleCloudFile;
+/**
+ * Server-side file accessor type that guarantees stream operations are available.
+ */
 export type GoogleCloudStorageAccessorFile = FirebaseStorageAccessorFile<GoogleCloudFile> & Required<Pick<FirebaseStorageAccessorFile<GoogleCloudFile>, 'uploadStream' | 'getStream'>>;
+/**
+ * Converts Google Cloud Storage {@link FileMetadata} into the normalized {@link StorageMetadata} format.
+ */
 export declare function googleCloudFileMetadataToStorageMetadata(file: GoogleCloudFile, metadata: FileMetadata): StorageMetadata;
+/**
+ * Creates a {@link GoogleCloudStorageAccessorFile} providing CRUD, streaming, signed URL,
+ * and ACL operations for a single file in Google Cloud Storage.
+ *
+ * Handles emulator-specific edge cases (e.g., signing errors, atomic move fallback).
+ */
 export declare function googleCloudStorageAccessorFile(storage: GoogleCloudStorage, storagePath: StoragePath): GoogleCloudStorageAccessorFile;
+/**
+ * Server-side folder accessor type for Google Cloud Storage.
+ */
 export type GoogleCloudStorageAccessorFolder = FirebaseStorageAccessorFolder<GoogleCloudFile>;
 export interface GoogleCloudListResult {
     readonly files: GoogleCloudFile[];
@@ -25,5 +46,17 @@ export interface GoogleCloudStorageListApiResponseItem extends Pick<StorageMetad
     readonly bucket: StorageBucketId;
 }
 export declare const googleCloudStorageListFilesResultFactory: import("@dereekb/firebase").StorageListFilesResultFactory<GoogleCloudStorage, GoogleCloudListResult>;
+/**
+ * Creates a {@link GoogleCloudStorageAccessorFolder} that supports checking folder existence
+ * and listing files/subfolders with pagination.
+ */
 export declare function googleCloudStorageAccessorFolder(storage: GoogleCloudStorage, storagePath: StoragePath): GoogleCloudStorageAccessorFolder;
+/**
+ * Creates a {@link FirebaseStorageAccessorDriver} for Google Cloud Storage (Admin SDK).
+ *
+ * @example
+ * ```typescript
+ * const driver = googleCloudStorageFirebaseStorageAccessorDriver();
+ * ```
+ */
 export declare function googleCloudStorageFirebaseStorageAccessorDriver(): FirebaseStorageAccessorDriver;

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

@@ -1,3 +1,17 @@
 import { type FirebaseStorageDrivers } from '@dereekb/firebase';
+/**
+ * Alias for {@link FirebaseStorageDrivers} specific to the Google Cloud Storage (server) implementation.
+ */
 export type GoogleCloudFirebaseStorageDrivers = FirebaseStorageDrivers;
+/**
+ * Creates a complete set of {@link FirebaseStorageDrivers} for Google Cloud Storage (Admin SDK).
+ *
+ * Bundles the server-side storage accessor driver, identified as `@google-cloud/storage`.
+ *
+ * @example
+ * ```typescript
+ * const drivers = googleCloudFirebaseStorageDrivers();
+ * const context = firebaseStorageContextFactory(drivers);
+ * ```
+ */
 export declare function googleCloudFirebaseStorageDrivers(): GoogleCloudFirebaseStorageDrivers;

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

@@ -2,13 +2,20 @@ import { type FirebaseStorageContextFactory } from '@dereekb/firebase';
 import { type Storage as FirebaseAdminStorage } from 'firebase-admin/storage';
 import { type Storage as GoogleCloudStorage } from '@google-cloud/storage';
 /**
- * Creates a FirestoreContextFactory that uses the @google-cloud/storage package.
+ * Pre-configured {@link FirebaseStorageContextFactory} using the Google Cloud Storage (Admin SDK) drivers.
  */
 export declare const googleCloudFirebaseStorageContextFactory: FirebaseStorageContextFactory;
 /**
- * Retrieves the GoogleCloudStorage object from the input FirebaseAdmin Storage type.
+ * Extracts the underlying {@link GoogleCloudStorage} client from a Firebase Admin {@link FirebaseAdminStorage} instance.
  *
- * @param storage
- * @returns
+ * This accesses an internal property (`storageClient`) to bridge between the Firebase Admin
+ * Storage wrapper and the raw Google Cloud Storage SDK.
+ *
+ * @param storage - The Firebase Admin Storage instance.
+ *
+ * @example
+ * ```typescript
+ * const gcs = googleCloudStorageFromFirebaseAdminStorage(admin.storage());
+ * ```
  */
 export declare function googleCloudStorageFromFirebaseAdminStorage(storage: FirebaseAdminStorage): GoogleCloudStorage;

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

@@ -6,7 +6,16 @@ export interface FirebaseServerStorageServiceRef<S extends FirebaseServerStorage
     readonly storageService: S;
 }
 /**
- * Basic service that implements FirebaseStorageAccessor and provides a FirebaseStorageContext.
+ * Server-side storage service that wraps a {@link FirebaseStorageContext} and implements
+ * the {@link FirebaseStorageAccessor} interface for file and folder operations.
+ *
+ * Typically injected via NestJS and backed by the Google Cloud Storage driver.
+ *
+ * @example
+ * ```typescript
+ * const storageService = new FirebaseServerStorageService(storageContext);
+ * const file = storageService.file({ bucketId: 'my-bucket', pathString: 'path/to/file.txt' });
+ * ```
  */
 export declare class FirebaseServerStorageService implements FirebaseStorageAccessor {
     private readonly _storageContext;

package/src/lib/type.d.ts

@@ -1,9 +1,14 @@
 import { type CallableRequest } from 'firebase-functions/v2/https';
 /**
- * CallableRequest auth data.
+ * The authenticated user's data from a Firebase v2 {@link CallableRequest}.
+ *
+ * Non-nullable — use this type when auth is guaranteed to be present.
  */
 export type AuthData = NonNullable<CallableRequest['auth']>;
 /**
- * CallableRequest context data (omits data and stream configs).
+ * The request context from a Firebase v2 callable function, excluding the payload and streaming fields.
+ *
+ * Used throughout `@dereekb/firebase-server` as the standard callable context type
+ * passed to auth services and function handlers.
  */
 export type CallableContext = Omit<CallableRequest<any>, 'data' | 'acceptsStreaming'>;