hazo_files 1.0.2 → 1.1.0

package/.env.example

@@ -0,0 +1,23 @@
+# Google Drive OAuth Configuration
+# Get these credentials from Google Cloud Console
+# https://console.cloud.google.com
+
+# Google Drive Client ID (required for Google Drive OAuth)
+HAZO_GOOGLE_DRIVE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+
+# Google Drive Client Secret (required for Google Drive OAuth)
+HAZO_GOOGLE_DRIVE_CLIENT_SECRET=your-client-secret
+
+# OAuth Redirect URI (must match Google Cloud Console settings)
+HAZO_GOOGLE_DRIVE_REDIRECT_URI=http://localhost:3000/api/auth/callback/google
+
+# Google Drive Refresh Token (obtained after OAuth flow)
+# Leave empty initially, will be set after first authentication
+HAZO_GOOGLE_DRIVE_REFRESH_TOKEN=
+
+# Google Drive Access Token (optional, auto-refreshed)
+HAZO_GOOGLE_DRIVE_ACCESS_TOKEN=
+
+# Google Drive Root Folder ID (optional, use specific folder as root)
+# Leave empty to use the root of Google Drive
+HAZO_GOOGLE_DRIVE_ROOT_FOLDER_ID=

package/README.md

@@ -480,7 +480,7 @@ The `FileBrowser` is a complete, drop-in file management UI with:
 - File preview (images, text, PDFs)
 - Context menus and actions
 - Upload, download, rename, delete operations
-- Drag-and-drop support (if implemented in API)
+- Drag-and-drop file moving between folders
 
 ```typescript
 import { FileBrowser } from 'hazo_files/ui';
@@ -499,6 +499,38 @@ import { FileBrowser } from 'hazo_files/ui';
 />
 ```
 
+#### Drag-and-Drop File Moving
+
+The FileBrowser includes built-in drag-and-drop functionality for moving files and folders:
+
+**Features**:
+- Drag files/folders from the file list
+- Drop onto folders in the sidebar tree or main file list
+- Visual feedback with opacity and colored borders during drag
+- Prevents invalid operations (dropping on self, into current parent, folder into descendant)
+- Shows dragged item preview during drag operation
+
+**How to use**:
+1. Click and hold on any file or folder in the file list
+2. Drag it over a folder in either the tree sidebar or file list
+3. Valid drop targets show a green ring/background
+4. Release to move the item to the new location
+
+**Technical requirements**:
+- Requires `@dnd-kit/core` peer dependency (already included for NamingRuleConfigurator)
+- API must implement `moveItem(sourcePath, destinationPath)` method
+- Automatically validates drop targets to prevent invalid moves
+
+**Visual feedback**:
+- **Dragging**: Item becomes semi-transparent (opacity-50)
+- **Valid drop target**: Green ring (`ring-2 ring-green-500`) and background (`bg-green-50`)
+- **Drag preview**: Shows file/folder icon and name following cursor
+
+**ID patterns used**:
+- File items: `file-item-{path}` (draggable)
+- Folder tree drops: `folder-drop-tree-{path}` (droppable)
+- Folder list drops: `folder-drop-list-{path}` (droppable)
+
 ### Individual Components
 
 You can also use individual components:

package/dist/index.d.mts

