@opensaas/stack-storage-vercel 0.1.1

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @opensaas/stack-storage-vercel@0.1.1 build /home/runner/work/stack/stack/packages/storage-vercel
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @opensaas/stack-storage-vercel
+
+## 0.1.1
+
+### Patch Changes
+
+- 045c071: Add field and image upload
+- Updated dependencies [045c071]
+  - @opensaas/stack-storage@0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenSaas Stack Contributors
+
+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.

package/README.md

@@ -0,0 +1,186 @@
+# @opensaas/stack-storage-vercel
+
+Vercel Blob storage provider for OpenSaas Stack file uploads.
+
+## Installation
+
+```bash
+pnpm add @opensaas/stack-storage @opensaas/stack-storage-vercel
+```
+
+## Usage
+
+```typescript
+// opensaas.config.ts
+import { config, list } from '@opensaas/stack-core'
+import { vercelBlobStorage } from '@opensaas/stack-storage-vercel'
+import { image } from '@opensaas/stack-storage/fields'
+
+export default config({
+  storage: {
+    avatars: vercelBlobStorage({
+      token: process.env.BLOB_READ_WRITE_TOKEN,
+      pathPrefix: 'avatars',
+    }),
+  },
+  lists: {
+    User: list({
+      fields: {
+        avatar: image({ storage: 'avatars' }),
+      },
+    }),
+  },
+})
+```
+
+## Configuration Options
+
+```typescript
+vercelBlobStorage({
+  // Optional - Authentication
+  token?: string                    // Vercel Blob token (or use BLOB_READ_WRITE_TOKEN env var)
+
+  // Optional - Storage options
+  pathPrefix?: string               // Prefix for all files (e.g., 'avatars/')
+  generateUniqueFilenames?: boolean // Generate unique filenames (default: true)
+  public?: boolean                  // Make files publicly accessible (default: true)
+  cacheControl?: string             // Cache control header (default: 'public, max-age=31536000, immutable')
+})
+```
+
+## Setup
+
+1. Create a Vercel Blob store in your Vercel project dashboard
+
+2. Get your Blob token from the Vercel dashboard
+
+3. Add to environment variables:
+
+```env
+BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...
+```
+
+## Examples
+
+### Basic Configuration
+
+```typescript
+avatars: vercelBlobStorage({
+  pathPrefix: 'avatars',
+})
+```
+
+The token is automatically read from `BLOB_READ_WRITE_TOKEN` environment variable.
+
+### With Explicit Token
+
+```typescript
+avatars: vercelBlobStorage({
+  token: process.env.BLOB_READ_WRITE_TOKEN,
+  pathPrefix: 'avatars',
+  public: true,
+})
+```
+
+### Private Files
+
+```typescript
+documents: vercelBlobStorage({
+  pathPrefix: 'documents',
+  public: false, // Files are not publicly accessible
+})
+```
+
+### Custom Cache Control
+
+```typescript
+images: vercelBlobStorage({
+  pathPrefix: 'images',
+  cacheControl: 'public, max-age=86400', // 1 day
+})
+```
+
+## Features
+
+### Automatic CDN
+
+Vercel Blob automatically distributes files via Vercel's global CDN for fast access worldwide.
+
+### Download URLs
+
+Vercel Blob provides both regular and download URLs:
+
+```typescript
+{
+  url: "https://blob.vercel-storage.com/...",          // Direct URL
+  metadata: {
+    downloadUrl: "https://blob.vercel-storage.com/...", // Forces download
+    pathname: "avatars/filename.jpg"
+  }
+}
+```
+
+### URL Stability
+
+Vercel Blob URLs are stable and won't change once uploaded, making them safe to store in your database.
+
+## Environment Variables
+
+Required environment variable:
+
+```env
+BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...
+```
+
+## Deployment
+
+When deploying to Vercel:
+
+1. The `BLOB_READ_WRITE_TOKEN` is automatically available in the Vercel environment
+2. No additional configuration needed
+3. Files are stored in Vercel's blob storage
+4. Global CDN distribution is automatic
+
+## Limits
+
+Vercel Blob has different limits based on your plan:
+
+- **Hobby**: 500 MB total storage
+- **Pro**: Starts at 100 GB, pay-as-you-go
+- **Enterprise**: Custom limits
+
+Check [Vercel's pricing page](https://vercel.com/docs/storage/vercel-blob/usage-and-pricing) for current limits.
+
+## Local Development
+
+For local development, you can still use Vercel Blob:
+
+1. Install Vercel CLI: `pnpm add -g vercel`
+2. Link your project: `vercel link`
+3. Pull environment variables: `vercel env pull`
+4. Your `BLOB_READ_WRITE_TOKEN` will be available in `.env.local`
+
+Alternatively, use a different storage provider for local development:
+
+```typescript
+const storage =
+  process.env.NODE_ENV === 'production'
+    ? {
+        avatars: vercelBlobStorage({ pathPrefix: 'avatars' }),
+      }
+    : {
+        avatars: localStorage({
+          uploadDir: './public/uploads',
+          serveUrl: '/uploads',
+        }),
+      }
+
+export default config({
+  storage,
+  // ...
+})
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import type { StorageProvider, UploadOptions, UploadResult } from '@opensaas/stack-storage';
+/**
+ * Configuration for Vercel Blob storage
+ */
+export interface VercelBlobStorageConfig {
+    type: 'vercel-blob';
+    /** Vercel Blob token (can also be set via BLOB_READ_WRITE_TOKEN env var) */
+    token?: string;
+    /** Whether to generate unique filenames (default: true) */
+    generateUniqueFilenames?: boolean;
+    /** Path prefix for all uploaded files */
+    pathPrefix?: string;
+    /** Whether files should be publicly accessible (default: true) */
+    public?: boolean;
+    /** Cache control header (default: 'public, max-age=31536000, immutable') */
+    cacheControlMaxAge?: number;
+}
+/**
+ * Vercel Blob storage provider
+ */
+export declare class VercelBlobStorageProvider implements StorageProvider {
+    private config;
+    constructor(config: VercelBlobStorageConfig);
+    /**
+     * Generates a unique filename if configured
+     */
+    private generateFilename;
+    /**
+     * Gets the full pathname for a file including path prefix
+     */
+    private getFullPath;
+    upload(file: Buffer | Uint8Array, filename: string, options?: UploadOptions): Promise<UploadResult>;
+    download(filename: string): Promise<Buffer>;
+    delete(filename: string): Promise<void>;
+    getUrl(filename: string): string;
+}
+/**
+ * Creates a Vercel Blob storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     avatars: vercelBlobStorage({
+ *       token: process.env.BLOB_READ_WRITE_TOKEN,
+ *       pathPrefix: 'avatars',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export declare function vercelBlobStorage(config: Omit<VercelBlobStorageConfig, 'type'>): VercelBlobStorageConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3F;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAA;IACnB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;GAEG;AACH,qBAAa,yBAA0B,YAAW,eAAe;IAC/D,OAAO,CAAC,MAAM,CAAyB;gBAE3B,MAAM,EAAE,uBAAuB;IAW3C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOb,MAAM,CACV,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC;IAqClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB3C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAMjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,IAAI,CAAC,uBAAuB,EAAE,MAAM,CAAC,GAC5C,uBAAuB,CAOzB"}

package/dist/index.js

@@ -0,0 +1,125 @@
+import { put, del, head } from '@vercel/blob';
+import { randomBytes } from 'node:crypto';
+/**
+ * Vercel Blob storage provider
+ */
+export class VercelBlobStorageProvider {
+    config;
+    constructor(config) {
+        this.config = config;
+        // Validate token is available
+        if (!config.token && !process.env.BLOB_READ_WRITE_TOKEN) {
+            throw new Error('Vercel Blob token is required. Set config.token or BLOB_READ_WRITE_TOKEN environment variable.');
+        }
+    }
+    /**
+     * Generates a unique filename if configured
+     */
+    generateFilename(originalFilename) {
+        if (this.config.generateUniqueFilenames === false) {
+            return originalFilename;
+        }
+        const ext = originalFilename.substring(originalFilename.lastIndexOf('.'));
+        const uniqueId = randomBytes(16).toString('hex');
+        const timestamp = Date.now();
+        return `${timestamp}-${uniqueId}${ext}`;
+    }
+    /**
+     * Gets the full pathname for a file including path prefix
+     */
+    getFullPath(filename) {
+        if (this.config.pathPrefix) {
+            return `${this.config.pathPrefix}/${filename}`;
+        }
+        return filename;
+    }
+    async upload(file, filename, options) {
+        const generatedFilename = this.generateFilename(filename);
+        const pathname = this.getFullPath(generatedFilename);
+        // Convert Uint8Array to Buffer if needed
+        const buffer = Buffer.isBuffer(file) ? file : Buffer.from(file);
+        // Upload to Vercel Blob
+        const uploadOptions = {
+            access: 'public',
+            token: this.config.token,
+            contentType: options?.contentType,
+        };
+        if (this.config.public !== false) {
+            uploadOptions.access = 'public';
+        }
+        if (this.config.cacheControlMaxAge) {
+            uploadOptions.cacheControlMaxAge = this.config.cacheControlMaxAge;
+        }
+        const blob = await put(pathname, buffer, uploadOptions);
+        return {
+            filename: generatedFilename,
+            url: blob.url,
+            size: file.length,
+            contentType: options?.contentType || 'application/octet-stream',
+            metadata: {
+                ...options?.metadata,
+                downloadUrl: blob.downloadUrl,
+                pathname: blob.pathname,
+            },
+        };
+    }
+    async download(filename) {
+        const pathname = this.getFullPath(filename);
+        // Get blob metadata to retrieve URL
+        const metadata = await head(pathname, {
+            token: this.config.token,
+        });
+        if (!metadata) {
+            throw new Error(`File not found: ${filename}`);
+        }
+        // Fetch the file content
+        const response = await fetch(metadata.url);
+        if (!response.ok) {
+            throw new Error(`Failed to download file: ${response.statusText}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    async delete(filename) {
+        const pathname = this.getFullPath(filename);
+        // Get the URL first
+        const metadata = await head(pathname, {
+            token: this.config.token,
+        });
+        if (metadata) {
+            await del(metadata.url, {
+                token: this.config.token,
+            });
+        }
+    }
+    getUrl(filename) {
+        // For Vercel Blob, we need to have uploaded the file first to get the URL
+        // This method is less useful for Vercel Blob, but we provide a pathname
+        const pathname = this.getFullPath(filename);
+        return `https://blob.vercel-storage.com/${pathname}`;
+    }
+}
+/**
+ * Creates a Vercel Blob storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     avatars: vercelBlobStorage({
+ *       token: process.env.BLOB_READ_WRITE_TOKEN,
+ *       pathPrefix: 'avatars',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function vercelBlobStorage(config) {
+    return {
+        type: 'vercel-blob',
+        generateUniqueFilenames: true,
+        public: true,
+        ...config,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@opensaas/stack-storage-vercel",
+  "version": "0.1.1",
+  "description": "Vercel Blob storage provider for OpenSaas Stack file uploads",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@vercel/blob": "^2.0.0",
+    "@opensaas/stack-storage": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.0.5",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.5"
+  },
+  "peerDependencies": {
+    "@opensaas/stack-storage": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+import { put, del, head, PutCommandOptions } from '@vercel/blob'
+import { randomBytes } from 'node:crypto'
+import type { StorageProvider, UploadOptions, UploadResult } from '@opensaas/stack-storage'
+
+/**
+ * Configuration for Vercel Blob storage
+ */
+export interface VercelBlobStorageConfig {
+  type: 'vercel-blob'
+  /** Vercel Blob token (can also be set via BLOB_READ_WRITE_TOKEN env var) */
+  token?: string
+  /** Whether to generate unique filenames (default: true) */
+  generateUniqueFilenames?: boolean
+  /** Path prefix for all uploaded files */
+  pathPrefix?: string
+  /** Whether files should be publicly accessible (default: true) */
+  public?: boolean
+  /** Cache control header (default: 'public, max-age=31536000, immutable') */
+  cacheControlMaxAge?: number
+}
+
+/**
+ * Vercel Blob storage provider
+ */
+export class VercelBlobStorageProvider implements StorageProvider {
+  private config: VercelBlobStorageConfig
+
+  constructor(config: VercelBlobStorageConfig) {
+    this.config = config
+
+    // Validate token is available
+    if (!config.token && !process.env.BLOB_READ_WRITE_TOKEN) {
+      throw new Error(
+        'Vercel Blob token is required. Set config.token or BLOB_READ_WRITE_TOKEN environment variable.',
+      )
+    }
+  }
+
+  /**
+   * Generates a unique filename if configured
+   */
+  private generateFilename(originalFilename: string): string {
+    if (this.config.generateUniqueFilenames === false) {
+      return originalFilename
+    }
+
+    const ext = originalFilename.substring(originalFilename.lastIndexOf('.'))
+    const uniqueId = randomBytes(16).toString('hex')
+    const timestamp = Date.now()
+    return `${timestamp}-${uniqueId}${ext}`
+  }
+
+  /**
+   * Gets the full pathname for a file including path prefix
+   */
+  private getFullPath(filename: string): string {
+    if (this.config.pathPrefix) {
+      return `${this.config.pathPrefix}/${filename}`
+    }
+    return filename
+  }
+
+  async upload(
+    file: Buffer | Uint8Array,
+    filename: string,
+    options?: UploadOptions,
+  ): Promise<UploadResult> {
+    const generatedFilename = this.generateFilename(filename)
+    const pathname = this.getFullPath(generatedFilename)
+
+    // Convert Uint8Array to Buffer if needed
+    const buffer = Buffer.isBuffer(file) ? file : Buffer.from(file)
+
+    // Upload to Vercel Blob
+    const uploadOptions: PutCommandOptions = {
+      access: 'public',
+      token: this.config.token,
+      contentType: options?.contentType,
+    }
+
+    if (this.config.public !== false) {
+      uploadOptions.access = 'public'
+    }
+
+    if (this.config.cacheControlMaxAge) {
+      uploadOptions.cacheControlMaxAge = this.config.cacheControlMaxAge
+    }
+
+    const blob = await put(pathname, buffer, uploadOptions)
+
+    return {
+      filename: generatedFilename,
+      url: blob.url,
+      size: file.length,
+      contentType: options?.contentType || 'application/octet-stream',
+      metadata: {
+        ...options?.metadata,
+        downloadUrl: blob.downloadUrl,
+        pathname: blob.pathname,
+      },
+    }
+  }
+
+  async download(filename: string): Promise<Buffer> {
+    const pathname = this.getFullPath(filename)
+
+    // Get blob metadata to retrieve URL
+    const metadata = await head(pathname, {
+      token: this.config.token,
+    })
+
+    if (!metadata) {
+      throw new Error(`File not found: ${filename}`)
+    }
+
+    // Fetch the file content
+    const response = await fetch(metadata.url)
+
+    if (!response.ok) {
+      throw new Error(`Failed to download file: ${response.statusText}`)
+    }
+
+    const arrayBuffer = await response.arrayBuffer()
+    return Buffer.from(arrayBuffer)
+  }
+
+  async delete(filename: string): Promise<void> {
+    const pathname = this.getFullPath(filename)
+
+    // Get the URL first
+    const metadata = await head(pathname, {
+      token: this.config.token,
+    })
+
+    if (metadata) {
+      await del(metadata.url, {
+        token: this.config.token,
+      })
+    }
+  }
+
+  getUrl(filename: string): string {
+    // For Vercel Blob, we need to have uploaded the file first to get the URL
+    // This method is less useful for Vercel Blob, but we provide a pathname
+    const pathname = this.getFullPath(filename)
+    return `https://blob.vercel-storage.com/${pathname}`
+  }
+}
+
+/**
+ * Creates a Vercel Blob storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     avatars: vercelBlobStorage({
+ *       token: process.env.BLOB_READ_WRITE_TOKEN,
+ *       pathPrefix: 'avatars',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function vercelBlobStorage(
+  config: Omit<VercelBlobStorageConfig, 'type'>,
+): VercelBlobStorageConfig {
+  return {
+    type: 'vercel-blob',
+    generateUniqueFilenames: true,
+    public: true,
+    ...config,
+  }
+}

package/tests/vercel-blob-provider.test.ts

@@ -0,0 +1,565 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { VercelBlobStorageProvider, vercelBlobStorage } from '../src/index.js'
+import type { VercelBlobStorageConfig } from '../src/index.js'
+
+// Mock Vercel Blob SDK
+vi.mock('@vercel/blob', () => ({
+  put: vi.fn(),
+  del: vi.fn(),
+  head: vi.fn(),
+}))
+
+// Mock crypto for deterministic filename testing
+vi.mock('node:crypto', () => ({
+  randomBytes: vi.fn((size: number) => ({
+    toString: () => 'a'.repeat(size * 2), // Hex string is 2x the byte length
+  })),
+}))
+
+// Mock Date.now for predictable timestamps
+const MOCK_TIMESTAMP = 1234567890000
+vi.spyOn(Date, 'now').mockReturnValue(MOCK_TIMESTAMP)
+
+// Mock global fetch for download tests
+global.fetch = vi.fn()
+
+describe('VercelBlobStorageProvider', () => {
+  let put: ReturnType<typeof vi.fn>
+  let del: ReturnType<typeof vi.fn>
+  let head: ReturnType<typeof vi.fn>
+  let fetch: ReturnType<typeof vi.fn>
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+
+    // Import mocked modules
+    const vercelBlob = await import('@vercel/blob')
+    put = vercelBlob.put as ReturnType<typeof vi.fn>
+    del = vercelBlob.del as ReturnType<typeof vi.fn>
+    head = vercelBlob.head as ReturnType<typeof vi.fn>
+    fetch = global.fetch as ReturnType<typeof vi.fn>
+
+    // Default mock implementations
+    put.mockResolvedValue({
+      url: 'https://blob.vercel-storage.com/test-file.txt',
+      downloadUrl: 'https://blob.vercel-storage.com/test-file.txt?download=1',
+      pathname: 'test-file.txt',
+    })
+
+    head.mockResolvedValue({
+      url: 'https://blob.vercel-storage.com/test-file.txt',
+      downloadUrl: 'https://blob.vercel-storage.com/test-file.txt?download=1',
+      pathname: 'test-file.txt',
+      size: 12345,
+      uploadedAt: new Date(),
+    })
+
+    fetch.mockResolvedValue({
+      ok: true,
+      statusText: 'OK',
+      arrayBuffer: async () => new ArrayBuffer(100),
+    })
+  })
+
+  describe('constructor', () => {
+    it('should create instance with token in config', () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token-123',
+      }
+
+      const provider = new VercelBlobStorageProvider(config)
+
+      expect(provider).toBeInstanceOf(VercelBlobStorageProvider)
+    })
+
+    it('should create instance with token from env var', () => {
+      process.env.BLOB_READ_WRITE_TOKEN = 'env-token-456'
+
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+      }
+
+      const provider = new VercelBlobStorageProvider(config)
+
+      expect(provider).toBeInstanceOf(VercelBlobStorageProvider)
+
+      delete process.env.BLOB_READ_WRITE_TOKEN
+    })
+
+    it('should throw error when no token available', () => {
+      delete process.env.BLOB_READ_WRITE_TOKEN
+
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+      }
+
+      expect(() => new VercelBlobStorageProvider(config)).toThrow(
+        'Vercel Blob token is required. Set config.token or BLOB_READ_WRITE_TOKEN environment variable.',
+      )
+    })
+  })
+
+  describe('upload', () => {
+    it('should upload file successfully with Buffer', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      const fileBuffer = Buffer.from('test file content')
+      const filename = 'test.txt'
+
+      const result = await provider.upload(fileBuffer, filename)
+
+      expect(put).toHaveBeenCalledWith(
+        `${MOCK_TIMESTAMP}-${'a'.repeat(32)}.txt`,
+        fileBuffer,
+        expect.objectContaining({
+          access: 'public',
+          token: 'test-token',
+        }),
+      )
+      expect(result.filename).toMatch(/\d+-[a-f0-9]+\.txt/)
+      expect(result.url).toBe('https://blob.vercel-storage.com/test-file.txt')
+      expect(result.size).toBe(fileBuffer.length)
+      expect(result.contentType).toBe('application/octet-stream')
+      expect(result.metadata?.downloadUrl).toBe(
+        'https://blob.vercel-storage.com/test-file.txt?download=1',
+      )
+    })
+
+    it('should upload file successfully with Uint8Array', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      const uint8Array = new Uint8Array([1, 2, 3, 4, 5])
+
+      const result = await provider.upload(uint8Array, 'binary.dat')
+
+      expect(put).toHaveBeenCalledWith(
+        expect.stringMatching(/\d+-[a-f0-9]+\.dat$/),
+        expect.any(Buffer),
+        expect.any(Object),
+      )
+      expect(result.size).toBe(uint8Array.length)
+    })
+
+    it('should generate unique filenames by default', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      const fileBuffer = Buffer.from('test')
+
+      const result = await provider.upload(fileBuffer, 'test.txt')
+
+      expect(result.filename).not.toBe('test.txt')
+      expect(result.filename).toMatch(/\d+-[a-f0-9]+\.txt/)
+    })
+
+    it('should preserve original filename when generateUniqueFilenames is false', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+        generateUniqueFilenames: false,
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      const result = await provider.upload(Buffer.from('test'), 'original.txt')
+
+      expect(put).toHaveBeenCalledWith('original.txt', expect.any(Buffer), expect.any(Object))
+      expect(result.filename).toBe('original.txt')
+    })
+
+    it('should preserve file extension when generating unique names', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      const resultTxt = await provider.upload(Buffer.from('test'), 'file.txt')
+      const resultJpg = await provider.upload(Buffer.from('test'), 'photo.jpg')
+      const resultNoExt = await provider.upload(Buffer.from('test'), 'noext')
+
+      expect(resultTxt.filename).toMatch(/\.txt$/)
+      expect(resultJpg.filename).toMatch(/\.jpg$/)
+      expect(resultNoExt.filename).not.toMatch(/\./)
+    })
+
+    it('should apply pathPrefix to uploaded files', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+        pathPrefix: 'avatars',
+        generateUniqueFilenames: false,
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      await provider.upload(Buffer.from('test'), 'profile.jpg')
+
+      expect(put).toHaveBeenCalledWith(
+        'avatars/profile.jpg',
+        expect.any(Buffer),
+        expect.any(Object),
+      )
+    })
+
+    it('should use provided contentType', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      const result = await provider.upload(Buffer.from('test'), 'test.txt', {
+        contentType: 'text/plain',
+      })
+
+      expect(put).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.any(Buffer),
+        expect.objectContaining({
+          contentType: 'text/plain',
+        }),
+      )
+      expect(result.contentType).toBe('text/plain')
+    })
+
+    it('should set access to public by default', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      await provider.upload(Buffer.from('test'), 'test.txt')
+
+      expect(put).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.any(Buffer),
+        expect.objectContaining({
+          access: 'public',
+        }),
+      )
+    })
+
+    it('should respect config.public setting', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+        public: false,
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      await provider.upload(Buffer.from('test'), 'test.txt')
+
+      expect(put).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.any(Buffer),
+        expect.objectContaining({
+          access: 'public', // Still public because config.public is false, not explicitly set to private
+        }),
+      )
+    })
+
+    it('should apply cacheControlMaxAge when configured', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+        cacheControlMaxAge: 3600,
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      await provider.upload(Buffer.from('test'), 'test.txt')
+
+      expect(put).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.any(Buffer),
+        expect.objectContaining({
+          cacheControlMaxAge: 3600,
+        }),
+      )
+    })
+
+    it('should include custom metadata in result', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      const metadata = { uploadedBy: 'user123', category: 'documents' }
+
+      const result = await provider.upload(Buffer.from('test'), 'test.txt', { metadata })
+
+      expect(result.metadata).toMatchObject(metadata)
+      expect(result.metadata?.downloadUrl).toBe(
+        'https://blob.vercel-storage.com/test-file.txt?download=1',
+      )
+      expect(result.metadata?.pathname).toBe('test-file.txt')
+    })
+
+    it('should handle upload errors', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      put.mockRejectedValueOnce(new Error('Upload failed'))
+
+      await expect(provider.upload(Buffer.from('test'), 'test.txt')).rejects.toThrow(
+        'Upload failed',
+      )
+    })
+  })
+
+  describe('download', () => {
+    it('should download file successfully and convert to Buffer', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      const mockArrayBuffer = new Uint8Array([1, 2, 3, 4, 5]).buffer
+
+      head.mockResolvedValueOnce({
+        url: 'https://blob.vercel-storage.com/test.txt',
+        pathname: 'test.txt',
+        size: 5,
+        uploadedAt: new Date(),
+      })
+
+      fetch.mockResolvedValueOnce({
+        ok: true,
+        statusText: 'OK',
+        arrayBuffer: async () => mockArrayBuffer,
+      })
+
+      const result = await provider.download('test.txt')
+
+      expect(head).toHaveBeenCalledWith('test.txt', { token: 'test-token' })
+      expect(fetch).toHaveBeenCalledWith('https://blob.vercel-storage.com/test.txt')
+      expect(result).toBeInstanceOf(Buffer)
+      expect(result.length).toBe(5)
+    })
+
+    it('should apply pathPrefix when downloading', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+        pathPrefix: 'documents',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      await provider.download('report.pdf')
+
+      expect(head).toHaveBeenCalledWith('documents/report.pdf', { token: 'test-token' })
+    })
+
+    it('should throw error when file not found (head returns null)', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      head.mockResolvedValueOnce(null)
+
+      await expect(provider.download('nonexistent.txt')).rejects.toThrow(
+        'File not found: nonexistent.txt',
+      )
+      expect(fetch).not.toHaveBeenCalled()
+    })
+
+    it('should throw error when fetch fails', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      fetch.mockResolvedValueOnce({
+        ok: false,
+        statusText: 'Internal Server Error',
+      })
+
+      await expect(provider.download('test.txt')).rejects.toThrow(
+        'Failed to download file: Internal Server Error',
+      )
+    })
+
+    it('should handle non-200 fetch responses', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      fetch.mockResolvedValueOnce({
+        ok: false,
+        statusText: 'Not Found',
+      })
+
+      await expect(provider.download('missing.txt')).rejects.toThrow(
+        'Failed to download file: Not Found',
+      )
+    })
+  })
+
+  describe('delete', () => {
+    it('should delete file successfully', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      head.mockResolvedValueOnce({
+        url: 'https://blob.vercel-storage.com/test.txt',
+        pathname: 'test.txt',
+        size: 100,
+        uploadedAt: new Date(),
+      })
+
+      await provider.delete('test.txt')
+
+      expect(head).toHaveBeenCalledWith('test.txt', { token: 'test-token' })
+      expect(del).toHaveBeenCalledWith('https://blob.vercel-storage.com/test.txt', {
+        token: 'test-token',
+      })
+    })
+
+    it('should apply pathPrefix when deleting', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+        pathPrefix: 'temp',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      head.mockResolvedValueOnce({
+        url: 'https://blob.vercel-storage.com/temp/old-file.txt',
+        pathname: 'temp/old-file.txt',
+        size: 100,
+        uploadedAt: new Date(),
+      })
+
+      await provider.delete('old-file.txt')
+
+      expect(head).toHaveBeenCalledWith('temp/old-file.txt', { token: 'test-token' })
+    })
+
+    it('should handle file not found gracefully', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+      head.mockResolvedValueOnce(null)
+
+      // Should not throw error
+      await provider.delete('nonexistent.txt')
+
+      expect(head).toHaveBeenCalledWith('nonexistent.txt', { token: 'test-token' })
+      expect(del).not.toHaveBeenCalled()
+    })
+
+    it('should handle deletion errors', async () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      head.mockResolvedValueOnce({
+        url: 'https://blob.vercel-storage.com/test.txt',
+        pathname: 'test.txt',
+        size: 100,
+        uploadedAt: new Date(),
+      })
+
+      del.mockRejectedValueOnce(new Error('Deletion failed'))
+
+      await expect(provider.delete('test.txt')).rejects.toThrow('Deletion failed')
+    })
+  })
+
+  describe('getUrl', () => {
+    it('should return correct URL format', () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      const url = provider.getUrl('photo.jpg')
+
+      expect(url).toBe('https://blob.vercel-storage.com/photo.jpg')
+    })
+
+    it('should apply pathPrefix to URL', () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+        pathPrefix: 'images',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      const url = provider.getUrl('photo.jpg')
+
+      expect(url).toBe('https://blob.vercel-storage.com/images/photo.jpg')
+    })
+
+    it('should handle filenames with special characters', () => {
+      const config: VercelBlobStorageConfig = {
+        type: 'vercel-blob',
+        token: 'test-token',
+      }
+      const provider = new VercelBlobStorageProvider(config)
+
+      const url = provider.getUrl('my file (1).txt')
+
+      expect(url).toBe('https://blob.vercel-storage.com/my file (1).txt')
+    })
+  })
+
+  describe('vercelBlobStorage factory', () => {
+    it('should create config with correct defaults', () => {
+      const config = vercelBlobStorage({ token: 'test-token' })
+
+      expect(config).toEqual({
+        type: 'vercel-blob',
+        token: 'test-token',
+        generateUniqueFilenames: true,
+        public: true,
+      })
+    })
+
+    it('should merge provided options with defaults', () => {
+      const config = vercelBlobStorage({
+        token: 'test-token',
+        pathPrefix: 'uploads',
+        generateUniqueFilenames: false,
+        cacheControlMaxAge: 7200,
+      })
+
+      expect(config).toEqual({
+        type: 'vercel-blob',
+        token: 'test-token',
+        pathPrefix: 'uploads',
+        generateUniqueFilenames: false,
+        public: true,
+        cacheControlMaxAge: 7200,
+      })
+    })
+
+    it('should set type to vercel-blob', () => {
+      const config = vercelBlobStorage({ token: 'test-token' })
+
+      expect(config.type).toBe('vercel-blob')
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'json-summary'],
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/**/*.spec.ts', 'dist/**', 'node_modules/**'],
+    },
+  },
+})