@emailmaker/emailmaker 1.1.65 → 1.1.69

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

@@ -0,0 +1,411 @@
+/**
+ * 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>;
+}