@dereekb/firebase-server 13.4.1 → 13.4.2

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

@@ -66,6 +66,9 @@ export declare abstract class StorageFileServerActions {
  *
  * @param context - the fully assembled storage file server actions context
  *
+ * @param context - the fully assembled storage file server actions context
+ * @returns a concrete {@link StorageFileServerActions} with all action methods wired to their factories
+ *
  * @example
  * ```ts
  * const actions = storageFileServerActions(context);
@@ -78,14 +81,20 @@ export declare function storageFileServerActions(context: StorageFileServerActio
  * Factory for the `createStorageFile` action.
  *
  * Creates a new {@link StorageFile} document using the provided template data.
+ *
+ * @param context - the base server actions context providing Firestore and storage access
+ * @returns an async transform-and-validate function that creates a StorageFile document
  */
-export declare function createStorageFileFactory(context: BaseStorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateStorageFileParams, () => Promise<any>, object, unknown>;
+export declare function createStorageFileFactory(context: BaseStorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateStorageFileParams, () => Promise<StorageFileDocument>, object, unknown>;
 /**
  * Factory for the `initializeAllStorageFilesFromUploads` action.
  *
  * Scans the uploads folder in Firebase Storage, identifies new uploaded files,
  * initializes each one via the upload service, and cleans up the source upload
  * on success. Failed initializations are logged but do not halt the batch.
+ *
+ * @param context - the storage file server actions context with storage service and upload initialization
+ * @returns an async transform-and-validate function that returns batch initialization results
  */
 export declare function initializeAllStorageFilesFromUploadsFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeAllStorageFilesFromUploadsParams, () => Promise<InitializeAllStorageFilesFromUploadsResult>, object, unknown>;
 export interface InitializeStorageFileFromUploadFileInput {
@@ -97,6 +106,15 @@ export interface InitializeStorageFileFromUploadFileInput {
      */
     readonly expediteProcessing?: Maybe<boolean>;
 }
+/**
+ * Internal factory that creates a function to initialize a {@link StorageFile} from an uploaded file.
+ *
+ * Validates the file exists and is allowed, runs the upload initializer, deletes the upload source
+ * on success, and optionally expedites processing of the created storage file.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that accepts an upload file input and returns the created StorageFileDocument
+ */
 export declare function _initializeStorageFileFromUploadFileFactory(context: StorageFileServerActionsContext): (input: InitializeStorageFileFromUploadFileInput) => Promise<StorageFileDocument>;
 /**
  * Factory for the `initializeStorageFileFromUpload` action.
@@ -104,9 +122,29 @@ export declare function _initializeStorageFileFromUploadFileFactory(context: Sto
  * Initializes a single {@link StorageFile} from an uploaded file at the given storage path.
  * Validates the file exists and is allowed, runs the type determiner and initializer,
  * then cleans up the upload source on success.
+ *
+ * @param context - the storage file server actions context with storage and upload services
+ * @returns an async transform-and-validate function that creates a StorageFile from an upload
  */
 export declare function initializeStorageFileFromUploadFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeStorageFileFromUploadParams, () => Promise<StorageFileDocument>, object, unknown>;
+/**
+ * Factory for the `updateStorageFile` action.
+ *
+ * Updates an existing {@link StorageFile} document with the provided schedule-delete-at time.
+ *
+ * @param context - the base server actions context providing Firestore access
+ * @returns an async transform-and-validate function that updates a StorageFile document
+ */
 export declare function updateStorageFileFactory(context: BaseStorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateStorageFileParams, (storageFileDocument: StorageFileDocument) => Promise<StorageFileDocument>, object, unknown>;
+/**
+ * Factory for the `updateStorageFileGroup` action.
+ *
+ * Updates embedded file entries within a {@link StorageFileGroup} document inside a
+ * Firestore transaction, merging display name changes into the existing entries.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that updates a StorageFileGroup document
+ */
 export declare function updateStorageFileGroupFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<UpdateStorageFileGroupParams, (storageFileGroupDocument: StorageFileGroupDocument) => Promise<StorageFileGroupDocument>, object, unknown>;
 /**
  * Factory for the `processAllQueuedStorageFiles` action.
@@ -114,6 +152,9 @@ export declare function updateStorageFileGroupFactory(context: StorageFileServer
  * Batch-processes all {@link StorageFile} documents queued for processing. Creates a
  * processing notification task for each file and optionally expedites delivery.
  * Handles stuck-processing detection with a throttle check.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch processing results
  */
 export declare function processAllQueuedStorageFilesFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ProcessAllQueuedStorageFilesParams, () => Promise<ProcessAllQueuedStorageFilesResult>, object, unknown>;
 export interface ProcessStorageFileInTransactionInput {
@@ -134,12 +175,24 @@ export interface ProcessStorageFileInTransactionInput {
      */
     readonly expediteInstance?: Maybe<NotificationExpediteServiceInstance>;
 }
+/**
+ * Internal factory that creates a function for processing a {@link StorageFile} within a Firestore transaction.
+ *
+ * Creates or restarts a notification task for the file based on its current processing state,
+ * handling stuck-processing detection, forced restarts, and re-processing of already-successful files.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that processes a storage file within a transaction
+ */
 export declare function _processStorageFileInTransactionFactory(context: StorageFileServerActionsContext): (input: ProcessStorageFileInTransactionInput, transaction: Transaction) => Promise<void>;
 /**
  * Factory for the `processStorageFile` action.
  *
  * Processes a single {@link StorageFile} by creating a notification task for it
  * and marking it as processing. Validates the file is in a valid state for processing.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that processes a single StorageFile
  */
 export declare function processStorageFileFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<ProcessStorageFileParams, (storageFileDocument: StorageFileDocument) => Promise<ProcessStorageFileResult>, object, unknown>;
 /**
@@ -148,6 +201,9 @@ export declare function processStorageFileFactory(context: StorageFileServerActi
  * Batch-deletes all {@link StorageFile} documents flagged for deletion whose
  * scheduled delete time has passed. Removes both the Firestore document and
  * the associated file in Cloud Storage.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch deletion results
  */
 export declare function deleteAllQueuedStorageFilesFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<DeleteAllQueuedStorageFilesParams, () => Promise<DeleteAllQueuedStorageFilesResult>, object, unknown>;
 /**
@@ -155,6 +211,9 @@ export declare function deleteAllQueuedStorageFilesFactory(context: StorageFileS
  *
  * Deletes a single {@link StorageFile} document and its associated Cloud Storage file.
  * Validates the file is flagged for deletion and the scheduled delete time has passed.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that deletes a StorageFile and its storage object
  */
 export declare function deleteStorageFileFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<DeleteStorageFileParams, (inputStorageFileDocument: StorageFileDocument) => Promise<void>, object, unknown>;
 /**
@@ -163,6 +222,9 @@ export declare function deleteStorageFileFactory(context: StorageFileServerActio
  * Generates a signed download URL for a {@link StorageFile}'s associated Cloud Storage file.
  * The URL expires after the configured duration. Supports loading the storage file document
  * by key if not provided directly.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that generates a signed download URL
  */
 export declare function downloadStorageFileFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<DownloadStorageFileParams, (storageFileDocument?: Maybe<StorageFileDocument>) => Promise<DownloadStorageFileResult>, object, unknown>;
 /**
@@ -184,6 +246,16 @@ export interface CreateStorageFileGroupInTransactionInput extends StorageFileGro
      */
     readonly template?: Maybe<Pick<StorageFileGroup, 'f' | 're'>>;
 }
+/**
+ * Internal factory that creates a function for creating a {@link StorageFileGroup} document
+ * within a Firestore transaction.
+ *
+ * The created group is flagged for initialization (`s=true`) and uses a dummy owner key
+ * that will be set during the initialization step.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that creates a StorageFileGroup within a transaction
+ */
 export declare function createStorageFileGroupInTransactionFactory(context: StorageFileServerActionsContext): (params: CreateStorageFileGroupInTransactionInput, transaction: Transaction) => Promise<{
     storageFileGroupTemplate: StorageFileGroup;
     storageFileGroupDocument: StorageFileGroupDocument;
@@ -193,6 +265,9 @@ export declare function createStorageFileGroupInTransactionFactory(context: Stor
  *
  * Creates a new {@link StorageFileGroup} document within a Firestore transaction,
  * associating it with a model key or storage file.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that creates a new StorageFileGroup
  */
 export declare function createStorageFileGroupFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<CreateStorageFileGroupParams, () => Promise<StorageFileGroupDocument>, object, unknown>;
 export interface SyncStorageFileWithGroupsInTransactionInput {
@@ -216,12 +291,25 @@ export interface SyncStorageFileWithGroupsInTransactionInput {
      */
     readonly skipStorageFileUpdate?: Maybe<boolean>;
 }
+/**
+ * Internal factory that creates a function for syncing a {@link StorageFile} with its
+ * associated {@link StorageFileGroup} documents within a Firestore transaction.
+ *
+ * Adds the storage file to groups it is missing from, removes it from groups when requested,
+ * and optionally creates new groups for references that do not yet exist.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async function that syncs a storage file with its groups within a transaction
+ */
 export declare function _syncStorageFileWithGroupsInTransactionFactory(context: StorageFileServerActionsContext): (input: SyncStorageFileWithGroupsInTransactionInput, transaction: Transaction) => Promise<SyncStorageFileWithGroupsResult>;
 /**
  * Factory for the `syncStorageFileWithGroups` action.
  *
  * Syncs a single {@link StorageFile}'s embedded data into its associated {@link StorageFileGroup}
  * documents and clears the sync flag on completion.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that syncs a StorageFile with its groups
  */
 export declare function syncStorageFileWithGroupsFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<SyncStorageFileWithGroupsParams, (storageFileDocument: StorageFileDocument) => Promise<SyncStorageFileWithGroupsResult>, object, unknown>;
 /**
@@ -230,6 +318,9 @@ export declare function syncStorageFileWithGroupsFactory(context: StorageFileSer
  * Batch-processes all {@link StorageFile} documents flagged for group sync,
  * updating their associated {@link StorageFileGroup} documents and flagging
  * groups for content regeneration when changes occur.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch sync results
  */
 export declare function syncAllFlaggedStorageFilesWithGroupsFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<SyncAllFlaggedStorageFilesWithGroupsParams, () => Promise<SyncAllFlaggedStorageFilesWithGroupsResult>, object, unknown>;
 /**
@@ -237,6 +328,9 @@ export declare function syncAllFlaggedStorageFilesWithGroupsFactory(context: Sto
  *
  * Regenerates the content of a single {@link StorageFileGroup}, including building a ZIP
  * archive from the group's embedded files and updating the group's content metadata.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that regenerates a StorageFileGroup's content
  */
 export declare function regenerateStorageFileGroupContentFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<RegenerateStorageFileGroupContentParams, (storageFileGroupDocument: StorageFileGroupDocument) => Promise<RegenerateStorageFileGroupContentResult>, object, unknown>;
 /**
@@ -244,5 +338,8 @@ export declare function regenerateStorageFileGroupContentFactory(context: Storag
  *
  * Batch-processes all {@link StorageFileGroup} documents flagged for content regeneration,
  * rebuilding their ZIP archives and updating content metadata.
+ *
+ * @param context - the storage file server actions context
+ * @returns an async transform-and-validate function that returns batch regeneration results
  */
 export declare function regenerateAllFlaggedStorageFileGroupsContentFactory(context: StorageFileServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<RegenerateAllFlaggedStorageFileGroupsContentParams, () => Promise<RegenerateAllFlaggedStorageFileGroupsContentResult>, object, unknown>;

package/model/src/lib/storagefile/{storagefile.action.init.service.d.ts → storagefile.action.server.init.d.ts}

@@ -68,13 +68,14 @@ export declare abstract class StorageFileInitServerActions {
  * initialization action to its factory function.
  *
  * @param context - the initialization context with template function and Firestore access
+ * @returns a {@link StorageFileInitServerActions} wired to the provided context
  */
 export declare function storageFileInitServerActions(context: StorageFileInitServerActionsContext): StorageFileInitServerActions;
 /**
  * Input for {@link initializeStorageFileModelInTransaction}, providing the document,
  * its current data, the template function, and the transaction context.
  */
-export interface InitializeStorageFileModelInTransactionInput<D extends FirestoreDocument<InitializedStorageFileModel, any>> {
+export interface InitializeStorageFileModelInTransactionInput<D extends FirestoreDocument<InitializedStorageFileModel>> {
     readonly makeTemplateFunction: MakeTemplateForStorageFileRelatedModelInitializationFunction<FirestoreDocumentData<D>>;
     readonly throwErrorIfAlreadyInitialized?: Maybe<boolean>;
     readonly transaction: Transaction;
@@ -90,9 +91,10 @@ export interface InitializeStorageFileModelInTransactionInput<D extends Firestor
  * - Returns `false` → deletes the document entirely
  *
  * @param input - the document, transaction, template function, and options
+ * @returns an object indicating whether the document was initialized or was already initialized
  * @throws storageFileModelAlreadyInitializedError when `throwErrorIfAlreadyInitialized` is true
  */
-export declare function initializeStorageFileModelInTransaction<D extends FirestoreDocument<InitializedStorageFileModel, any>>(input: InitializeStorageFileModelInTransactionInput<D>): Promise<{
+export declare function initializeStorageFileModelInTransaction<D extends FirestoreDocument<InitializedStorageFileModel>>(input: InitializeStorageFileModelInTransactionInput<D>): Promise<{
     initialized: boolean;
     alreadyInitialized: boolean;
 }>;
@@ -101,6 +103,9 @@ export declare function initializeStorageFileModelInTransaction<D extends Firest
  *
  * Applies the app-specific template function, restricting the template to only the `o` (owner)
  * and content flag properties, and always flags the group for content regeneration.
+ *
+ * @param context - the initialization context providing collection access and the template function
+ * @returns an async function that initializes a storage file group document within a transaction
  */
 export declare function initializeStorageFileGroupInTransactionFactory(context: StorageFileInitServerActionsContext): (params: InitializeStorageFileModelParams, storageFileGroupDocument: StorageFileGroupDocument, transaction: Transaction) => Promise<{
     initialized: boolean;
@@ -111,6 +116,9 @@ export declare function initializeStorageFileGroupInTransactionFactory(context:
  *
  * Wraps the in-transaction group initialization in a Firestore transaction
  * and follows the transform-and-validate pattern.
+ *
+ * @param context - the initialization context with Firestore access and template function
+ * @returns a transform-and-validate function for single storage file group initialization
  */
 export declare function initializeStorageFileGroupFactory(context: StorageFileInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeStorageFileModelParams, (storageFileGroupDocument: StorageFileGroupDocument) => Promise<StorageFileGroupDocument>, object, unknown>;
 /**
@@ -119,5 +127,8 @@ export declare function initializeStorageFileGroupFactory(context: StorageFileIn
  * Batch-processes all {@link StorageFileGroup} documents flagged for initialization,
  * initializing each in parallel (up to 5 concurrent tasks). Loops until no more
  * flagged groups are found.
+ *
+ * @param context - the initialization context with Firestore access, collection, and template function
+ * @returns a transform-and-validate function for batch storage file group initialization
  */
 export declare function initializeAllApplicableStorageFileGroupsFactory(context: StorageFileInitServerActionsContext): import("@dereekb/model").TransformAndValidateFunctionResultFunction<InitializeAllApplicableStorageFileGroupsParams, () => Promise<InitializeAllApplicableStorageFileGroupsResult>, object, unknown>;

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

@@ -1,59 +1,86 @@
 import { type UploadedFileInitializationFailedErrorData } from '@dereekb/firebase';
 /**
  * Creates an error indicating that a storage file model has already been initialized.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_MODEL_ALREADY_INITIALIZED error code
  */
 export declare function storageFileModelAlreadyInitializedError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the StorageFile is not flagged for group sync.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_NOT_FLAGGED_FOR_GROUPS_SYNC error code
  */
 export declare function storageFileNotFlaggedForGroupsSyncError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the target uploaded file does not exist in storage.
+ *
+ * @returns a precondition-conflict HttpsError with the UPLOADED_FILE_DOES_NOT_EXIST error code
  */
 export declare function uploadedFileDoesNotExistError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the file is not allowed to be initialized (rejected by the check function).
+ *
+ * @returns a precondition-conflict HttpsError with the UPLOADED_FILE_NOT_ALLOWED_TO_BE_INITIALIZED error code
  */
 export declare function uploadedFileIsNotAllowedToBeInitializedError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the file initialization failed with the given result type.
  *
  * @param data - error data containing the result type that caused the failure
+ * @returns an internal-server HttpsError with the UPLOADED_FILE_INITIALIZATION_FAILED error code and the result type
  */
 export declare function uploadedFileInitializationFailedError(data: UploadedFileInitializationFailedErrorData): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the initialization result was discarded (e.g., the created file no longer exists).
+ *
+ * @returns an internal-server HttpsError with the UPLOADED_FILE_INITIALIZATION_DISCARDED error code
  */
 export declare function uploadedFileInitializationDiscardedError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the StorageFile is not in a valid state for processing.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_PROCESSING_NOT_ALLOWED_FOR_INVALID_STATE error code
  */
 export declare function storageFileProcessingNotAllowedForInvalidStateError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the StorageFile is not queued for processing.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_PROCESSING_NOT_QUEUED_FOR_PROCESSING error code
  */
 export declare function storageFileProcessingNotQueuedForProcessingError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that no processor is configured for the StorageFile's type.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_PROCESSING_NOT_AVAILABLE_FOR_TYPE error code
  */
 export declare function storageFileProcessingNotAvailableForTypeError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the StorageFile has already finished processing.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_ALREADY_PROCESSED error code
  */
 export declare function storageFileAlreadyProcessedError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the StorageFile is not flagged for deletion.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_NOT_FLAGGED_FOR_DELETION error code
  */
 export declare function storageFileNotFlaggedForDeletionError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the StorageFile's scheduled deletion time has not yet passed.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_CANNOT_BE_DELETED_YET error code
  */
 export declare function storageFileCannotBeDeletedYetError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the StorageFileGroup is still queued for initialization and cannot be operated on.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_GROUP_QUEUED_FOR_INITIALIZATION error code
  */
 export declare function storageFileGroupQueuedForInitializationError(): import("firebase-functions/https").HttpsError;
 /**
  * Creates an error indicating that the required model key or storageFileId is missing when creating a StorageFileGroup.
+ *
+ * @returns a precondition-conflict HttpsError with the STORAGE_FILE_GROUP_CREATE_INPUT error code
  */
 export declare function createStorageFileGroupInputError(): import("firebase-functions/https").HttpsError;

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

@@ -2,19 +2,30 @@ import { type ModuleMetadata } from '@nestjs/common';
 import { type Maybe } from '@dereekb/util';
 import { type BaseStorageFileServerActionsContext, StorageFileServerActions, type StorageFileServerActionsContext } from './storagefile.action.server';
 import { StorageFileInitializeFromUploadService } from './storagefile.upload.service';
-import { StorageFileInitServerActions, type StorageFileInitServerActionsContextConfig } from './storagefile.action.init.service';
+import { StorageFileInitServerActions, type StorageFileInitServerActionsContextConfig } from './storagefile.action.server.init';
 /**
  * Factory that assembles the full {@link StorageFileServerActionsContext} by combining
  * the base context with the upload initialization service.
+ *
+ * @param context - the base server actions context providing Firebase infrastructure
+ * @param storageFileInitializeFromUploadService - the service for initializing storage files from uploads
+ * @returns the fully assembled StorageFileServerActionsContext
  */
 export declare function storageFileServerActionsContextFactory(context: BaseStorageFileServerActionsContext, storageFileInitializeFromUploadService: StorageFileInitializeFromUploadService): StorageFileServerActionsContext;
 /**
  * Factory that creates a {@link StorageFileServerActions} instance from the assembled context.
+ *
+ * @param context - the fully assembled storage file server actions context
+ * @returns a concrete StorageFileServerActions instance
  */
 export declare function storageFileServerActionsFactory(context: StorageFileServerActionsContext): StorageFileServerActions;
 /**
  * Factory that creates a {@link StorageFileInitServerActions} instance by merging the
  * server actions context with the init-specific configuration.
+ *
+ * @param context - the storage file server actions context
+ * @param storageFileInitServerActionsContextConfig - init-specific configuration with the template function
+ * @returns a concrete StorageFileInitServerActions instance
  */
 export declare function storageFileInitServerActionsFactory(context: StorageFileServerActionsContext, storageFileInitServerActionsContextConfig: StorageFileInitServerActionsContextConfig): StorageFileInitServerActions;
 export interface ProvideAppStorageFileMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
@@ -38,8 +49,7 @@ export interface ProvideAppStorageFileMetadataConfig extends Pick<ModuleMetadata
  *
  * Be sure the class that delares the module using this function also extends AbstractAppStorageFileModule.
  *
- * @param provide
- * @param useFactory
- * @returns
+ * @param config - the module configuration including optional dependency module, imports, exports, and providers
+ * @returns the assembled {@link ModuleMetadata} for the storage file module
  */
 export declare function appStorageFileModuleMetadata(config: ProvideAppStorageFileMetadataConfig): ModuleMetadata;

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

@@ -10,7 +10,7 @@ import archiver from 'archiver';
  * Extends the generic subtask input with storage-file-specific context: the document reference,
  * a lazy loader for the current file data, and a file reader for accessing the stored file's content.
  */
-export interface StorageFileProcessingPurposeSubtaskInput<M extends StorageFileProcessingSubtaskMetadata = any, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> extends NotificationTaskSubtaskInput<StorageFileProcessingNotificationTaskData<M, S>, M, S> {
+export interface StorageFileProcessingPurposeSubtaskInput<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> extends NotificationTaskSubtaskInput<StorageFileProcessingNotificationTaskData<M, S>, M, S> {
     /**
      * The associated StorageFileDocument.
      */
@@ -29,15 +29,15 @@ export interface StorageFileProcessingPurposeSubtaskInput<M extends StorageFileP
 /**
  * Result of a StorageFileProcessingPurposeSubtask.
  */
-export type StorageFileProcessingPurposeSubtaskResult<M extends StorageFileProcessingSubtaskMetadata = any, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = NotificationTaskServiceHandleNotificationTaskResult<M, S>;
+export type StorageFileProcessingPurposeSubtaskResult<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = NotificationTaskServiceHandleNotificationTaskResult<M, S>;
 /**
  * A StorageFileProcessingPurposeSubtask is a function that handles a specific StorageFilePurpose subtask.
  */
-export type StorageFileProcessingPurposeSubtask<M extends StorageFileProcessingSubtaskMetadata = any, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = (input: StorageFileProcessingPurposeSubtaskInput<M>) => Promise<StorageFileProcessingPurposeSubtaskResult<M, S>>;
+export type StorageFileProcessingPurposeSubtask<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = (input: StorageFileProcessingPurposeSubtaskInput<M>) => Promise<StorageFileProcessingPurposeSubtaskResult<M, S>>;
 /**
  * Similar to NotificationTaskServiceTaskHandlerFlowEntry, but used in StorageFileProcessingPurposeTaskProcessorConfig as part of the flow.
  */
-export type StorageFileProcessingPurposeSubtaskFlowEntry<M extends StorageFileProcessingSubtaskMetadata = any, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = NotificationTaskSubtaskFlowEntry<StorageFileProcessingPurposeSubtaskInput<M, S>, StorageFileProcessingNotificationTaskData<M, S>, M, S>;
+export type StorageFileProcessingPurposeSubtaskFlowEntry<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = NotificationTaskSubtaskFlowEntry<StorageFileProcessingPurposeSubtaskInput<M, S>, StorageFileProcessingNotificationTaskData<M, S>, M, S>;
 /**
  * The output cleanup configuration.
  */
@@ -63,13 +63,13 @@ export interface StorageFileProcessingPurposeSubtaskCleanupOutput extends Notifi
      */
     readonly flagResyncWithStorageFileGroups?: boolean;
 }
-export type StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget<M extends StorageFileProcessingSubtaskMetadata = any, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = NotificationTaskSubtaskProcessorConfig<StorageFileProcessingPurposeSubtaskInput<M, S>, StorageFileProcessingPurposeSubtaskCleanupOutput, StorageFileProcessingNotificationTaskData<M, S>>;
+export type StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = NotificationTaskSubtaskProcessorConfig<StorageFileProcessingPurposeSubtaskInput<M, S>, StorageFileProcessingPurposeSubtaskCleanupOutput, StorageFileProcessingNotificationTaskData<M, S>>;
 /**
  * Similar to NotificationTaskServiceTaskHandlerConfig, but instead targets a specific StorageFilePurpose.
  *
  * The flows behave the same way.
  */
-export type StorageFileProcessingPurposeSubtaskProcessorConfig<M extends StorageFileProcessingSubtaskMetadata = any, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget<M, S>;
+export type StorageFileProcessingPurposeSubtaskProcessorConfig<M extends StorageFileProcessingSubtaskMetadata = StorageFileProcessingSubtaskMetadata, S extends StorageFileProcessingSubtask = StorageFileProcessingSubtask> = StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget<M, S>;
 export interface StorageFileProcessingNotificationTaskHandlerConfig extends Omit<NotificationTaskSubtaskNotificationTaskHandlerConfig<StorageFileProcessingPurposeSubtaskInput, StorageFileProcessingPurposeSubtaskCleanupOutput, StorageFileProcessingNotificationTaskData>, 'processors'> {
     /**
      * The input processors.
@@ -93,6 +93,13 @@ export interface StorageFileProcessingNotificationTaskHandlerConfig extends Omit
 export declare const storageFileProcessingNotificationTaskHandlerDefaultCleanup: () => StorageFileProcessingPurposeSubtaskCleanupOutput;
 /**
  * Creates a NotificationTaskServiceTaskHandlerConfig that handles the StorageFileProcessingNotificationTask.
+ *
+ * Builds a subtask-based notification handler that loads the storage file document,
+ * determines its purpose, and dispatches to the appropriate purpose-specific processor.
+ * Includes optional StorageFileGroup processors (e.g., ZIP generation) by default.
+ *
+ * @param config - handler configuration including processors, storage accessor, and Firestore collections
+ * @returns a NotificationTaskServiceTaskHandlerConfig wired for storage file processing
  */
 export declare function storageFileProcessingNotificationTaskHandler(config: StorageFileProcessingNotificationTaskHandlerConfig): NotificationTaskServiceTaskHandlerConfig<StorageFileProcessingNotificationTaskData>;
 export interface AllStorageFileGroupStorageFileProcessingPurposeSubtaskProcessorsConfig extends StorageFileGroupStorageFileProcessingPurposeSubtaskProcessorsConfig {
@@ -103,6 +110,12 @@ export interface AllStorageFileGroupStorageFileProcessingPurposeSubtaskProcessor
      */
     readonly excludeZipProcessing?: boolean;
 }
+/**
+ * Assembles all built-in StorageFileGroup subtask processors, such as ZIP generation.
+ *
+ * @param config - configuration controlling which group processors to include
+ * @returns an array of subtask processor configs for StorageFileGroup processing purposes
+ */
 export declare function allStorageFileGroupStorageFileProcessingPurposeSubtaskProcessors(config: AllStorageFileGroupStorageFileProcessingPurposeSubtaskProcessorsConfig): StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget[];
 export interface StorageFileGroupStorageFileProcessingPurposeSubtaskProcessorsConfig {
     readonly storageFileFirestoreCollections: StorageFileFirestoreCollections;
@@ -161,10 +174,19 @@ export interface StorageFileGroupStorageFileProcessingPurposeSubtaskProcessorsCo
      *
      * The function should return an object that can be serialized to JSON.
      */
-    readonly configureZipInfoJson?: false | ((baseInfoJson: StorageFileGroupStorageFileZipInfoJson) => PromiseOrValue<Maybe<any>>);
+    readonly configureZipInfoJson?: false | ((baseInfoJson: StorageFileGroupStorageFileZipInfoJson) => PromiseOrValue<Maybe<unknown>>);
     /**
      * Optional function to hook into the finalization of the target zip archive.
      */
     readonly finalizeZipArchive?: StorageFileGroupStorageFileZipFinalizeArchiveFunction;
 }
+/**
+ * Creates the ZIP subtask processor for {@link StorageFileGroup} processing.
+ *
+ * This processor streams all files in the group into a ZIP archive, attaches an info JSON
+ * manifest, and uploads the result to the group's designated storage path.
+ *
+ * @param config - configuration providing Firestore collections, storage accessor, and ZIP options
+ * @returns a subtask processor config targeting the StorageFileGroup ZIP purpose
+ */
 export declare function storageFileGroupZipStorageFileProcessingPurposeSubtaskProcessor(config: StorageFileGroupStorageFileProcessingPurposeSubtaskProcessorsConfig): StorageFileProcessingPurposeSubtaskProcessorConfigWithTarget<StorageFileGroupZipStorageFileProcessingSubtaskMetadata, StorageFileGroupZipStorageFileProcessingSubtask>;

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

@@ -71,6 +71,7 @@ export interface StorageFileInitializeFromUploadServiceInitializerStorageFileDoc
  *
  * @param error - the error that caused the permanent failure
  * @param createdFile - optional path to a file that was created before the error and should be deleted
+ * @returns a permanent failure result with the error and optional created file reference
  */
 export declare function storageFileInitializeFromUploadServiceInitializerResultPermanentFailure(error: unknown, createdFile?: Maybe<StoragePathRef>): StorageFileInitializeFromUploadServiceInitializerResult;
 /**
@@ -145,6 +146,7 @@ export interface StorageFileInitializeFromUploadServiceConfig {
  * 4. Optionally, previous files for the same purpose/user are flagged for deletion
  *
  * @param config - service configuration including determiners, initializers, and storage references
+ * @returns a {@link StorageFileInitializeFromUploadService} with type detection and upload initialization
  *
  * @example
  * ```ts