@happyvertical/files 0.74.8

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

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/providers/s3.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,KAAK,gBAAgB,EAErB,KAAK,eAAe,EACpB,KAAK,QAAQ,EAEb,KAAK,SAAS,EACd,KAAK,sBAAsB,EAG3B,KAAK,WAAW,EAEhB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AA2BzB,qBAAa,oBAAqB,SAAQ,sBAAsB;IAIlD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,OAAO,EAAE,SAAS;IAiB/C,OAAO,CAAC,eAAe;IAyBvB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,gBAAgB;YAgBV,mBAAmB;YAgBnB,oBAAoB;IAclC,OAAO,CAAC,wBAAwB;YAqClB,YAAY;YAkCZ,IAAI;IA2BlB,OAAO,CAAC,UAAU;IA0BZ,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAmCtC,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;IAoCrB,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAiCV,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCnC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBzD,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzD,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,gBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAQV,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAyElE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAiD1C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB1C,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,aAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAKV,QAAQ,CACZ,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,GAAE,eAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC;IAQZ,eAAe,IAAI,OAAO,CAAC,sBAAsB,CAAC;CAwBzD"}

package/dist/redact.d.ts

@@ -0,0 +1,2 @@
+export declare function redactFilesystemConfig<T>(value: T): T extends object ? unknown : T;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AA8BA,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,CAAC,GACP,CAAC,SAAS,MAAM,GAAG,OAAO,GAAG,CAAC,CAIhC"}

package/dist/shared/base.d.ts

