hazo_files 1.4.5 → 1.4.6

package/README.md

@@ -1573,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/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>;
-    /**
-     * @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;
-    /**
-     * 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

package/dist/index.d.ts

@@ -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>;
-    /**
-     * @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;
-    /**
-     * 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