import { type Maybe } from '@dereekb/util';
import { StorageFileCreationType, type StorageFileGroup, type StorageFile, type StorageFileDocument, type StorageFileFirestoreCollections } from './storagefile';
import { type Transaction } from '../../common/firestore/types';
import { type FirestoreDocumentAccessor } from '../../common/firestore/accessor/document';
import { type FirebaseStorageAccessorFile } from '../../common/storage/driver/accessor';
import { type StoragePathRef, type StoragePath } from '../../common/storage/storage';
import { type FirebaseAuthOwnershipKey, type FirebaseAuthUserId } from '../../common/auth/auth';
import { type StorageFilePurposeSubgroup, type StorageFileGroupId, type StorageFileGroupRelatedStorageFilePurpose, type StorageFileMetadata, type StorageFilePurpose } from './storagefile.id';
import { type ReadFirestoreModelKeyInput } from '../../common';
/**
 * Input for creating a StorageFile document paired with its storage path.
 *
 * Provides all the fields needed to create a fully-configured {@link StorageFile} Firestore document,
 * including ownership, purpose, group membership, and processing state.
 *
 * Either a `file`, `storagePathRef`, or `storagePath` must be provided to identify the storage location.
 * Either an `accessor` or `context` must be provided for Firestore document creation.
 *
 * @template M - type of arbitrary metadata stored in the `d` field
 */
export interface CreateStorageFileDocumentPairInput<M extends StorageFileMetadata = StorageFileMetadata> {
    /**
     * Optional "now" value that is assigned to the "cat" value, created at time.
     */
    readonly now?: Maybe<Date>;
    /**
     * The document transaction
     */
    readonly transaction?: Transaction;
    /**
     * The storage path to set on the StorageFile template.
     *
     * Is ignored if file or storagePathRef is provided.
     */
    readonly storagePath?: StoragePath;
    /**
     * The ref of the storage path to set on the StorageFile template.
     *
     * Is ignored if file is provided.
     */
    readonly storagePathRef?: StoragePathRef;
    /**
     * File to use when creating the StorageFile.
     */
    readonly file?: FirebaseStorageAccessorFile;
    /**
     * The display name of the StorageFile.
     *
     * Corresponds with the "n" value in the StorageFile template.
     */
    readonly displayName?: Maybe<string>;
    /**
     * The user that the file is associated with.
     *
     * Corresponds with the "u" value in the StorageFile template.
     */
    readonly user?: Maybe<FirebaseAuthUserId>;
    /**
     * The user that uploaded the file.
     *
     * Corresponds with the "uby" value in the StorageFile template.
     */
    readonly uploadedBy?: Maybe<FirebaseAuthUserId>;
    /**
     * The group ids of the file.
     *
     * Corresponds with the "g" value in the StorageFile template.
     */
    readonly storageFileGroupIds?: Maybe<StorageFileGroupId[]>;
    /**
     * If true, will flag the file for group sync.
     *
     * Defaults to true if one or more values in "storageFileGroupIds" are provided.
     *
     * Ignored if the "storageFileGroupIds" value is empty.
     */
    readonly flagForStorageFileGroupsSync?: boolean;
    /**
     * The ownership key of the file.
     *
     * Corresponds with the "o" value in the StorageFile template.
     */
    readonly ownershipKey?: Maybe<FirebaseAuthOwnershipKey>;
    /**
     * The purpose of the file.
     *
     * Corresponds with the "p" value in the StorageFile template.
     */
    readonly purpose?: Maybe<StorageFilePurpose | StorageFileGroupRelatedStorageFilePurpose>;
    /**
     * The subgroup of the purpose.
     *
     * Corresponds with the "pg" value in the StorageFile template.
     */
    readonly purposeSubgroup?: Maybe<StorageFilePurposeSubgroup>;
    /**
     * The StorageFileGroup that the file is associated with.
     *
     * This is ONLY used if the creation type is StorageFileCreationType.FOR_STORAGE_FILE_GROUP.
     */
    readonly parentStorageFileGroup?: Maybe<ReadFirestoreModelKeyInput<StorageFileGroup>>;
    /**
     * The metadata of the file.
     *
     * Corresponds with the "m" value in the StorageFile template.
     */
    readonly metadata?: Maybe<M>;
    /**
     * If true, will queue the StorageFile for processing.
     */
    readonly shouldBeProcessed?: Maybe<boolean>;
    /**
     * Template details for the StorageFileDocument.
     */
    readonly template?: Maybe<Omit<Partial<StorageFile<M>>, 'cat'>>;
    /**
     * Context to create the accessor from.
     */
    readonly context?: Pick<StorageFileFirestoreCollections, 'storageFileCollection'>;
    /**
     * Accessor to use directly.
     */
    readonly accessor?: FirestoreDocumentAccessor<StorageFile, StorageFileDocument>;
}
/**
 * Result of creating a StorageFile document pair, containing the document and its template data.
 */
export interface CreateStorageFileDocumentPairResult<M extends StorageFileMetadata = StorageFileMetadata> {
    /**
     * The StorageFileDocument that was created.
     */
    readonly storageFileDocument: StorageFileDocument;
    /**
     * The template that was passed to create the StorageFileDocument.
     */
    readonly storageFile: StorageFile<M>;
}
/**
 * Configuration for {@link createStorageFileDocumentPairFactory}, controlling default values
 * for creation type, purpose subgroup, and processing state.
 */
export interface CreateStorageFileDocumentPairFactoryConfig {
    /**
     * The default creation type to use.
     *
     * Defaults to StorageFileCreationType.DIRECTLY_CREATED.
     */
    readonly defaultCreationType?: Maybe<StorageFileCreationType>;
    /**
     * The default value for purposeSubgroup.
     *
     * If true, defaults to EMPTY_STORAGE_FILE_PURPOSE_SUBGROUP.
     */
    readonly defaultPurposeSubgroup?: Maybe<StorageFilePurposeSubgroup | true>;
    /**
     * The default value for shouldBeProcessed.
     *
     * Defaults to false.
     */
    readonly defaultShouldBeProcessed?: Maybe<boolean>;
}
/**
 * Factory function for creating StorageFileDocument pairs.
 */
export type CreateStorageFileDocumentPairFactory = <M extends StorageFileMetadata = StorageFileMetadata>(input: CreateStorageFileDocumentPairInput<M>) => Promise<CreateStorageFileDocumentPairResult<M>>;
/**
 * Creates a factory for producing StorageFile document pairs with pre-configured defaults.
 *
 * The factory handles document ID generation (random for direct creation, deterministic for
 * {@link StorageFileCreationType.FOR_STORAGE_FILE_GROUP}), storage path resolution, and
 * initial state setup.
 *
 * @param config - optional defaults for creation type, subgroup, and processing state
 * @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
 *
 * @example
 * ```ts
 * const factory = createStorageFileDocumentPairFactory({
 *   defaultShouldBeProcessed: true
 * });
 *
 * const { storageFileDocument, storageFile } = await factory({
 *   storagePath: { bucketId: 'my-bucket', pathString: '/files/report.pdf' },
 *   purpose: 'report',
 *   context: collections
 * });
 * ```
 */
export declare function createStorageFileDocumentPairFactory(config?: CreateStorageFileDocumentPairFactoryConfig): CreateStorageFileDocumentPairFactory;
/**
 * 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>>;