@emailmaker/emailmaker 1.1.69 → 1.1.70

package/file-manager/types/storage.d.ts

@@ -1,411 +0,0 @@
-/**
- * Storage-provider contract types.
- * These types define the interface between the file-manager package and any backend storage implementation.
- */
-export type MayBePromise<T> = T | Promise<T>;
-export interface FileManagerApiErrorInfo {
-    message?: string;
-    code?: string | number;
-    status?: number;
-    raw?: unknown;
-    stack?: string;
-}
-export interface OperationResult<T = void> {
-    /**
-     * Unique identifier of the item that was processed.
-     * This should match the ID of the original item from the request.
-     */
-    requestId?: string;
-    success?: boolean;
-    data?: T;
-    error?: FileManagerApiErrorInfo;
-}
-export type BatchResult<T> = {
-    success: boolean;
-    error?: FileManagerApiErrorInfo;
-    detailed?: OperationResult<T>[];
-};
-/**
- * File information.
- */
-export interface FileSystemItem {
-    /** Unique file identifier */
-    id: string;
-    /** File name */
-    name: string;
-    /** Identifier of the folder the file belongs to. Empty string means root; null means no folder assigned. */
-    folderId: string | null;
-    /** Item type - file or folder */
-    isFolder?: boolean;
-    /** File size */
-    size?: number;
-    /** File creation or upload date */
-    date?: string;
-    /** File MIME type */
-    type?: string;
-    /** File download URL (used if `getFile` method is not implemented) */
-    url?: string;
-    /** File thumbnail */
-    thumbnail?: string;
-    /** Alternative thumbnail URL */
-    thumbnailUrl?: string;
-    /** Image dimensions (width x height) */
-    dimensions?: string;
-    /** Aspect ratio */
-    aspectRatio?: string;
-    /** File extension */
-    extension?: string;
-    /** Whether the file is selected in the UI */
-    selected?: boolean;
-    /** Date when the file was last edited */
-    lastEdited?: string;
-    /** Number of children items (for folders) */
-    childrenCount?: number;
-}
-/**
- * Represents partial updates to a file system item after an operation.
- * Contains only the fields that were changed during the operation.
- */
-export type FileSystemItemUpdate = Partial<FileSystemItem> & {
-    id: string;
-};
-/**
- * Options for {@link StorageProvider.getFileData} when loading file bytes (blob).
- */
-export interface GetFileDataOptions {
-    /**
-     * When `true`, bypass the HTTP cache (`fetch` with `cache: 'no-store'`).
-     * When `false`, allow normal browser caching.
-     * When omitted, normal browser caching is used unless a caller applies a one-shot bypass after overwrite.
-     */
-    forceReload?: boolean;
-}
-/**
- * API response with pagination details.
- */
-export interface StorageApiPaginationResponse {
-    /** Current page number */
-    page: number;
-    /** Number of items per page */
-    limit: number;
-    /** Total number of items */
-    total: number;
-    /** Total number of pages */
-    totalPages: number;
-    /** Whether there is a next page */
-    hasNext: boolean;
-    /** Whether there is a previous page */
-    hasPrev: boolean;
-}
-/**
- * Sorting state.
- */
-export interface StorageSortState {
-    /** Field to sort by */
-    sortBy: 'name' | 'size' | 'date' | 'type';
-    /** Sort order */
-    sortOrder: 'asc' | 'desc';
-}
-export interface StorageProviderController {
-    /**
-     * Invalidates the cache for a specific file system item.
-     *
-     * This method should be called when an item's data has changed externally
-     * and the cached version is no longer valid. After invalidation, the next
-     * access to this item will trigger a fresh fetch from the storage backend.
-     *
-     * @param itemId - The unique identifier of the file or folder to invalidate
-     */
-    invalidateItemCache(itemId: string): void;
-    /**
-     * Retrieves a cached file system item.
-     *
-     * @param itemId - The unique identifier of the file or folder
-     * @returns The cached item or undefined if not found in cache
-     */
-    getCachedItem(itemId: string): FileSystemItem | undefined;
-}
-export interface StorageUploadFileItemInput {
-    /**
-     * Arbitrary identifier used to match an upload result with this item.
-     * If not provided, the result is matched by the order of items.
-     */
-    requestId?: string;
-    /** File name. */
-    name: string;
-    /** File size in bytes. */
-    size: number;
-    /** MIME type of the file. */
-    type: string;
-    /** Target folder ID, or null if not applicable. */
-    folderId?: string | null;
-    /** File data as a Blob or File. */
-    data: Blob | File;
-    /** Optional file extension. */
-    extension?: string;
-}
-export interface StorageUploadFilesRequest {
-    /**
-     * List of files to upload. The order of items matters — if `requestId`
-     * is omitted, results are matched to items by index.
-     */
-    items: StorageUploadFileItemInput[];
-    /** Target folder ID for batch upload, or null. */
-    folderId?: string | null;
-}
-/**
- * Interface for storage providers.
- * Defines the contract for different storage backends (e.g., cloud APIs, REST services).
- */
-export interface StorageProvider {
-    /**
-     * @default false
-     * Client-side check for existing files or folders
-     */
-    validateDuplicates?: boolean;
-    /**
-     * Use the path as an identifier for folders
-     */
-    pathMode?: boolean;
-    /**
-     * Custom identifier for the root folder.
-     * - This ID will be used internally for the root of the file tree.
-     * - Defaults to an empty string `''` if not provided.
-     */
-    rootId?: string;
-    /**
-     * Path to the trash/recycle bin folder.
-     * - Used when `useSoftDelete` is enabled or for trash operations.
-     * - The provider will resolve this path to an actual folder ID.
-     */
-    trashPath?: string;
-    /**
-     * Path to the temporary folder for uploads and transient files.
-     * - Used for operations where temporary storage is needed.
-     * - The provider will resolve this path to an actual folder ID.
-     */
-    tempPath?: string;
-    /**
-     * @default true
-     */
-    ensureFolderTrailingSlash?: boolean;
-    /**
-     * Utility method for finding system files/folders by path.
-     * By default, searches for folders through getFiles method.
-     *
-     * @param path - Path to the file or folder
-     * @returns The found item or undefined if not found
-     */
-    findItemByPath?(path: string): MayBePromise<FileSystemItem | undefined>;
-    /**
-     * Clear cache for the specified folder path.
-     * @param pathFolder - Path to folder inside project
-     */
-    clearCache?(pathFolder?: string | null): MayBePromise<void>;
-    /**
-     * Sets the controller for cache management.
-     *
-     * This method provides the storage provider with a controller interface
-     * that allows it to communicate cache invalidation requests back to the file manager.
-     *
-     * @param controller - The controller instance for cache management
-     */
-    setController?(controller: StorageProviderController): MayBePromise<void>;
-    /**
-     * Enables client-side soft delete implementation.
-     * When enabled, delete operations will move items to trashPath instead of permanent deletion.
-     *
-     * @note If your backend already implements soft delete, keep this disabled
-     * to avoid double soft-delete logic.
-     *
-     * @default false
-     */
-    useSoftDelete?: boolean;
-    /**
-     * Retrieve the file content as a binary blob.
-     *
-     * ⚠️ If this method is not implemented, the file will be downloaded
-     * using the `url` property from the `FileInfo` object.
-     *
-     * @param file - File object
-     * @param options - See {@link GetFileDataOptions}
-     * @returns File contents as a Blob
-     */
-    getFileData?: (file: FileSystemItem, options?: GetFileDataOptions) => MayBePromise<Blob>;
-    /**
-     * Get URL for file access
-     * @param file - File object
-     * @returns File URL
-     */
-    getUrl?: (file: FileSystemItem) => MayBePromise<string>;
-    /**
-     * Get thumbnail URL for file
-     * @param file - File object
-     * @returns Thumbnail URL
-     */
-    getThumbnailUrl?: (file: FileSystemItem) => MayBePromise<string>;
-    /**
-     * Retrieve a list of files and folders.
-     * Supports filtering, sorting, and pagination.
-     *
-     * @param options.folderId - Parent folder (or undefined for root)
-     * @param options.search - Search query
-     * @param options.sortBy - Field to sort by
-     * @param options.sortOrder - Sort direction
-     * @param options.page - Page number
-     * @param options.limit - Number of items per page
-     * @param options.itemType - Filter by item type
-     * @returns List of files/folders and optional pagination details
-     */
-    getItems: (options: {
-        folderId?: string;
-        search?: string;
-        sortBy?: StorageSortState['sortBy'];
-        sortOrder?: StorageSortState['sortOrder'];
-        page?: number;
-        limit?: number;
-        itemType: 'all' | 'file' | 'folder';
-    }) => MayBePromise<{
-        items: FileSystemItem[];
-        pagination?: Partial<StorageApiPaginationResponse>;
-    }>;
-    /**
-     * Create a new folder.
-     *
-     * @param name - Folder name
-     * @param parent - Parent folder (or undefined for root)
-     * @returns The created folder object
-     */
-    createFolder: (name: string, parentid?: string, is_force_create?: boolean) => MayBePromise<FileSystemItem>;
-    /**
-     * Rename an item (file or folder).
-     *
-     * @param options.item - Item to rename (file or folder)
-     * @param options.newName - New item name
-     * @returns Updated item with changed fields
-     */
-    renameItem?: (item: FileSystemItem, newName: string) => MayBePromise<FileSystemItemUpdate>;
-    /**
-     * Delete an item (file or folder).
-     * When useSoftDelete is enabled, moves item to trashPath instead of permanent deletion.
-     *
-     * @param item - Item to delete (file or folder)
-     * @throws {Error} If deletion fails
-     */
-    deleteItem?: (item: FileSystemItem, options: {
-        permanent: boolean;
-    }) => MayBePromise<void>;
-    /**
-     * Upload a file.
-     *
-     * @param file.name - File name
-     * @param file.size - File size
-     * @param file.type - MIME type
-     * @param file.folderId - Target folder (or undefined for root)
-     * @param file.data - File data
-     * @returns The uploaded file with changed fields
-     */
-    uploadFile?: (file: {
-        name: string;
-        size: number;
-        type: string;
-        folderId?: string;
-        data: Blob | File;
-        thumbnail?: string;
-        dimensions?: string;
-        aspectRatio?: string;
-        extension?: string;
-    }) => MayBePromise<FileSystemItemUpdate>;
-    /**
-     * Uploads multiple files and returns a batch result containing metadata
-     * for each uploaded file.
-     */
-    uploadFiles?: (request: StorageUploadFilesRequest) => MayBePromise<BatchResult<FileSystemItem>>;
-    /**
-     * Upload a file by URL.
-     *
-     * ⚠️ Implementation should check if the file already belongs
-     * to the current server. If it does, return the existing file object
-     * instead of uploading it again.
-     *
-     * @param url - File URL
-     * @param folderId - Target folder (or undefined for root). If not specified,
-     * uses the root folder.
-     * @param options - Optional. eventSource — upload origin for integrator logic
-     *   (e.g. disable proxy when uploading from stock sources: imageStock, iconStock, gif).
-     * @returns The uploaded or existing complete file object
-     */
-    uploadFileByUrl: (url: string, folderId?: string, options?: {
-        eventSource?: 'upload' | 'uploadByUrl' | 'pixie' | 'iconStock' | 'imageStock' | 'gif';
-    }) => MayBePromise<FileSystemItem>;
-    /**
-     * Delete multiple items (files or folders).
-     *
-     * @param items - Array of items to delete (files or folders)
-     * @param options - Delete options
-     * @returns Batch operation result with success/failure details
-     */
-    deleteItems?: (items: FileSystemItem[], options: {
-        permanent: boolean;
-    }) => MayBePromise<BatchResult<never>>;
-    /**
-     * Move a single item to the target folder
-     * @param item - Item to move (file or folder)
-     * @param targetFolderId - Destination folder. If undefined, uses root folder
-     * @returns The moved item with changed fields
-     */
-    moveItem?: (item: FileSystemItem, targetFolderId?: string) => MayBePromise<FileSystemItemUpdate>;
-    /**
-     * Move multiple items to the target folder
-     * @param items - Array of items to move (files or folders)
-     * @param targetFolderId - Destination folder. If undefined, uses root folder
-     * @returns Batch operation result with success/failure details
-     */
-    moveItems?: (items: FileSystemItem[], targetFolderId?: string) => MayBePromise<BatchResult<FileSystemItemUpdate>>;
-    /**
-     * Clear all items from trash folder permanently
-     * @returns Result object with success flag and optional count of deleted items
-     */
-    cleanTrash?: () => MayBePromise<{
-        success: boolean;
-        deletedCount?: number;
-    }>;
-    /**
-     * Copy a single item to the target folder
-     * @param item - Item to copy (file or folder)
-     * @param targetFolderId - Destination folder. If undefined, uses root folder
-     * @returns The copied item with changed fields
-     */
-    copyItem?: (item: FileSystemItem, targetFolderId?: string) => MayBePromise<FileSystemItemUpdate>;
-    /**
-     * Copy multiple items to the target folder
-     * @param items - Array of items to copy (files or folders)
-     * @param targetFolderId - Destination folder. If undefined, uses root folder
-     * @returns Batch operation result with success/failure details
-     */
-    copyItems?: (items: FileSystemItem[], targetFolderId?: string) => MayBePromise<BatchResult<FileSystemItemUpdate>>;
-    /**
-     * Find a file by its URL.
-     * Implementation should check if the file already belongs to the current server.
-     * @param url - File URL
-     * @param folderId - Target folder (or undefined for root)
-     * @returns The existing file object if found, otherwise undefined
-     */
-    findFileByUrl?: (url: string, folderId?: string) => MayBePromise<FileSystemItem | undefined>;
-    /**
-     * Update file metadata or content.
-     *
-     * @param file - File to update
-     * @param updates - Object with fields to update (name, type, data, thumbnail, etc.)
-     * @returns Updated file with changed fields
-     */
-    updateFile?: (file: FileSystemItem, updates: {
-        name?: string;
-        type?: string;
-        data?: Blob | string;
-        thumbnail?: string;
-        dimensions?: string;
-        aspectRatio?: string;
-        extension?: string;
-    }) => MayBePromise<FileSystemItemUpdate>;
-}