@pelatform/storage 1.0.1 → 1.0.2

package/README.md

@@ -1,10 +1,258 @@
 # @pelatform/storage
 
-A comprehensive storage utilities for SaaS applications. This package provides a unified interface for working with various storage providers including AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Supabase, and Cloudinary Storage.
-
 [![Version](https://img.shields.io/npm/v/@pelatform/storage.svg)](https://www.npmjs.com/package/@pelatform/storage)
-[![License](https://img.shields.io/npm/l/@pelatform/storage.svg)](https://github.com/devpelatform/storage/blob/main/LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A comprehensive storage utilities package for SaaS applications. This package provides a unified interface for working with various storage providers including AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Supabase Storage, and Cloudinary.
+
+## Installation
+
+```bash
+npm install @pelatform/storage
+# or
+bun add @pelatform/storage
+
+# Install peer dependencies for the provider(s) you need
+npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner  # For S3-compatible providers
+npm install cloudinary  # For Cloudinary
+```
+
+## Quick Start
+
+### S3-Compatible Storage (AWS, R2, MinIO, etc.)
+
+```typescript
+import { S3Storage } from "@pelatform/storage/s3";
+
+const storage = new S3Storage({
+  provider: "aws", // or 'cloudflare-r2', 'minio', 'digitalocean', 'supabase'
+  region: "us-east-1",
+  bucket: "my-bucket",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+});
+
+// Upload a file
+await storage.upload({
+  key: "documents/file.pdf",
+  file: fileBuffer,
+  contentType: "application/pdf",
+});
+
+// Download a file
+const result = await storage.download({ key: "documents/file.pdf" });
+
+// Generate a presigned URL (temporary access)
+const url = await storage.getPresignedUrl({
+  key: "documents/file.pdf",
+  operation: "get",
+  expiresIn: 3600, // 1 hour
+});
+```
+
+### Cloudinary Storage
+
+```typescript
+import { CloudinaryStorage } from "@pelatform/storage/cloudinary";
+
+const storage = new CloudinaryStorage({
+  provider: "cloudinary",
+  cloudName: process.env.CLOUDINARY_CLOUD_NAME,
+  apiKey: process.env.CLOUDINARY_API_KEY,
+  apiSecret: process.env.CLOUDINARY_API_SECRET,
+});
+
+// Upload an image
+await storage.upload({
+  key: "images/photo.jpg",
+  file: imageBuffer,
+  contentType: "image/jpeg",
+});
+```
+
+## Key Features
+
+- **Unified Interface**: Single API for multiple storage providers
+- **S3-Compatible Providers**: AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Supabase Storage
+- **Cloudinary Support**: Image and media management with built-in optimizations
+- **File Operations**: Upload, download, delete, copy, move, and check existence
+- **Folder Operations**: Create, delete, list, and manage folders
+- **Presigned URLs**: Generate time-limited access URLs for secure sharing
+- **Public URLs**: Get public access URLs with optional CDN support
+- **Type-Safe**: Full TypeScript support with comprehensive types
+- **Flexible Configuration**: Support for custom endpoints and CDN URLs
+
+## Supported Providers
+
+### S3-Compatible
+
+- **AWS S3** - Amazon's object storage service
+- **Cloudflare R2** - Cloudflare's S3-compatible storage (no egress fees)
+- **MinIO** - Self-hosted S3-compatible storage
+- **DigitalOcean Spaces** - DigitalOcean's object storage
+- **Supabase Storage** - Supabase's S3-compatible storage
+
+### Other Providers
+
+- **Cloudinary** - Image and video management platform
+
+## Configuration
+
+### AWS S3
+
+```typescript
+const storage = new S3Storage({
+  provider: "aws",
+  region: "us-east-1",
+  bucket: "my-bucket",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  publicUrl: "https://cdn.example.com", // Optional CDN URL
+});
+```
+
+### Cloudflare R2
+
+```typescript
+const storage = new S3Storage({
+  provider: "cloudflare-r2",
+  region: "auto",
+  bucket: "my-bucket",
+  accessKeyId: process.env.R2_ACCESS_KEY_ID,
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+  endpoint: "https://<account-id>.r2.cloudflarestorage.com",
+});
+```
+
+### MinIO
+
+```typescript
+const storage = new S3Storage({
+  provider: "minio",
+  region: "us-east-1",
+  bucket: "my-bucket",
+  accessKeyId: "minioadmin",
+  secretAccessKey: "minioadmin",
+  endpoint: "http://localhost:9000",
+  forcePathStyle: true, // Required for MinIO
+});
+```
+
+## Basic Usage
+
+### File Operations
+
+```typescript
+// Upload with options
+await storage.upload({
+  key: "uploads/document.pdf",
+  file: buffer,
+  contentType: "application/pdf",
+  metadata: { userId: "123", category: "documents" },
+  cacheControl: "max-age=31536000",
+});
+
+// Download file
+const { content, metadata } = await storage.download({
+  key: "uploads/document.pdf",
+});
+
+// Check if file exists
+const exists = await storage.exists("uploads/document.pdf");
+
+// Delete file
+await storage.delete({ key: "uploads/document.pdf" });
+
+// Copy file
+await storage.copy({
+  sourceKey: "uploads/old.pdf",
+  destinationKey: "uploads/new.pdf",
+});
+
+// Move file
+await storage.move({
+  sourceKey: "uploads/temp.pdf",
+  destinationKey: "uploads/final.pdf",
+});
+
+// List files
+const files = await storage.list({
+  prefix: "uploads/",
+  maxKeys: 100,
+});
+```
+
+### Folder Operations
+
+```typescript
+// Create folder
+await storage.createFolder({ path: "documents/" });
+
+// Delete folder (recursive)
+await storage.deleteFolder({
+  path: "documents/",
+  recursive: true,
+});
+
+// List folders
+const folders = await storage.listFolders({
+  prefix: "uploads/",
+});
+
+// Check if folder exists
+const exists = await storage.folderExists("documents/");
+```
+
+### URL Generation
+
+```typescript
+// Get public URL
+const publicUrl = storage.getPublicUrl("images/photo.jpg");
+
+// Generate presigned URL for download
+const downloadUrl = await storage.getPresignedUrl({
+  key: "documents/private.pdf",
+  operation: "get",
+  expiresIn: 3600, // 1 hour
+});
+
+// Generate presigned URL for upload
+const uploadUrl = await storage.getPresignedUrl({
+  key: "uploads/new-file.pdf",
+  operation: "put",
+  expiresIn: 900, // 15 minutes
+  contentType: "application/pdf",
+});
+```
+
+## API Reference
+
+### File Operations
+
+- `upload(options)` - Upload a file
+- `download(options)` - Download a file
+- `delete(options)` - Delete a file
+- `exists(key)` - Check if file exists
+- `copy(options)` - Copy a file
+- `move(options)` - Move a file
+- `list(options)` - List files with prefix
+- `getPresignedUrl(options)` - Generate presigned URL
+- `getPublicUrl(key)` - Get public URL
+
+### Folder Operations
+
+- `createFolder(options)` - Create a folder
+- `deleteFolder(options)` - Delete a folder
+- `listFolders(options)` - List folders
+- `folderExists(path)` - Check if folder exists
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@pelatform/storage)
+- [Contributing Guide](../../CONTRIBUTING.md)
+- [Code of Conduct](../../CODE_OF_CONDUCT.md)
+- [License](../../LICENSE)
 
-## Getting Started
+## License
 
-Visit https://devpelatform.github.io/storage to get started with this package.
+MIT © [Pelatform Inc.](../../LICENSE)

package/dist/cloudinary.d.ts

@@ -1,4 +1,4 @@
-import { A as StorageInterface, C as CloudinaryConfig, 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';
+import { S as StorageInterface, C as CloudinaryConfig, U as UploadOptions, a as UploadResult, D as DownloadOptions, b as DownloadResult, c as DeleteOptions, d as DeleteResult, B as BatchDeleteOptions, e as BatchDeleteResult, L as ListOptions, f as ListResult, E as ExistsResult, g as CopyOptions, h as CopyResult, M as MoveOptions, i as MoveResult, j as DuplicateOptions, k as DuplicateResult, P as PresignedUrlOptions, l as PresignedUrlResult, m as CreateFolderOptions, n as CreateFolderResult, o as DeleteFolderOptions, p as DeleteFolderResult, q as ListFoldersOptions, r as ListFoldersResult, F as FolderExistsResult, R as RenameFolderOptions, s as RenameFolderResult, t as CopyFolderOptions, u as CopyFolderResult } from './storage-interface-BKeDAlGP.js';
 
 /**
  * Cloudinary storage service implementation

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { v as S3Config, C as CloudinaryConfig, w as StorageConfig } from './storage-interface-BKeDAlGP.js';
+export { B as BatchDeleteOptions, e as BatchDeleteResult, t as CopyFolderOptions, u as CopyFolderResult, g as CopyOptions, h as CopyResult, m as CreateFolderOptions, n as CreateFolderResult, o as DeleteFolderOptions, p as DeleteFolderResult, c as DeleteOptions, d as DeleteResult, D as DownloadOptions, b as DownloadResult, j as DuplicateOptions, k as DuplicateResult, E as ExistsResult, z as FileInfo, F as FolderExistsResult, A as FolderInfo, q as ListFoldersOptions, r as ListFoldersResult, L as ListOptions, f as ListResult, M as MoveOptions, i as MoveResult, P as PresignedUrlOptions, l as PresignedUrlResult, R as RenameFolderOptions, s as RenameFolderResult, x as S3ProviderType, S as StorageInterface, y as StorageProvider, U as UploadOptions, a as UploadResult } from './storage-interface-BKeDAlGP.js';
 
 /**
  * Storage configuration from environment variables

package/dist/s3.d.ts

@@ -1,4 +1,4 @@
-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';
+import { S as StorageInterface, v as S3Config, U as UploadOptions, a as UploadResult, D as DownloadOptions, b as DownloadResult, c as DeleteOptions, d as DeleteResult, B as BatchDeleteOptions, e as BatchDeleteResult, L as ListOptions, f as ListResult, E as ExistsResult, g as CopyOptions, h as CopyResult, M as MoveOptions, i as MoveResult, j as DuplicateOptions, k as DuplicateResult, P as PresignedUrlOptions, l as PresignedUrlResult, m as CreateFolderOptions, n as CreateFolderResult, o as DeleteFolderOptions, p as DeleteFolderResult, q as ListFoldersOptions, r as ListFoldersResult, F as FolderExistsResult, R as RenameFolderOptions, s as RenameFolderResult, t as CopyFolderOptions, u as CopyFolderResult } from './storage-interface-BKeDAlGP.js';
 
 /**
  * S3 storage service implementation

package/dist/s3.js

@@ -1,10 +1,10 @@
-import {
-  loadS3Config
-} from "./chunk-ZTZZCC52.js";
 import {
   buildPublicUrl,
   getMimeType
 } from "./chunk-KJMGBTTL.js";
+import {
+  loadS3Config
+} from "./chunk-ZTZZCC52.js";
 
 // src/providers/s3.ts
 import { S3Client } from "@aws-sdk/client-s3";

package/dist/{storage-interface-UizTndyU.d.ts → storage-interface-BKeDAlGP.d.ts}

@@ -313,4 +313,4 @@ interface StorageInterface {
     copyFolder(options: CopyFolderOptions): Promise<CopyFolderResult>;
 }
 
-export type { StorageInterface as A, BatchDeleteOptions as B, CloudinaryConfig as C, DownloadOptions as D, ExistsResult as E, FileInfo as F, ListOptions as L, MoveOptions as M, PresignedUrlOptions as P, RenameFolderOptions as R, S3Config as S, UploadOptions as U, StorageConfig as a, S3ProviderType as b, StorageProvider as c, FolderInfo as d, UploadResult as e, DownloadResult as f, DeleteOptions as g, DeleteResult as h, BatchDeleteResult as i, CopyOptions as j, CopyResult as k, MoveResult as l, DuplicateOptions as m, DuplicateResult as n, ListResult as o, PresignedUrlResult as p, CreateFolderOptions as q, CreateFolderResult as r, DeleteFolderOptions as s, DeleteFolderResult as t, ListFoldersOptions as u, ListFoldersResult as v, FolderExistsResult as w, RenameFolderResult as x, CopyFolderOptions as y, CopyFolderResult as z };
+export type { FolderInfo as A, BatchDeleteOptions as B, CloudinaryConfig as C, DownloadOptions as D, ExistsResult as E, FolderExistsResult as F, ListOptions as L, MoveOptions as M, PresignedUrlOptions as P, RenameFolderOptions as R, StorageInterface as S, UploadOptions as U, UploadResult as a, DownloadResult as b, DeleteOptions as c, DeleteResult as d, BatchDeleteResult as e, ListResult as f, CopyOptions as g, CopyResult as h, MoveResult as i, DuplicateOptions as j, DuplicateResult as k, PresignedUrlResult as l, CreateFolderOptions as m, CreateFolderResult as n, DeleteFolderOptions as o, DeleteFolderResult as p, ListFoldersOptions as q, ListFoldersResult as r, RenameFolderResult as s, CopyFolderOptions as t, CopyFolderResult as u, S3Config as v, StorageConfig as w, S3ProviderType as x, StorageProvider as y, FileInfo as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelatform/storage",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Storage utilities for SaaS applications.",
   "author": "Pelatform Dev",
   "license": "MIT",
@@ -26,10 +26,15 @@
       "default": "./dist/helpers.js"
     }
   },
-  "homepage": "https://devpelatform.github.io/storage",
+  "scripts": {
+    "clean": "rimraf dist",
+    "clean:all": "rimraf .turbo dist node_modules",
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "types:check": "tsc --noEmit"
+  },
   "files": [
-    "dist/*",
-    "README.md"
+    "dist"
   ],
   "keywords": [
     "pelatform",
@@ -44,15 +49,18 @@
     "mime-types": "^3.0.2"
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.939.0",
+    "@aws-sdk/s3-request-presigner": "^3.939.0",
     "@types/mime-types": "^3.0.1",
     "@types/node": "^24.10.1",
+    "cloudinary": "^2.8.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@aws-sdk/client-s3": ">=3.0.0",
-    "@aws-sdk/s3-request-presigner": ">=3.0.0",
-    "cloudinary": ">=2.0.0"
+    "@aws-sdk/client-s3": ">=3.8.0",
+    "@aws-sdk/s3-request-presigner": ">=3.8.0",
+    "cloudinary": ">=2.8.0"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-s3": {
@@ -67,12 +75,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "clean": "rimraf dist",
-    "clean:all": "rimraf .turbo dist node_modules",
-    "dev": "tsup --watch",
-    "build": "tsup --clean",
-    "types:check": "tsc --noEmit"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Pelatform
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.