@@ -133,6 +133,74 @@ interface UseNamingRuleActions {
 interface UseNamingRuleReturn extends UseNamingRuleState, UseNamingRuleActions {
 }
 
+/**
+ * Metadata tracking types for hazo_files
+ * Used for database tracking of file operations
+ */
+
+/**
+ * Record stored in the hazo_files database table
+ * Extends Record<string, unknown> for compatibility with hazo_connect CrudService
+ */
+interface FileMetadataRecord extends Record<string, unknown> {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** File or folder name */
+    filename: string;
+    /** MIME type for files, 'folder' for directories */
+    file_type: string;
+    /** Custom metadata as JSON string */
+    file_data: string;
+    /** ISO timestamp when record was created */
+    created_at: string;
+    /** ISO timestamp of last access or modification */
+    changed_at: string;
+    /** Virtual path in storage */
+    file_path: string;
+    /** Storage provider type */
+    storage_type: StorageProvider;
+}
+/**
+ * Input for creating a new metadata record
+ */
+interface FileMetadataInput {
+    filename: string;
+    file_type: string;
+    file_data?: Record<string, unknown>;
+    file_path: string;
+    storage_type: StorageProvider;
+}
+/**
+ * Input for updating an existing metadata record
+ */
+interface FileMetadataUpdate {
+    filename?: string;
+    file_type?: string;
+    file_data?: Record<string, unknown>;
+    file_path?: string;
+    changed_at?: string;
+}
+/**
+ * Configuration for database tracking
+ */
+interface DatabaseTrackingConfig {
+    /** Enable database tracking (default: false) */
+    enabled: boolean;
+    /** Table name for metadata (default: 'hazo_files') */
+    tableName?: string;
+    /** Track download operations as access (default: true) */
+    trackDownloads?: boolean;
+    /** Log database errors instead of failing silently (default: true) */
+    logErrors?: boolean;
+}
+/**
+ * Options for TrackedFileManager
+ */
+interface TrackedFileManagerOptions {
+    /** Database tracking configuration */
+    tracking?: DatabaseTrackingConfig;
+}
+
 /**
  * Core types for the hazo_files package
  */
@@ -416,6 +484,208 @@ declare function createFileManager(options?: FileManagerOptions): FileManager;
  */
 declare function createInitializedFileManager(options?: FileManagerOptions): Promise<FileManager>;
 
+/**
+ * File Metadata Service
+ * Handles database operations for tracking file metadata
+ * Uses hazo_connect for database interactions
+ */
+
+/**
+ * Logger interface compatible with hazo_connect
+ */
+interface MetadataLogger {
+    debug?(message: string, data?: Record<string, unknown>): void;
+    info?(message: string, data?: Record<string, unknown>): void;
+    warn?(message: string, data?: Record<string, unknown>): void;
+    error?(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Minimal CRUD service interface (compatible with hazo_connect CrudService)
+ */
+interface CrudServiceLike<T> {
+    list(configure?: (qb: unknown) => unknown): Promise<T[]>;
+    findBy(criteria: Record<string, unknown>): Promise<T[]>;
+    findOneBy(criteria: Record<string, unknown>): Promise<T | null>;
+    insert(data: Partial<T> | Partial<T>[]): Promise<T[]>;
+    updateById(id: unknown, patch: Partial<T>): Promise<T[]>;
+    deleteById(id: unknown): Promise<void>;
+}
+/**
+ * Options for FileMetadataService
+ */
+interface FileMetadataServiceOptions {
+    /** Table name (default: 'hazo_files') */
+    tableName?: string;
+    /** Logger for diagnostics */
+    logger?: MetadataLogger;
+    /** Log errors to console (default: true) */
+    logErrors?: boolean;
+}
+/**
+ * File Metadata Service
+ * Provides methods to track file operations in a database
+ */
+declare class FileMetadataService {
+    private crud;
+    private logger?;
+    private logErrors;
+    constructor(crudService: CrudServiceLike<FileMetadataRecord>, options?: FileMetadataServiceOptions);
+    /**
+     * Generate ISO timestamp
+     */
+    private now;
+    /**
+     * Log an error if logging is enabled
+     */
+    private logError;
+    /**
+     * Record a file upload
+     */
+    recordUpload(input: FileMetadataInput): Promise<FileMetadataRecord | null>;
+    /**
+     * Record a directory creation
+     */
+    recordDirectoryCreation(path: string, storageType: StorageProvider, metadata?: Record<string, unknown>): Promise<FileMetadataRecord | null>;
+    /**
+     * Record a file access (download)
+     */
+    recordAccess(path: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Record a file deletion
+     */
+    recordDelete(path: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Record a directory deletion (recursive)
+     */
+    recordDirectoryDelete(path: string, storageType: StorageProvider, recursive: boolean): Promise<boolean>;
+    /**
+     * Record a file or folder move
+     */
+    recordMove(sourcePath: string, destinationPath: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Record a file or folder rename
+     */
+    recordRename(path: string, newName: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Find a record by path and storage type
+     */
+    findByPath(path: string, storageType: StorageProvider): Promise<FileMetadataRecord | null>;
+    /**
+     * Find all records for a storage type
+     */
+    findByStorageType(storageType: StorageProvider): Promise<FileMetadataRecord[]>;
+    /**
+     * Find all records in a directory
+     */
+    findInDirectory(directoryPath: string, storageType: StorageProvider): Promise<FileMetadataRecord[]>;
+    /**
+     * Update custom metadata for a file
+     */
+    updateMetadata(path: string, storageType: StorageProvider, metadata: Record<string, unknown>): Promise<boolean>;
+}
+/**
+ * Create a FileMetadataService instance
+ */
+declare function createFileMetadataService(crudService: CrudServiceLike<FileMetadataRecord>, options?: FileMetadataServiceOptions): FileMetadataService;
+
+/**
+ * Tracked File Manager
+ * Extends FileManager to add database tracking of file operations
+ */
+
+/**
+ * Options for creating a TrackedFileManager
+ */
+interface TrackedFileManagerFullOptions extends FileManagerOptions {
+    /** CRUD service for database operations (from hazo_connect) */
+    crudService?: CrudServiceLike<FileMetadataRecord>;
+    /** Database tracking configuration */
+    tracking?: DatabaseTrackingConfig;
+}
+/**
+ * TrackedFileManager - File manager with database tracking
+ *
+ * Extends FileManager to record file operations in a database table.
+ * Database operations are non-blocking and failures don't affect file operations.
+ */
+declare class TrackedFileManager extends FileManager {
+    private metadataService;
+    private trackingConfig;
+    constructor(options?: TrackedFileManagerFullOptions);
+    /**
+     * Check if tracking is enabled and service is available
+     */
+    private isTrackingEnabled;
+    /**
+     * Get the current storage provider type
+     */
+    private getStorageType;
+    /**
+     * Create a directory and record it in the database
+     */
+    createDirectory(path: string): Promise<OperationResult<FolderItem>>;
+    /**
+     * Remove a directory and delete its record from the database
+     */
+    removeDirectory(path: string, recursive?: boolean): Promise<OperationResult>;
+    /**
+     * Upload a file and record it in the database
+     */
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Download a file and optionally track access
+     */
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    /**
+     * Move a file or folder and update its path in the database
+     */
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    /**
+     * Delete a file and remove its record from the database
+     */
+    deleteFile(path: string): Promise<OperationResult>;
+    /**
+     * Rename a file and update its record in the database
+     */
+    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Rename a folder and update its record in the database
+     */
+    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    /**
+     * Write a file with string content and track it
+     */
+    writeFile(path: string, content: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Read a file and optionally track access
+     */
+    readFile(path: string): Promise<OperationResult<string>>;
+    /**
+     * Copy a file and track the new file
+     */
+    copyFile(sourcePath: string, destinationPath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Get the metadata service for direct access
+     */
+    getMetadataService(): FileMetadataService | null;
+    /**
+     * Check if database tracking is enabled
+     */
+    isTrackingActive(): boolean;
+    /**
+     * Get tracking configuration
+     */
+    getTrackingConfig(): DatabaseTrackingConfig;
+}
+/**
+ * Create a new TrackedFileManager instance
+ */
+declare function createTrackedFileManager(options?: TrackedFileManagerFullOptions): TrackedFileManager;
+/**
+ * Create and initialize a TrackedFileManager instance
+ */
+declare function createInitializedTrackedFileManager(options?: TrackedFileManagerFullOptions): Promise<TrackedFileManager>;
+
 /**
  * Configuration loader for hazo_files
  * Reads configuration from hazo_files_config.ini file
@@ -1028,4 +1298,4 @@ declare function generatePreviewName(pattern: PatternSegment[], userVariables: N
     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 };
+export { ALL_SYSTEM_VARIABLES, type AuthCallbacks, AuthenticationError, ConfigurationError, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type FileBrowserState, FileExistsError, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, 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 MetadataLogger, 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, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TreeNode, type UploadOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, clonePattern, createAndInitializeModule, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLiteralSegment, createLocalModule, createModule, createTrackedFileManager, 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 };

package/dist/index.d.ts

@@ -133,6 +133,74 @@ interface UseNamingRuleActions {
 interface UseNamingRuleReturn extends UseNamingRuleState, UseNamingRuleActions {
 }
 
+/**
+ * Metadata tracking types for hazo_files
+ * Used for database tracking of file operations
+ */
+
+/**
+ * Record stored in the hazo_files database table
+ * Extends Record<string, unknown> for compatibility with hazo_connect CrudService
+ */
+interface FileMetadataRecord extends Record<string, unknown> {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** File or folder name */
+    filename: string;
+    /** MIME type for files, 'folder' for directories */
+    file_type: string;
+    /** Custom metadata as JSON string */
+    file_data: string;
+    /** ISO timestamp when record was created */
+    created_at: string;
+    /** ISO timestamp of last access or modification */
+    changed_at: string;
+    /** Virtual path in storage */
+    file_path: string;
+    /** Storage provider type */
+    storage_type: StorageProvider;
+}
+/**
+ * Input for creating a new metadata record
+ */
+interface FileMetadataInput {
+    filename: string;
+    file_type: string;
+    file_data?: Record<string, unknown>;
+    file_path: string;
+    storage_type: StorageProvider;
+}
+/**
+ * Input for updating an existing metadata record
+ */
+interface FileMetadataUpdate {
+    filename?: string;
+    file_type?: string;
+    file_data?: Record<string, unknown>;
+    file_path?: string;
+    changed_at?: string;
+}
+/**
+ * Configuration for database tracking
+ */
+interface DatabaseTrackingConfig {
+    /** Enable database tracking (default: false) */
+    enabled: boolean;
+    /** Table name for metadata (default: 'hazo_files') */
+    tableName?: string;
+    /** Track download operations as access (default: true) */
+    trackDownloads?: boolean;
+    /** Log database errors instead of failing silently (default: true) */
+    logErrors?: boolean;
+}
+/**
+ * Options for TrackedFileManager
+ */
+interface TrackedFileManagerOptions {
+    /** Database tracking configuration */
+    tracking?: DatabaseTrackingConfig;
+}
+
 /**
  * Core types for the hazo_files package
  */
@@ -416,6 +484,208 @@ declare function createFileManager(options?: FileManagerOptions): FileManager;
  */
 declare function createInitializedFileManager(options?: FileManagerOptions): Promise<FileManager>;
 
+/**
+ * File Metadata Service
+ * Handles database operations for tracking file metadata
+ * Uses hazo_connect for database interactions
+ */
+
+/**
+ * Logger interface compatible with hazo_connect
+ */
+interface MetadataLogger {
+    debug?(message: string, data?: Record<string, unknown>): void;
+    info?(message: string, data?: Record<string, unknown>): void;
+    warn?(message: string, data?: Record<string, unknown>): void;
+    error?(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Minimal CRUD service interface (compatible with hazo_connect CrudService)
+ */
+interface CrudServiceLike<T> {
+    list(configure?: (qb: unknown) => unknown): Promise<T[]>;
+    findBy(criteria: Record<string, unknown>): Promise<T[]>;
+    findOneBy(criteria: Record<string, unknown>): Promise<T | null>;
+    insert(data: Partial<T> | Partial<T>[]): Promise<T[]>;
+    updateById(id: unknown, patch: Partial<T>): Promise<T[]>;
+    deleteById(id: unknown): Promise<void>;
+}
+/**
+ * Options for FileMetadataService
+ */
+interface FileMetadataServiceOptions {
+    /** Table name (default: 'hazo_files') */
+    tableName?: string;
+    /** Logger for diagnostics */
+    logger?: MetadataLogger;
+    /** Log errors to console (default: true) */
+    logErrors?: boolean;
+}
+/**
+ * File Metadata Service
+ * Provides methods to track file operations in a database
+ */
+declare class FileMetadataService {
+    private crud;
+    private logger?;
+    private logErrors;
+    constructor(crudService: CrudServiceLike<FileMetadataRecord>, options?: FileMetadataServiceOptions);
+    /**
+     * Generate ISO timestamp
+     */
+    private now;
+    /**
+     * Log an error if logging is enabled
+     */
+    private logError;
+    /**
+     * Record a file upload
+     */
+    recordUpload(input: FileMetadataInput): Promise<FileMetadataRecord | null>;
+    /**
+     * Record a directory creation
+     */
+    recordDirectoryCreation(path: string, storageType: StorageProvider, metadata?: Record<string, unknown>): Promise<FileMetadataRecord | null>;
+    /**
+     * Record a file access (download)
+     */
+    recordAccess(path: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Record a file deletion
+     */
+    recordDelete(path: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Record a directory deletion (recursive)
+     */
+    recordDirectoryDelete(path: string, storageType: StorageProvider, recursive: boolean): Promise<boolean>;
+    /**
+     * Record a file or folder move
+     */
+    recordMove(sourcePath: string, destinationPath: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Record a file or folder rename
+     */
+    recordRename(path: string, newName: string, storageType: StorageProvider): Promise<boolean>;
+    /**
+     * Find a record by path and storage type
+     */
+    findByPath(path: string, storageType: StorageProvider): Promise<FileMetadataRecord | null>;
+    /**
+     * Find all records for a storage type
+     */
+    findByStorageType(storageType: StorageProvider): Promise<FileMetadataRecord[]>;
+    /**
+     * Find all records in a directory
+     */
+    findInDirectory(directoryPath: string, storageType: StorageProvider): Promise<FileMetadataRecord[]>;
+    /**
+     * Update custom metadata for a file
+     */
+    updateMetadata(path: string, storageType: StorageProvider, metadata: Record<string, unknown>): Promise<boolean>;
+}
+/**
+ * Create a FileMetadataService instance
+ */
+declare function createFileMetadataService(crudService: CrudServiceLike<FileMetadataRecord>, options?: FileMetadataServiceOptions): FileMetadataService;
+
+/**
+ * Tracked File Manager
+ * Extends FileManager to add database tracking of file operations
+ */
+
+/**
+ * Options for creating a TrackedFileManager
+ */
+interface TrackedFileManagerFullOptions extends FileManagerOptions {
+    /** CRUD service for database operations (from hazo_connect) */
+    crudService?: CrudServiceLike<FileMetadataRecord>;
+    /** Database tracking configuration */
+    tracking?: DatabaseTrackingConfig;
+}
+/**
+ * TrackedFileManager - File manager with database tracking
+ *
+ * Extends FileManager to record file operations in a database table.
+ * Database operations are non-blocking and failures don't affect file operations.
+ */
+declare class TrackedFileManager extends FileManager {
+    private metadataService;
+    private trackingConfig;
+    constructor(options?: TrackedFileManagerFullOptions);
+    /**
+     * Check if tracking is enabled and service is available
+     */
+    private isTrackingEnabled;
+    /**
+     * Get the current storage provider type
+     */
+    private getStorageType;
+    /**
+     * Create a directory and record it in the database
+     */
+    createDirectory(path: string): Promise<OperationResult<FolderItem>>;
+    /**
+     * Remove a directory and delete its record from the database
+     */
+    removeDirectory(path: string, recursive?: boolean): Promise<OperationResult>;
+    /**
+     * Upload a file and record it in the database
+     */
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Download a file and optionally track access
+     */
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    /**
+     * Move a file or folder and update its path in the database
+     */
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    /**
+     * Delete a file and remove its record from the database
+     */
+    deleteFile(path: string): Promise<OperationResult>;
+    /**
+     * Rename a file and update its record in the database
+     */
+    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Rename a folder and update its record in the database
+     */
+    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    /**
+     * Write a file with string content and track it
+     */
+    writeFile(path: string, content: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Read a file and optionally track access
+     */
+    readFile(path: string): Promise<OperationResult<string>>;
+    /**
+     * Copy a file and track the new file
+     */
+    copyFile(sourcePath: string, destinationPath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Get the metadata service for direct access
+     */
+    getMetadataService(): FileMetadataService | null;
+    /**
+     * Check if database tracking is enabled
+     */
+    isTrackingActive(): boolean;
+    /**
+     * Get tracking configuration
+     */
+    getTrackingConfig(): DatabaseTrackingConfig;
+}
+/**
+ * Create a new TrackedFileManager instance
+ */
+declare function createTrackedFileManager(options?: TrackedFileManagerFullOptions): TrackedFileManager;
+/**
+ * Create and initialize a TrackedFileManager instance
+ */
+declare function createInitializedTrackedFileManager(options?: TrackedFileManagerFullOptions): Promise<TrackedFileManager>;
+
 /**
  * Configuration loader for hazo_files
  * Reads configuration from hazo_files_config.ini file
@@ -1028,4 +1298,4 @@ declare function generatePreviewName(pattern: PatternSegment[], userVariables: N
     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 };
+export { ALL_SYSTEM_VARIABLES, type AuthCallbacks, AuthenticationError, ConfigurationError, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type FileBrowserState, FileExistsError, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, 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 MetadataLogger, 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, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TreeNode, type UploadOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, clonePattern, createAndInitializeModule, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLiteralSegment, createLocalModule, createModule, createTrackedFileManager, 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 };