@@ -0,0 +1,106 @@
+import { BaseProviderOptions, CacheOptions, CreateDirOptions, DownloadOptions, FileInfo, FileStats, FilesystemCapabilities, FilesystemInterface, ListFilesOptions, ListOptions, ReadOptions, UploadOptions, WriteOptions } from './types';
+/**
+ * Abstract base class for filesystem providers.
+ *
+ * Implements {@link FilesystemInterface} with shared logic for path normalization,
+ * validation, caching, and legacy method adapters. Concrete providers (e.g.
+ * {@link LocalFilesystemProvider}, {@link GoogleDriveProvider}) extend this class
+ * and implement the abstract methods for their specific storage backend.
+ */
+export declare abstract class BaseFilesystemProvider implements FilesystemInterface {
+    protected basePath: string;
+    protected applyBasePath: boolean;
+    protected cacheDir: string;
+    protected createMissing: boolean;
+    protected providerType: string;
+    constructor(options?: BaseProviderOptions);
+    /**
+     * Get default cache directory for the current context
+     */
+    private getDefaultCacheDir;
+    /**
+     * Throw error for unsupported operations
+     */
+    protected throwUnsupported(operation: string): never;
+    /**
+     * Normalize path by removing leading/trailing slashes and resolving relative paths
+     */
+    protected normalizePath(path: string): string;
+    /**
+     * Universal path joining function that works in both Node.js and browser
+     */
+    private joinPaths;
+    /**
+     * Validate that a path is safe (no directory traversal)
+     */
+    protected validatePath(path: string): void;
+    /**
+     * Get cache key for a given path
+     */
+    protected getCacheKey(path: string): string;
+    /**
+     * Abstract methods that must be implemented by providers
+     */
+    abstract exists(path: string): Promise<boolean>;
+    abstract read(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    abstract write(path: string, content: string | Buffer, options?: WriteOptions): Promise<void>;
+    abstract delete(path: string): Promise<void>;
+    abstract copy(sourcePath: string, destPath: string): Promise<void>;
+    abstract move(sourcePath: string, destPath: string): Promise<void>;
+    abstract createDirectory(path: string, options?: CreateDirOptions): Promise<void>;
+    abstract list(path: string, options?: ListOptions): Promise<FileInfo[]>;
+    abstract getStats(path: string): Promise<FileStats>;
+    abstract getMimeType(path: string): Promise<string>;
+    abstract getCapabilities(): Promise<FilesystemCapabilities>;
+    /**
+     * Provider methods with default implementations (may be overridden)
+     */
+    upload(_localPath: string, _remotePath: string, _options?: UploadOptions): Promise<void>;
+    download(_remotePath: string, _localPath?: string, _options?: DownloadOptions): Promise<string>;
+    downloadWithCache(remotePath: string, options?: CacheOptions): Promise<string>;
+    /**
+     * Cache implementation - providers can override for their specific storage
+     */
+    cache: {
+        get: (_key: string, _expiry?: number) => Promise<string | undefined>;
+        set: (_key: string, _data: string) => Promise<void>;
+        clear: (_key?: string) => Promise<void>;
+    };
+    /**
+     * Check if a path is a file (legacy)
+     */
+    isFile(file: string): Promise<false | FileStats>;
+    /**
+     * Check if a path is a directory (legacy)
+     */
+    isDirectory(dir: string): Promise<boolean>;
+    /**
+     * Create a directory if it doesn't exist (legacy)
+     */
+    ensureDirectoryExists(dir: string): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * List files in a directory with optional filtering (legacy)
+     */
+    listFiles(dirPath: string, options?: ListFilesOptions): 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>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/shared/base.d.ts.map

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

package/dist/shared/factory.d.ts

@@ -0,0 +1,148 @@
+import { FilesystemInterface, GetFilesystemOptions } from './types';
+/**
+ * Register a filesystem provider factory function
+ *
+ * This function allows registration of new filesystem providers at runtime.
+ * Each provider must implement the FilesystemInterface.
+ *
+ * @param type - The provider type identifier (e.g., 'local', 's3', 'webdav')
+ * @param factory - Async factory function that returns the provider class constructor
+ *
+ * @example
+ * ```typescript
+ * registerProvider('custom', async () => {
+ *   const { CustomProvider } = await import('./custom-provider.js');
+ *   return CustomProvider;
+ * });
+ * ```
+ */
+export declare function registerProvider(type: string, factory: () => Promise<any>): void;
+/**
+ * Get list of available provider types
+ *
+ * Returns an array of all registered filesystem provider type identifiers.
+ * This can be used to check which providers are available in the current environment.
+ *
+ * @returns Array of provider type strings (e.g., ['local', 's3', 'webdav'])
+ *
+ * @example
+ * ```typescript
+ * const availableProviders = getAvailableProviders();
+ * console.log('Available providers:', availableProviders);
+ * // Output: ['local', 's3', 'webdav']
+ * ```
+ */
+export declare function getAvailableProviders(): string[];
+/**
+ * Create a filesystem instance with the specified provider and configuration
+ *
+ * This is the main entry point for creating filesystem instances. It automatically
+ * detects the provider type from the options, validates the configuration, and
+ * returns a fully configured filesystem interface.
+ *
+ * @param options - Provider configuration options. Defaults to local filesystem if not specified
+ * @returns Promise resolving to a configured filesystem instance
+ * @throws {FilesystemError} When provider options are invalid or provider creation fails
+ *
+ * @example
+ * ```typescript
+ * // Create local filesystem provider
+ * const localFs = await getFilesystem({ type: 'local', basePath: '/app/data' });
+ *
+ * // Create S3 provider
+ * const s3Fs = await getFilesystem({
+ *   type: 's3',
+ *   region: 'us-east-1',
+ *   bucket: 'my-bucket',
+ *   accessKeyId: 'AKIA...',
+ *   secretAccessKey: 'secret'
+ * });
+ *
+ * // Create WebDAV provider for Nextcloud
+ * const webdavFs = await getFilesystem({
+ *   type: 'webdav',
+ *   baseUrl: 'https://cloud.example.com',
+ *   username: 'user',
+ *   password: 'password',
+ *   davPath: '/remote.php/dav/files/user/'
+ * });
+ *
+ * // Auto-detect provider type from options
+ * const autoFs = await getFilesystem({ region: 'us-west-2', bucket: 'data' }); // detects S3
+ * ```
+ */
+export declare function getFilesystem(options?: GetFilesystemOptions): Promise<FilesystemInterface>;
+/**
+ * Initialize and register all available filesystem providers
+ *
+ * This function registers the built-in providers that are available in the current
+ * environment. It's called automatically when the module is imported, but can be
+ * called manually if needed.
+ *
+ * In Node.js environments, this registers the local filesystem provider.
+ * In browser environments, this would register the browser storage provider.
+ *
+ * @returns Promise that resolves when all providers are registered
+ *
+ * @example
+ * ```typescript
+ * // Manually reinitialize providers
+ * await initializeProviders();
+ * console.log('Providers:', getAvailableProviders());
+ * ```
+ */
+export declare function initializeProviders(): Promise<void>;
+/**
+ * Check if a specific provider type is available
+ *
+ * Determines whether a provider has been registered and is available for use.
+ * This is useful for feature detection and graceful degradation.
+ *
+ * @param type - Provider type to check (e.g., 'local', 's3', 'webdav')
+ * @returns True if the provider is registered and available, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isProviderAvailable('s3')) {
+ *   // Use S3 provider
+ *   const fs = await getFilesystem({ type: 's3', region: 'us-east-1', bucket: 'data' });
+ * } else {
+ *   // Fallback to local provider
+ *   const fs = await getFilesystem({ type: 'local' });
+ * }
+ * ```
+ */
+export declare function isProviderAvailable(type: string): boolean;
+/**
+ * Get detailed information about a specific provider
+ *
+ * Returns comprehensive information about a provider including availability,
+ * description, and required configuration options.
+ *
+ * @param type - Provider type to get information about
+ * @returns Object containing provider availability, description, and required options
+ *
+ * @example
+ * ```typescript
+ * const s3Info = getProviderInfo('s3');
+ * console.log(s3Info);
+ * // {
+ * //   available: true,
+ * //   description: 'S3-compatible provider supporting AWS S3, MinIO, and other S3-compatible services',
+ * //   requiredOptions: ['region', 'bucket']
+ * // }
+ *
+ * // Check requirements before configuration
+ * const webdavInfo = getProviderInfo('webdav');
+ * if (webdavInfo.available) {
+ *   console.log('WebDAV requires:', webdavInfo.requiredOptions);
+ *   // ['baseUrl', 'username', 'password']
+ * }
+ * ```
+ */
+export declare function getProviderInfo(type: string): {
+    available: boolean;
+    description: string;
+    requiredOptions: string[];
+};
+//# sourceMappingURL=factory.d.ts.map

package/dist/shared/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/shared/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAI1B,MAAM,SAAS,CAAC;AAQjB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GAC1B,IAAI,CAEN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAoJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA4B9B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAoBzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CA0BA"}