@pelatform/storage 1.0.1

package/dist/helpers.js

@@ -0,0 +1,68 @@
+import {
+  base64ToBuffer,
+  bufferToBase64,
+  buildPublicUrl,
+  detectFileTypeFromContent,
+  extractS3Info,
+  fileToBuffer,
+  formatFileSize,
+  generateBatchKeys,
+  generateCacheControl,
+  generateFileHash,
+  generateFileKey,
+  generateUniqueKey,
+  getContentDisposition,
+  getFileExtension,
+  getFileInfo,
+  getFileName,
+  getMimeType,
+  getParentPath,
+  isAudioFile,
+  isDocumentFile,
+  isImageFile,
+  isVideoFile,
+  joinPath,
+  normalizePath,
+  parseS3Url,
+  sanitizeFileName,
+  validateBatchFiles,
+  validateBucketName,
+  validateFileSize,
+  validateFileType,
+  validateS3Config,
+  validateS3Key
+} from "./chunk-KJMGBTTL.js";
+export {
+  base64ToBuffer,
+  bufferToBase64,
+  buildPublicUrl,
+  detectFileTypeFromContent,
+  extractS3Info,
+  fileToBuffer,
+  formatFileSize,
+  generateBatchKeys,
+  generateCacheControl,
+  generateFileHash,
+  generateFileKey,
+  generateUniqueKey,
+  getContentDisposition,
+  getFileExtension,
+  getFileInfo,
+  getFileName,
+  getMimeType,
+  getParentPath,
+  isAudioFile,
+  isDocumentFile,
+  isImageFile,
+  isVideoFile,
+  joinPath,
+  normalizePath,
+  parseS3Url,
+  sanitizeFileName,
+  validateBatchFiles,
+  validateBucketName,
+  validateFileSize,
+  validateFileType,
+  validateS3Config,
+  validateS3Key
+};

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+import { S as S3Config, C as CloudinaryConfig, a as StorageConfig } from './storage-interface-UizTndyU.js';
+export { B as BatchDeleteOptions, i as BatchDeleteResult, y as CopyFolderOptions, z as CopyFolderResult, j as CopyOptions, k as CopyResult, q as CreateFolderOptions, r as CreateFolderResult, s as DeleteFolderOptions, t as DeleteFolderResult, g as DeleteOptions, h as DeleteResult, D as DownloadOptions, f as DownloadResult, m as DuplicateOptions, n as DuplicateResult, E as ExistsResult, F as FileInfo, w as FolderExistsResult, d as FolderInfo, u as ListFoldersOptions, v as ListFoldersResult, L as ListOptions, o as ListResult, M as MoveOptions, l as MoveResult, P as PresignedUrlOptions, p as PresignedUrlResult, R as RenameFolderOptions, x as RenameFolderResult, b as S3ProviderType, A as StorageInterface, c as StorageProvider, U as UploadOptions, e as UploadResult } from './storage-interface-UizTndyU.js';
+
+/**
+ * Storage configuration from environment variables
+ * Provides automatic configuration loading from environment variables
+ */
+
+/**
+ * Environment variable names for storage configuration
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { ENV_VARS } from '@pelatform/storage';
+ *
+ * // Check if specific env vars are set
+ * console.log(process.env[ENV_VARS.PELATFORM_S3_BUCKET]);
+ * console.log(process.env[ENV_VARS.PELATFORM_CLOUDINARY_CLOUD_NAME]);
+ * ```
+ */
+declare const ENV_VARS: {
+    readonly PELATFORM_S3_PROVIDER: "PELATFORM_S3_PROVIDER";
+    readonly PELATFORM_S3_REGION: "PELATFORM_S3_REGION";
+    readonly PELATFORM_S3_BUCKET: "PELATFORM_S3_BUCKET";
+    readonly PELATFORM_S3_ACCESS_KEY_ID: "PELATFORM_S3_ACCESS_KEY_ID";
+    readonly PELATFORM_S3_SECRET_ACCESS_KEY: "PELATFORM_S3_SECRET_ACCESS_KEY";
+    readonly PELATFORM_S3_ENDPOINT: "PELATFORM_S3_ENDPOINT";
+    readonly PELATFORM_S3_FORCE_PATH_STYLE: "PELATFORM_S3_FORCE_PATH_STYLE";
+    readonly PELATFORM_S3_PUBLIC_URL: "PELATFORM_S3_PUBLIC_URL";
+    readonly PELATFORM_CLOUDINARY_CLOUD_NAME: "PELATFORM_CLOUDINARY_CLOUD_NAME";
+    readonly PELATFORM_CLOUDINARY_API_KEY: "PELATFORM_CLOUDINARY_API_KEY";
+    readonly PELATFORM_CLOUDINARY_API_SECRET: "PELATFORM_CLOUDINARY_API_SECRET";
+    readonly PELATFORM_CLOUDINARY_SECURE: "PELATFORM_CLOUDINARY_SECURE";
+    readonly PELATFORM_CLOUDINARY_FOLDER: "PELATFORM_CLOUDINARY_FOLDER";
+};
+/**
+ * Load S3 configuration from environment variables
+ * @returns S3 configuration object
+ * @throws Error if required environment variables are missing
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { loadS3Config } from '@pelatform/storage';
+ *
+ * // Set environment variables first:
+ * // PELATFORM_S3_PROVIDER=aws
+ * // PELATFORM_S3_REGION=us-east-1
+ * // PELATFORM_S3_BUCKET=my-bucket
+ * // PELATFORM_S3_ACCESS_KEY_ID=AKIA...
+ * // PELATFORM_S3_SECRET_ACCESS_KEY=secret...
+ *
+ * try {
+ *   const config = loadS3Config();
+ *   console.log(config);
+ *   // Returns: {
+ *   //   provider: 'aws',
+ *   //   region: 'us-east-1',
+ *   //   bucket: 'my-bucket',
+ *   //   accessKeyId: 'AKIA...',
+ *   //   secretAccessKey: 'secret...'
+ *   // }
+ * } catch (error) {
+ *   console.error('Missing S3 configuration:', error.message);
+ * }
+ * ```
+ */
+declare function loadS3Config(): S3Config;
+/**
+ * Load Cloudinary configuration from environment variables
+ * @returns Cloudinary configuration object
+ * @throws Error if required environment variables are missing
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { loadCloudinaryConfig } from '@pelatform/storage';
+ *
+ * // Set environment variables first:
+ * // PELATFORM_CLOUDINARY_CLOUD_NAME=my-cloud
+ * // PELATFORM_CLOUDINARY_API_KEY=123456789
+ * // PELATFORM_CLOUDINARY_API_SECRET=secret...
+ * // PELATFORM_CLOUDINARY_SECURE=true (optional)
+ * // PELATFORM_CLOUDINARY_FOLDER=uploads (optional)
+ *
+ * try {
+ *   const config = loadCloudinaryConfig();
+ *   console.log(config);
+ *   // Returns: {
+ *   //   provider: 'cloudinary',
+ *   //   cloudName: 'my-cloud',
+ *   //   apiKey: '123456789',
+ *   //   apiSecret: 'secret...',
+ *   //   secure: true,
+ *   //   folder: 'uploads'
+ *   // }
+ * } catch (error) {
+ *   console.error('Missing Cloudinary configuration:', error.message);
+ * }
+ * ```
+ */
+declare function loadCloudinaryConfig(): CloudinaryConfig;
+/**
+ * Auto-detect and load storage configuration from environment variables
+ * Determines the provider based on available environment variables
+ * @returns Storage configuration object (S3 or Cloudinary)
+ * @throws Error if no valid configuration is found
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { loadStorageConfig } from '@pelatform/storage';
+ *
+ * // Auto-detection based on available env vars
+ * try {
+ *   const config = loadStorageConfig();
+ *
+ *   if (config.provider === 'cloudinary') {
+ *     console.log('Using Cloudinary:', config.cloudName);
+ *   } else {
+ *     console.log('Using S3:', config.provider, config.bucket);
+ *   }
+ * } catch (error) {
+ *   console.error('No storage configuration found:', error.message);
+ * }
+ *
+ * // Explicit provider (set PELATFORM_S3_PROVIDER=cloudinary)
+ * // Will load Cloudinary config even if S3 vars are also present
+ * ```
+ */
+declare function loadStorageConfig(): StorageConfig;
+/**
+ * Check if storage configuration is available in environment variables
+ * @returns True if valid storage configuration is found
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { hasStorageConfig, loadStorageConfig } from '@pelatform/storage';
+ *
+ * if (hasStorageConfig()) {
+ *   const config = loadStorageConfig();
+ *   console.log('Storage configured:', config.provider);
+ * } else {
+ *   console.log('Please set storage environment variables');
+ * }
+ *
+ * // Use in conditional initialization
+ * const storage = hasStorageConfig() ? createStorage() : null;
+ * ```
+ */
+declare function hasStorageConfig(): boolean;
+/**
+ * Check if storage configuration is available in environment variables
+ * @returns True if either S3 or Cloudinary configuration is available
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { isStorageConfigured, createS3, createCloudinary } from '@pelatform/storage';
+ *
+ * if (isStorageConfigured()) {
+ *   // Choose your preferred provider
+ *   const s3 = createS3();
+ *   // OR
+ *   const cloudinary = createCloudinary();
+ *
+ *   await s3.uploadFile('test.txt', 'Hello World');
+ * } else {
+ *   console.log('Storage not configured. Please set environment variables.');
+ * }
+ *
+ * // Use in conditional initialization
+ * const storage = isStorageConfigured() ? createS3() : null;
+ * if (storage) {
+ *   await storage.uploadFile('file.txt', content);
+ * }
+ * ```
+ */
+declare function isStorageConfigured(): boolean;
+/**
+ * Get storage provider name from environment variables without loading full config
+ * @returns Provider name or undefined if not configured
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getStorageProvider } from '@pelatform/storage';
+ *
+ * const provider = getStorageProvider();
+ *
+ * switch (provider) {
+ *   case 'aws':
+ *     console.log('Using AWS S3');
+ *     break;
+ *   case 'cloudinary':
+ *     console.log('Using Cloudinary');
+ *     break;
+ *   case 'cloudflare-r2':
+ *     console.log('Using Cloudflare R2');
+ *     break;
+ *   default:
+ *     console.log('No storage provider configured');
+ * }
+ *
+ * // Quick check without throwing errors
+ * if (getStorageProvider()) {
+ *   // Storage is configured
+ * }
+ * ```
+ */
+declare function getStorageProvider(): string | undefined;
+/**
+ * Validate if all required environment variables are set for S3
+ * @returns Validation result with missing variables
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateS3EnvVars } from '@pelatform/storage';
+ *
+ * const validation = validateS3EnvVars();
+ *
+ * if (validation.valid) {
+ *   console.log('S3 configuration is complete');
+ * } else {
+ *   console.log('Missing S3 variables:', validation.missing);
+ *   // Returns: ["PELATFORM_S3_REGION", "PELATFORM_S3_BUCKET"]
+ * }
+ * ```
+ */
+declare function validateS3EnvVars(): {
+    valid: boolean;
+    missing: string[];
+};
+/**
+ * Validate if all required environment variables are set for Cloudinary
+ * @returns Validation result with missing variables
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { validateCloudinaryEnvVars } from '@pelatform/storage';
+ *
+ * const validation = validateCloudinaryEnvVars();
+ *
+ * if (validation.valid) {
+ *   console.log('Cloudinary configuration is complete');
+ * } else {
+ *   console.log('Missing Cloudinary variables:', validation.missing);
+ *   // Returns: ["PELATFORM_CLOUDINARY_API_KEY"]
+ * }
+ * ```
+ */
+declare function validateCloudinaryEnvVars(): {
+    valid: boolean;
+    missing: string[];
+};
+/**
+ * Get all available environment variables for debugging
+ * @returns Object containing all storage-related env vars
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { getStorageEnvVars } from '@pelatform/storage';
+ *
+ * const envVars = getStorageEnvVars();
+ * console.log('Storage environment variables:', envVars);
+ * // Returns: {
+ * //   PELATFORM_S3_PROVIDER: 'aws',
+ * //   PELATFORM_S3_REGION: 'us-east-1',
+ * //   PELATFORM_S3_BUCKET: 'my-bucket',
+ * //   // ... other set variables (secrets are masked)
+ * // }
+ * ```
+ */
+declare function getStorageEnvVars(): Record<string, string | undefined>;
+
+export { CloudinaryConfig, ENV_VARS, S3Config, StorageConfig, getStorageEnvVars, getStorageProvider, hasStorageConfig, isStorageConfigured, loadCloudinaryConfig, loadS3Config, loadStorageConfig, validateCloudinaryEnvVars, validateS3EnvVars };

