@dereekb/firebase 13.2.2 → 13.3.0

package/src/lib/model/storagefile/storagefile.create.d.ts

@@ -7,6 +7,17 @@ import { type StoragePathRef, type StoragePath } from '../../common/storage/stor
 import { type FirebaseAuthOwnershipKey, type FirebaseAuthUserId } from '../../common/auth/auth';
 import { type StorageFilePurposeSubgroup, type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
 import { type ReadFirestoreModelKeyInput } from '../../common';
+/**
+ * Input for creating a StorageFile document paired with its storage path.
+ *
+ * Provides all the fields needed to create a fully-configured {@link StorageFile} Firestore document,
+ * including ownership, purpose, group membership, and processing state.
+ *
+ * Either a `file`, `storagePathRef`, or `storagePath` must be provided to identify the storage location.
+ * Either an `accessor` or `context` must be provided for Firestore document creation.
+ *
+ * @template M - type of arbitrary metadata stored in the `d` field
+ */
 export interface CreateStorageFileDocumentPairInput<M extends StorageFileMetadata = StorageFileMetadata> {
     /**
      * Optional "now" value that is assigned to the "cat" value, created at time.
@@ -111,6 +122,9 @@ export interface CreateStorageFileDocumentPairInput<M extends StorageFileMetadat
      */
     readonly accessor?: FirestoreDocumentAccessor<StorageFile, StorageFileDocument>;
 }
+/**
+ * Result of creating a StorageFile document pair, containing the document and its template data.
+ */
 export interface CreateStorageFileDocumentPairResult<M extends StorageFileMetadata = StorageFileMetadata> {
     /**
      * The StorageFileDocument that was created.
@@ -121,6 +135,10 @@ export interface CreateStorageFileDocumentPairResult<M extends StorageFileMetada
      */
     readonly storageFile: StorageFile<M>;
 }
+/**
+ * Configuration for {@link createStorageFileDocumentPairFactory}, controlling default values
+ * for creation type, purpose subgroup, and processing state.
+ */
 export interface CreateStorageFileDocumentPairFactoryConfig {
     /**
      * The default creation type to use.
@@ -146,10 +164,29 @@ export interface CreateStorageFileDocumentPairFactoryConfig {
  */
 export type CreateStorageFileDocumentPairFactory = <M extends StorageFileMetadata = StorageFileMetadata>(input: CreateStorageFileDocumentPairInput<M>) => Promise<CreateStorageFileDocumentPairResult<M>>;
 /**
- * Creates a CreateStorageFileDocumentPairFactory.
+ * Creates a factory for producing StorageFile document pairs with pre-configured defaults.
+ *
+ * The factory handles document ID generation (random for direct creation, deterministic for
+ * {@link StorageFileCreationType.FOR_STORAGE_FILE_GROUP}), storage path resolution, and
+ * initial state setup.
+ *
+ * @param config - optional defaults for creation type, subgroup, and processing state
+ * @throws {Error} When neither accessor nor context is provided
+ * @throws {Error} When no storage path can be resolved from the input
+ * @throws {Error} When FOR_STORAGE_FILE_GROUP is used without parentStorageFileGroup or purpose
+ *
+ * @example
+ * ```ts
+ * const factory = createStorageFileDocumentPairFactory({
+ *   defaultShouldBeProcessed: true
+ * });
  *
- * @param config
- * @returns
+ * const { storageFileDocument, storageFile } = await factory({
+ *   storagePath: { bucketId: 'my-bucket', pathString: '/files/report.pdf' },
+ *   purpose: 'report',
+ *   context: collections
+ * });
+ * ```
  */
 export declare function createStorageFileDocumentPairFactory(config?: CreateStorageFileDocumentPairFactoryConfig): CreateStorageFileDocumentPairFactory;
 /**

package/src/lib/model/storagefile/storagefile.d.ts

@@ -3,10 +3,33 @@ import { type GrantedReadRole, type GrantedUpdateRole } from '@dereekb/model';
 import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext, type FirebaseAuthUserId, type FirebaseAuthOwnershipKey, type StoragePath, type StorageSignedDownloadUrl, type StorageDownloadUrl, type SavedToFirestoreIfTrue, type OneWayFlatFirestoreModelKey, type FirestoreCollectionModelKey } from '../../common';
 import { type StorageFilePurposeSubgroup, type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileId, type StorageFileMetadata, type StorageFilePurpose, type StorageFileDisplayName } from './storagefile.id';
 import { type NotificationKey } from '../notification';
+/**
+ * @module storagefile
+ *
+ * Defines the StorageFile and StorageFileGroup Firestore models for managing files in Google Cloud Storage.
+ *
+ * **StorageFile** tracks individual files with ownership, state machine (INIT → OK → QUEUED_FOR_DELETE),
+ * processing lifecycle (INIT_OR_NONE → QUEUED → PROCESSING → SUCCESS/FAILED), and group membership.
+ * Files are created either directly, from uploads, or for a {@link StorageFileGroup}.
+ *
+ * **StorageFileGroup** aggregates multiple StorageFiles around a related model (e.g., a user or entity).
+ * Groups support automatic zip generation and content regeneration via the `re` flag.
+ *
+ * Server-side processing is handled via NotificationTask integration — see `@dereekb/firebase-server/model`
+ * for the StorageFile action service.
+ */
+/**
+ * Abstract base providing access to StorageFile and StorageFileGroup Firestore collections.
+ *
+ * Implement this in your app module to wire up the collections for dependency injection.
+ */
 export declare abstract class StorageFileFirestoreCollections {
     abstract readonly storageFileCollection: StorageFileFirestoreCollection;
     abstract readonly storageFileGroupCollection: StorageFileGroupFirestoreCollection;
 }
+/**
+ * Union of all StorageFile-related model identity types.
+ */
 export type StorageFileTypes = typeof storageFileIdentity | typeof storageFileGroupIdentity;
 /**
  * StorageFile-related model that is initialized asynchronously at a later time.
@@ -65,7 +88,10 @@ export interface StorageFileRelatedFileMetadata {
     readonly [STORAGEFILE_RELATED_FILE_METADATA_KEY]?: Maybe<StorageFileId>;
 }
 /**
- * The current file state.
+ * How a StorageFile was created, which affects document ID generation and initialization behavior.
+ *
+ * When {@link FOR_STORAGE_FILE_GROUP} is used, the StorageFile ID is derived deterministically
+ * from the parent StorageFileGroup, enabling predictable document references.
  */
 export declare enum StorageFileCreationType {
     /**
@@ -89,7 +115,13 @@ export declare enum StorageFileCreationType {
     FOR_STORAGE_FILE_GROUP = 3
 }
 /**
- * The current file state.
+ * Lifecycle state of a StorageFile document.
+ *
+ * State transitions:
+ * - `INIT` → `OK` (successful initialization) or `INVALID` (failed initialization)
+ * - `OK` → `QUEUED_FOR_DELETE` (flagged for deletion)
+ * - `INVALID` → (deleted after a period)
+ * - `QUEUED_FOR_DELETE` → (deleted once `sdat` is reached)
  */
 export declare enum StorageFileState {
     /**
@@ -114,7 +146,17 @@ export declare enum StorageFileState {
     QUEUED_FOR_DELETE = 3
 }
 /**
- * The current processing state of the file.
+ * Processing lifecycle state for a StorageFile.
+ *
+ * Processing is driven by NotificationTask integration. State transitions:
+ * - `INIT_OR_NONE` → `QUEUED_FOR_PROCESSING` (flagged for processing)
+ * - `QUEUED_FOR_PROCESSING` → `PROCESSING` (NotificationTask created)
+ * - `PROCESSING` → `SUCCESS` or `FAILED`
+ * - `FAILED` → `QUEUED_FOR_PROCESSING` (retry) or `DO_NOT_PROCESS`
+ * - `SUCCESS` → `QUEUED_FOR_PROCESSING` (reprocess) or `ARCHIVED`
+ * - `ARCHIVED` and `DO_NOT_PROCESS` are terminal states.
+ *
+ * Use {@link canQueueStorageFileForProcessing} to check if a file can be re-queued.
  */
 export declare enum StorageFileProcessingState {
     /**
@@ -155,19 +197,26 @@ export declare enum StorageFileProcessingState {
     DO_NOT_PROCESS = 6
 }
 /**
- * If true, the StorageFile can safely be re-queued for processing.
+ * Checks whether a StorageFile can safely be re-queued for processing.
+ *
+ * A file is eligible when it has a purpose set and its processing state allows re-queuing
+ * (INIT_OR_NONE, FAILED, or SUCCESS). Files that are already QUEUED/PROCESSING, ARCHIVED,
+ * or DO_NOT_PROCESS are not eligible.
  *
- * Requirements:
- * - Has a purpose
- * - The processing state is not already queued for processing, or processing.
- * - The processing state is not archived or marked as do not process, as these should never be re-processed.
+ * @param storageFile - the file's processing state (`ps`) and purpose (`p`) fields
+ * @returns true if the file can be queued for processing
  *
- * @param state
- * @returns
+ * @example
+ * ```ts
+ * if (canQueueStorageFileForProcessing(storageFile)) {
+ *   // safe to set ps = QUEUED_FOR_PROCESSING
+ * }
+ * ```
  */
 export declare function canQueueStorageFileForProcessing(storageFile: Pick<StorageFile, 'ps' | 'p'>): boolean;
 /**
- * After 3 hours of being in the PROCESSING state, we can check for retring processing.
+ * Throttle duration (3 hours) after which a PROCESSING-state file is considered "stuck"
+ * and eligible for retry checks.
  */
 export declare const STORAGE_FILE_PROCESSING_STUCK_THROTTLE_CHECK_MS: number;
 /**
@@ -191,9 +240,16 @@ export type StorageFileSignedDownloadUrl = StorageSignedDownloadUrl;
  */
 export type StorageFileDownloadUrl = StorageFilePublicDownloadUrl | StorageFileSignedDownloadUrl;
 /**
- * A StorageFile in the system, which references a file in Google Cloud Storage.
+ * A StorageFile Firestore document that references a file in Google Cloud Storage.
+ *
+ * Tracks file ownership, lifecycle state ({@link StorageFileState}), processing state
+ * ({@link StorageFileProcessingState}), group membership, and arbitrary metadata. Extends
+ * {@link StoragePath} to carry the bucket and path of the underlying storage object.
+ *
+ * Server-side processing is driven by the NotificationTask system — see
+ * `StorageFileActionServerActions` in `@dereekb/firebase-server/model`.
  *
- * Contains file metadata and ownership information, along with other arbitrary metadata.
+ * @template M - type of the arbitrary metadata stored in the `d` field
  */
 export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata> extends StoragePath {
     /**
@@ -299,17 +355,54 @@ export interface StorageFile<M extends StorageFileMetadata = StorageFileMetadata
  * The admin_download role allows specifying additional parameters and longer expiration times.
  */
 export type StorageFileDownloadRole = 'download' | 'admin_download';
+/**
+ * All available permission roles for StorageFile operations.
+ *
+ * Includes download roles, sync/processing roles, and standard CRUD roles.
+ */
 export type StorageFileRoles = StorageFileDownloadRole | 'forceSyncWithGroups' | 'syncWithGroups' | 'process' | GrantedUpdateRole | GrantedReadRole;
+/**
+ * Firestore document wrapper for a {@link StorageFile}.
+ */
 export declare class StorageFileDocument extends AbstractFirestoreDocument<StorageFile, StorageFileDocument, typeof storageFileIdentity> {
     get modelIdentity(): import("../..").RootFirestoreModelIdentity<"storageFile", "sf">;
 }
+/**
+ * Snapshot converter for {@link StorageFile} documents, handling field-level serialization
+ * between the application model and Firestore storage format.
+ */
 export declare const storageFileConverter: import("../..").SnapshotConverterFunctions<StorageFile<Readonly<Record<string, any>>>, Partial<import("@dereekb/util").ReplaceType<StorageFile<Readonly<Record<string, any>>>, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Returns the raw Firestore CollectionReference for the StorageFile collection.
+ *
+ * @example
+ * ```ts
+ * const colRef = storageFileCollectionReference(firestoreContext);
+ * ```
+ */
 export declare function storageFileCollectionReference(context: FirestoreContext): CollectionReference<StorageFile>;
+/**
+ * Typed FirestoreCollection for {@link StorageFile} documents.
+ */
 export type StorageFileFirestoreCollection = FirestoreCollection<StorageFile, StorageFileDocument>;
+/**
+ * Creates a fully configured {@link StorageFileFirestoreCollection} with snapshot conversion and document factory.
+ *
+ * @example
+ * ```ts
+ * const collection = storageFileFirestoreCollection(firestoreContext);
+ * const doc = collection.documentAccessor().newDocument();
+ * ```
+ */
 export declare function storageFileFirestoreCollection(firestoreContext: FirestoreContext): StorageFileFirestoreCollection;
+/**
+ * Model identity for the StorageFileGroup collection (collection name: `storageFileGroup`, prefix: `sfg`).
+ */
 export declare const storageFileGroupIdentity: import("../..").RootFirestoreModelIdentity<"storageFileGroup", "sfg">;
 /**
- * Current embedded state
+ * Represents a single StorageFile's embedding within a {@link StorageFileGroup}.
+ *
+ * Tracks when the file was added to the group and when it was last included in a zip archive.
  */
 export interface StorageFileGroupEmbeddedFile {
     /**
@@ -330,11 +423,20 @@ export interface StorageFileGroupEmbeddedFile {
      */
     zat?: Maybe<Date>;
 }
+/**
+ * Firestore sub-object converter for {@link StorageFileGroupEmbeddedFile}, handling date serialization
+ * of `sat` and `zat` fields as Unix timestamp seconds.
+ */
 export declare const storageFileGroupEmbeddedFile: import("../..").FirestoreSubObjectFieldMapFunctionsConfig<StorageFileGroupEmbeddedFile, Partial<import("@dereekb/util").ReplaceType<StorageFileGroupEmbeddedFile, import("@dereekb/util").MaybeMap<object>, any>>>;
 /**
- * A group of StorageFiles.
+ * A group of {@link StorageFile}s aggregated around a related model or common identifier.
+ *
+ * Groups are identified by a two-way flat key derived from the related model's key
+ * (see {@link storageFileGroupIdForModel}). They support automatic zip file generation
+ * via the `z` flag and content regeneration via the `re` flag.
  *
- * Contains file metadata and ownership information, along with other arbitrary metadata.
+ * Implements {@link InitializedStorageFileModel} for async initialization tracking —
+ * the `s` (needs sync) flag is set on creation and cleared once initialized.
  */
 export interface StorageFileGroup extends InitializedStorageFileModel {
     /**
@@ -374,13 +476,48 @@ export interface StorageFileGroup extends InitializedStorageFileModel {
      */
     c?: Maybe<SavedToFirestoreIfTrue>;
 }
+/**
+ * Subset of {@link StorageFileGroup} fields controlling content generation flags.
+ */
 export type StorageFileGroupContentFlagsData = Pick<StorageFileGroup, 'z'>;
+/**
+ * Permission roles for StorageFileGroup operations.
+ */
 export type StorageFileGroupRoles = 'regenerate' | GrantedReadRole;
+/**
+ * Firestore document wrapper for a {@link StorageFileGroup}.
+ *
+ * Provides a convenience getter to infer the related model key from the group's own ID.
+ */
 export declare class StorageFileGroupDocument extends AbstractFirestoreDocument<StorageFileGroup, StorageFileGroupDocument, typeof storageFileGroupIdentity> {
     get modelIdentity(): import("../..").RootFirestoreModelIdentity<"storageFileGroup", "sfg">;
     get storageFileGroupRelatedModelKey(): string;
 }
+/**
+ * Snapshot converter for {@link StorageFileGroup} documents, including nested
+ * {@link StorageFileGroupEmbeddedFile} array conversion.
+ */
 export declare const storageFileGroupConverter: import("../..").SnapshotConverterFunctions<StorageFileGroup, Partial<import("@dereekb/util").ReplaceType<StorageFileGroup, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Returns the raw Firestore CollectionReference for the StorageFileGroup collection.
+ *
+ * @example
+ * ```ts
+ * const colRef = storageFileGroupCollectionReference(firestoreContext);
+ * ```
+ */
 export declare function storageFileGroupCollectionReference(context: FirestoreContext): CollectionReference<StorageFileGroup>;
+/**
+ * Typed FirestoreCollection for {@link StorageFileGroup} documents.
+ */
 export type StorageFileGroupFirestoreCollection = FirestoreCollection<StorageFileGroup, StorageFileGroupDocument>;
+/**
+ * Creates a fully configured {@link StorageFileGroupFirestoreCollection} with snapshot conversion and document factory.
+ *
+ * @example
+ * ```ts
+ * const collection = storageFileGroupFirestoreCollection(firestoreContext);
+ * const doc = collection.documentAccessor().loadDocumentForId(groupId);
+ * ```
+ */
 export declare function storageFileGroupFirestoreCollection(firestoreContext: FirestoreContext): StorageFileGroupFirestoreCollection;

package/src/lib/model/storagefile/storagefile.file.d.ts

@@ -3,19 +3,23 @@ import { type StoragePath } from '../../common/storage/storage';
 import { type StorageCustomMetadata } from '../../common/storage/types';
 import { type FirebaseStorageAccessorFile } from '../../common/storage/driver/accessor';
 /**
- * Details from the input.
+ * Input for a {@link StoredFileReader}, carrying the storage bucket and path of the file.
  */
 export type StoredFileReaderInput = StoragePath;
 /**
- * Factory function that creates a StoredFileReader from the input details.
+ * Factory that creates a {@link StoredFileReader} from a {@link FirebaseStorageAccessorFile}.
+ *
+ * Use {@link storedFileReaderFactory} to create an instance.
  */
 export type StoredFileReaderFactory = FactoryWithRequiredInput<StoredFileReader, FirebaseStorageAccessorFile>;
 /**
- * A read-only accessor for file in FirebaseStorage.
+ * Read-only accessor for a file in Firebase Storage.
  *
- * It exposes only read-only methods for accessing details about the file.
+ * Provides lazy-loading access to file bytes, streams, metadata, and copy operations
+ * without exposing write/delete methods. Metadata is cached after first load.
  *
- * This accessor is generally a server-side only interface.
+ * Primarily used server-side for upload processing and file type determination
+ * (see {@link UploadedFileTypeDeterminer} in `storagefile.upload.determiner.ts`).
  */
 export interface StoredFileReader {
     /**
@@ -48,8 +52,19 @@ export interface StoredFileReader {
     readonly copy: Required<FirebaseStorageAccessorFile>['copy'];
 }
 /**
- * Creates a StoredFileReaderFactory.
+ * Creates a {@link StoredFileReaderFactory} that wraps {@link FirebaseStorageAccessorFile} instances
+ * into read-only {@link StoredFileReader} accessors.
+ *
+ * File metadata is cached after first load; byte/stream accessors are not cached to avoid
+ * holding large data in memory.
+ *
+ * Should only be used server-side, as `copy` may not be available on the client.
  *
- * Should generally only be used on the server-side, as copy may not be available on the client-side.
+ * @example
+ * ```ts
+ * const factory = storedFileReaderFactory();
+ * const reader = factory(storageAccessorFile);
+ * const bytes = await reader.loadFileBytes();
+ * ```
  */
 export declare function storedFileReaderFactory(): StoredFileReaderFactory;

package/src/lib/model/storagefile/storagefile.group.d.ts

@@ -1,9 +1,38 @@
 import { type SlashPathFile, type SlashPathFolder, type SlashPath, type Maybe } from '@dereekb/util';
 import { type StorageFileGroupId } from './storagefile.id';
 /**
- * All StorageFileGroup generated files are stored under this root folder.
+ * Root folder in Firebase Storage where all StorageFileGroup-generated files are stored.
+ *
+ * Each group gets a subfolder: `/sfg/{storageFileGroupId}/`.
  */
 export declare const STORAGE_FILE_GROUP_ROOT_FOLDER_PATH: SlashPathFolder;
+/**
+ * Builds the storage folder path for a specific StorageFileGroup, optionally with sub-paths.
+ *
+ * @param storageFileGroupId - the group's document ID
+ * @param subPath - optional sub-paths to append
+ *
+ * @example
+ * ```ts
+ * const folder = storageFileGroupFolderPath('abc123');
+ * // folder === '/sfg/abc123/'
+ *
+ * const nested = storageFileGroupFolderPath('abc123', 'output');
+ * // nested === '/sfg/abc123/output/'
+ * ```
+ */
 export declare function storageFileGroupFolderPath(storageFileGroupId: StorageFileGroupId, ...subPath: Maybe<SlashPath>[]): SlashPathFolder;
+/**
+ * File name for a StorageFileGroup's generated zip archive within its folder.
+ */
 export declare const STORAGE_FILE_GROUP_ZIP_FILE_PATH: SlashPathFile;
+/**
+ * Returns the full storage path for a StorageFileGroup's zip file.
+ *
+ * @example
+ * ```ts
+ * const zipPath = storageFileGroupZipFileStoragePath('abc123');
+ * // zipPath === '/sfg/abc123/z.zip'
+ * ```
+ */
 export declare function storageFileGroupZipFileStoragePath(storageFileGroupId: StorageFileGroupId): SlashPath;

package/src/lib/model/storagefile/storagefile.group.processing.d.ts

@@ -3,7 +3,10 @@ import { type StorageFileGroupId, type StorageFilePurpose } from './storagefile.
 import { type StorageFileProcessingSubtask, type StorageFileProcessingSubtaskMetadata } from './storagefile.task';
 import { type StorageFileGroupCreatedStorageFileKey } from './storagefile';
 /**
- * StorageFilePurpose for a StorageFileGroup's generated zip file.
+ * {@link StorageFilePurpose} identifier for a StorageFileGroup's generated zip file.
+ *
+ * This purpose is used to create a predictable {@link StorageFileGroupCreatedStorageFileKey}
+ * for the group's zip StorageFile, enabling deterministic document ID generation.
  */
 export declare const STORAGE_FILE_GROUP_ZIP_STORAGE_FILE_PURPOSE: StorageFilePurpose;
 /**
@@ -15,12 +18,27 @@ export type StorageFileGroupZipStorageFileKey = StorageFileGroupCreatedStorageFi
  */
 export declare const storageFileGroupZipStorageFileKey: import("./storagefile").StorageFileGroupCreateStorageFileKeyFactory<string>;
 /**
- * Metadata for the StorageFileGroupZipStorageFile.
+ * Metadata stored on the zip StorageFile, linking it back to its parent StorageFileGroup.
  */
 export interface StorageFileGroupZipStorageFileMetadata {
+    /**
+     * StorageFileGroup ID. ID of the StorageFileGroup that this zip file was generated for.
+     */
     readonly sfg: StorageFileGroupId;
 }
+/**
+ * Subtask checkpoint identifier for the zip creation step of StorageFileGroup processing.
+ */
 export declare const STORAGE_FILE_GROUP_ZIP_STORAGE_FILE_PURPOSE_CREATE_ZIP_SUBTASK: StorageFileProcessingSubtask;
+/**
+ * Type alias for the zip creation subtask checkpoint string.
+ */
 export type StorageFileGroupZipStorageFileProcessingSubtask = typeof STORAGE_FILE_GROUP_ZIP_STORAGE_FILE_PURPOSE_CREATE_ZIP_SUBTASK;
+/**
+ * Metadata type for the zip creation subtask.
+ */
 export type StorageFileGroupZipStorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata;
+/**
+ * File name of the JSON metadata file stored alongside the zip in the group's storage folder.
+ */
 export declare const STORAGE_FILE_GROUP_ZIP_INFO_JSON_FILE_NAME: SlashPathTypedFile;

package/src/lib/model/storagefile/storagefile.id.d.ts

@@ -1,6 +1,21 @@
 import { type SlashPathUntypedFile } from '@dereekb/util';
 import { type FlatFirestoreModelKey, inferKeyFromTwoWayFlatFirestoreModelKey, twoWayFlatFirestoreModelKey, type FirestoreModelId, type FirestoreModelKey } from '../../common';
+/**
+ * @module storagefile.id
+ *
+ * Defines identity types and ID generation patterns for the StorageFile and StorageFileGroup models.
+ *
+ * StorageFileGroup IDs use a two-way flat key encoding of the related model's key, enabling
+ * bidirectional lookup between a group and its source model via {@link storageFileGroupIdForModel}
+ * and {@link inferStorageFileGroupRelatedModelKey}.
+ */
+/**
+ * Firestore document ID for a StorageFile.
+ */
 export type StorageFileId = FirestoreModelId;
+/**
+ * Full Firestore document key (collection path + ID) for a StorageFile.
+ */
 export type StorageFileKey = FirestoreModelKey;
 /**
  * Arbitrary string that can be used to describe the file's purpose.
@@ -46,17 +61,41 @@ export type StorageFileGroupRelatedStorageFilePurpose = StorageFilePurpose;
  */
 export type StorageFileMetadata = Readonly<Record<string, any>>;
 /**
- * The StorgaeFileGroupId is a two way flat firestore model key of the object that it represents.
+ * A StorageFileGroup's document ID, encoded as a two-way flat Firestore model key
+ * of the model it represents.
  *
- * This identifier is used by StorageFile's to group files together based around some other model or common identifier.
+ * This encoding enables bidirectional lookup: given a model key you can derive the
+ * group ID, and given a group ID you can recover the original model key.
+ *
+ * @example
+ * ```ts
+ * const groupId = storageFileGroupIdForModel('notification/abc123');
+ * // groupId is a flat key like "notification_abc123"
+ *
+ * const modelKey = inferStorageFileGroupRelatedModelKey(groupId);
+ * // modelKey === 'notification/abc123'
+ * ```
  */
 export type StorageFileGroupId = FlatFirestoreModelKey;
+/**
+ * Full Firestore document key (collection path + ID) for a StorageFileGroup.
+ */
 export type StorageFileGroupKey = FirestoreModelKey;
 /**
- * Creates a StorgaeFileGroupId from the input FirestoreModelKey.
+ * Encodes a FirestoreModelKey into a {@link StorageFileGroupId} using two-way flat key encoding.
  *
- * @param modelKey
- * @returns
+ * @example
+ * ```ts
+ * const groupId = storageFileGroupIdForModel('notification/abc123');
+ * ```
  */
 export declare const storageFileGroupIdForModel: typeof twoWayFlatFirestoreModelKey;
+/**
+ * Decodes a {@link StorageFileGroupId} back into the original FirestoreModelKey.
+ *
+ * @example
+ * ```ts
+ * const modelKey = inferStorageFileGroupRelatedModelKey(groupId);
+ * ```
+ */
 export declare const inferStorageFileGroupRelatedModelKey: typeof inferKeyFromTwoWayFlatFirestoreModelKey;

package/src/lib/model/storagefile/storagefile.permission.d.ts

@@ -1,13 +1,18 @@
 import { type FirebasePermissionServiceModel, type FirestoreModelKey, type GrantedRolesOtherwiseFunctionResult, type GrantRolesOtherwiseFunction, type StorageFile, type StorageFileDocument, type StorageFileRoles, type FirebaseModelContext } from '@dereekb/firebase';
 import { type Getter, type Maybe } from '@dereekb/util';
 /**
- * grantStorageFileRolesForUserAuthFunction() configuration
+ * Configuration for {@link grantStorageFileRolesForUserAuthFunction}, providing the permission
+ * service output, auth context, and target StorageFile document.
  */
 export interface GrantStorageFileRolesForUserAuthFunctionConfig<T extends FirebaseModelContext> {
     readonly output: FirebasePermissionServiceModel<StorageFile, StorageFileDocument>;
     readonly context: T;
     readonly model: StorageFileDocument;
 }
+/**
+ * Input for the role granting function, specifying which roles to grant based on
+ * user ownership and/or ownership key matching.
+ */
 export interface GrantStorageFileRolesForUserAuthInput {
     /**
      * Roles to grant if the user matches the storage file user.
@@ -20,9 +25,23 @@ export interface GrantStorageFileRolesForUserAuthInput {
 }
 export type GrantStorageFileRolesForUserAuthFunction = (input: GrantStorageFileRolesForUserAuthInput) => GrantRolesOtherwiseFunction<StorageFileRoles>;
 /**
- * Creates a new GrantStorageFileRolesForUserAuthFunction given the input config/context.
+ * Creates a function that grants {@link StorageFileRoles} based on user authentication context.
+ *
+ * The returned function checks two conditions in parallel:
+ * 1. Whether the authenticated user matches the StorageFile's `u` (user) field
+ * 2. Whether the StorageFile has an ownership key (`o`) that grants additional roles
+ *
+ * Use this within a permission service to define role-based access for StorageFile operations.
+ *
+ * @param config - the permission output, auth context, and target document
  *
- * @param config
- * @returns
+ * @example
+ * ```ts
+ * const grantRoles = grantStorageFileRolesForUserAuthFunction({ output, context, model });
+ * const otherwise = grantRoles({
+ *   rolesForStorageFileUser: () => ({ download: true, update: true }),
+ *   rolesForStorageFileOwnershipKey: (key) => ({ read: true })
+ * });
+ * ```
  */
 export declare function grantStorageFileRolesForUserAuthFunction<T extends FirebaseModelContext>(config: GrantStorageFileRolesForUserAuthFunctionConfig<T>): GrantStorageFileRolesForUserAuthFunction;