hazo_files 1.4.4 → 1.4.6

package/README.md

@@ -45,13 +45,20 @@ For the NamingRuleConfigurator component (drag-and-drop interface), also install
 npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
 ```
 
+For cloud storage providers (install only what you need):
+
+```bash
+npm install googleapis        # Google Drive support
+npm install dropbox           # Dropbox support
+```
+
 For database tracking and LLM extraction features (optional):
 
 ```bash
 npm install hazo_connect      # Database tracking
 npm install hazo_llm_api      # LLM document extraction
 npm install server-only       # Server-side safety (recommended)
-# Note: xxhash-wasm is included automatically as a dependency
+npm install xxhash-wasm       # File change detection (optional)
 ```
 
 ### Tailwind CSS v4 Setup (Required for UI Components)
@@ -1566,6 +1573,51 @@ import { registerModule } from 'hazo_files';
 registerModule('s3', () => new S3StorageModule());
 ```
 
+## Debug Integration (hazo_debug)
+
+hazo_files emits structured `file_operation` log entries with timing, storage provider, and operation type on every file operation. You can forward these to `hazo_debug` for a visual Files tab in the debug panel.
+
+The integration uses the existing `logger` option — no direct dependency on hazo_debug is needed:
+
+```typescript
+import { createHazoFilesServer } from 'hazo_files/server';
+import { use_debug_files } from 'hazo_debug/client';
+
+// In your server setup:
+const { log_file_op } = use_debug_files();
+
+const { fileManager } = await createHazoFilesServer({
+  config: { provider: 'local', local: { basePath: './files' } },
+  logger: {
+    info: (msg, data) => {
+      if (msg === 'file_operation') log_file_op(data);
+    },
+    error: (msg, data) => {
+      if (msg === 'file_operation') log_file_op(data);
+    },
+  },
+});
+```
+
+Every `file_operation` log entry includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `operation` | `string` | `'upload'` \| `'download'` \| `'delete'` \| `'move'` \| `'list'` \| `'extract'` |
+| `file_name` | `string?` | File name |
+| `file_path` | `string?` | Virtual file path |
+| `mime_type` | `string?` | MIME type |
+| `size_bytes` | `number?` | File size in bytes |
+| `storage` | `string?` | Storage provider (`'local'`, `'google_drive'`, etc.) |
+| `duration_ms` | `number` | Operation duration in milliseconds |
+| `success` | `boolean` | Whether the operation succeeded |
+| `error` | `string?` | Error message (on failure) |
+| `metadata` | `object?` | Extra context (e.g., `{ type: 'rename', new_name }`) |
+
+Logging is emitted at two levels:
+- **FileManager** logs the storage-level operation (actual file I/O timing)
+- **FileMetadataService** logs the database tracking operation (if tracking is enabled)
+
 ## Testing
 
 The package includes a test application in `test-app/` demonstrating:

package/{hazo_files_config.ini → config/hazo_files_config.ini.sample}

@@ -1,8 +1,9 @@
 ; Hazo Files Configuration
 ; This file configures the file management system
+; Copy to hazo_files_config.ini and fill in your values
 
 [general]
-; Available providers: local, google_drive
+; Available providers: local, google_drive, dropbox
 provider = local
 
 [local]
@@ -25,6 +26,18 @@ access_token =
 ; Optional: Root folder ID to use as base (empty = root of Drive)
 root_folder_id =
 
+[dropbox]
+; Dropbox OAuth credentials
+; These can also be set via environment variables:
+; HAZO_DROPBOX_CLIENT_ID, HAZO_DROPBOX_CLIENT_SECRET, etc.
+client_id =
+client_secret =
+redirect_uri = http://localhost:3000/api/auth/callback/dropbox
+refresh_token =
+access_token =
+; Optional: Root folder path within Dropbox (empty = root)
+root_path =
+
 [naming]
 ; Comma-separated list of supported date format tokens for naming rules
 ; Available: YYYY, YY, MM, M, DD, D, MMM, MMMM, YYYY-MM-DD, YYYY-MMM-DD, DD-MM-YYYY, MM-DD-YYYY

package/dist/index.d.mts

@@ -657,152 +657,6 @@ interface StorageModule {
     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>;
-
 /**
  * File Metadata Service
  * Handles database operations for tracking file metadata
@@ -1046,6 +900,159 @@ declare class FileMetadataService {
  */
 declare function createFileMetadataService(crudService: CrudServiceLike<FileMetadataRecord>, options?: FileMetadataServiceOptions): FileMetadataService;
 
+/**
+ * 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;
+    /** Logger for structured file operation logging (compatible with MetadataLogger) */
+    logger?: MetadataLogger;
+}
+/**
+ * FileManager - Main service class for file operations
+ */
+declare class FileManager {
+    private module;
+    private config;
+    private initialized;
+    private options;
+    protected logger?: MetadataLogger;
+    constructor(options?: FileManagerOptions);
+    /**
+     * Initialize the file manager with configuration
+     */
+    initialize(config?: HazoFilesConfig): Promise<void>;
+    /**
+     * @deprecated Storage modules require async initialization. Use initialize() instead.
+     */
+    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;
+    /**
+     * Log a structured file operation event
+     */
+    private logFileOp;
+    /**
+     * 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>;
+
 /**
  * Tracked File Manager
  * Extends FileManager to add database tracking of file operations
@@ -1059,6 +1066,8 @@ interface TrackedFileManagerFullOptions extends FileManagerOptions {
     crudService?: CrudServiceLike<FileMetadataRecord>;
     /** Database tracking configuration */
     tracking?: DatabaseTrackingConfig;
+    /** Logger for structured file operation logging */
+    logger?: MetadataLogger;
 }
 /**
  * Extended upload options with hash tracking