package/dist/index.js

@@ -0,0 +1,24 @@
+import {
+  ENV_VARS,
+  getStorageEnvVars,
+  getStorageProvider,
+  hasStorageConfig,
+  isStorageConfigured,
+  loadCloudinaryConfig,
+  loadS3Config,
+  loadStorageConfig,
+  validateCloudinaryEnvVars,
+  validateS3EnvVars
+} from "./chunk-ZTZZCC52.js";
+export {
+  ENV_VARS,
+  getStorageEnvVars,
+  getStorageProvider,
+  hasStorageConfig,
+  isStorageConfigured,
+  loadCloudinaryConfig,
+  loadS3Config,
+  loadStorageConfig,
+  validateCloudinaryEnvVars,
+  validateS3EnvVars
+};

package/dist/s3.d.ts

@@ -0,0 +1,108 @@
+import { A as StorageInterface, S as S3Config, U as UploadOptions, e as UploadResult, D as DownloadOptions, f as DownloadResult, g as DeleteOptions, h as DeleteResult, B as BatchDeleteOptions, i as BatchDeleteResult, L as ListOptions, o as ListResult, E as ExistsResult, j as CopyOptions, k as CopyResult, M as MoveOptions, l as MoveResult, m as DuplicateOptions, n as DuplicateResult, P as PresignedUrlOptions, p as PresignedUrlResult, q as CreateFolderOptions, r as CreateFolderResult, s as DeleteFolderOptions, t as DeleteFolderResult, u as ListFoldersOptions, v as ListFoldersResult, w as FolderExistsResult, R as RenameFolderOptions, x as RenameFolderResult, y as CopyFolderOptions, z as CopyFolderResult } from './storage-interface-UizTndyU.js';
+
+/**
+ * S3 storage service implementation
+ * High-level service wrapper for S3-compatible storage operations with convenience methods
+ */
+
+/**
+ * S3 storage service
+ * High-level service for S3-compatible storage operations with convenience methods
+ * @public
+ */
+declare class S3Service implements StorageInterface {
+    private provider;
+    private config;
+    constructor();
+    constructor(config: S3Config);
+    private createProvider;
+    getConfig(): S3Config;
+    getBucket(): string;
+    getRegion(): string;
+    getProvider(): string;
+    getPublicUrl(key: string): string;
+    upload(options: UploadOptions): Promise<UploadResult>;
+    download(options: DownloadOptions): Promise<DownloadResult>;
+    delete(options: DeleteOptions): Promise<DeleteResult>;
+    batchDelete(options: BatchDeleteOptions): Promise<BatchDeleteResult>;
+    list(options?: ListOptions): Promise<ListResult>;
+    exists(key: string): Promise<ExistsResult>;
+    copy(options: CopyOptions): Promise<CopyResult>;
+    move(options: MoveOptions): Promise<MoveResult>;
+    duplicate(options: DuplicateOptions): Promise<DuplicateResult>;
+    getPresignedUrl(options: PresignedUrlOptions): Promise<PresignedUrlResult>;
+    createFolder(options: CreateFolderOptions): Promise<CreateFolderResult>;
+    deleteFolder(options: DeleteFolderOptions): Promise<DeleteFolderResult>;
+    listFolders(options?: ListFoldersOptions): Promise<ListFoldersResult>;
+    folderExists(path: string): Promise<FolderExistsResult>;
+    renameFolder(options: RenameFolderOptions): Promise<RenameFolderResult>;
+    copyFolder(options: CopyFolderOptions): Promise<CopyFolderResult>;
+    uploadFile(key: string, file: Buffer | Uint8Array | string, options?: Partial<UploadOptions>): Promise<UploadResult>;
+    downloadFile(key: string): Promise<DownloadResult>;
+    deleteFile(key: string): Promise<DeleteResult>;
+    deleteFiles(keys: string[]): Promise<BatchDeleteResult>;
+    fileExists(key: string): Promise<boolean>;
+    copyFile(sourceKey: string, destinationKey: string, options?: Partial<CopyOptions>): Promise<CopyResult>;
+    moveFile(sourceKey: string, destinationKey: string, options?: Partial<MoveOptions>): Promise<MoveResult>;
+    duplicateFile(sourceKey: string, destinationKey: string, options?: Partial<DuplicateOptions>): Promise<DuplicateResult>;
+    renameFile(sourceKey: string, newKey: string, options?: Partial<MoveOptions>): Promise<MoveResult>;
+    getDownloadUrl(key: string, expiresIn?: number): Promise<PresignedUrlResult>;
+    getUploadUrl(key: string, contentType?: string, expiresIn?: number): Promise<PresignedUrlResult>;
+    createFolderPath(path: string): Promise<CreateFolderResult>;
+    deleteFolderPath(path: string, recursive?: boolean): Promise<DeleteFolderResult>;
+    folderPathExists(path: string): Promise<boolean>;
+    renameFolderPath(oldPath: string, newPath: string): Promise<RenameFolderResult>;
+    copyFolderPath(sourcePath: string, destinationPath: string, recursive?: boolean): Promise<CopyFolderResult>;
+}
+
+/**
+ * Create S3 service using environment variables or manual configuration
+ * @param config Optional S3 configuration. If not provided, loads from environment variables
+ * @returns S3Service instance
+ * @throws Error if configuration is invalid or environment variables are missing
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { createS3 } from '@pelatform/storage/s3';
+ *
+ * // Using environment variables
+ * // Set: PELATFORM_S3_PROVIDER=aws, PELATFORM_S3_REGION=us-east-1, etc.
+ * const s3FromEnv = createS3();
+ * await s3FromEnv.uploadFile('test.txt', 'Hello World');
+ *
+ * // Using manual configuration
+ * const s3Manual = createS3({
+ *   provider: 'aws',
+ *   region: 'us-east-1',
+ *   bucket: 'my-bucket',
+ *   accessKeyId: 'AKIA...',
+ *   secretAccessKey: 'secret...'
+ * });
+ *
+ * // Cloudflare R2
+ * const r2 = createS3({
+ *   provider: 'cloudflare-r2',
+ *   region: 'auto',
+ *   bucket: 'my-r2-bucket',
+ *   accessKeyId: 'your-r2-key',
+ *   secretAccessKey: 'your-r2-secret',
+ *   endpoint: 'https://account-id.r2.cloudflarestorage.com'
+ * });
+ *
+ * // MinIO
+ * const minio = createS3({
+ *   provider: 'minio',
+ *   region: 'us-east-1',
+ *   bucket: 'my-minio-bucket',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ *   endpoint: 'http://localhost:9000',
+ *   forcePathStyle: true
+ * });
+ * ```
+ */
+declare function createS3(): S3Service;
+declare function createS3(config: S3Config): S3Service;
+
+export { S3Service, createS3 };