@happyvertical/files 0.74.8

package/dist/legacy.d.ts

@@ -0,0 +1,209 @@
+import { statSync } from 'node:fs';
+/**
+ * Checks if a path is a file (legacy compatibility function)
+ *
+ * This function provides backward compatibility with the existing @happyvertical/files API.
+ * It synchronously checks if the given path exists and is a file (not a directory).
+ *
+ * @param file - Path to check
+ * @returns File stats object if the path is a file, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const stats = isFile('/path/to/document.txt');
+ * if (stats) {
+ *   console.log(`File size: ${stats.size} bytes`);
+ *   console.log(`Modified: ${stats.mtime}`);
+ * }
+ * ```
+ *
+ * @deprecated Use the async filesystem interface methods instead
+ */
+export declare const isFile: (file: string) => false | ReturnType<typeof statSync>;
+/**
+ * Checks if a path is a directory (legacy compatibility function)
+ *
+ * This function provides backward compatibility with the existing @happyvertical/files API.
+ * It synchronously checks if the given path exists and is a directory.
+ *
+ * @param dir - Path to check
+ * @returns True if the path is a directory, false if it doesn't exist
+ * @throws {Error} If the path exists but is not a directory
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const isDir = isDirectory('/path/to/folder');
+ *   if (isDir) {
+ *     console.log('Path is a directory');
+ *   } else {
+ *     console.log('Directory does not exist');
+ *   }
+ * } catch (error) {
+ *   console.error('Path exists but is not a directory');
+ * }
+ * ```
+ *
+ * @deprecated Use the async filesystem interface methods instead
+ */
+export declare const isDirectory: (dir: string) => boolean;
+/**
+ * Creates a directory if it doesn't exist (legacy compatibility function)
+ *
+ * This function provides backward compatibility with the existing @happyvertical/files API.
+ * It ensures a directory exists by creating it (and any parent directories) if needed.
+ *
+ * @param dir - Directory path to create
+ * @returns Promise that resolves when the directory exists or has been created
+ *
+ * @example
+ * ```typescript
+ * await ensureDirectoryExists('/path/to/nested/directory');
+ * console.log('Directory is ready for use');
+ * ```
+ *
+ * @deprecated Use the async filesystem interface createDirectory method instead
+ */
+export declare const ensureDirectoryExists: (dir: string) => Promise<void>;
+/**
+ * Uploads data to a URL using PUT method (legacy compatibility function)
+ *
+ * This function provides backward compatibility with the existing @happyvertical/files API.
+ * It performs an HTTP PUT request to upload data to a remote URL.
+ *
+ * @param url - URL to upload data to
+ * @param data - String or Buffer data to upload
+ * @returns Promise that resolves with the Response object
+ * @throws {Error} If the upload fails (network error or non-2xx response)
+ *
+ * @example
+ * ```typescript
+ * const response = await upload('https://api.example.com/files/document.txt', 'file content');
+ * console.log('Upload successful:', response.status);
+ *
+ * // Upload binary data
+ * const imageBuffer = await fs.readFile('image.png');
+ * await upload('https://api.example.com/files/image.png', imageBuffer);
+ * ```
+ *
+ * @deprecated Use the async filesystem interface upload method instead
+ */
+export declare const upload: (url: string, data: string | Buffer) => Promise<Response>;
+/**
+ * Downloads a file from a URL and saves it to a local file (legacy compatibility function)
+ *
+ * This function provides backward compatibility with the existing @happyvertical/files API.
+ * It downloads content from a URL and writes it to a local file using streaming
+ * to handle large files efficiently.
+ *
+ * @param url - URL to download from
+ * @param filepath - Local file path to save to
+ * @returns Promise that resolves when the download is complete
+ * @throws {Error} If the download fails (network error, file write error, etc.)
+ *
+ * @example
+ * ```typescript
+ * await download('https://example.com/document.pdf', './downloads/document.pdf');
+ * console.log('Download complete');
+ *
+ * // Download with error handling
+ * try {
+ *   await download('https://example.com/large-file.zip', './temp/file.zip');
+ * } catch (error) {
+ *   console.error('Download failed:', error.message);
+ * }
+ * ```
+ *
+ * @deprecated Use the async filesystem interface download method instead
+ */
+export declare function download(url: string, filepath: string): Promise<void>;
+/**
+ * Downloads a file with caching support (legacy compatibility function)
+ *
+ * This function provides backward compatibility with the existing @happyvertical/files API.
+ * It downloads a file only if it doesn't already exist locally, implementing
+ * a simple caching mechanism to avoid redundant downloads.
+ *
+ * @param url - URL to download from
+ * @param targetPath - Optional custom target path. If null, uses a generated path in temp directory
+ * @returns Promise that resolves with the path to the downloaded file (either cached or newly downloaded)
+ *
+ * @example
+ * ```typescript
+ * // Download with auto-generated cache path
+ * const filePath = await downloadFileWithCache('https://example.com/data.json');
+ * console.log('File available at:', filePath);
+ *
+ * // Download to specific path
+ * const customPath = await downloadFileWithCache(
+ *   'https://example.com/document.pdf',
+ *   './cache/document.pdf'
+ * );
+ * ```
+ *
+ * @deprecated Use the async filesystem interface downloadWithCache method instead
+ */
+export declare const downloadFileWithCache: (url: string, targetPath?: string | null) => Promise<string>;
+/**
+ * Options for listing files in a directory
+ */
+interface ListFilesOptions {
+    /**
+     * Optional regular expression to filter files by name
+     */
+    match?: RegExp;
+}
+/**
+ * Lists files in a directory with optional filtering (legacy compatibility function)
+ *
+ * This function provides backward compatibility with the existing @happyvertical/files API.
+ * It returns only files (not directories) from the specified directory, with
+ * optional regular expression filtering.
+ *
+ * @param dirPath - Directory path to list files from
+ * @param options - Filtering options
+ * @param options.match - Optional regular expression to filter files by name
+ * @returns Promise that resolves with an array of file names (not full paths)
+ *
+ * @example
+ * ```typescript
+ * // List all files
+ * const allFiles = await listFiles('/path/to/directory');
+ * console.log('Files:', allFiles);
+ *
+ * // List only JavaScript files
+ * const jsFiles = await listFiles('/project/src', { match: /\.js$/ });
+ * console.log('JS files:', jsFiles);
+ *
+ * // List image files
+ * const images = await listFiles('/photos', { match: /\.(jpg|png|gif)$/i });
+ * ```
+ *
+ * @deprecated Use the async filesystem interface list method instead
+ */
+export declare const listFiles: (dirPath: string, options?: ListFilesOptions) => Promise<string[]>;
+/**
+ * Gets data from cache if available and not expired
+ *
+ * @param file - Cache file identifier
+ * @param expiry - Cache expiry time in milliseconds
+ * @returns Promise that resolves with the cached data or undefined if not found/expired
+ */
+export declare function getCached(file: string, expiry?: number): Promise<string | undefined>;
+/**
+ * Sets data in cache
+ *
+ * @param file - Cache file identifier
+ * @param data - Data to cache
+ * @returns Promise that resolves when the data is cached
+ */
+export declare function setCached(file: string, data: string): Promise<void>;
+/**
+ * Gets the MIME type for a file or URL based on its extension
+ *
+ * @param fileOrUrl - File path or URL to get MIME type for
+ * @returns MIME type string, defaults to 'application/octet-stream' if not found
+ */
+export declare function getMimeType(fileOrUrl: string): string;
+export {};
+//# sourceMappingURL=legacy.d.ts.map

