@dereekb/firebase 13.2.2 → 13.3.0

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

@@ -3,13 +3,33 @@ import { type FirestoreQueryConstraint } from '../../common/firestore/query/cons
 import { type StorageFilePurposeSubgroup, type StorageFilePurpose } from './storagefile.id';
 import { type FirebaseAuthUserId } from '../../common/auth/auth';
 /**
- * Returns a query constraint for StorageFiles that are queued for processing.
+ * Returns query constraints for StorageFiles with `ps == QUEUED_FOR_PROCESSING`.
+ *
+ * Used by the server action service to find files awaiting processing task creation.
+ *
+ * @example
+ * ```ts
+ * const constraints = storageFilesQueuedForProcessingQuery();
+ * const results = await collection.query(constraints);
+ * ```
  */
 export declare function storageFilesQueuedForProcessingQuery(): FirestoreQueryConstraint[];
 /**
- * Returns a query constraint for StorageFiles that are queued for deletion and are past their scheduled delete date.
+ * Returns query constraints for StorageFiles whose scheduled delete date (`sdat`) has passed.
+ *
+ * Used by the cleanup service to find files ready for permanent deletion.
+ *
+ * @param now - reference time for comparison; defaults to current time
+ *
+ * @example
+ * ```ts
+ * const constraints = storageFilesQueuedForDeleteQuery();
+ * ```
  */
 export declare function storageFilesQueuedForDeleteQuery(now?: Maybe<Date>): FirestoreQueryConstraint[];
