@kumix/storage 0.1.0

package/README.md

@@ -0,0 +1,291 @@
+# @kumix/storage
+
+[![Version](https://img.shields.io/npm/v/@kumix/storage.svg)](https://www.npmjs.com/package/@kumix/storage)
+[![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 @kumix/storage
+# or
+bun add @kumix/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 { S3Service } from "@kumix/storage/s3";
+
+const storage = new S3Service({
+  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 { CloudinaryService } from "@kumix/storage/cloudinary";
+
+const storage = new CloudinaryService({
+  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 S3Service({
+  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 S3Service({
+  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 S3Service({
+  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
+
+## Runtime Compatibility
+
+| Export         | Node.js | Bun | CF Workers | Deno | Browser |
+| -------------- | ------- | --- | ---------- | ---- | ------- |
+| `.` (config)   | Yes     | Yes | Yes\*      | Yes  | Yes     |
+| `./helpers`    | Yes     | Yes | Yes        | Yes  | Yes     |
+| `./s3`         | Yes     | Yes | No         | Yes  | No      |
+| `./cloudinary` | Yes     | Yes | No         | Yes  | No      |
+
+\* Pass env via `EnvRecord`: `loadS3Config(myEnv)`.
+
+### `EnvRecord` Pattern
+
+All config functions accept an optional `env` parameter. On Node/Bun it defaults to `process.env`. On other runtimes, pass your environment explicitly:
+
+```typescript
+import { loadS3Config, loadCloudinaryConfig, hasStorageConfig } from "@kumix/storage";
+
+// Cloudflare Workers
+const config = loadS3Config(ctx.env);
+
+// Deno
+const config = loadCloudinaryConfig(Deno.env.toObject());
+
+// Manual config (works everywhere, no env needed)
+const s3 = createS3({ provider: "aws", region: "us-east-1", ... });
+const cloudinary = createCloudinary({ provider: "cloudinary", cloudName: "...", ... });
+```
+
+> **Note**: `./s3` and `./cloudinary` subpaths require the AWS SDK or Cloudinary SDK
+> peer dependencies respectively, which are Node.js packages. Use these subpaths only in
+> Node.js, Bun, or Deno environments.
+
+## Links
+
+- [npm Package](https://www.npmjs.com/package/@kumix/storage)
+- [Contributing Guide](../../CONTRIBUTING.md)
+- [Code of Conduct](../../CODE_OF_CONDUCT.md)
+- [License](../../LICENSE)
+
+## License
+
+MIT © [Kumix Labs](../../LICENSE)

package/dist/cloudinary.d.ts

@@ -0,0 +1,93 @@
+import { A as DownloadOptions, B as PresignedUrlResult, C as RenameFolderResult, D as CopyResult, E as CopyOptions, F as ListOptions, H as UploadResult, I as ListResult, L as MoveOptions, M as DuplicateOptions, N as DuplicateResult, O as DeleteOptions, P as ExistsResult, R as MoveResult, S as RenameFolderOptions, T as BatchDeleteResult, U as CloudinaryConfig, V as UploadOptions, _ as DeleteFolderOptions, b as ListFoldersOptions, f as StorageInterface, g as CreateFolderResult, h as CreateFolderOptions, j as DownloadResult, k as DeleteResult, m as CopyFolderResult, n as EnvRecord, p as CopyFolderOptions, v as DeleteFolderResult, w as BatchDeleteOptions, x as ListFoldersResult, y as FolderExistsResult, z as PresignedUrlOptions } from "./config-J6AdDh_c.js";
+
+//#region src/services/cloudinary.d.ts
+/**
+ * Cloudinary storage service
+ * High-level service for Cloudinary storage operations with convenience methods
+ * @public
+ */
+declare class CloudinaryService implements StorageInterface {
+  private provider;
+  private config;
+  constructor();
+  constructor(config: CloudinaryConfig);
+  getConfig(): CloudinaryConfig;
+  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, contentType?: string, metadata?: Record<string, string>): Promise<UploadResult>;
+  downloadFile(key: string): Promise<DownloadResult>;
+  deleteFile(key: string): Promise<DeleteResult>;
+  deleteFiles(keys: string[]): Promise<BatchDeleteResult>;
+  listFiles(prefix?: string, maxKeys?: number): Promise<ListResult>;
+  fileExists(key: string): Promise<boolean>;
+  copyFile(sourceKey: string, destinationKey: string, metadata?: Record<string, string>): Promise<CopyResult>;
+  moveFile(sourceKey: string, destinationKey: string, metadata?: Record<string, string>): Promise<MoveResult>;
+  duplicateFile(sourceKey: string, destinationKey: string, metadata?: Record<string, string>): Promise<DuplicateResult>;
+  renameFile(sourceKey: string, destinationKey: string, metadata?: Record<string, string>): 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>;
+}
+//#endregion
+//#region src/cloudinary.d.ts
+/**
+ * Create Cloudinary service using environment variables or manual configuration
+ * @param config Optional Cloudinary configuration. If not provided, loads from environment variables
+ * @param env - Optional environment record
+ * @returns CloudinaryService instance
+ * @throws Error if configuration is invalid or environment variables are missing
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { createCloudinary } from '@kumix/storage/cloudinary';
+ *
+ * // Using environment variables
+ * // Set: KUMIX_CLOUDINARY_CLOUD_NAME=my-cloud, KUMIX_CLOUDINARY_API_KEY=123..., etc.
+ * const cloudinaryFromEnv = createCloudinary();
+ * await cloudinaryFromEnv.uploadFile('photo.jpg', imageBuffer);
+ *
+ * // Using manual configuration
+ * const cloudinary = createCloudinary({
+ *   provider: 'cloudinary',
+ *   cloudName: 'my-cloud-name',
+ *   apiKey: '123456789012345',
+ *   apiSecret: 'your-api-secret',
+ *   secure: true,
+ *   folder: 'uploads'
+ * });
+ *
+ * // Upload with transformations
+ * await cloudinary.uploadFile('profile-pic.jpg', imageBuffer);
+ *
+ * // Get optimized URL
+ * const publicUrl = cloudinary.getPublicUrl('profile-pic.jpg');
+ * console.log(publicUrl); // Cloudinary optimized URL
+ * ```
+ */
+declare function createCloudinary(): CloudinaryService;
+declare function createCloudinary(config: CloudinaryConfig): CloudinaryService;
+declare function createCloudinary(config: CloudinaryConfig, env: EnvRecord): CloudinaryService;
+//#endregion
+export { CloudinaryService, createCloudinary };
+//# sourceMappingURL=cloudinary.d.ts.map

package/dist/cloudinary.d.ts.map

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