package/dist/legacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy.d.ts","sourceRoot":"","sources":["../src/legacy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA8C,QAAQ,EAAE,MAAM,SAAS,CAAC;AAY/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,KAAK,GAAG,UAAU,CAAC,OAAO,QAAQ,CAOvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,OAWzC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,IAAI,CAKrE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,MAAM,GACjB,KAAK,MAAM,EACX,MAAM,MAAM,GAAG,MAAM,KACpB,OAAO,CAAC,QAAQ,CAiBlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmC3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,qBAAqB,GAChC,KAAK,MAAM,EACX,aAAY,MAAM,GAAG,IAAW,KAC/B,OAAO,CAAC,MAAM,CAchB,CAAC;AAEF;;GAEG;AACH,UAAU,gBAAgB;IACxB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,SAAS,GACpB,SAAS,MAAM,EACf,UAAS,gBAAkC,KAC1C,OAAO,CAAC,MAAM,EAAE,CASlB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS,+BAY5D;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,iBAIzD;AA+BD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAcrD"}

package/dist/node/local.d.ts

@@ -0,0 +1,332 @@
+import { BaseFilesystemProvider } from '../shared/base';
+import { CreateDirOptions, FileInfo, FileStats, FilesystemCapabilities, ListOptions, LocalOptions, ReadOptions, WriteOptions } from '../shared/types';
+/**
+ * Local filesystem provider using Node.js fs module with full feature support
+ *
+ * This provider implements all filesystem operations using the Node.js built-in
+ * fs/promises module. It supports all standard file operations including reading,
+ * writing, directory management, and caching. The provider operates within a
+ * configurable root path for security and organization.
+ *
+ * @example
+ * ```typescript
+ * // Create provider with default settings (current working directory)
+ * const fs = new LocalFilesystemProvider();
+ *
+ * // Create provider with custom base path
+ * const fs = new LocalFilesystemProvider({ basePath: '/app/data' });
+ *
+ * // Use the provider
+ * await fs.write('config.json', JSON.stringify({ key: 'value' }));
+ * const content = await fs.read('config.json');
+ * ```
+ */
+export declare class LocalFilesystemProvider extends BaseFilesystemProvider {
+    private readonly rootPath;
+    constructor(options?: LocalOptions);
+    /**
+     * Resolve a relative path to an absolute path within the root directory
+     *
+     * This method validates the path, normalizes it, and resolves it relative to
+     * the configured root path. It ensures path safety by preventing directory
+     * traversal attacks.
+     *
+     * @param path - Relative path to resolve
+     * @returns Absolute path within the root directory
+     * @throws {FilesystemError} When path is invalid or contains directory traversal
+     *
+     * @internal
+     */
+    private resolvePath;
+    private resolveCachePath;
+    /**
+     * Check if a file or directory exists at the specified path
+     *
+     * Uses Node.js fs.access() to check for file existence without reading
+     * the file contents. This is more efficient than trying to read or stat
+     * the file when only existence needs to be verified.
+     *
+     * @param path - Path to check for existence
+     * @returns Promise resolving to true if the path exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const exists = await fs.exists('config.json');
+     * if (exists) {
+     *   console.log('Config file found');
+     * }
+     * ```
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Read file contents as string or Buffer
+     *
+     * Reads the entire contents of a file into memory. For large files, consider
+     * using streaming approaches to avoid memory issues.
+     *
+     * @param path - Path to the file to read
+     * @param options - Read options including encoding and raw mode
+     * @param options.encoding - Text encoding for string output (default: 'utf8')
+     * @param options.raw - If true, returns Buffer instead of string
+     * @returns Promise resolving to file contents as string or Buffer
+     * @throws {FileNotFoundError} When the file doesn't exist
+     * @throws {PermissionError} When read access is denied
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * // Read as UTF-8 string (default)
+     * const text = await fs.read('document.txt');
+     *
+     * // Read as Buffer for binary data
+     * const buffer = await fs.read('image.png', { raw: true });
+     *
+     * // Read with specific encoding
+     * const latin1Text = await fs.read('legacy.txt', { encoding: 'latin1' });
+     * ```
+     */
+    read(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    /**
+     * Write content to a file
+     *
+     * Creates or overwrites a file with the provided content. Can automatically
+     * create parent directories if they don't exist. Supports both string and
+     * binary data.
+     *
+     * @param path - Path where the file should be written
+     * @param content - Content to write (string or Buffer)
+     * @param options - Write options
+     * @param options.encoding - Text encoding for string content
+     * @param options.mode - File permissions (e.g., 0o644)
+     * @param options.createParents - Whether to create parent directories (default: true)
+     * @returns Promise that resolves when the file is written
+     * @throws {FileNotFoundError} When parent directory doesn't exist and createParents is false
+     * @throws {PermissionError} When write access is denied
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * // Write text file
+     * await fs.write('config.json', JSON.stringify({ key: 'value' }));
+     *
+     * // Write binary data
+     * const imageBuffer = await someImageProcessing();
+     * await fs.write('output.png', imageBuffer);
+     *
+     * // Write with specific permissions
+     * await fs.write('secret.txt', 'sensitive data', { mode: 0o600 });
+     *
+     * // Write without creating parent directories
+     * await fs.write('existing/dir/file.txt', 'content', { createParents: false });
+     * ```
+     */
+    write(path: string, content: string | Buffer, options?: WriteOptions): Promise<void>;
+    /**
+     * Delete a file or empty directory
+     *
+     * Removes a file or directory from the filesystem. For directories, they must
+     * be empty. Use recursive deletion utilities for non-empty directories.
+     *
+     * @param path - Path to the file or directory to delete
+     * @returns Promise that resolves when the item is deleted
+     * @throws {FileNotFoundError} When the file or directory doesn't exist
+     * @throws {PermissionError} When delete access is denied
+     * @throws {DirectoryNotEmptyError} When trying to delete a non-empty directory
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * // Delete a file
+     * await fs.delete('temp.txt');
+     *
+     * // Delete an empty directory
+     * await fs.delete('empty-dir/');
+     * ```
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Copy a file from source to destination
+     *
+     * Creates an exact copy of a file at the destination path. Will create
+     * parent directories if they don't exist and createMissing is enabled.
+     * The operation preserves file contents but not necessarily all metadata.
+     *
+     * @param sourcePath - Path to the source file
+     * @param destPath - Path where the copy should be created
+     * @returns Promise that resolves when the file is copied
+     * @throws {FileNotFoundError} When the source file doesn't exist
+     * @throws {PermissionError} When read/write access is denied
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * // Copy a file
+     * await fs.copy('original.txt', 'backup.txt');
+     *
+     * // Copy to a different directory
+     * await fs.copy('data.json', 'backup/data-copy.json');
+     * ```
+     */
+    copy(sourcePath: string, destPath: string): Promise<void>;
+    /**
+     * Move/rename a file from source to destination
+     *
+     * Moves a file to a new location, effectively combining copy and delete
+     * operations. This is atomic on most filesystems when moving within the
+     * same filesystem. Will create parent directories if they don't exist.
+     *
+     * @param sourcePath - Path to the source file
+     * @param destPath - Path where the file should be moved
+     * @returns Promise that resolves when the file is moved
+     * @throws {FileNotFoundError} When the source file doesn't exist
+     * @throws {PermissionError} When move access is denied
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * // Rename a file
+     * await fs.move('old-name.txt', 'new-name.txt');
+     *
+     * // Move to a different directory
+     * await fs.move('temp.txt', 'archive/temp.txt');
+     * ```
+     */
+    move(sourcePath: string, destPath: string): Promise<void>;
+    /**
+     * Create a directory at the specified path
+     *
+     * Creates a new directory with optional recursive creation of parent
+     * directories. Supports setting directory permissions.
+     *
+     * @param path - Path where the directory should be created
+     * @param options - Directory creation options
+     * @param options.recursive - Whether to create parent directories (default: true)
+     * @param options.mode - Directory permissions (e.g., 0o755)
+     * @returns Promise that resolves when the directory is created
+     * @throws {PermissionError} When create access is denied
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * // Create directory with parents
+     * await fs.createDirectory('path/to/new/dir');
+     *
+     * // Create directory with specific permissions
+     * await fs.createDirectory('private-dir', { mode: 0o700 });
+     *
+     * // Create directory without parent creation
+     * await fs.createDirectory('existing-parent/new-dir', { recursive: false });
+     * ```
+     */
+    createDirectory(path: string, options?: CreateDirOptions): Promise<void>;
+    /**
+     * List the contents of a directory
+     *
+     * Returns an array of FileInfo objects describing each item in the directory.
+     * Supports filtering, recursive listing, and detailed metadata retrieval.
+     *
+     * @param path - Path to the directory to list
+     * @param options - Listing options
+     * @param options.recursive - Whether to include subdirectories recursively
+     * @param options.filter - RegExp or string pattern to filter file names
+     * @param options.detailed - Whether to include MIME types and extended metadata
+     * @returns Promise resolving to array of FileInfo objects
+     * @throws {FileNotFoundError} When the directory doesn't exist
+     * @throws {PermissionError} When read access is denied
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * // List all files and directories
+     * const items = await fs.list('/path/to/dir');
+     * items.forEach(item => {
+     *   console.log(`${item.name} (${item.isDirectory ? 'dir' : 'file'})`);
+     * });
+     *
+     * // List only text files
+     * const textFiles = await fs.list('/documents', { filter: /\.txt$/ });
+     *
+     * // Recursive listing with detailed info
+     * const allFiles = await fs.list('/project', {
+     *   recursive: true,
+     *   detailed: true
+     * });
+     * ```
+     */
+    list(path: string, options?: ListOptions): Promise<FileInfo[]>;
+    /**
+     * Get detailed file or directory statistics
+     *
+     * Returns comprehensive metadata about a file or directory including size,
+     * timestamps, permissions, and ownership information.
+     *
+     * @param path - Path to the file or directory
+     * @returns Promise resolving to FileStats object with detailed metadata
+     * @throws {FileNotFoundError} When the path doesn't exist
+     * @throws {PermissionError} When stat access is denied
+     * @throws {FilesystemError} For other filesystem errors
+     *
+     * @example
+     * ```typescript
+     * const stats = await fs.getStats('document.pdf');
+     * console.log(`Size: ${stats.size} bytes`);
+     * console.log(`Modified: ${stats.mtime}`);
+     * console.log(`Is file: ${stats.isFile}`);
+     * console.log(`Permissions: ${stats.mode.toString(8)}`);
+     * ```
+     */
+    getStats(path: string): Promise<FileStats>;
+    /**
+     * Get the MIME type for a file based on its extension
+     *
+     * Determines the MIME type by examining the file extension. Returns a
+     * standard MIME type string that can be used for content-type headers
+     * or file type detection.
+     *
+     * @param path - Path to the file
+     * @returns Promise resolving to MIME type string (e.g., 'text/plain', 'image/png')
+     *
+     * @example
+     * ```typescript
+     * const mimeType = await fs.getMimeType('document.pdf');
+     * console.log(mimeType); // 'application/pdf'
+     *
+     * const imageMime = await fs.getMimeType('photo.jpg');
+     * console.log(imageMime); // 'image/jpeg'
+     * ```
+     */
+    getMimeType(path: string): Promise<string>;
+    /**
+     * Upload data to a URL using PUT method (legacy)
+     */
+    uploadToUrl(url: string, data: string | Buffer): Promise<Response>;
+    /**
+     * Download a file from a URL and save it to a local file (legacy)
+     */
+    downloadFromUrl(url: string, filepath: string): Promise<void>;
+    /**
+     * Download a file with caching support (legacy)
+     */
+    downloadFileWithCache(url: string, targetPath?: string | null): Promise<string>;
+    /**
+     * Get data from cache if available and not expired (legacy)
+     */
+    getCached(file: string, expiry?: number): Promise<string | undefined>;
+    /**
+     * Set data in cache (legacy)
+     */
+    setCached(file: string, data: string): Promise<void>;
+    /**
+     * Cache implementation using file system
+     */
+    cache: {
+        get: (key: string, expiry?: number) => Promise<string | undefined>;
+        set: (key: string, data: string) => Promise<void>;
+        clear: (key?: string) => Promise<void>;
+    };
+    /**
+     * Get provider capabilities
+     */
+    getCapabilities(): Promise<FilesystemCapabilities>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/node/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/node/local.ts"],"names":[],"mappings":"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"}

package/dist/providers/gdrive.d.ts

@@ -0,0 +1,87 @@
+import { BaseFilesystemProvider } from '../shared/base';
+import { CreateDirOptions, DownloadOptions, FileInfo, FileStats, FilesystemCapabilities, GoogleDriveOptions, ListOptions, ReadOptions, UploadOptions, WriteOptions } from '../shared/types';
+/**
+ * Google Drive filesystem provider using the Drive API v3
+ *
+ * Supports three authentication modes:
+ * - OAuth2: clientId + clientSecret + refreshToken (auto-refreshes)
+ * - Service account: serviceAccountKey JSON string
+ * - Access token: short-lived token (no auto-refresh)
+ *
+ * Maps hierarchical paths to Google Drive file IDs via folder traversal
+ * with an in-memory TTL cache for performance.
+ *
+ * @example
+ * ```typescript
+ * const fs = new GoogleDriveProvider({
+ *   type: 'gdrive',
+ *   clientId: 'xxx',
+ *   clientSecret: 'yyy',
+ *   refreshToken: 'zzz',
+ * });
+ *
+ * await fs.write('documents/readme.txt', 'Hello');
+ * const content = await fs.read('documents/readme.txt');
+ * ```
+ */
+export declare class GoogleDriveProvider extends BaseFilesystemProvider {
+    private options;
+    private drive;
+    private rootFolderId;
+    private pathCache;
+    private pathCacheTTL;
+    private pageSize;
+    constructor(options: GoogleDriveOptions);
+    /**
+     * Lazily initialize the Google Drive client on first use
+     */
+    private getDrive;
+    /**
+     * Resolve a hierarchical path like "folder/sub/file.txt" to a Drive file ID
+     * by walking each segment. Results are cached with a configurable TTL.
+     */
+    private resolvePathToId;
+    /**
+     * Resolve a path to an ID, throwing FileNotFoundError if it doesn't exist
+     */
+    private requireId;
+    /**
+     * Ensure all parent folders exist for a given path, creating them if needed.
+     * Returns the parent folder ID and the final segment name.
+     */
+    private ensureParents;
+    /**
+     * Invalidate cache entries that are prefixed by the given path
+     */
+    private invalidateCache;
+    /**
+     * Wrap a Drive API call and map HTTP errors to typed filesystem errors
+     */
+    private wrapApiCall;
+    /** Checks whether a non-trashed file or folder exists at the given path. */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Read a file from Google Drive. Google Docs native types (Document,
+     * Spreadsheet, Presentation, Drawing) are automatically exported to a
+     * portable format (plain text, CSV, PDF, PNG respectively).
+     */
+    read(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    /** Write content to Drive. Updates the file in-place if it already exists, otherwise creates it. */
+    write(path: string, content: string | Buffer, options?: WriteOptions): Promise<void>;
+    /** Moves the file to the Drive trash rather than permanently deleting it. */
+    delete(path: string): Promise<void>;
+    copy(sourcePath: string, destPath: string): Promise<void>;
+    /** Moves a file by updating its parent references (single API call, not copy+delete). */
+    move(sourcePath: string, destPath: string): Promise<void>;
+    createDirectory(path: string, options?: CreateDirOptions): Promise<void>;
+    /** Lists non-trashed children of a folder, with optional pagination via {@link GoogleDriveOptions.pageSize}. */
+    list(path: string, options?: ListOptions): Promise<FileInfo[]>;
+    /** Returns file metadata. Mode is synthetic (0o755 for folders, 0o644 for files); uid/gid are always 0. */
+    getStats(path: string): Promise<FileStats>;
+    getMimeType(path: string): Promise<string>;
+    upload(localPath: string, remotePath: string, _options?: UploadOptions): Promise<void>;
+    /** Downloads a file from Drive to the local filesystem, defaulting to the provider's cache directory. */
+    download(remotePath: string, localPath?: string, _options?: DownloadOptions): Promise<string>;
+    getCapabilities(): Promise<FilesystemCapabilities>;
+}
+//# sourceMappingURL=gdrive.d.ts.map

package/dist/providers/gdrive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gdrive.d.ts","sourceRoot":"","sources":["../../src/providers/gdrive.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,QAAQ,EAEb,KAAK,SAAS,EACd,KAAK,sBAAsB,EAE3B,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAEhB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAsDzB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAoB,SAAQ,sBAAsB;IAOjD,OAAO,CAAC,OAAO;IAN3B,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAS;gBAEL,OAAO,EAAE,kBAAkB;IAO/C;;OAEG;YACW,QAAQ;IAmDtB;;;OAGG;YACW,eAAe;IAoC7B;;OAEG;YACW,SAAS;IAMvB;;;OAGG;YACW,aAAa;IAsC3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAavB;;OAEG;YACW,WAAW;IA2CzB,4EAA4E;IACtE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK5C;;;;OAIG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;IA4C3B,oGAAoG;IAC9F,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IA6DhB,6EAA6E;IACvE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB/D,yFAAyF;IACnF,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BzD,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC;IA8DhB,gHAAgH;IAC1G,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IA2ExE,2GAA2G;IACrG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAgC1C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1C,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,aAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAKhB,yGAAyG;IACnG,QAAQ,CACZ,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,GAAE,eAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC;IASZ,eAAe,IAAI,OAAO,CAAC,sBAAsB,CAAC;CAyBzD"}

package/dist/providers/s3.d.ts

@@ -0,0 +1,32 @@
+import { BaseFilesystemProvider } from '../shared/base';
+import { CreateDirOptions, DownloadOptions, FileInfo, FileStats, FilesystemCapabilities, ListOptions, ReadOptions, S3Options, UploadOptions, WriteOptions } from '../shared/types';
+export declare class S3FilesystemProvider extends BaseFilesystemProvider {
+    private readonly options;
+    private readonly client;
+    private readonly bucket;
+    constructor(options: S3Options);
+    private normalizeS3Path;
+    private toDirectoryKey;
+    private isRootPath;
+    private toDirectoryStats;
+    private headDirectoryMarker;
+    private directoryHasChildren;
+    private getDefaultDownloadTarget;
+    private bodyToBuffer;
+    private head;
+    private toFileInfo;
+    exists(path: string): Promise<boolean>;
+    read(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    write(path: string, content: string | Buffer, options?: WriteOptions): Promise<void>;
+    delete(path: string): Promise<void>;
+    copy(sourcePath: string, destPath: string): Promise<void>;
+    move(sourcePath: string, destPath: string): Promise<void>;
+    createDirectory(path: string, _options?: CreateDirOptions): Promise<void>;
+    list(path: string, options?: ListOptions): Promise<FileInfo[]>;
+    getStats(path: string): Promise<FileStats>;
+    getMimeType(path: string): Promise<string>;
+    upload(localPath: string, remotePath: string, _options?: UploadOptions): Promise<void>;
+    download(remotePath: string, localPath?: string, _options?: DownloadOptions): Promise<string>;
+    getCapabilities(): Promise<FilesystemCapabilities>;
+}
+//# sourceMappingURL=s3.d.ts.map