+/**
+ * Input for querying StorageFiles by purpose and owning user, with optional subgroup filtering.
+ */
 export interface StorageFilePurposeAndUserQueryInput {
     readonly user: FirebaseAuthUserId;
     readonly purpose: StorageFilePurpose;
@@ -18,26 +38,58 @@ export interface StorageFilePurposeAndUserQueryInput {
      */
     readonly purposeSubgroup?: Maybe<StorageFilePurposeSubgroup>;
 }
+/**
+ * Returns query constraints for StorageFiles matching a specific purpose and user,
+ * with optional subgroup filtering.
+ *
+ * @example
+ * ```ts
+ * const constraints = storageFilePurposeAndUserQuery({
+ *   user: 'user123',
+ *   purpose: 'avatar'
+ * });
+ * ```
+ */
 export declare function storageFilePurposeAndUserQuery(input: StorageFilePurposeAndUserQueryInput): FirestoreQueryConstraint[];
+/**
+ * Returns query constraints for StorageFiles flagged for group synchronization (`gs == true`).
+ *
+ * Used by the sync service to find files whose group memberships need to be propagated.
+ *
+ * @example
+ * ```ts
+ * const constraints = storageFileFlaggedForSyncWithGroupsQuery();
+ * ```
+ */
 export declare function storageFileFlaggedForSyncWithGroupsQuery(): FirestoreQueryConstraint[];
 /**
- * Query for storageFileGroups that are flagged for initialization.
+ * Returns query constraints for StorageFileGroups that need initialization (`s == true`).
  *
- * @param now
- * @returns
+ * Used by the initialization service to find newly-created groups that haven't been synced yet.
+ *
+ * @example
+ * ```ts
+ * const constraints = storageFileGroupsFlaggedForNeedsInitializationQuery();
+ * ```
  */
 export declare function storageFileGroupsFlaggedForNeedsInitializationQuery(): FirestoreQueryConstraint[];
 /**
- * Query for storageFileGroups that are flagged for content regeneration.
+ * Returns query constraints for StorageFileGroups flagged for content regeneration (`re == true`).
  *
- * @param now
- * @returns
+ * @example
+ * ```ts
+ * const constraints = storageFileGroupsFlaggedForContentRegenerationQuery();
+ * ```
  */
 export declare function storageFileGroupsFlaggedForContentRegenerationQuery(): FirestoreQueryConstraint[];
 /**
- * Query for storageFileGroups that are flagged as invalid.
+ * Returns query constraints for StorageFileGroups flagged as invalid (`fi == true`).
+ *
+ * Invalid groups are typically cleaned up (deleted along with their associated files).
  *
- * @param now
- * @returns
+ * @example
+ * ```ts
+ * const constraints = storageFileGroupsFlaggedInvalidQuery();
+ * ```
  */
 export declare function storageFileGroupsFlaggedInvalidQuery(): FirestoreQueryConstraint[];

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

@@ -5,19 +5,36 @@ import { type NotificationTaskType } from '../notification/notification.id';
 import { type StorageFileDocument } from './storagefile';
 import { type StorageFileId, type StorageFilePurpose } from './storagefile.id';
 import { type StoragePath } from '../../common';
+/**
+ * NotificationTask type identifier for StorageFile processing tasks.
+ *
+ * Tasks with this type drive the StorageFile processing lifecycle, executing
+ * purpose-specific processing logic through the subtask checkpoint system.
+ */
 export declare const STORAGE_FILE_PROCESSING_NOTIFICATION_TASK_TYPE: NotificationTaskType;
 /**
- * A subtask checkpoint.
+ * Checkpoint string for a StorageFile processing subtask.
  *
- * It is similar to NotificationTaskCheckpointString, but is used for StorageFile processing.
+ * Subtasks within a StorageFile processing task use these checkpoints to track
+ * multi-step progress (e.g., zip creation, file conversion).
  */
 export type StorageFileProcessingSubtask = NotificationTaskSubtaskCheckpointString;
 /**
- * Metadata for a subtask.
+ * Arbitrary metadata passed to StorageFile processing subtasks.
  *
- * It is similar to NotificationItemMetadata, but is stored within the StorageFileProcessingNotificationTaskData and passed to the subtasks.
+ * Stored within {@link StorageFileProcessingNotificationTaskData} and made available
+ * to each subtask handler during execution.
  */
 export type StorageFileProcessingSubtaskMetadata = NotificationTaskSubtaskMetadata;
+/**
+ * Data payload for a StorageFile processing NotificationTask.
+ *
+ * Extends the subtask data model with StorageFile-specific fields (file ID, storage path, purpose).
+ * The storage path and purpose are populated from the StorageFile on first task execution.
+ *
+ * @template M - subtask metadata type
+ * @template S - subtask checkpoint string type
+ */
 export interface StorageFileProcessingNotificationTaskData<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> extends NotificationTaskSubtaskData<M, S> {
     /**
      * The StorageFileDocument id.
@@ -36,9 +53,35 @@ export interface StorageFileProcessingNotificationTaskData<M extends StorageFile
      */
     readonly p?: Maybe<StorageFilePurpose>;
 }
+/**
+ * Input for creating a StorageFile processing NotificationTask.
+ *
+ * Accepts the target StorageFileDocument (from which the ID and purpose are derived)
+ * and optional override behavior for existing tasks.
+ */
 export interface StorageFileProcessingNotificationTaskInput<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata> extends Omit<StorageFileProcessingNotificationTaskData<M>, 'storageFile' | 'p' | 'sfps'> {
     readonly storageFileDocument: StorageFileDocument;
     readonly overrideExistingTask?: Maybe<boolean>;
 }
+/**
+ * Creates a {@link CreateNotificationTaskTemplate} for a StorageFile processing task.
+ *
+ * The created task is unique per StorageFile (only one processing task at a time).
+ *
+ * @param input - the target StorageFileDocument and optional subtask data
+ *
+ * @example
+ * ```ts
+ * const template = storageFileProcessingNotificationTaskTemplate({
+ *   storageFileDocument: doc,
+ *   sd: { customKey: 'value' }
+ * });
+ * ```
+ */
 export declare function storageFileProcessingNotificationTaskTemplate(input: StorageFileProcessingNotificationTaskInput): CreateNotificationTaskTemplate;
+/**
+ * All NotificationTask types used by the StorageFile system.
+ *
+ * Register these with the notification task handler to enable StorageFile processing.
+ */
 export declare const ALL_STORAGE_FILE_NOTIFICATION_TASK_TYPES: NotificationTaskType[];

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

@@ -1,12 +1,19 @@
 import { type AUTH_ROLE_CLAIMS_DEFAULT_CLAIM_VALUE, type AuthRoleClaimsFactoryConfigEntrySimpleOptions } from '@dereekb/util';
 /**
- * Used as a flag to disable uploads for a user.
+ * Claim value type used to restrict file uploads for a user.
+ *
+ * When set to true in the user's custom claims, the `uploads` role is revoked
+ * (inverse claim pattern).
  */
 export type StorageFileUploadUserRestriction = typeof AUTH_ROLE_CLAIMS_DEFAULT_CLAIM_VALUE;
 /**
- * Claims value for disabling uploads for a user.
+ * Custom claims shape for controlling a user's file upload permission.
+ *
+ * Uses an inverse claim pattern: when `fr` is set to true, the `uploads` role
+ * is removed from the user, preventing file uploads. When absent or false,
+ * the user retains the `uploads` role by default.
  *
- * Can be used in conjuction with the Storage security roles to prevent users from uploading files.
+ * Used with Firebase Storage security rules to enforce upload restrictions.
  */
 export type StorageFileUploadUserClaims = {
     /**
@@ -21,6 +28,16 @@ export type StorageFileUploadUserClaims = {
  */
 export declare const STORAGE_FILE_UPLOAD_USER_ROLE = "uploads";
 /**
- * AuthRoleClaimsFactoryConfigEntrySimpleOptions configuration for adding the "uploads" role to the user when the disable uploads claim is not present.
+ * Pre-configured claims entry that grants the `uploads` role by default and revokes it
+ * when the `fr` claim is set (inverse pattern).
+ *
+ * Pass this to an `AuthRoleClaimsFactory` to integrate upload restrictions into your auth system.
+ *
+ * @example
+ * ```ts
+ * const claimsConfig = {
+ *   fr: storageFileUploadUserSimpleClaimsConfiguration
+ * };
+ * ```
  */
 export declare const storageFileUploadUserSimpleClaimsConfiguration: AuthRoleClaimsFactoryConfigEntrySimpleOptions<StorageFileUploadUserRestriction>;

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

@@ -2,9 +2,12 @@ import { type FactoryWithRequiredInput, type Maybe, type SlashPath } from '@dere
 import { type StoragePath } from '../../common/storage/storage';
 import { type FirebaseAuthUserId } from '../../common';
 /**
- * The base path for all uploaded files.
+ * Root path for all uploaded files in Firebase Storage.
  *
- * The uploads folder is a transient folder that is cleared/processed often of files that are uploaded to it.
+ * Files uploaded here are transient and are processed/cleared by the upload initialization
+ * service. The folder structure is: `uploads/u/{userId}/{fileName}`.
+ *
+ * See {@link userUploadsFolderSlashPathFactory} for building user-specific upload paths.
  */
 export declare const UPLOADS_FOLDER_PATH = "uploads";
 /**
@@ -18,15 +21,43 @@ export declare const ALL_USER_UPLOADS_FOLDER_NAME = "u";
  */
 export declare const ALL_USER_UPLOADS_FOLDER_PATH = "uploads/u";
 /**
- * Creates a SlashPath for the input user's uploads folder.
+ * Factory that generates the uploads folder SlashPath for a given user ID.
  */
 export type UserUploadsFolderSlashPathFactory = FactoryWithRequiredInput<SlashPath, FirebaseAuthUserId>;
+/**
+ * Creates a {@link UserUploadsFolderSlashPathFactory} that generates per-user upload folder paths.
+ *
+ * @param inputBasePath - optional custom base path; defaults to {@link ALL_USER_UPLOADS_FOLDER_PATH}
+ *
+ * @example
+ * ```ts
+ * const factory = userUploadsFolderSlashPathFactory();
+ * const path = factory('user123');
+ * // path === '/uploads/u/user123'
+ * ```
+ */
 export declare function userUploadsFolderSlashPathFactory(inputBasePath?: Maybe<string>): UserUploadsFolderSlashPathFactory;
+/**
+ * Factory that generates a full {@link StoragePath} (with bucket) for a given user's uploads folder.
+ */
 export type UserUploadsFolderStoragePathFactory = FactoryWithRequiredInput<StoragePath, FirebaseAuthUserId>;
+/**
+ * Configuration for {@link userUploadsFolderStoragePathFactory}.
+ */
 export interface UserUploadsFolderStoragePathFactoryConfig {
     readonly bucketId: string;
     readonly basePath?: Maybe<string>;
 }
+/**
+ * Creates a {@link UserUploadsFolderStoragePathFactory} that includes the storage bucket ID.
+ *
+ * @example
+ * ```ts
+ * const factory = userUploadsFolderStoragePathFactory({ bucketId: 'my-bucket' });
+ * const storagePath = factory('user123');
+ * // storagePath === { pathString: '/uploads/u/user123', bucketId: 'my-bucket' }
+ * ```
+ */
 export declare function userUploadsFolderStoragePathFactory({ bucketId, basePath: inputBasePath }: UserUploadsFolderStoragePathFactoryConfig): UserUploadsFolderStoragePathFactory;
 /**
  * StorageFile uploaded-file type identifier.
@@ -41,12 +72,13 @@ export declare function userUploadsFolderStoragePathFactory({ bucketId, basePath
  */
 export type UploadedFileTypeIdentifier = string;
 /**
- * Result type of a StorageFileInitializeFromUploadService.handleNotificationTask() call.
+ * Result of a `StorageFileInitializeFromUploadService.handleNotificationTask()` call,
+ * indicating how the upload initialization concluded.
  *
- * success: The file was used/processed successfully.
- * no_determiner_match: Could not determine the proper processor for this file.
- * no_initializer_configured: There was no processor configured for this file.
- * initializer_error: There was an error thrown during processing.
- * permanent_initializer_failure: The initializer failed permanently and the file should be deleted.
+ * - `success` — file was used/processed successfully and a StorageFile was created
+ * - `no_determiner_match` — no {@link UploadedFileTypeDeterminer} could identify this file
+ * - `no_initializer_configured` — the file type was identified but no initializer is registered for it
+ * - `initializer_error` — the initializer threw an error during processing
+ * - `permanent_initializer_failure` — the initializer failed permanently; the file should be deleted
  */
 export type StorageFileInitializeFromUploadResultType = 'success' | 'no_determiner_match' | 'no_initializer_configured' | 'initializer_error' | 'permanent_initializer_failure';

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

@@ -3,7 +3,24 @@ import { type UploadedFileTypeIdentifier } from './storagefile.upload';
 import { type FirebaseAuthUserId, type StorageBucketId } from '../../common';
 import { type StoredFileReader } from './storagefile.file';
 /**
- * The level of confidence in the determined upload type.
+ * @module storagefile.upload.determiner
+ *
+ * Provides the upload type determination system for classifying uploaded files.
+ *
+ * Determiners inspect a file's path, name, metadata, or content to assign an
+ * {@link UploadedFileTypeIdentifier} with a confidence level. Multiple determiners
+ * can be combined via {@link combineUploadFileTypeDeterminers}, and user detection
+ * can be added via {@link determineUserByFolderWrapperFunction}.
+ *
+ * Built-in determiners:
+ * - {@link determineByFileName} — match by file name or prefix
+ * - {@link determineByFolderName} — match by parent folder name
+ * - {@link determineByFilePath} — match by full path pattern with optional bucket filtering
+ */
+/**
+ * Confidence level of a file type determination. Higher values indicate higher confidence.
+ *
+ * When multiple determiners match, the one with the highest level wins.
  *
  * Higher values indicate higher confidence.
  *
@@ -66,7 +83,11 @@ export interface UploadedFileTypeDeterminerResult {
  */
 export type UploadedFileTypeDeterminationFunction = (input: StoredFileReader) => PromiseOrValue<Maybe<UploadedFileTypeDeterminerResult>>;
 /**
- * Determines the upload type of a StorageFile.
+ * Strategy interface for determining the upload type of a file in Firebase Storage.
+ *
+ * Implement custom determiners for application-specific file type classification,
+ * or use the built-in factory functions ({@link determineByFileName}, {@link determineByFolderName},
+ * {@link determineByFilePath}).
  */
 export interface UploadedFileTypeDeterminer {
     /**
@@ -105,10 +126,21 @@ export interface DetermineByFileNameConfig {
     readonly nameMatchDeterminationLevel?: Maybe<UploadedFileTypeDeterminationLevel>;
 }
 /**
- * Creates an UploadedFileTypeDeterminer that determines the upload type based on the file name.
+ * Creates a determiner that classifies files by their file name.
+ *
+ * If the match string includes a file extension (e.g., `avatar.png`), only exact matches succeed
+ * at {@link EXACT_UPLOADED_FILE_TYPE_DETERMINATION_LEVEL}. Otherwise, prefix matching is used
+ * (e.g., `image` matches `image.png`, `image-test.jpg`) at {@link HIGH_UPLOADED_FILE_TYPE_DETERMINATION_LEVEL}.
+ *
+ * @param config - file type, match string, and optional determination levels
  *
- * @param config The configuration for the determiner.
- * @returns The determiner.
+ * @example
+ * ```ts
+ * const avatarDeterminer = determineByFileName({
+ *   fileType: 'avatar',
+ *   match: 'avatar.png'
+ * });
+ * ```
  */
 export declare function determineByFileName(config: DetermineByFileNameConfig): UploadedFileTypeDeterminer;
 export interface DetermineByFolderNameConfig {
@@ -122,10 +154,20 @@ export interface DetermineByFolderNameConfig {
     readonly match: SlashPathPart;
 }
 /**
- * Creates an UploadedFileTypeDeterminer that determines the upload type based on the folder name.
+ * Creates a determiner that classifies files by their parent folder name.
+ *
+ * Matches at {@link EXACT_UPLOADED_FILE_TYPE_DETERMINATION_LEVEL} when the folder path
+ * exactly equals the configured match string.
+ *
+ * @param config - file type and folder name to match
  *
- * @param config The configuration for the determiner.
- * @returns The determiner.
+ * @example
+ * ```ts
+ * const photoDeterminer = determineByFolderName({
+ *   fileType: 'photo',
+ *   match: 'photos'
+ * });
+ * ```
  */
 export declare function determineByFolderName(config: DetermineByFolderNameConfig): UploadedFileTypeDeterminer;
 export interface DetermineByFilePathConfig {
@@ -153,10 +195,22 @@ export interface DetermineByFilePathConfig {
     readonly matchDeterminationLevel?: Maybe<UploadedFileTypeDeterminationLevel>;
 }
 /**
- * Creates an UploadedFileTypeDeterminer that determines the upload type based on the file name.
+ * Creates a determiner that classifies files by their full storage path, with optional
+ * bucket filtering and additional file details matching.
  *
- * @param config The configuration for the determiner.
- * @returns The determiner.
+ * Uses {@link slashPathPathMatcher} for path pattern matching. Most flexible of the
+ * built-in determiners.
+ *
+ * @param config - file type, path match config, optional bucket/file filters
+ *
+ * @example
+ * ```ts
+ * const reportDeterminer = determineByFilePath({
+ *   fileType: 'report',
+ *   match: { targetPath: 'reports', matchType: 'startsWith' },
+ *   matchBucket: (bucket) => bucket === 'my-bucket'
+ * });
+ * ```
  */
 export declare function determineByFilePath(config: DetermineByFilePathConfig): UploadedFileTypeDeterminer;
 export interface DetermineUserByFolderWrapperFunctionConfig {
@@ -198,11 +252,33 @@ export interface DetermineUserByFolderWrapperFunctionConfig {
  */
 export type DetermineUserByFolderDeterminerWrapperFunction = (determiner: UploadedFileTypeDeterminer) => UploadedFileTypeDeterminer;
 /**
- * Wraps a separate UploadedFileTypeDeterminer and adds user determination based on folder path structure.
+ * Creates a wrapper function that adds user detection to any {@link UploadedFileTypeDeterminer}
+ * by inspecting the folder path structure.
  *
- * @param config Configuration.
+ * Extracts the user ID from a path like `{rootFolder}/{userFolderPrefix}/{userId}/{file}`.
+ * If `requireUser` is true, the determination fails when no user can be detected.
+ *
+ * @param config - root folder, user prefix, and matching options
+ *
+ * @example
+ * ```ts
+ * const addUser = determineUserByFolderWrapperFunction({
+ *   rootFolder: 'uploads',
+ *   userFolderPrefix: 'u'
+ * });
+ * const withUser = addUser(myDeterminer);
+ * ```
  */
 export declare function determineUserByFolderWrapperFunction(config: DetermineUserByFolderWrapperFunctionConfig): DetermineUserByFolderDeterminerWrapperFunction;
+/**
+ * Convenience wrapper pre-configured for the standard uploads folder structure (`uploads/u/{userId}/...`).
+ *
+ * @example
+ * ```ts
+ * const addUser = determineUserByUserUploadsFolderWrapperFunction();
+ * const withUser = addUser(myDeterminer);
+ * ```
+ */
 export declare function determineUserByUserUploadsFolderWrapperFunction(config?: Omit<DetermineUserByFolderWrapperFunctionConfig, 'rootFolder' | 'userFolderPrefix'>): DetermineUserByFolderDeterminerWrapperFunction;
 /**
  * Configuration for determineUserByFolder().
@@ -234,10 +310,17 @@ export interface LimitUploadFileTypeDeterminerConfig {
     readonly determiner: UploadedFileTypeDeterminer;
 }
 /**
- * Wraps an UploadedFileTypeDeterminer to only allow respond to certain file types.
+ * Wraps an {@link UploadedFileTypeDeterminer} to only return results for the specified file types.
+ *
+ * Useful for scoping a broad determiner to a subset of types in a specific context.
  *
- * @param determiner The determiner to wrap.
- * @param types The file types to allow.
+ * @param determiner - the determiner to filter
+ * @param types - allowed file type identifier(s)
+ *
+ * @example
+ * ```ts
+ * const limited = limitUploadFileTypeDeterminer(broadDeterminer, ['avatar', 'photo']);
+ * ```
  */
 export declare function limitUploadFileTypeDeterminer(determiner: UploadedFileTypeDeterminer, types: ArrayOrValue<UploadedFileTypeIdentifier>): UploadedFileTypeDeterminer;
 export interface CombineUploadFileTypeDeterminerConfig {
@@ -261,11 +344,20 @@ export interface CombineUploadFileTypeDeterminerConfig {
     readonly completeSearchAtLevel?: Maybe<UploadedFileTypeDeterminationLevel>;
 }
 /**
- * Combines multiple UploadedFileTypeDeterminer instances into a single determiner.
+ * Combines multiple {@link UploadedFileTypeDeterminer} instances into a single determiner
+ * that tries each in order and returns the highest-confidence match.
+ *
+ * If only one determiner is provided, it is returned unwrapped. The search can be
+ * short-circuited via `completeSearchOnFirstMatch` or `completeSearchAtLevel`.
  *
- * If a single determiner is provided, it will be returned and not wrapped.
+ * @param config - determiners to combine and optional early-exit settings
  *
- * @param determiners The determiners to combine.
- * @returns The combined determiner.
+ * @example
+ * ```ts
+ * const combined = combineUploadFileTypeDeterminers({
+ *   determiners: [avatarDeterminer, photoDeterminer, documentDeterminer],
+ *   completeSearchOnFirstMatch: true
+ * });
+ * ```
  */
 export declare function combineUploadFileTypeDeterminers(config: CombineUploadFileTypeDeterminerConfig): UploadedFileTypeDeterminer;

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

@@ -2,6 +2,12 @@ import { type Maybe } from '@dereekb/util';
 import { type FirestoreModelKey, type FirestoreDocumentAccessor } from '../../common';
 import { type StorageFileGroupDocument, type StorageFileGroup, type StorageFileGroupEmbeddedFile } from './storagefile';
 import { type StorageFileId } from './storagefile.id';
+/**
+ * Reference to a StorageFileGroup document, either directly or by the related model key.
+ *
+ * Used by utility functions that need to load or update a StorageFileGroup but accept
+ * either a pre-loaded document or a model key for lazy loading.
+ */
 export interface StorageFileGroupDocumentReferencePair {
     /**
      * StorageFileGroupDocument to update.
@@ -14,7 +20,27 @@ export interface StorageFileGroupDocumentReferencePair {
      */
     readonly storageFileGroupRelatedModelKey?: Maybe<FirestoreModelKey>;
 }
+/**
+ * Resolves a {@link StorageFileGroupDocumentReferencePair} to a concrete {@link StorageFileGroupDocument}.
+ *
+ * If a document is provided directly, it is returned as-is. Otherwise, the related model key
+ * is converted to a group ID via {@link storageFileGroupIdForModel} and loaded from the accessor.
+ *
+ * @throws {Error} When neither storageFileGroupDocument nor storageFileGroupRelatedModelKey is provided
+ *
+ * @example
+ * ```ts
+ * const doc = loadStorageFileGroupDocumentForReferencePair(
+ *   { storageFileGroupRelatedModelKey: 'notification/abc123' },
+ *   accessor
+ * );
+ * ```
+ */
 export declare function loadStorageFileGroupDocumentForReferencePair(input: StorageFileGroupDocumentReferencePair, accessor: FirestoreDocumentAccessor<StorageFileGroup, StorageFileGroupDocument>): StorageFileGroupDocument;
+/**
+ * Input for {@link calculateStorageFileGroupEmbeddedFileUpdate}, specifying the current group state
+ * and files to insert/remove.
+ */
 export interface CalculateStorageFileGroupEmbeddedFileUpdateInput {
     readonly storageFileGroup: Pick<StorageFileGroup, 'f' | 're' | 'z' | 'zat'>;
     readonly insert?: Maybe<(Pick<StorageFileGroupEmbeddedFile, 's'> & Partial<Omit<StorageFileGroupEmbeddedFile, 's'>>)[]>;
@@ -28,7 +54,32 @@ export interface CalculateStorageFileGroupEmbeddedFileUpdateInput {
      */
     readonly allowRecalculateRegenerateFlag?: Maybe<boolean>;
 }
+/**
+ * Calculates the updated embedded file list and regeneration flag for a StorageFileGroup
+ * after inserting and/or removing files.
+ *
+ * Handles deduplication via {@link ModelRelationUtility.insertCollection}, merging new entries
+ * with existing ones by StorageFile ID. Automatically flags regeneration when files are removed
+ * or when new files haven't been added to the zip yet.
+ *
+ * @param input - current group state, files to insert/remove, and regeneration options
+ * @returns updated `f` (embedded files) and `re` (regeneration flag)
+ *
+ * @example
+ * ```ts
+ * const update = calculateStorageFileGroupEmbeddedFileUpdate({
+ *   storageFileGroup: group,
+ *   insert: [{ s: 'newFileId' }],
+ *   remove: ['oldFileId']
+ * });
+ * // update.f = [...updated file list]
+ * // update.re = true (because a file was removed)
+ * ```
+ */
 export declare function calculateStorageFileGroupEmbeddedFileUpdate(input: CalculateStorageFileGroupEmbeddedFileUpdateInput): Pick<StorageFileGroup, 'f' | 're'>;
+/**
+ * Input for {@link calculateStorageFileGroupRegeneration}.
+ */
 export interface CalculateStorageFileGroupRegenerationInput {
     readonly storageFileGroup: Pick<StorageFileGroup, 'f' | 'z' | 'zat'>;
     /**
@@ -47,9 +98,21 @@ export interface CalculateStorageFileGroupRegenerationResult {
     readonly flagRegenerate: boolean;
 }
 /**
- * Calculates the regeneration flags for a StorageFileGroup.
+ * Determines whether a StorageFileGroup's derived content (e.g., zip files) needs regeneration.
+ *
+ * The zip needs regeneration when:
+ * - `force` is true
+ * - The zip has never been generated (`zat` is unset) and files exist
+ * - Any embedded file has never been included in the zip (`zat` is unset on the entry)
+ *
+ * @param input - group state and optional force flag
  *
- * @param input CalculateStorageFileGroupRegenerationInput
- * @returns CalculateStorageFileGroupRegenerationResult
+ * @example
+ * ```ts
+ * const { flagRegenerate, regenerateZip } = calculateStorageFileGroupRegeneration({
+ *   storageFileGroup: group,
+ *   force: false
+ * });
+ * ```
  */
 export declare function calculateStorageFileGroupRegeneration(input: CalculateStorageFileGroupRegenerationInput): CalculateStorageFileGroupRegenerationResult;

package/src/lib/model/system/system.action.d.ts

@@ -1,8 +1,33 @@
 import { type AsyncFirebaseFunctionCreateAction, type AsyncFirebaseFunctionDeleteAction, type AsyncFirebaseFunctionUpdateAction, type FirebaseFunctionCreateAction, type FirebaseFunctionDeleteAction, type FirebaseFunctionUpdateAction } from '@dereekb/firebase';
 import { type SystemStateDocument } from './system';
+/**
+ * @module system.action
+ *
+ * Type aliases for SystemState server action functions.
+ *
+ * @template P - the API parameter type for the action
+ */
+/**
+ * Synchronous create action targeting a {@link SystemStateDocument}.
+ */
 export type SystemStateCreateAction<P extends object> = FirebaseFunctionCreateAction<P, SystemStateDocument>;
+/**
+ * Async create action targeting a {@link SystemStateDocument}.
+ */
 export type AsyncSystemStateCreateAction<P extends object> = AsyncFirebaseFunctionCreateAction<P, SystemStateDocument>;
+/**
+ * Synchronous update action targeting a {@link SystemStateDocument}.
+ */
 export type SystemStateUpdateAction<P extends object> = FirebaseFunctionUpdateAction<P, SystemStateDocument>;
+/**
+ * Async update action targeting a {@link SystemStateDocument}.
+ */
 export type AsyncSystemStateUpdateAction<P extends object> = AsyncFirebaseFunctionUpdateAction<P, SystemStateDocument>;
+/**
+ * Synchronous delete action targeting a {@link SystemStateDocument}.
+ */
 export type SystemStateDeleteAction<P extends object> = FirebaseFunctionDeleteAction<P, SystemStateDocument>;
+/**
+ * Async delete action targeting a {@link SystemStateDocument}.
+ */
 export type AsyncSystemStateDeleteAction<P extends object> = AsyncFirebaseFunctionDeleteAction<P, SystemStateDocument>;