@pelatform/storage 1.0.0 → 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/package.json

@@ -1,60 +1,40 @@
 {
   "name": "@pelatform/storage",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Storage utilities for SaaS applications.",
   "author": "Pelatform Dev",
   "license": "MIT",
   "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./s3": {
-      "import": {
-        "types": "./dist/s3.d.ts",
-        "default": "./dist/s3.js"
-      },
-      "require": {
-        "types": "./dist/s3.d.cts",
-        "default": "./dist/s3.cjs"
-      }
+      "types": "./dist/s3.d.ts",
+      "default": "./dist/s3.js"
     },
     "./cloudinary": {
-      "import": {
-        "types": "./dist/cloudinary.d.ts",
-        "default": "./dist/cloudinary.js"
-      },
-      "require": {
-        "types": "./dist/cloudinary.d.cts",
-        "default": "./dist/cloudinary.cjs"
-      }
+      "types": "./dist/cloudinary.d.ts",
+      "default": "./dist/cloudinary.js"
     },
     "./helpers": {
-      "import": {
-        "types": "./dist/helpers.d.ts",
-        "default": "./dist/helpers.js"
-      },
-      "require": {
-        "types": "./dist/helpers.d.cts",
-        "default": "./dist/helpers.cjs"
-      }
+      "types": "./dist/helpers.d.ts",
+      "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",
@@ -66,18 +46,21 @@
     "supabase"
   ],
   "dependencies": {
-    "mime-types": "^3.0.1"
+    "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.8.1",
-    "tsup": "^8.5.0",
+    "@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": {
@@ -92,12 +75,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "clean": "rimraf dist",
-    "clean:all": "rimraf .turbo dist node_modules",
-    "dev": "tsup --watch",
-    "build": "tsup --clean --dts",
-    "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.