hazo_files 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1031 @@
+import { OAuth2Client } from 'google-auth-library';
+
+/**
+ * Naming rule types for hazo_files package
+ * Used for configuring and generating file/folder names based on patterns
+ */
+/** Variable category for grouping in UI */
+type VariableCategory = 'user' | 'date' | 'file' | 'counter';
+/** A variable that can be used in naming patterns */
+interface NamingVariable {
+    /** Variable name (without braces), e.g., "project_name", "YYYY" */
+    variable_name: string;
+    /** Human-readable description */
+    description: string;
+    /** Example value for preview */
+    example_value: string;
+    /** Category for grouping in UI */
+    category?: VariableCategory;
+}
+/** A segment in a naming pattern */
+interface PatternSegment {
+    /** Unique ID for React keys and drag-drop operations */
+    id: string;
+    /** Type of segment */
+    type: 'variable' | 'literal';
+    /** Variable name (for type='variable') or literal text (for type='literal') */
+    value: string;
+}
+/** Complete naming rule schema */
+interface NamingRuleSchema {
+    /** Schema version for future compatibility */
+    version: number;
+    /** Pattern segments for file names */
+    filePattern: PatternSegment[];
+    /** Pattern segments for folder names (can include / for nested paths) */
+    folderPattern: PatternSegment[];
+    /** Optional metadata */
+    metadata?: {
+        /** Optional name for the rule */
+        name?: string;
+        /** Optional description */
+        description?: string;
+        /** ISO date string when created */
+        createdAt?: string;
+        /** ISO date string when last updated */
+        updatedAt?: string;
+    };
+}
+/** Result of name generation */
+interface GeneratedNameResult {
+    /** Whether generation was successful */
+    success: boolean;
+    /** Generated name (if successful) */
+    name?: string;
+    /** Error message (if failed) */
+    error?: string;
+}
+/** Options for name generation functions */
+interface NameGenerationOptions {
+    /** Custom date formats to use (overrides defaults) */
+    dateFormats?: string[];
+    /** Date to use for date variables (defaults to current date) */
+    date?: Date;
+    /** Whether to preserve original file extension (default: true) */
+    preserveExtension?: boolean;
+    /** Counter value for {counter} variable */
+    counterValue?: number;
+    /** Number of digits for counter padding (default: 3) */
+    counterDigits?: number;
+}
+/** History entry for undo/redo in the configurator */
+interface NamingRuleHistoryEntry {
+    /** File pattern at this point */
+    filePattern: PatternSegment[];
+    /** Folder pattern at this point */
+    folderPattern: PatternSegment[];
+    /** Timestamp of the change */
+    timestamp: number;
+}
+/** Props for the NamingRuleConfigurator component */
+interface NamingRuleConfiguratorProps {
+    /** User-defined variables to include */
+    variables: NamingVariable[];
+    /** Initial schema to load (for editing existing rules) */
+    initialSchema?: NamingRuleSchema;
+    /** Callback when schema changes */
+    onChange?: (schema: NamingRuleSchema) => void;
+    /** Callback when user exports the schema */
+    onExport?: (schema: NamingRuleSchema) => void;
+    /** Callback when user imports a schema */
+    onImport?: (schema: NamingRuleSchema) => void;
+    /** Additional CSS class name */
+    className?: string;
+    /** Custom date formats (overrides config defaults) */
+    customDateFormats?: string[];
+    /** Read-only mode - disables editing */
+    readOnly?: boolean;
+    /** Original file name for preview (to show extension preservation) */
+    sampleFileName?: string;
+}
+/** State returned by useNamingRule hook */
+interface UseNamingRuleState {
+    /** Current file pattern */
+    filePattern: PatternSegment[];
+    /** Current folder pattern */
+    folderPattern: PatternSegment[];
+    /** Whether undo is available */
+    canUndo: boolean;
+    /** Whether redo is available */
+    canRedo: boolean;
+    /** Whether patterns have been modified from initial state */
+    isDirty: boolean;
+}
+/** Actions returned by useNamingRule hook */
+interface UseNamingRuleActions {
+    addToFilePattern: (segment: PatternSegment, index?: number) => void;
+    removeFromFilePattern: (id: string) => void;
+    updateFilePatternSegment: (id: string, value: string) => void;
+    reorderFilePattern: (fromIndex: number, toIndex: number) => void;
+    clearFilePattern: () => void;
+    addToFolderPattern: (segment: PatternSegment, index?: number) => void;
+    removeFromFolderPattern: (id: string) => void;
+    updateFolderPatternSegment: (id: string, value: string) => void;
+    reorderFolderPattern: (fromIndex: number, toIndex: number) => void;
+    clearFolderPattern: () => void;
+    undo: () => void;
+    redo: () => void;
+    getSchema: () => NamingRuleSchema;
+    loadSchema: (schema: NamingRuleSchema) => void;
+    reset: () => void;
+}
+/** Return type of useNamingRule hook */
+interface UseNamingRuleReturn extends UseNamingRuleState, UseNamingRuleActions {
+}
+
+/**
+ * Core types for the hazo_files package
+ */
+/** Supported storage provider types */
+type StorageProvider = 'local' | 'google_drive';
+/** File item representing a file in storage */
+interface FileItem {
+    id: string;
+    name: string;
+    path: string;
+    size: number;
+    mimeType: string;
+    createdAt: Date;
+    modifiedAt: Date;
+    isDirectory: false;
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Folder item representing a directory in storage */
+interface FolderItem {
+    id: string;
+    name: string;
+    path: string;
+    createdAt: Date;
+    modifiedAt: Date;
+    isDirectory: true;
+    parentId?: string;
+    children?: (FileItem | FolderItem)[];
+    metadata?: Record<string, unknown>;
+}
+/** Union type for file system items */
+type FileSystemItem = FileItem | FolderItem;
+/** Configuration for the file manager */
+interface HazoFilesConfig {
+    provider: StorageProvider;
+    local?: LocalStorageConfig;
+    google_drive?: GoogleDriveConfig;
+}
+/** Local storage specific configuration */
+interface LocalStorageConfig {
+    basePath: string;
+    allowedExtensions?: string[];
+    maxFileSize?: number;
+}
+/** Google Drive specific configuration */
+interface GoogleDriveConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    refreshToken?: string;
+    accessToken?: string;
+    rootFolderId?: string;
+}
+/** Result of file operations */
+interface OperationResult<T = void> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/** Progress callback for upload/download operations */
+type ProgressCallback = (progress: number, bytesTransferred: number, totalBytes: number) => void;
+/** Options for upload operations */
+interface UploadOptions {
+    overwrite?: boolean;
+    onProgress?: ProgressCallback;
+    metadata?: Record<string, unknown>;
+}
+/** Options for download operations */
+interface DownloadOptions {
+    onProgress?: ProgressCallback;
+}
+/** Options for list operations */
+interface ListOptions {
+    recursive?: boolean;
+    includeHidden?: boolean;
+    filter?: (item: FileSystemItem) => boolean;
+}
+/** Options for move operations */
+interface MoveOptions {
+    overwrite?: boolean;
+}
+/** Options for rename operations */
+interface RenameOptions {
+    overwrite?: boolean;
+}
+/** Tree node for folder tree representation */
+interface TreeNode {
+    id: string;
+    name: string;
+    path: string;
+    children: TreeNode[];
+    isExpanded?: boolean;
+    isLoading?: boolean;
+}
+/** UI State for the file browser */
+interface FileBrowserState {
+    currentPath: string;
+    selectedItem: FileSystemItem | null;
+    tree: TreeNode[];
+    files: FileSystemItem[];
+    isLoading: boolean;
+    error: string | null;
+}
+/**
+ * Interface that all storage modules must implement
+ */
+interface StorageModule {
+    /** Provider identifier */
+    readonly provider: StorageProvider;
+    /** Initialize the module with configuration */
+    initialize(config: HazoFilesConfig): Promise<void>;
+    /** Create a directory */
+    createDirectory(path: string): Promise<OperationResult<FolderItem>>;
+    /** Remove a directory */
+    removeDirectory(path: string, recursive?: boolean): Promise<OperationResult>;
+    /** Upload/save a file */
+    uploadFile(localPath: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /** Download a file */
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    /** Move a file or folder */
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    /** Delete a file */
+    deleteFile(path: string): Promise<OperationResult>;
+    /** Rename a file */
+    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    /** Rename a folder */
+    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    /** List contents of a directory */
+    listDirectory(path: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    /** Get item info */
+    getItem(path: string): Promise<OperationResult<FileSystemItem>>;
+    /** Check if item exists */
+    exists(path: string): Promise<boolean>;
+    /** Get folder tree structure */
+    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
+}
+
+/**
+ * File Manager Service
+ * Main service that provides a unified API for file operations
+ * Delegates to the appropriate storage module based on configuration
+ */
+
+interface FileManagerOptions {
+    /** Path to configuration file */
+    configPath?: string;
+    /** Configuration object (takes precedence over configPath) */
+    config?: HazoFilesConfig;
+    /** Auto-initialize on creation */
+    autoInit?: boolean;
+}
+/**
+ * FileManager - Main service class for file operations
+ */
+declare class FileManager {
+    private module;
+    private config;
+    private initialized;
+    private options;
+    constructor(options?: FileManagerOptions);
+    /**
+     * Initialize the file manager with configuration
+     */
+    initialize(config?: HazoFilesConfig): Promise<void>;
+    /**
+     * Initialize synchronously (uses sync config loading)
+     */
+    initializeSync(config?: HazoFilesConfig): void;
+    /**
+     * Check if manager is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): HazoFilesConfig | null;
+    /**
+     * Get the current provider
+     */
+    getProvider(): StorageProvider | null;
+    /**
+     * Get the underlying storage module
+     */
+    getModule(): StorageModule;
+    /**
+     * Ensure manager is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Create a directory at the specified path
+     */
+    createDirectory(path: string): Promise<OperationResult<FolderItem>>;
+    /**
+     * Remove a directory
+     * @param path - Directory path
+     * @param recursive - If true, remove directory and all contents
+     */
+    removeDirectory(path: string, recursive?: boolean): Promise<OperationResult>;
+    /**
+     * Upload/save a file
+     * @param source - File path, Buffer, or ReadableStream
+     * @param remotePath - Destination path in storage
+     * @param options - Upload options
+     */
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Download a file
+     * @param remotePath - Path in storage
+     * @param localPath - Optional local destination path
+     * @param options - Download options
+     */
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    /**
+     * Move a file or folder
+     * @param sourcePath - Current path
+     * @param destinationPath - New path
+     * @param options - Move options
+     */
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    /**
+     * Delete a file
+     */
+    deleteFile(path: string): Promise<OperationResult>;
+    /**
+     * Rename a file
+     * @param path - Current file path
+     * @param newName - New filename (not full path)
+     * @param options - Rename options
+     */
+    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Rename a folder
+     * @param path - Current folder path
+     * @param newName - New folder name (not full path)
+     * @param options - Rename options
+     */
+    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    /**
+     * List contents of a directory
+     * @param path - Directory path
+     * @param options - List options
+     */
+    listDirectory(path: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    /**
+     * Get information about a file or folder
+     */
+    getItem(path: string): Promise<OperationResult<FileSystemItem>>;
+    /**
+     * Check if a file or folder exists
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Get folder tree structure
+     * @param path - Starting path (default: root)
+     * @param depth - Maximum depth to traverse
+     */
+    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
+    /**
+     * Create a file with string content
+     */
+    writeFile(path: string, content: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Read a file as string
+     */
+    readFile(path: string): Promise<OperationResult<string>>;
+    /**
+     * Copy a file to a new location
+     */
+    copyFile(sourcePath: string, destinationPath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Ensure a directory exists (creates if needed)
+     */
+    ensureDirectory(path: string): Promise<OperationResult<FolderItem>>;
+}
+/**
+ * Create a new FileManager instance
+ */
+declare function createFileManager(options?: FileManagerOptions): FileManager;
+/**
+ * Create and initialize a FileManager instance
+ */
+declare function createInitializedFileManager(options?: FileManagerOptions): Promise<FileManager>;
+
+/**
+ * Configuration loader for hazo_files
+ * Reads configuration from hazo_files_config.ini file
+ */
+
+/**
+ * Parse INI configuration file and return typed config object
+ */
+declare function parseConfig(configContent: string): HazoFilesConfig;
+/**
+ * Load configuration from file
+ * @param configPath - Path to the config file, defaults to hazo_files_config.ini in current directory
+ */
+declare function loadConfig(configPath?: string): HazoFilesConfig;
+/**
+ * Load configuration asynchronously
+ */
+declare function loadConfigAsync(configPath?: string): Promise<HazoFilesConfig>;
+/**
+ * Generate a sample configuration file content
+ */
+declare function generateSampleConfig(): string;
+/**
+ * Save configuration to file
+ */
+declare function saveConfig(config: HazoFilesConfig, configPath?: string): Promise<void>;
+
+/**
+ * Common utility functions
+ */
+
+/**
+ * Create a successful operation result
+ */
+declare function successResult<T>(data?: T): OperationResult<T>;
+/**
+ * Create a failed operation result
+ */
+declare function errorResult<T = void>(error: string): OperationResult<T>;
+/**
+ * Generate a unique ID
+ */
+declare function generateId(): string;
+/**
+ * Format bytes to human readable string
+ */
+declare function formatBytes(bytes: number, decimals?: number): string;
+/**
+ * Check if item is a file
+ */
+declare function isFile(item: FileSystemItem): item is FileItem;
+/**
+ * Check if item is a folder
+ */
+declare function isFolder(item: FileSystemItem): item is FolderItem;
+/**
+ * Sort file system items (folders first, then alphabetically)
+ */
+declare function sortItems(items: FileSystemItem[]): FileSystemItem[];
+/**
+ * Filter items by search term
+ */
+declare function filterItems(items: FileSystemItem[], searchTerm: string): FileSystemItem[];
+/**
+ * Create a FileItem object
+ */
+declare function createFileItem(params: {
+    id: string;
+    name: string;
+    path: string;
+    size: number;
+    mimeType: string;
+    createdAt?: Date;
+    modifiedAt?: Date;
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+}): FileItem;
+/**
+ * Create a FolderItem object
+ */
+declare function createFolderItem(params: {
+    id: string;
+    name: string;
+    path: string;
+    createdAt?: Date;
+    modifiedAt?: Date;
+    parentId?: string;
+    children?: (FileItem | FolderItem)[];
+    metadata?: Record<string, unknown>;
+}): FolderItem;
+
+/**
+ * Path manipulation utilities
+ */
+/**
+ * Normalize a path (handle separators, remove trailing slashes, resolve . and ..)
+ */
+declare function normalizePath(inputPath: string): string;
+/**
+ * Join path segments
+ */
+declare function joinPath(...segments: string[]): string;
+/**
+ * Get the parent directory of a path
+ */
+declare function getParentPath(inputPath: string): string;
+/**
+ * Get the base name (file/folder name) from a path
+ */
+declare function getBaseName(inputPath: string): string;
+/**
+ * Get the directory name from a path (alias for getParentPath)
+ */
+declare function getDirName(inputPath: string): string;
+/**
+ * Get path segments as array
+ */
+declare function getPathSegments(inputPath: string): string[];
+/**
+ * Check if a path is a child of another path
+ */
+declare function isChildPath(parentPath: string, childPath: string): boolean;
+/**
+ * Get relative path from base to target
+ */
+declare function getRelativePath(basePath: string, targetPath: string): string;
+/**
+ * Validate a path for security issues
+ */
+declare function validatePath(inputPath: string, basePath?: string): void;
+/**
+ * Create a safe filename by removing/replacing invalid characters
+ */
+declare function sanitizeFilename(filename: string): string;
+/**
+ * Get file extension
+ */
+declare function getExtension(filename: string): string;
+/**
+ * Get filename without extension
+ */
+declare function getNameWithoutExtension(filename: string): string;
+/**
+ * Check if filename has specific extension
+ */
+declare function hasExtension(filename: string, extension: string): boolean;
+/**
+ * Get breadcrumb segments for a path
+ */
+declare function getBreadcrumbs(inputPath: string): Array<{
+    name: string;
+    path: string;
+}>;
+
+/**
+ * Base module class providing common functionality for all storage modules.
+ * All storage module implementations should extend this class.
+ */
+
+/**
+ * Abstract base class for storage modules.
+ * Provides common functionality and enforces the StorageModule interface.
+ */
+declare abstract class BaseStorageModule implements StorageModule {
+    abstract readonly provider: StorageProvider;
+    protected config: HazoFilesConfig | null;
+    protected _initialized: boolean;
+    /**
+     * Check if the module is initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Initialize the module with configuration.
+     * Subclasses should call super.initialize(config) first.
+     */
+    initialize(config: HazoFilesConfig): Promise<void>;
+    /**
+     * Ensure the module is initialized before operations
+     */
+    protected ensureInitialized(): void;
+    /**
+     * Get the provider-specific configuration
+     */
+    protected getProviderConfig<T>(): T;
+    abstract createDirectory(path: string): Promise<OperationResult<FolderItem>>;
+    abstract removeDirectory(path: string, recursive?: boolean): Promise<OperationResult>;
+    abstract uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    abstract downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    abstract moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    abstract deleteFile(path: string): Promise<OperationResult>;
+    abstract renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    abstract renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    abstract listDirectory(path: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    abstract getItem(path: string): Promise<OperationResult<FileSystemItem>>;
+    abstract exists(path: string): Promise<boolean>;
+    /**
+     * Get folder tree structure.
+     * Default implementation that can be overridden by subclasses for optimization.
+     */
+    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
+    /**
+     * Recursively build folder tree
+     */
+    protected buildTree(path: string, maxDepth: number, currentDepth: number): Promise<TreeNode[]>;
+    protected normalizePath: typeof normalizePath;
+    protected joinPath: typeof joinPath;
+    protected getBaseName: typeof getBaseName;
+    protected getParentPath: typeof getParentPath;
+    protected successResult: typeof successResult;
+    protected errorResult: typeof errorResult;
+}
+
+/**
+ * Local File System Storage Module
+ * Implements file operations using Node.js fs module
+ */
+
+declare class LocalStorageModule extends BaseStorageModule {
+    readonly provider: StorageProvider;
+    private basePath;
+    private allowedExtensions;
+    private maxFileSize;
+    initialize(config: HazoFilesConfig): Promise<void>;
+    /**
+     * Resolve a virtual path to an absolute file system path
+     */
+    private resolveFullPath;
+    /**
+     * Convert absolute path back to virtual path
+     */
+    private toVirtualPath;
+    /**
+     * Validate file extension against allowed list
+     */
+    private validateExtension;
+    /**
+     * Validate file size against maximum
+     */
+    private validateFileSize;
+    /**
+     * Create file/folder stats to FileSystemItem
+     */
+    private statToItem;
+    createDirectory(virtualPath: string): Promise<OperationResult<FolderItem>>;
+    removeDirectory(virtualPath: string, recursive?: boolean): Promise<OperationResult>;
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    deleteFile(virtualPath: string): Promise<OperationResult>;
+    renameFile(virtualPath: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    renameFolder(virtualPath: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    listDirectory(virtualPath: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    getItem(virtualPath: string): Promise<OperationResult<FileSystemItem>>;
+    exists(virtualPath: string): Promise<boolean>;
+}
+/**
+ * Factory function to create a LocalStorageModule instance
+ */
+declare function createLocalModule(): LocalStorageModule;
+
+/**
+ * Google Drive OAuth Authentication Handler
+ * Manages OAuth flow, token storage, and token refresh
+ */
+
+interface GoogleAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+interface TokenData {
+    accessToken: string;
+    refreshToken: string;
+    expiryDate?: number;
+    scope?: string;
+}
+interface AuthCallbacks {
+    onTokensUpdated?: (tokens: TokenData) => Promise<void>;
+    getStoredTokens?: () => Promise<TokenData | null>;
+}
+/**
+ * Google Drive Authentication Manager
+ */
+declare class GoogleDriveAuth {
+    private oauth2Client;
+    private callbacks;
+    private tokens;
+    constructor(config: GoogleAuthConfig, callbacks?: AuthCallbacks);
+    /**
+     * Get the OAuth2 client instance
+     */
+    getClient(): OAuth2Client;
+    /**
+     * Generate the authorization URL for OAuth consent
+     */
+    getAuthUrl(state?: string): string;
+    /**
+     * Exchange authorization code for tokens
+     */
+    exchangeCodeForTokens(code: string): Promise<TokenData>;
+    /**
+     * Set tokens directly (e.g., from stored tokens)
+     */
+    setTokens(tokens: TokenData): Promise<void>;
+    /**
+     * Load tokens from storage using callback
+     */
+    loadStoredTokens(): Promise<boolean>;
+    /**
+     * Check if authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current tokens
+     */
+    getTokens(): TokenData | null;
+    /**
+     * Refresh the access token
+     */
+    refreshAccessToken(): Promise<TokenData>;
+    /**
+     * Revoke access (disconnect)
+     */
+    revokeAccess(): Promise<void>;
+    /**
+     * Check if token is expired or will expire soon
+     */
+    isTokenExpired(bufferSeconds?: number): boolean;
+    /**
+     * Ensure valid access token (refresh if needed)
+     */
+    ensureValidToken(): Promise<void>;
+}
+/**
+ * Create a new GoogleDriveAuth instance
+ */
+declare function createGoogleDriveAuth(config: GoogleAuthConfig, callbacks?: AuthCallbacks): GoogleDriveAuth;
+
+/**
+ * Google Drive Storage Module
+ * Implements file operations using Google Drive API
+ */
+
+declare class GoogleDriveModule extends BaseStorageModule {
+    readonly provider: StorageProvider;
+    private auth;
+    private drive;
+    private rootFolderId;
+    private authCallbacks;
+    /**
+     * Set authentication callbacks for token persistence
+     */
+    setAuthCallbacks(callbacks: AuthCallbacks): void;
+    initialize(config: HazoFilesConfig): Promise<void>;
+    /**
+     * Get the auth instance for OAuth flow
+     */
+    getAuth(): GoogleDriveAuth;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Authenticate with provided tokens
+     */
+    authenticate(tokens: TokenData): Promise<void>;
+    /**
+     * Ensure authenticated before operations
+     */
+    private ensureAuthenticated;
+    /**
+     * Get folder ID from path (creates folders if needed for certain operations)
+     */
+    private getIdFromPath;
+    /**
+     * Convert Drive file to FileSystemItem
+     */
+    private driveFileToItem;
+    createDirectory(virtualPath: string): Promise<OperationResult<FolderItem>>;
+    removeDirectory(virtualPath: string, recursive?: boolean): Promise<OperationResult>;
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    moveItem(sourcePath: string, destinationPath: string, _options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    deleteFile(virtualPath: string): Promise<OperationResult>;
+    renameFile(virtualPath: string, newName: string, _options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    renameFolder(virtualPath: string, newName: string, _options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    listDirectory(virtualPath: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    getItem(virtualPath: string): Promise<OperationResult<FileSystemItem>>;
+    exists(virtualPath: string): Promise<boolean>;
+    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
+}
+/**
+ * Factory function to create a GoogleDriveModule instance
+ */
+declare function createGoogleDriveModule(): GoogleDriveModule;
+
+/**
+ * Module Registry
+ * Central registry for all storage modules
+ */
+
+/**
+ * Factory function type for creating modules
+ */
+type ModuleFactory = () => StorageModule;
+/**
+ * Get a list of registered providers
+ */
+declare function getRegisteredProviders(): StorageProvider[];
+/**
+ * Check if a provider is registered
+ */
+declare function isProviderRegistered(provider: string): provider is StorageProvider;
+/**
+ * Create a storage module instance for the given provider
+ */
+declare function createModule(provider: StorageProvider): StorageModule;
+/**
+ * Create and initialize a storage module with configuration
+ */
+declare function createAndInitializeModule(config: HazoFilesConfig): Promise<StorageModule>;
+/**
+ * Register a custom module (for extensibility)
+ */
+declare function registerModule(provider: StorageProvider, factory: ModuleFactory): void;
+
+/**
+ * Custom error classes for hazo_files
+ */
+declare class HazoFilesError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+declare class FileNotFoundError extends HazoFilesError {
+    constructor(path: string);
+}
+declare class DirectoryNotFoundError extends HazoFilesError {
+    constructor(path: string);
+}
+declare class FileExistsError extends HazoFilesError {
+    constructor(path: string);
+}
+declare class DirectoryExistsError extends HazoFilesError {
+    constructor(path: string);
+}
+declare class DirectoryNotEmptyError extends HazoFilesError {
+    constructor(path: string);
+}
+declare class PermissionDeniedError extends HazoFilesError {
+    constructor(path: string, operation: string);
+}
+declare class InvalidPathError extends HazoFilesError {
+    constructor(path: string, reason: string);
+}
+declare class FileTooLargeError extends HazoFilesError {
+    constructor(path: string, size: number, maxSize: number);
+}
+declare class InvalidExtensionError extends HazoFilesError {
+    constructor(path: string, extension: string, allowedExtensions: string[]);
+}
+declare class AuthenticationError extends HazoFilesError {
+    constructor(provider: string, message: string);
+}
+declare class ConfigurationError extends HazoFilesError {
+    constructor(message: string);
+}
+declare class OperationError extends HazoFilesError {
+    constructor(operation: string, message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * MIME type utilities
+ */
+/**
+ * Get MIME type from file extension
+ */
+declare function getMimeType(filename: string): string;
+/**
+ * Get extension from MIME type
+ */
+declare function getExtensionFromMime(mimeType: string): string;
+/**
+ * Check if file is an image
+ */
+declare function isImage(filenameOrMime: string): boolean;
+/**
+ * Check if file is a video
+ */
+declare function isVideo(filenameOrMime: string): boolean;
+/**
+ * Check if file is audio
+ */
+declare function isAudio(filenameOrMime: string): boolean;
+/**
+ * Check if file is a text file
+ */
+declare function isText(filenameOrMime: string): boolean;
+/**
+ * Check if file is a document (PDF, Word, Excel, etc.)
+ */
+declare function isDocument(filenameOrMime: string): boolean;
+/**
+ * Check if file can be previewed in browser
+ */
+declare function isPreviewable(filenameOrMime: string): boolean;
+/**
+ * Get file type category
+ */
+declare function getFileCategory(filenameOrMime: string): 'image' | 'video' | 'audio' | 'document' | 'text' | 'other';
+
+/**
+ * Naming utilities for hazo_files package
+ * Functions for generating file/folder names from naming rule schemas
+ */
+
+/** Default date formats supported by the system */
+declare const DEFAULT_DATE_FORMATS: readonly ["YYYY", "YY", "MM", "M", "DD", "D", "MMM", "MMMM", "YYYY-MM-DD", "YYYY-MMM-DD", "DD-MM-YYYY", "MM-DD-YYYY"];
+/** System date variables with descriptions */
+declare const SYSTEM_DATE_VARIABLES: NamingVariable[];
+/** System file metadata variables */
+declare const SYSTEM_FILE_VARIABLES: NamingVariable[];
+/** System counter variables */
+declare const SYSTEM_COUNTER_VARIABLES: NamingVariable[];
+/** All system variables combined */
+declare const ALL_SYSTEM_VARIABLES: NamingVariable[];
+/**
+ * Format a date according to the format token
+ */
+declare function formatDateToken(date: Date, format: string): string;
+/**
+ * Check if a variable name is a date format
+ */
+declare function isDateVariable(variableName: string, dateFormats?: readonly string[]): boolean;
+/**
+ * Check if a variable name is a file metadata variable
+ */
+declare function isFileMetadataVariable(variableName: string): boolean;
+/**
+ * Check if a variable name is the counter variable
+ */
+declare function isCounterVariable(variableName: string): boolean;
+/**
+ * Format counter value with padding
+ */
+declare function formatCounter(value: number, digits?: number): string;
+/**
+ * Get file metadata values from a filename
+ */
+declare function getFileMetadataValues(filename?: string): Record<string, string>;
+/**
+ * Generate a folder name using the schema and variable values
+ * Supports nested paths with / separators in the pattern
+ */
+declare function hazo_files_generate_folder_name(schema: NamingRuleSchema, variables: Record<string, string>, options?: NameGenerationOptions): GeneratedNameResult;
+/**
+ * Generate a file name using the schema and variable values
+ * Optionally preserves the original file extension
+ */
+declare function hazo_files_generate_file_name(schema: NamingRuleSchema, variables: Record<string, string>, originalFileName?: string, options?: NameGenerationOptions): GeneratedNameResult;
+/**
+ * Validate a naming rule schema
+ */
+declare function validateNamingRuleSchema(schema: unknown): schema is NamingRuleSchema;
+/**
+ * Create an empty naming rule schema
+ */
+declare function createEmptyNamingRuleSchema(): NamingRuleSchema;
+/**
+ * Generate a unique ID for pattern segments
+ */
+declare function generateSegmentId(): string;
+/**
+ * Create a variable segment
+ */
+declare function createVariableSegment(variableName: string): PatternSegment;
+/**
+ * Create a literal segment
+ */
+declare function createLiteralSegment(text: string): PatternSegment;
+/**
+ * Convert pattern to human-readable string representation
+ */
+declare function patternToString(pattern: PatternSegment[]): string;
+/**
+ * Parse a pattern string to segments
+ * Handles {variable} syntax for variables, everything else is literal
+ */
+declare function parsePatternString(patternStr: string): PatternSegment[];
+/**
+ * Clone a pattern with new segment IDs
+ */
+declare function clonePattern(pattern: PatternSegment[]): PatternSegment[];
+/**
+ * Get preview values for all system variables
+ * Uses the current date and provided options
+ */
+declare function getSystemVariablePreviewValues(date?: Date, options?: {
+    counterValue?: number;
+    counterDigits?: number;
+    originalFileName?: string;
+}): Record<string, string>;
+/**
+ * Generate a preview name from a pattern using example values
+ */
+declare function generatePreviewName(pattern: PatternSegment[], userVariables: NamingVariable[], options?: {
+    date?: Date;
+    counterValue?: number;
+    counterDigits?: number;
+    originalFileName?: string;
+}): string;
+
+export { ALL_SYSTEM_VARIABLES, type AuthCallbacks, AuthenticationError, ConfigurationError, DEFAULT_DATE_FORMATS, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type FileBrowserState, FileExistsError, type FileItem, FileManager, type FileManagerOptions, FileNotFoundError, type FileSystemItem, FileTooLargeError, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, type HazoFilesConfig, HazoFilesError, InvalidExtensionError, InvalidPathError, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MoveOptions, type NameGenerationOptions, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, type NamingVariable, OperationError, type OperationResult, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, type TreeNode, type UploadOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, clonePattern, createAndInitializeModule, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createLiteralSegment, createLocalModule, createModule, createVariableSegment, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateId, generatePreviewName, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getFileCategory, getFileMetadataValues, getMimeType, getNameWithoutExtension, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSystemVariablePreviewValues, hasExtension, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, normalizePath, parseConfig, parsePatternString, patternToString, registerModule, sanitizeFilename, saveConfig, sortItems, successResult, validateNamingRuleSchema, validatePath };