@dereekb/firebase 13.4.1 → 13.4.2

package/src/lib/model/notification/notification.send.d.ts

@@ -35,6 +35,10 @@ export interface NotificationSendMessagesResult<K> {
  *
  * Used when combining results from multiple send batches within the same channel.
  *
+ * @param a - first result to merge
+ * @param b - second result to merge
+ * @returns a new result with all recipient lists concatenated from both inputs
+ *
  * @example
  * ```ts
  * const combined = mergeNotificationSendMessagesResult(firstBatchResult, secondBatchResult);

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

@@ -78,6 +78,8 @@ export interface NotificationTask<D extends NotificationItemMetadata = {}> {
  * Use this when the handler needs more time but doesn't want to increment the failure counter.
  * The task will be re-queued without counting as an error attempt.
  *
+ * @returns an empty checkpoint array signaling in-progress without failure
+ *
  * @example
  * ```ts
  * // Waiting for an external process — delay without failing
@@ -92,6 +94,7 @@ export declare function delayCompletion<S extends NotificationTaskCheckpointStri
  *
  * @param delayUntil - absolute date or relative milliseconds from the task's run start time
  * @param updateMetadata - optional metadata updates to merge into the notification item
+ * @returns a task result that re-queues the task after the specified delay without marking it failed
  *
  * @example
  * ```ts
@@ -108,6 +111,7 @@ export declare function notificationTaskDelayRetry<D extends NotificationItemMet
  *
  * @param completedParts - checkpoint string(s) that were just completed
  * @param updateMetadata - optional metadata updates to merge into the notification item
+ * @returns a task result marking the given checkpoints complete while keeping the task running
  *
  * @example
  * ```ts
@@ -120,6 +124,7 @@ export declare function notificationTaskPartiallyComplete<D extends Notification
  * Returns a result indicating the task completed successfully. The notification document will be deleted.
  *
  * @param updateMetadata - optional final metadata update (applied before deletion if subtasks need it)
+ * @returns a task result signaling successful completion; the notification document will be deleted
  *
  * @example
  * ```ts
@@ -135,6 +140,7 @@ export declare function notificationTaskComplete<D extends NotificationItemMetad
  *
  * @param updateMetadata - optional metadata updates
  * @param removeFromCompletedCheckpoints - checkpoint(s) to remove from the completed set (e.g., to retry a checkpoint)
+ * @returns a task result signaling failure; the error attempt counter is incremented
  *
  * @example
  * ```ts
@@ -151,6 +157,7 @@ export declare function notificationTaskFailed<D extends NotificationItemMetadat
  *
  * @param result - the task result to wrap
  * @param force - when true, overrides any existing `canRunNextCheckpoint` value
+ * @returns a copy of the result with `canRunNextCheckpoint` set to true
  */
 export declare function notificationTaskCanRunNextCheckpoint<D extends NotificationItemMetadata = {}, S extends NotificationTaskCheckpointString = NotificationTaskCheckpointString>(result: NotificationTaskServiceHandleNotificationTaskResult<D, S>, force?: Maybe<boolean>): NotificationTaskServiceHandleNotificationTaskResult<D, S>;
 /**

package/src/lib/model/notification/notification.task.subtask.d.ts

@@ -71,6 +71,8 @@ export type NotificationTaskSubtaskCheckpoint = typeof NOTIFICATION_TASK_SUBTASK
  * Internal helper that marks the `'processing'` checkpoint complete and schedules the `'cleanup'` phase.
  *
  * Prefer using {@link notificationSubtaskComplete} in subtask handlers instead of calling this directly.
+ *
+ * @returns a partially-complete task result with the processing checkpoint marked done
  */
 export declare function completeSubtaskProcessingAndScheduleCleanupTaskResult<D extends NotificationTaskSubtaskData>(): NotificationTaskServiceHandleNotificationTaskResult<D, NotificationTaskSubtaskCheckpoint>;
 /**
@@ -79,6 +81,9 @@ export declare function completeSubtaskProcessingAndScheduleCleanupTaskResult<D
  * Unlike {@link notificationTaskComplete}, this signals that the cleanup checkpoint should still run.
  * Use `canRunNextCheckpoint: true` in options to run cleanup immediately in the same execution.
  *
+ * @param options - optional metadata updates and flag to run cleanup immediately in the same execution
+ * @returns a task result marking the subtask as complete while allowing cleanup to proceed
+ *
  * @example
  * ```ts
  * // Processing done, schedule cleanup for next run

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

@@ -28,6 +28,9 @@ export interface EffectiveNotificationBoxRecipientConfigInput {
  *
  * Filters template configs to only include types applicable to the notification box's model.
  * Used during the server-side sync process to update box recipient entries from user configs.
+ *
+ * @param input - the merged config inputs including uid, global config, box config, and optional existing recipient
+ * @returns the computed effective box recipient with merged config, contact info, and flags
  */
 export declare function effectiveNotificationBoxRecipientConfig(input: EffectiveNotificationBoxRecipientConfigInput): NotificationBoxRecipient;
 /**
@@ -47,6 +50,9 @@ export interface UpdateNotificationUserNotificationSendExclusionsResult {
  * and propagates exclusion flags to the per-box configs.
  *
  * Exclusions not matching any associated notification box are automatically filtered out.
+ *
+ * @param input - the user, exclusions to add, and exclusions to remove
+ * @returns the updated exclusion list and the partial user update to apply
  */
 export declare function updateNotificationUserNotificationSendExclusions(input: UpdateNotificationUserNotificationSendExclusionsInput): UpdateNotificationUserNotificationSendExclusionsResult;
 /**
@@ -62,10 +68,16 @@ export type ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsResu
 /**
  * Applies the current exclusion list to per-box configs, setting/clearing the `x` flag and marking
  * changed configs as needing sync (`ns = true`).
+ *
+ * @param params - the exclusion list, per-box configs, and optional flag to recalculate the global ns flag
+ * @returns the updated per-box configs and the recalculated needs-sync flag
  */
 export declare function applyExclusionsToNotificationUserNotificationBoxRecipientConfigs(params: ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsParams): ApplyExclusionsToNotificationUserNotificationBoxRecipientConfigsResult;
 /**
  * Returns true if any of the per-box configs need syncing (`ns == true`).
+ *
+ * @param configs - array of per-box recipient configs to check
+ * @returns true if at least one config has its needs-sync flag set
  */
 export declare function calculateNsForNotificationUserNotificationBoxRecipientConfigs(configs: NotificationUserNotificationBoxRecipientConfig[]): boolean;
 /**
@@ -78,16 +90,25 @@ export type NotificationSendExclusionCanSendFunction = ((notification: Notificat
 /**
  * Creates a {@link NotificationSendExclusionCanSendFunction} from the given exclusion list.
  * Returns true for IDs that don't match any exclusion prefix.
+ *
+ * @param exclusions - the list of box IDs or prefixes that should be excluded from delivery
+ * @returns a predicate function that returns true if the given notification/box ID is not excluded
  */
 export declare const notificationSendExclusionCanSendFunction: (exclusions: NotificationBoxSendExclusionList) => NotificationSendExclusionCanSendFunction;
 /**
  * Returns true if all channels on the notification have reached a terminal state
  * (NONE, NO_TRY, SENT, or SKIPPED). Used to determine if the notification can be marked done.
+ *
+ * @param input - the per-channel send flags to evaluate
+ * @returns true if all channels are in a terminal send state
  */
 export declare function notificationSendFlagsImplyIsComplete(input: NotificationSendFlags): boolean;
 /**
  * Returns true if the given send state is terminal — no further send attempts will be made.
  * Terminal states: NONE, NO_TRY, SENT, SKIPPED.
+ *
+ * @param input - the send state to evaluate
+ * @returns true if the state is terminal and no further delivery will be attempted
  */
 export declare function isCompleteNotificationSendState(input: NotificationSendState): boolean;
 /**
@@ -100,6 +121,9 @@ export interface AllowedNotificationRecipients {
 }
 /**
  * Resolves which recipient groups (global, box, explicit) are allowed based on the {@link NotificationRecipientSendFlag}.
+ *
+ * @param flag - the recipient send flag controlling which groups are included
+ * @returns an object indicating which recipient groups are permitted for this notification
  */
 export declare function allowedNotificationRecipients(flag?: Maybe<NotificationRecipientSendFlag>): AllowedNotificationRecipients;
 /**
@@ -107,15 +131,26 @@ export declare function allowedNotificationRecipients(flag?: Maybe<NotificationR
  *
  * Only notifications that can be sent to box recipients are archived (notifications restricted
  * to only explicit or only global recipients are not saved to the weekly archive).
+ *
+ * @param notification - the notification to check
+ * @returns true if the notification should be saved to the weekly archive after delivery
  */
 export declare function shouldSaveNotificationToNotificationWeek(notification: Notification): boolean;
 /**
  * Merges a partial update into a {@link NotificationUserNotificationBoxRecipientConfig},
  * preserving user-controlled fields (`nb`, `rm`, `ns`, `lk`, `bk`) and respecting OPT_OUT state.
+ *
+ * @param a - base user box recipient config to merge into
+ * @param b - partial update to apply on top of the base
+ * @returns the merged config with protected fields retained from `a`
  */
 export declare function mergeNotificationUserNotificationBoxRecipientConfigs(a: NotificationUserNotificationBoxRecipientConfig, b: Partial<NotificationUserNotificationBoxRecipientConfig>): NotificationUserNotificationBoxRecipientConfig;
 /**
  * Merges a partial update into a {@link NotificationBoxRecipient}, deeply merging the `c` (config record) field.
+ *
+ * @param a - base recipient to merge into
+ * @param b - partial recipient update to apply on top of the base
+ * @returns the merged recipient with deeply merged template config records
  */
 export declare function mergeNotificationBoxRecipients<T extends NotificationBoxRecipient>(a: T, b: Partial<T>): T;
 /**
@@ -136,6 +171,9 @@ export interface NotificationBoxDocumentReferencePair {
 /**
  * Resolves a {@link NotificationBoxDocument} from a reference pair, loading by model key if no document is provided directly.
  *
+ * @param input - reference pair containing either a direct document or a model key to load from
+ * @param accessor - Firestore document accessor used to load the document by ID when needed
+ * @returns the resolved NotificationBoxDocument
  * @throws {Error} When neither a document nor a model key is provided.
  */
 export declare function loadNotificationBoxDocumentForReferencePair(input: NotificationBoxDocumentReferencePair, accessor: FirestoreDocumentAccessor<NotificationBox, NotificationBoxDocument>): NotificationBoxDocument;

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

@@ -106,9 +106,15 @@ export interface OidcEntryFirestoreCollectionConfig {
 }
 /**
  * Returns the Firestore {@link CollectionReference} for {@link OidcEntry} documents.
+ *
+ * @param context - the Firestore context to use
+ * @returns the CollectionReference for OidcEntry documents
  */
 export declare function oidcEntryCollectionReference(context: FirestoreContext): CollectionReference<OidcEntry>;
 /**
  * Creates an {@link OidcEntryFirestoreCollection} from the given configuration.
+ *
+ * @param config - the Firestore context and collection configuration
+ * @returns a configured OidcEntryFirestoreCollection
  */
 export declare function oidcEntryFirestoreCollection(config: OidcEntryFirestoreCollectionConfig): OidcEntryFirestoreCollection;

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

@@ -2,21 +2,39 @@ import { type FirebaseAuthOwnershipKey, type FirebaseAuthUserId, type FirestoreQ
 import { type OidcEntryType } from './oidcmodel';
 /**
  * Query for OidcEntry documents with a specific type.
+ *
+ * @param type - the OIDC entry type to filter by
+ * @returns Firestore query constraints for the given type
  */
 export declare function oidcEntriesWithTypeQuery(type: OidcEntryType): FirestoreQueryConstraint[];
 /**
  * Query for OidcEntry documents with a specific type and userCode.
+ *
+ * @param type - the OIDC entry type to filter by
+ * @param userCode - the user code to match
+ * @returns Firestore query constraints for the given type and userCode
  */
 export declare function oidcEntriesByUserCodeQuery(type: OidcEntryType, userCode: string): FirestoreQueryConstraint[];
 /**
  * Query for OidcEntry documents with a specific type and uid.
+ *
+ * @param type - the OIDC entry type to filter by
+ * @param uid - the Firebase user ID to match
+ * @returns Firestore query constraints for the given type and uid
  */
 export declare function oidcEntriesByUidQuery(type: OidcEntryType, uid: FirebaseAuthUserId): FirestoreQueryConstraint[];
 /**
  * Query for OidcEntry documents with a specific type and grantId.
+ *
+ * @param type - the OIDC entry type to filter by
+ * @param grantId - the grant ID to match
+ * @returns Firestore query constraints for the given type and grantId
  */
 export declare function oidcEntriesByGrantIdQuery(type: OidcEntryType, grantId: string): FirestoreQueryConstraint[];
 /**
  * Query for OidcEntry Client documents owned by a specific user.
+ *
+ * @param ownershipKey - the ownership key identifying the owner
+ * @returns Firestore query constraints for Client entries matching the ownership key
  */
 export declare function oidcClientEntriesByOwnerQuery(ownershipKey: FirebaseAuthOwnershipKey): FirestoreQueryConstraint[];

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

@@ -171,6 +171,7 @@ export type CreateStorageFileDocumentPairFactory = <M extends StorageFileMetadat
  * initial state setup.
  *
  * @param config - optional defaults for creation type, subgroup, and processing state
+ * @returns a factory function that creates StorageFile document pairs
  * @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
@@ -193,5 +194,8 @@ export declare function createStorageFileDocumentPairFactory(config?: CreateStor
  * Convenience function for creating a StorageFileDocumentPair.
  *
  * Calls createStorageFileDocumentPairFactory() with no arguments, then passes the input to the factory and returns the result.
+ *
+ * @param input - the creation input specifying the storage path, purpose, and context
+ * @returns a promise resolving to the created StorageFileDocument and StorageFile data
  */
 export declare function createStorageFileDocumentPair<M extends StorageFileMetadata = StorageFileMetadata>(input: CreateStorageFileDocumentPairInput<M>): Promise<CreateStorageFileDocumentPairResult<M>>;

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

@@ -61,6 +61,10 @@ export declare const storageFileIdentity: import("../..").RootFirestoreModelIden
 export type StorageFileGroupCreatedStorageFileKey<P extends StorageFileGroupRelatedStorageFilePurpose> = FirestoreCollectionModelKey<typeof storageFileIdentity, `${P}_${OneWayFlatFirestoreModelKey}`>;
 /**
  * Creates a StorageFileGroupCreatedStorageFileKey from the input StorageFileGroupId and purpose.
+ *
+ * @param purpose - the purpose identifying the type of file within the group
+ * @param storageFileGroupId - the ID of the parent StorageFileGroup
+ * @returns a deterministic FirestoreCollectionModelKey for the storage file
  */
 export declare function storageFileGroupCreatedStorageFileKey<P extends StorageFileGroupRelatedStorageFilePurpose>(purpose: P, storageFileGroupId: StorageFileGroupId): StorageFileGroupCreatedStorageFileKey<P>;
 /**
@@ -379,6 +383,9 @@ export declare const storageFileConverter: import("../..").SnapshotConverterFunc
  * ```ts
  * const colRef = storageFileCollectionReference(firestoreContext);
  * ```
+ *
+ * @param context - the Firestore context to use
+ * @returns the CollectionReference for StorageFile documents
  */
 export declare function storageFileCollectionReference(context: FirestoreContext): CollectionReference<StorageFile>;
 /**
@@ -393,6 +400,9 @@ export type StorageFileFirestoreCollection = FirestoreCollection<StorageFile, St
  * const collection = storageFileFirestoreCollection(firestoreContext);
  * const doc = collection.documentAccessor().newDocument();
  * ```
+ *
+ * @param firestoreContext - the Firestore context to use
+ * @returns a configured StorageFileFirestoreCollection
  */
 export declare function storageFileFirestoreCollection(firestoreContext: FirestoreContext): StorageFileFirestoreCollection;
 /**
@@ -505,6 +515,9 @@ export declare const storageFileGroupConverter: import("../..").SnapshotConverte
  * ```ts
  * const colRef = storageFileGroupCollectionReference(firestoreContext);
  * ```
+ *
+ * @param context - the Firestore context to use
+ * @returns the CollectionReference for StorageFileGroup documents
  */
 export declare function storageFileGroupCollectionReference(context: FirestoreContext): CollectionReference<StorageFileGroup>;
 /**
@@ -519,5 +532,8 @@ export type StorageFileGroupFirestoreCollection = FirestoreCollection<StorageFil
  * const collection = storageFileGroupFirestoreCollection(firestoreContext);
  * const doc = collection.documentAccessor().loadDocumentForId(groupId);
  * ```
+ *
+ * @param firestoreContext - the Firestore context to use
+ * @returns a configured StorageFileGroupFirestoreCollection
  */
 export declare function storageFileGroupFirestoreCollection(firestoreContext: FirestoreContext): StorageFileGroupFirestoreCollection;

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

@@ -60,6 +60,8 @@ export interface StoredFileReader {
  *
  * Should only be used server-side, as `copy` may not be available on the client.
  *
+ * @returns a factory function that wraps FirebaseStorageAccessorFile instances into StoredFileReader accessors
+ *
  * @example
  * ```ts
  * const factory = storedFileReaderFactory();

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

@@ -11,6 +11,7 @@ export declare const STORAGE_FILE_GROUP_ROOT_FOLDER_PATH: SlashPathFolder;
  *
  * @param storageFileGroupId - the group's document ID
  * @param subPath - optional sub-paths to append
+ * @returns the folder path as a SlashPathFolder string
  *
  * @example
  * ```ts
@@ -29,6 +30,9 @@ export declare const STORAGE_FILE_GROUP_ZIP_FILE_PATH: SlashPathFile;
 /**
  * Returns the full storage path for a StorageFileGroup's zip file.
  *
+ * @param storageFileGroupId - the group's document ID
+ * @returns the full SlashPath to the group's zip archive
+ *
  * @example
  * ```ts
  * const zipPath = storageFileGroupZipFileStoragePath('abc123');

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

@@ -34,6 +34,7 @@ export type GrantStorageFileRolesForUserAuthFunction = (input: GrantStorageFileR
  * Use this within a permission service to define role-based access for StorageFile operations.
  *
  * @param config - the permission output, auth context, and target document
+ * @returns a function that accepts role configuration and returns a GrantRolesOtherwiseFunction
  *
  * @example
  * ```ts

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

@@ -12,6 +12,8 @@ import { type FirebaseAuthUserId } from '../../common/auth/auth';
  * const constraints = storageFilesQueuedForProcessingQuery();
  * const results = await collection.query(constraints);
  * ```
+ *
+ * @returns Firestore query constraints for StorageFiles queued for processing
  */
 export declare function storageFilesQueuedForProcessingQuery(): FirestoreQueryConstraint[];
 /**
@@ -20,6 +22,7 @@ export declare function storageFilesQueuedForProcessingQuery(): FirestoreQueryCo
  * Used by the cleanup service to find files ready for permanent deletion.
  *
  * @param now - reference time for comparison; defaults to current time
+ * @returns Firestore query constraints for StorageFiles whose scheduled delete date has passed
  *
  * @example
  * ```ts
@@ -43,6 +46,10 @@ export interface StorageFilePurposeAndUserQueryInput {
  * with optional subgroup filtering.
  *
  * @example
+ * @param input - the user, purpose, and optional subgroup to filter by
+ * @returns Firestore query constraints for the given purpose and user
+ *
+ * @example
  * ```ts
  * const constraints = storageFilePurposeAndUserQuery({
  *   user: 'user123',
@@ -57,6 +64,9 @@ export declare function storageFilePurposeAndUserQuery(input: StorageFilePurpose
  * Used by the sync service to find files whose group memberships need to be propagated.
  *
  * @example
+ * @returns Firestore query constraints for StorageFiles flagged for group synchronization
+ *
+ * @example
  * ```ts
  * const constraints = storageFileFlaggedForSyncWithGroupsQuery();
  * ```
@@ -68,6 +78,9 @@ export declare function storageFileFlaggedForSyncWithGroupsQuery(): FirestoreQue
  * Used by the initialization service to find newly-created groups that haven't been synced yet.
  *
  * @example
+ * @returns Firestore query constraints for StorageFileGroups needing initialization
+ *
+ * @example
  * ```ts
  * const constraints = storageFileGroupsFlaggedForNeedsInitializationQuery();
  * ```
@@ -77,6 +90,9 @@ export declare function storageFileGroupsFlaggedForNeedsInitializationQuery(): F
  * Returns query constraints for StorageFileGroups flagged for content regeneration (`re == true`).
  *
  * @example
+ * @returns Firestore query constraints for StorageFileGroups flagged for content regeneration
+ *
+ * @example
  * ```ts
  * const constraints = storageFileGroupsFlaggedForContentRegenerationQuery();
  * ```
@@ -88,6 +104,9 @@ export declare function storageFileGroupsFlaggedForContentRegenerationQuery(): F
  * Invalid groups are typically cleaned up (deleted along with their associated files).
  *
  * @example
+ * @returns Firestore query constraints for StorageFileGroups flagged as invalid
+ *
+ * @example
  * ```ts
  * const constraints = storageFileGroupsFlaggedInvalidQuery();
  * ```

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

@@ -69,6 +69,7 @@ export interface StorageFileProcessingNotificationTaskInput<M extends StorageFil
  * The created task is unique per StorageFile (only one processing task at a time).
  *
  * @param input - the target StorageFileDocument and optional subtask data
+ * @returns a CreateNotificationTaskTemplate for the StorageFile processing task
  *
  * @example
  * ```ts

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

@@ -28,6 +28,7 @@ export type UserUploadsFolderSlashPathFactory = FactoryWithRequiredInput<SlashPa
  * 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}
+ * @returns a factory function that generates per-user upload folder slash paths
  *
  * @example
  * ```ts
@@ -51,6 +52,11 @@ export interface UserUploadsFolderStoragePathFactoryConfig {
 /**
  * Creates a {@link UserUploadsFolderStoragePathFactory} that includes the storage bucket ID.
  *
+ * @param root0 - the configuration object
+ * @param root0.bucketId - the storage bucket ID to include in each generated path
+ * @param root0.basePath - optional custom base path; defaults to {@link ALL_USER_UPLOADS_FOLDER_PATH}
+ * @returns a factory function that generates per-user StoragePath values including the bucket ID
+ *
  * @example
  * ```ts
  * const factory = userUploadsFolderStoragePathFactory({ bucketId: 'my-bucket' });

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

@@ -133,6 +133,7 @@ export interface DetermineByFileNameConfig {
  * (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
+ * @returns an UploadedFileTypeDeterminer that classifies by file name
  *
  * @example
  * ```ts
@@ -160,6 +161,7 @@ export interface DetermineByFolderNameConfig {
  * exactly equals the configured match string.
  *
  * @param config - file type and folder name to match
+ * @returns an UploadedFileTypeDeterminer that classifies by folder name
  *
  * @example
  * ```ts
@@ -202,6 +204,7 @@ export interface DetermineByFilePathConfig {
  * built-in determiners.
  *
  * @param config - file type, path match config, optional bucket/file filters
+ * @returns an UploadedFileTypeDeterminer that classifies by storage path
  *
  * @example
  * ```ts
@@ -259,6 +262,7 @@ export type DetermineUserByFolderDeterminerWrapperFunction = (determiner: Upload
  * If `requireUser` is true, the determination fails when no user can be detected.
  *
  * @param config - root folder, user prefix, and matching options
+ * @returns a wrapper function that adds user detection to any UploadedFileTypeDeterminer
  *
  * @example
  * ```ts
@@ -273,6 +277,9 @@ export declare function determineUserByFolderWrapperFunction(config: DetermineUs
 /**
  * Convenience wrapper pre-configured for the standard uploads folder structure (`uploads/u/{userId}/...`).
  *
+ * @param config - optional matching options (rootFolder and userFolderPrefix are pre-configured)
+ * @returns a wrapper function that adds user detection for the standard uploads folder structure
+ *
  * @example
  * ```ts
  * const addUser = determineUserByUserUploadsFolderWrapperFunction();
@@ -316,6 +323,7 @@ export interface LimitUploadFileTypeDeterminerConfig {
  *
  * @param determiner - the determiner to filter
  * @param types - allowed file type identifier(s)
+ * @returns an UploadedFileTypeDeterminer that only returns results for the specified file types
  *
  * @example
  * ```ts
@@ -351,6 +359,7 @@ export interface CombineUploadFileTypeDeterminerConfig {
  * short-circuited via `completeSearchOnFirstMatch` or `completeSearchAtLevel`.
  *
  * @param config - determiners to combine and optional early-exit settings
+ * @returns a combined UploadedFileTypeDeterminer that returns the highest-confidence match
  *
  * @example
  * ```ts

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

@@ -26,6 +26,9 @@ export interface StorageFileGroupDocumentReferencePair {
  * 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.
  *
+ * @param input - reference pair containing either a document or a related model key
+ * @param accessor - document accessor used to load the group document by ID
+ * @returns the resolved StorageFileGroupDocument
  * @throws {Error} When neither storageFileGroupDocument nor storageFileGroupRelatedModelKey is provided
  *
  * @example
@@ -106,6 +109,7 @@ export interface CalculateStorageFileGroupRegenerationResult {
  * - Any embedded file has never been included in the zip (`zat` is unset on the entry)
  *
  * @param input - group state and optional force flag
+ * @returns the regeneration result indicating whether the zip or other derived files need to be regenerated
  *
  * @example
  * ```ts

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

@@ -85,6 +85,9 @@ export declare const systemStateConverter: import("../..").SnapshotConverterFunc
  * ```ts
  * const colRef = systemStateCollectionReference(firestoreContext);
  * ```
+ *
+ * @param context - the Firestore context to use
+ * @returns the CollectionReference for SystemState documents
  */
 export declare function systemStateCollectionReference(context: FirestoreContext): CollectionReference<SystemState>;
 export type SystemStateFirestoreCollection<T extends SystemStateStoredData = SystemStateStoredData> = FirestoreCollection<SystemState<T>, SystemStateDocument<T>>;
@@ -113,6 +116,7 @@ export type SystemStateStoredDataConverterMap = {
  *
  * @param firestoreContext - the Firestore context
  * @param converters - map of type identifiers to their data field converters
+ * @returns a configured SystemStateFirestoreCollection with per-type data converters
  *
  * @example
  * ```ts

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.4.1",
+  "version": "13.4.2",
   "peerDependencies": {
-    "@dereekb/date": "13.4.1",
-    "@dereekb/firebase": "13.4.1",
-    "@dereekb/model": "13.4.1",
-    "@dereekb/rxjs": "13.4.1",
-    "@dereekb/util": "13.4.1",
+    "@dereekb/date": "13.4.2",
+    "@dereekb/firebase": "13.4.2",
+    "@dereekb/model": "13.4.2",
+    "@dereekb/rxjs": "13.4.2",
+    "@dereekb/util": "13.4.2",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.0.0",
     "firebase": "^12.0.0",