@opensaas/stack-storage 0.1.1

package/README.md

@@ -0,0 +1,425 @@
+# @opensaas/stack-storage
+
+File and image upload field types with pluggable storage providers for OpenSaas Stack.
+
+## Features
+
+- 📁 **File Upload Field** - Generic file uploads with metadata storage
+- 🖼️ **Image Upload Field** - Image uploads with automatic transformations
+- 🔌 **Pluggable Storage** - Multiple named storage providers (local, S3, Vercel Blob)
+- 🎨 **Image Transformations** - Automatic thumbnail/variant generation with sharp
+- ✅ **Validation** - File size, MIME type, and extension validation
+- 📦 **JSON Storage** - Metadata stored as JSON in your database
+- 🎯 **Type-Safe** - Full TypeScript support
+
+## Installation
+
+```bash
+pnpm add @opensaas/stack-storage sharp
+```
+
+For S3 storage:
+
+```bash
+pnpm add @opensaas/stack-storage-s3
+```
+
+For Vercel Blob storage:
+
+```bash
+pnpm add @opensaas/stack-storage-vercel
+```
+
+## Basic Usage
+
+### 1. Configure Storage Providers
+
+```typescript
+// opensaas.config.ts
+import { config, list } from '@opensaas/stack-core'
+import { localStorage } from '@opensaas/stack-storage'
+import { s3Storage } from '@opensaas/stack-storage-s3'
+import { file, image } from '@opensaas/stack-storage/fields'
+
+export default config({
+  storage: {
+    // Local filesystem storage
+    documents: localStorage({
+      uploadDir: './public/uploads/documents',
+      serveUrl: '/uploads/documents',
+    }),
+
+    // S3 storage for images
+    avatars: s3Storage({
+      bucket: 'my-avatars',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+  },
+
+  lists: {
+    User: list({
+      fields: {
+        // Image field with transformations
+        avatar: image({
+          storage: 'avatars',
+          transformations: {
+            thumbnail: { width: 100, height: 100, fit: 'cover' },
+            profile: { width: 400, height: 400, fit: 'cover' },
+          },
+          validation: {
+            maxFileSize: 5 * 1024 * 1024, // 5MB
+            acceptedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+          },
+        }),
+
+        // File field
+        resume: file({
+          storage: 'documents',
+          validation: {
+            maxFileSize: 10 * 1024 * 1024, // 10MB
+            acceptedMimeTypes: ['application/pdf'],
+          },
+        }),
+      },
+    }),
+  },
+})
+```
+
+### 2. Create Upload API Route
+
+```typescript
+// app/api/upload/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import config from '@/opensaas.config'
+import { uploadFile, uploadImage, parseFileFromFormData } from '@opensaas/stack-storage/runtime'
+
+export async function POST(request: NextRequest) {
+  try {
+    const formData = await request.formData()
+    const storageProvider = formData.get('storage') as string
+    const fieldType = formData.get('fieldType') as 'file' | 'image'
+
+    // Parse file from FormData
+    const fileData = await parseFileFromFormData(formData, 'file')
+    if (!fileData) {
+      return NextResponse.json({ error: 'No file provided' }, { status: 400 })
+    }
+
+    // Upload based on field type
+    if (fieldType === 'image') {
+      // Get transformations from config if needed
+      const metadata = await uploadImage(config, storageProvider, fileData, {
+        validation: {
+          maxFileSize: 5 * 1024 * 1024,
+          acceptedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+        },
+        transformations: {
+          thumbnail: { width: 100, height: 100, fit: 'cover' },
+        },
+      })
+      return NextResponse.json(metadata)
+    } else {
+      const metadata = await uploadFile(config, storageProvider, fileData, {
+        validation: {
+          maxFileSize: 10 * 1024 * 1024,
+        },
+      })
+      return NextResponse.json(metadata)
+    }
+  } catch (error) {
+    console.error('Upload error:', error)
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Upload failed' },
+      { status: 500 },
+    )
+  }
+}
+```
+
+### 3. Use in Admin UI
+
+The file and image fields work automatically in the admin UI. For custom forms, provide an `onUpload` handler:
+
+```typescript
+import { FileField, ImageField } from '@opensaas/stack-ui/fields'
+
+function CustomForm() {
+  const [avatar, setAvatar] = useState<ImageMetadata | null>(null)
+
+  const handleUpload = async (file: File) => {
+    const formData = new FormData()
+    formData.append('file', file)
+    formData.append('storage', 'avatars')
+    formData.append('fieldType', 'image')
+
+    const response = await fetch('/api/upload', {
+      method: 'POST',
+      body: formData,
+    })
+
+    if (!response.ok) {
+      throw new Error('Upload failed')
+    }
+
+    return await response.json()
+  }
+
+  return (
+    <ImageField
+      name="avatar"
+      value={avatar}
+      onChange={setAvatar}
+      label="Avatar"
+      onUpload={handleUpload}
+    />
+  )
+}
+```
+
+## Storage Providers
+
+### Local Filesystem
+
+```typescript
+import { localStorage } from '@opensaas/stack-storage'
+
+storage: {
+  documents: localStorage({
+    uploadDir: './public/uploads/documents',
+    serveUrl: '/uploads/documents',
+    generateUniqueFilenames: true, // default
+  }),
+}
+```
+
+### AWS S3
+
+```typescript
+import { s3Storage } from '@opensaas/stack-storage-s3'
+
+storage: {
+  avatars: s3Storage({
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    pathPrefix: 'avatars', // optional
+    acl: 'public-read', // default: 'private'
+    customDomain: 'https://cdn.example.com', // optional
+  }),
+}
+```
+
+### S3-Compatible Services (MinIO, Backblaze, etc.)
+
+```typescript
+storage: {
+  files: s3Storage({
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    endpoint: 'https://s3.backblazeb2.com',
+    forcePathStyle: true,
+    accessKeyId: process.env.B2_KEY_ID,
+    secretAccessKey: process.env.B2_APPLICATION_KEY,
+  }),
+}
+```
+
+### Vercel Blob
+
+```typescript
+import { vercelBlobStorage } from '@opensaas/stack-storage-vercel'
+
+storage: {
+  images: vercelBlobStorage({
+    token: process.env.BLOB_READ_WRITE_TOKEN,
+    pathPrefix: 'images',
+    public: true, // default
+  }),
+}
+```
+
+## Image Transformations
+
+Generate multiple image variants automatically:
+
+```typescript
+avatar: image({
+  storage: 'avatars',
+  transformations: {
+    thumbnail: {
+      width: 100,
+      height: 100,
+      fit: 'cover', // crop to fill
+      format: 'webp',
+      quality: 80,
+    },
+    large: {
+      width: 1200,
+      height: 1200,
+      fit: 'inside', // scale to fit within bounds
+      format: 'jpeg',
+      quality: 90,
+    },
+  },
+})
+```
+
+Available fit modes:
+
+- `cover` - Crop to fill dimensions
+- `contain` - Scale to fit within dimensions (letterbox)
+- `fill` - Stretch to fill dimensions
+- `inside` - Scale down to fit within dimensions
+- `outside` - Scale up to cover dimensions
+
+## Validation
+
+```typescript
+file({
+  storage: 'documents',
+  validation: {
+    maxFileSize: 10 * 1024 * 1024, // 10MB in bytes
+    acceptedMimeTypes: ['application/pdf', 'application/msword'],
+    acceptedExtensions: ['.pdf', '.doc', '.docx'],
+  },
+})
+```
+
+## Metadata Storage
+
+Files and images store metadata as JSON in your database:
+
+```typescript
+// FileMetadata
+{
+  filename: "1234567890-abc123.pdf",
+  originalFilename: "resume.pdf",
+  url: "https://bucket.s3.amazonaws.com/...",
+  mimeType: "application/pdf",
+  size: 245678,
+  uploadedAt: "2025-10-31T12:00:00Z",
+  storageProvider: "documents",
+  metadata: { /* custom metadata */ }
+}
+
+// ImageMetadata (extends FileMetadata)
+{
+  filename: "1234567890-abc123.jpg",
+  originalFilename: "avatar.jpg",
+  url: "https://bucket.s3.amazonaws.com/...",
+  mimeType: "image/jpeg",
+  size: 123456,
+  width: 1200,
+  height: 800,
+  uploadedAt: "2025-10-31T12:00:00Z",
+  storageProvider: "avatars",
+  transformations: {
+    thumbnail: {
+      url: "https://...",
+      width: 100,
+      height: 100,
+      size: 5678
+    }
+  }
+}
+```
+
+## Runtime Utilities
+
+### Upload Helpers
+
+```typescript
+import { uploadFile, uploadImage, deleteFile, deleteImage } from '@opensaas/stack-storage/runtime'
+
+// Upload file
+const metadata = await uploadFile(
+  config,
+  'documents',
+  { file, buffer },
+  {
+    validation: { maxFileSize: 10 * 1024 * 1024 },
+  },
+)
+
+// Upload image with transformations
+const imageMetadata = await uploadImage(
+  config,
+  'avatars',
+  { file, buffer },
+  {
+    validation: { maxFileSize: 5 * 1024 * 1024 },
+    transformations: {
+      thumbnail: { width: 100, height: 100, fit: 'cover' },
+    },
+  },
+)
+
+// Delete file
+await deleteFile(config, 'documents', metadata.filename)
+
+// Delete image (includes all transformations)
+await deleteImage(config, imageMetadata)
+```
+
+### Validation Utilities
+
+```typescript
+import { validateFile, formatFileSize, getMimeType } from '@opensaas/stack-storage/utils'
+
+const validation = validateFile(
+  { size: file.size, name: file.name, type: file.type },
+  { maxFileSize: 10 * 1024 * 1024, acceptedMimeTypes: ['application/pdf'] },
+)
+
+if (!validation.valid) {
+  console.error(validation.error)
+}
+```
+
+## Custom Storage Providers
+
+Implement the `StorageProvider` interface:
+
+```typescript
+import type { StorageProvider, UploadOptions, UploadResult } from '@opensaas/stack-storage'
+
+export class CustomStorageProvider implements StorageProvider {
+  async upload(
+    file: Buffer | Uint8Array,
+    filename: string,
+    options?: UploadOptions,
+  ): Promise<UploadResult> {
+    // Your upload logic
+    return {
+      filename: 'generated-filename.jpg',
+      url: 'https://your-cdn.com/file.jpg',
+      size: file.length,
+      contentType: options?.contentType || 'application/octet-stream',
+    }
+  }
+
+  async download(filename: string): Promise<Buffer> {
+    // Your download logic
+  }
+
+  async delete(filename: string): Promise<void> {
+    // Your delete logic
+  }
+
+  getUrl(filename: string): string {
+    return `https://your-cdn.com/${filename}`
+  }
+
+  async getSignedUrl(filename: string, expiresIn?: number): Promise<string> {
+    // Optional: signed URLs for private files
+  }
+}
+```
+
+## License
+
+MIT

package/dist/config/index.d.ts

@@ -0,0 +1,19 @@
+import type { LocalStorageConfig } from './types.js';
+export * from './types.js';
+/**
+ * Creates a local filesystem storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     documents: localStorage({
+ *       uploadDir: './uploads/documents',
+ *       serveUrl: '/api/files',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export declare function localStorage(config: Pick<LocalStorageConfig, 'uploadDir' | 'serveUrl'> & Partial<Pick<LocalStorageConfig, 'generateUniqueFilenames'>>): LocalStorageConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,cAAc,YAAY,CAAA;AAE1B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,yBAAyB,CAAC,CAAC,GAC7D,kBAAkB,CAOpB"}

package/dist/config/index.js

@@ -0,0 +1,25 @@
+export * from './types.js';
+/**
+ * Creates a local filesystem storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     documents: localStorage({
+ *       uploadDir: './uploads/documents',
+ *       serveUrl: '/api/files',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function localStorage(config) {
+    return {
+        type: 'local',
+        uploadDir: config.uploadDir,
+        serveUrl: config.serveUrl,
+        generateUniqueFilenames: config.generateUniqueFilenames ?? true,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAEA,cAAc,YAAY,CAAA;AAE1B;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,MAC8D;IAE9D,OAAO;QACL,IAAI,EAAE,OAAO;QACb,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAI,IAAI;KAChE,CAAA;AACH,CAAC"}

package/dist/config/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Storage provider interface that all storage backends must implement.
+ * This allows pluggable storage solutions (local, S3, Vercel Blob, etc.)
+ */
+export interface StorageProvider {
+    /**
+     * Uploads a file to the storage provider
+     * @param file - File data as Buffer or Uint8Array
+     * @param filename - Desired filename (may be transformed by provider)
+     * @param options - Additional upload options (contentType, metadata, etc.)
+     * @returns Upload result with URL and metadata
+     */
+    upload(file: Buffer | Uint8Array, filename: string, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Downloads a file from the storage provider
+     * @param filename - Filename to download
+     * @returns File data as Buffer
+     */
+    download(filename: string): Promise<Buffer>;
+    /**
+     * Deletes a file from the storage provider
+     * @param filename - Filename to delete
+     */
+    delete(filename: string): Promise<void>;
+    /**
+     * Gets the public URL for a file
+     * @param filename - Filename to get URL for
+     * @returns Public URL string
+     */
+    getUrl(filename: string): string;
+    /**
+     * Optional: Gets a signed URL for private files
+     * @param filename - Filename to get signed URL for
+     * @param expiresIn - Expiration time in seconds
+     * @returns Signed URL string
+     */
+    getSignedUrl?(filename: string, expiresIn?: number): Promise<string>;
+}
+/**
+ * Options for uploading a file
+ */
+export interface UploadOptions {
+    /** MIME type of the file */
+    contentType?: string;
+    /** Custom metadata to store with the file */
+    metadata?: Record<string, string>;
+    /** Whether the file should be publicly accessible */
+    public?: boolean;
+    /** Cache control header */
+    cacheControl?: string;
+}
+/**
+ * Result from uploading a file
+ */
+export interface UploadResult {
+    /** Generated filename (may differ from input) */
+    filename: string;
+    /** Public URL to access the file */
+    url: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    contentType: string;
+    /** Additional provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for local filesystem storage
+ */
+export interface LocalStorageConfig {
+    type: 'local';
+    /** Directory to store uploaded files */
+    uploadDir: string;
+    /** Base URL for serving files (e.g., '/api/files' or 'https://cdn.example.com') */
+    serveUrl: string;
+    /** Whether to generate unique filenames (default: true) */
+    generateUniqueFilenames?: boolean;
+    /** Allow additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Base configuration shared by all storage providers
+ */
+export interface BaseStorageConfig {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Storage configuration - maps names to storage provider configs
+ * Example: { avatars: s3Config, documents: localConfig }
+ */
+export type StorageConfig = Record<string, BaseStorageConfig | LocalStorageConfig>;
+/**
+ * Re-export metadata types from core package
+ * These types are now defined in @opensaas/stack-core to avoid circular dependencies
+ */
+export type { FileMetadata, ImageMetadata, ImageTransformationResult } from '@opensaas/stack-core';
+/**
+ * Configuration for image transformations
+ */
+export interface ImageTransformationConfig {
+    /** Target width in pixels */
+    width?: number;
+    /** Target height in pixels */
+    height?: number;
+    /** Fit mode: cover (crop), contain (letterbox), fill (stretch) */
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    /** Output format (default: original format) */
+    format?: 'jpeg' | 'png' | 'webp' | 'avif';
+    /** Quality 1-100 (default: 80) */
+    quality?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,MAAM,CACJ,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAA;IAExB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3C;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IAEhC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAA;IACX,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAA;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAA;IAChB,2DAA2D;IAC3D,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC,kCAAkC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,kBAAkB,CAAC,CAAA;AAElF;;;GAGG;AACH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAA;AAElG;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kEAAkE;IAClE,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;IACzD,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAA;IACzC,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB"}

package/dist/config/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":""}