@nextlyhq/storage-vercel-blob 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,727 @@
+/**
+ * Media Storage Types
+ *
+ * Defines interfaces and types for the unified media storage system.
+ * Supports cloud storage adapters via plugins.
+ *
+ * Storage Backends:
+ * - AWS S3 / Cloudflare R2 / MinIO (via @nextlyhq/storage-s3)
+ * - Vercel Blob (via @nextlyhq/storage-vercel-blob)
+ */
+interface UploadOptions {
+    /** Original filename from user */
+    filename: string;
+    /** MIME type (e.g., 'image/png', 'video/mp4') */
+    mimeType: string;
+    /** Optional content type override */
+    contentType?: string;
+    /** Optional folder/prefix for organizing uploads */
+    folder?: string;
+    /** Collection slug this upload belongs to (for collection-specific storage) */
+    collection?: string;
+    /** Optional Content-Disposition header value (e.g., 'attachment' for SVG security) */
+    contentDisposition?: "inline" | "attachment";
+}
+interface UploadResult {
+    /** Public URL to access the file */
+    url: string;
+    /** Storage path/key (for deletion and metadata retrieval) */
+    path: string;
+}
+/**
+ * Extended file metadata returned by getMetadata()
+ *
+ * Contains comprehensive information about an uploaded file,
+ * including dimensions for images and creation timestamps.
+ */
+interface FileMetadata {
+    /** Unique identifier (typically the storage path/key) */
+    id: string;
+    /** Storage filename (may differ from original) */
+    filename: string;
+    /** Original filename as uploaded by user */
+    originalFilename: string;
+    /** MIME type (e.g., 'image/jpeg', 'application/pdf') */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Public URL to access the file */
+    url: string;
+    /** Thumbnail URL for images (if generated) */
+    thumbnailUrl?: string;
+    /** Image width in pixels (for images only) */
+    width?: number;
+    /** Image height in pixels (for images only) */
+    height?: number;
+    /** ISO timestamp when file was uploaded */
+    createdAt: string;
+    /** ISO timestamp when file was last modified */
+    updatedAt?: string;
+}
+/**
+ * Storage type identifier.
+ * - "s3": AWS S3 or S3-compatible services (R2, MinIO, DigitalOcean Spaces)
+ * - "vercel-blob": Vercel Blob Storage
+ * - "local": Local disk storage (default for development)
+ * - "uploadthing": Uploadthing cloud storage
+ */
+type StorageType = "s3" | "vercel-blob" | "local" | "uploadthing";
+/**
+ * Information about a storage adapter's capabilities.
+ * Returned by adapter.getInfo() method.
+ */
+interface StorageAdapterInfo {
+    /** Storage type identifier */
+    type: StorageType;
+    /** Human-readable adapter name */
+    name: string;
+    /** Whether this adapter supports signed URLs for private access */
+    supportsSignedUrls: boolean;
+    /** Whether this adapter supports client-side (direct) uploads */
+    supportsClientUploads: boolean;
+}
+/**
+ * Per-collection storage configuration.
+ * Allows customizing storage behavior for specific upload collections.
+ */
+interface CollectionStorageConfig {
+    /** Prefix/folder for this collection's uploads */
+    prefix?: string;
+    /** Enable client-side uploads (for serverless platforms with body size limits) */
+    clientUploads?: boolean;
+    /** Generate signed URLs for downloads (for private buckets) */
+    signedDownloads?: boolean;
+    /** Signed URL expiry time in seconds (default: 3600) */
+    signedUrlExpiresIn?: number;
+}
+/**
+ * Collection storage map - maps collection slugs to their config.
+ * Used in storage plugin configuration.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   media: true,  // Use default config
+ *   'private-docs': {
+ *     prefix: 'private/',
+ *     signedDownloads: true,
+ *     signedUrlExpiresIn: 900
+ *   }
+ * }
+ * ```
+ */
+type CollectionStorageMap = Record<string, boolean | CollectionStorageConfig>;
+/**
+ * Base configuration for storage plugins.
+ * Extended by specific adapter configs (S3StorageConfig, etc.)
+ */
+interface StoragePluginConfig {
+    /** Enable/disable the plugin (default: true) */
+    enabled?: boolean;
+    /** Collections to apply this storage adapter to */
+    collections: CollectionStorageMap;
+}
+/**
+ * Storage plugin returned by adapter plugin functions.
+ * These are processed during Nextly initialization.
+ *
+ * @example
+ * ```typescript
+ * // From @nextlyhq/storage-s3
+ * const plugin = s3Storage({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   collections: { media: true }
+ * });
+ * // plugin implements StoragePlugin
+ * ```
+ */
+interface StoragePlugin {
+    /** Plugin name for identification */
+    name: string;
+    /** Storage type */
+    type: StorageType;
+    /** Collections this plugin handles */
+    collections: CollectionStorageMap;
+    /** The storage adapter instance */
+    adapter: IStorageAdapter;
+    /**
+     * Handler for generating client-side upload URLs.
+     * Called when clientUploads is enabled for a collection.
+     */
+    getClientUploadUrl?: (filename: string, mimeType: string, collection: string) => Promise<ClientUploadData>;
+    /**
+     * Handler for generating signed download URLs.
+     * Called when signedDownloads is enabled for a collection.
+     */
+    getSignedDownloadUrl?: (path: string, expiresIn?: number) => Promise<string>;
+}
+/**
+ * Data returned for client-side (direct) uploads.
+ * Contains pre-signed URL and headers for direct-to-storage uploads.
+ *
+ * @example
+ * ```typescript
+ * // Usage in frontend
+ * const uploadData = await fetch('/api/nextly/storage/upload-url', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ filename: 'photo.jpg', mimeType: 'image/jpeg', collection: 'media' })
+ * }).then(r => r.json());
+ *
+ * // Direct upload to storage
+ * await fetch(uploadData.uploadUrl, {
+ *   method: uploadData.method,
+ *   headers: uploadData.headers,
+ *   body: file
+ * });
+ * ```
+ */
+interface ClientUploadData {
+    /** Pre-signed URL for direct upload */
+    uploadUrl: string;
+    /** Storage path/key that will be used */
+    path: string;
+    /** HTTP method to use (usually PUT for S3, POST for some services) */
+    method: "PUT" | "POST";
+    /** Headers to include in upload request */
+    headers?: Record<string, string>;
+    /** Form fields for multipart uploads (some services require this) */
+    fields?: Record<string, string>;
+    /** URL expiry timestamp */
+    expiresAt: Date;
+}
+/**
+ * Base storage adapter interface.
+ * All storage adapters must implement this interface.
+ *
+ * Core methods (required):
+ * - upload: Store file buffer
+ * - delete: Remove file from storage
+ * - exists: Check if file exists
+ * - getPublicUrl: Get public URL for file access
+ * - getType: Get storage type identifier
+ *
+ * Optional methods:
+ * - getInfo: Get adapter capabilities (recommended)
+ * - getMetadata: Retrieve file metadata
+ * - getSignedUrl: Generate temporary signed URLs for private access
+ * - getPresignedUploadUrl: Generate pre-signed URL for client uploads
+ */
+interface BulkDeleteResult {
+    successful: string[];
+    failed: Array<{
+        filePath: string;
+        error: string;
+    }>;
+}
+interface IStorageAdapter {
+    /** Upload file buffer to storage */
+    upload(buffer: Buffer, options: UploadOptions): Promise<UploadResult>;
+    /** Delete file from storage */
+    delete(filePath: string): Promise<void>;
+    /** Bulk delete files from storage. Optional — adapters that support batch operations should implement this. */
+    bulkDelete?(filePaths: string[]): Promise<BulkDeleteResult>;
+    /** Check if file exists in storage */
+    exists(filePath: string): Promise<boolean>;
+    /** Get public URL for file */
+    getPublicUrl(filePath: string): string;
+    /** Get storage type identifier */
+    getType(): string;
+    /** Read file contents from storage (optional - not all adapters support this) */
+    read?(filePath: string): Promise<Buffer | null>;
+    /** Get adapter info including capabilities (optional but recommended) */
+    getInfo?(): StorageAdapterInfo;
+    /** Get file metadata (optional - not all adapters support this) */
+    getMetadata?(filePath: string): Promise<FileMetadata | null>;
+    /** Generate signed URL for temporary private access (optional) */
+    getSignedUrl?(filePath: string, expiresIn?: number): Promise<string>;
+    /** Generate pre-signed upload URL for client-side uploads (optional) */
+    getPresignedUploadUrl?(key: string, mimeType: string, expiresIn?: number): Promise<ClientUploadData>;
+}
+
+/**
+ * Vercel Blob Storage Types
+ *
+ * Type definitions for the @nextly/storage-vercel-blob package.
+ * Optimized for Vercel deployments with client-side upload support.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Vercel Blob storage adapter configuration.
+ *
+ * Extends the base storage plugin config with Vercel Blob-specific options.
+ * Designed for seamless integration with Vercel's serverless platform.
+ *
+ * @example Basic usage
+ * ```typescript
+ * vercelBlobStorage({
+ *   token: process.env.BLOB_READ_WRITE_TOKEN,
+ *   collections: {
+ *     media: true
+ *   }
+ * })
+ * ```
+ *
+ * @example With client uploads (recommended for large files)
+ * ```typescript
+ * vercelBlobStorage({
+ *   collections: {
+ *     media: {
+ *       clientUploads: true // Bypass 4.5MB serverless limit
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example With folder prefix
+ * ```typescript
+ * vercelBlobStorage({
+ *   collections: {
+ *     media: {
+ *       prefix: 'uploads/',
+ *     },
+ *     'private-docs': {
+ *       prefix: 'documents/',
+ *       clientUploads: true
+ *     }
+ *   }
+ * })
+ * ```
+ */
+interface VercelBlobStorageConfig extends StoragePluginConfig {
+    /** Enable/disable this storage plugin (default: true). */
+    enabled?: boolean;
+    /** Collections this plugin handles. */
+    collections: Record<string, boolean | CollectionStorageConfig>;
+    /**
+     * Vercel Blob read/write token.
+     *
+     * If not provided, falls back to `BLOB_READ_WRITE_TOKEN` environment variable.
+     * Get your token from: Vercel Dashboard > Storage > Blob > Tokens
+     *
+     * @example
+     * ```typescript
+     * token: process.env.BLOB_READ_WRITE_TOKEN
+     * ```
+     */
+    token?: string;
+    /**
+     * Add a random suffix to uploaded filenames.
+     * Prevents filename collisions when uploading files with the same name.
+     *
+     * When true, `photo.jpg` becomes `photo-abc123.jpg`
+     *
+     * @default true
+     */
+    addRandomSuffix?: boolean;
+    /**
+     * Cache-Control max-age in seconds.
+     * Controls how long browsers and CDNs cache the files.
+     *
+     * Note: Vercel Blob has a minimum cache time of 1 minute.
+     *
+     * @default 31536000 (1 year)
+     */
+    cacheControlMaxAge?: number;
+    /**
+     * Access level for uploaded blobs.
+     * Vercel Blob only supports 'public' access.
+     *
+     * @default 'public'
+     */
+    access?: "public";
+    /**
+     * Store ID for multi-store setups.
+     * Required if you have multiple blob stores in your Vercel project.
+     *
+     * Get the store ID from: Vercel Dashboard > Storage > Blob > Settings
+     */
+    storeId?: string;
+    /**
+     * Whether to allow overwriting existing blobs.
+     * When false, uploading a file with the same path will throw an error.
+     *
+     * Note: Only relevant when `addRandomSuffix` is false.
+     *
+     * @default false
+     */
+    allowOverwrite?: boolean;
+    /**
+     * Multipart upload threshold in bytes.
+     * Files larger than this will be uploaded using multipart upload.
+     *
+     * @default 5242880 (5MB)
+     */
+    multipartThreshold?: number;
+}
+/**
+ * Vercel Blob-specific collection storage configuration.
+ * Extends base collection config with Vercel Blob-specific options.
+ *
+ * @example
+ * ```typescript
+ * vercelBlobStorage({
+ *   collections: {
+ *     // Simple enable with defaults
+ *     media: true,
+ *
+ *     // Full configuration
+ *     documents: {
+ *       prefix: 'docs/',
+ *       addRandomSuffix: false,
+ *       allowOverwrite: true,
+ *       clientUploads: true
+ *     }
+ *   }
+ * })
+ * ```
+ */
+interface VercelBlobCollectionConfig extends CollectionStorageConfig {
+    /**
+     * Override addRandomSuffix for this collection.
+     * If not set, uses the adapter-level setting.
+     */
+    addRandomSuffix?: boolean;
+    /**
+     * Override allowOverwrite for this collection.
+     * If not set, uses the adapter-level setting.
+     */
+    allowOverwrite?: boolean;
+}
+/**
+ * Type-safe collection storage map for Vercel Blob.
+ * Maps collection slugs to Vercel Blob-specific configurations.
+ */
+type VercelBlobCollectionStorageMap = Record<string, boolean | VercelBlobCollectionConfig>;
+/**
+ * Resolved Vercel Blob configuration after applying defaults.
+ * Used internally by the adapter.
+ *
+ * @internal
+ */
+interface ResolvedVercelBlobConfig {
+    token: string;
+    addRandomSuffix: boolean;
+    cacheControlMaxAge: number;
+    access: "public";
+    storeId?: string;
+    allowOverwrite: boolean;
+    multipartThreshold: number;
+}
+
+/**
+ * Vercel Blob Storage Plugin
+ *
+ * Factory function that creates a storage plugin for Vercel Blob Storage.
+ * Returns a StoragePlugin that can be registered with MediaStorage.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { vercelBlobStorage } from '@nextly/storage-vercel-blob'
+ * import { defineConfig } from 'nextly/config'
+ *
+ * export default defineConfig({
+ *   storage: [
+ *     vercelBlobStorage({
+ *       token: process.env.BLOB_READ_WRITE_TOKEN,
+ *       collections: {
+ *         media: true
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example With client uploads (recommended for Vercel)
+ * ```typescript
+ * vercelBlobStorage({
+ *   collections: {
+ *     media: {
+ *       clientUploads: true // Bypass 4.5MB serverless limit
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @example With collection-specific configuration
+ * ```typescript
+ * vercelBlobStorage({
+ *   addRandomSuffix: true,
+ *   cacheControlMaxAge: 86400, // 1 day
+ *   collections: {
+ *     // Simple enable with defaults
+ *     media: true,
+ *
+ *     // Full configuration
+ *     documents: {
+ *       prefix: 'docs/',
+ *       addRandomSuffix: false,
+ *       allowOverwrite: true
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create a Vercel Blob storage plugin for Nextly.
+ *
+ * This factory function creates a StoragePlugin that can be added to
+ * the `storage` array in `nextly.config.ts`. Vercel Blob is optimized
+ * for Vercel deployments with:
+ *
+ * - Global CDN distribution
+ * - Simple token-based authentication
+ * - Client-side upload support (via handleUpload API)
+ * - Automatic file management
+ *
+ * @param config - Vercel Blob storage configuration
+ * @returns A StoragePlugin that MediaStorage can register
+ *
+ * @throws Error if token is not provided (via adapter)
+ */
+declare function vercelBlobStorage(config: VercelBlobStorageConfig): StoragePlugin;
+
+/**
+ * Vercel Blob Storage Adapter
+ *
+ * Stores files on Vercel Blob Storage, a globally distributed object storage
+ * service powered by Cloudflare R2. Optimized for Vercel deployments with
+ * built-in CDN distribution.
+ *
+ * Features:
+ * - Globally distributed CDN-backed storage
+ * - Automatic file management with unique filenames
+ * - Token-based authentication
+ * - Client-side upload support (via handleUpload API)
+ * - Serverless-friendly (no filesystem access required)
+ *
+ * @example Basic usage
+ * ```typescript
+ * const adapter = new VercelBlobStorageAdapter({
+ *   token: process.env.BLOB_READ_WRITE_TOKEN,
+ *   collections: { media: true }
+ * });
+ *
+ * const result = await adapter.upload(buffer, {
+ *   filename: 'photo.jpg',
+ *   mimeType: 'image/jpeg'
+ * });
+ * // result.url: "https://abc123.public.blob.vercel-storage.com/photo-xyz.jpg"
+ * ```
+ */
+
+/**
+ * Vercel Blob Storage Adapter
+ *
+ * Implements the IStorageAdapter interface for Vercel Blob Storage.
+ * Provides file upload, deletion, existence checks, and metadata retrieval.
+ */
+declare class VercelBlobStorageAdapter implements IStorageAdapter {
+    private config;
+    private resolvedConfig;
+    /**
+     * Create a new Vercel Blob storage adapter.
+     *
+     * @param config - Vercel Blob storage configuration
+     * @throws Error if token is not provided
+     */
+    constructor(config: VercelBlobStorageConfig);
+    /**
+     * Upload file to Vercel Blob.
+     *
+     * Files are stored with globally distributed CDN backing.
+     * By default, a random suffix is added to prevent filename collisions.
+     *
+     * @param buffer - File content as Buffer
+     * @param options - Upload options (filename, mimeType, folder, collection)
+     * @returns Upload result with URL and storage path
+     */
+    upload(buffer: Buffer, options: UploadOptions): Promise<UploadResult>;
+    /**
+     * Delete file from Vercel Blob.
+     *
+     * @param filePath - Full blob URL to delete
+     */
+    delete(filePath: string): Promise<void>;
+    /**
+     * Delete multiple files from Vercel Blob in chunked batches.
+     *
+     * Processes deletions in chunks of 10 concurrent calls using Promise.allSettled,
+     * collecting successes and failures without short-circuiting.
+     *
+     * @param filePaths - Array of full blob URLs to delete
+     * @returns BulkDeleteResult with successful and failed arrays
+     */
+    bulkDelete(filePaths: string[]): Promise<BulkDeleteResult>;
+    /**
+     * Check if file exists in Vercel Blob.
+     *
+     * Uses the head() function which is efficient for existence checks.
+     *
+     * @param filePath - Full blob URL to check
+     * @returns true if file exists, false otherwise
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * Get public URL for Vercel Blob file.
+     *
+     * Vercel Blob paths ARE the public URLs - they're already full HTTPS URLs
+     * with CDN distribution.
+     *
+     * @param filePath - Full blob URL
+     * @returns The same URL (Vercel Blob paths are already public URLs)
+     */
+    getPublicUrl(filePath: string): string;
+    /**
+     * Get storage type identifier.
+     */
+    getType(): "vercel-blob";
+    /**
+     * Get adapter info including capabilities.
+     *
+     * @returns Adapter info with type, name, and capability flags
+     */
+    getInfo(): StorageAdapterInfo;
+    /**
+     * Get file metadata from Vercel Blob.
+     *
+     * Retrieves file information including size, content type, and upload date.
+     *
+     * @param filePath - Full blob URL
+     * @returns File metadata or null if file not found
+     */
+    getMetadata(filePath: string): Promise<FileMetadata | null>;
+    /**
+     * Generate pre-signed URL for client-side uploads.
+     *
+     * Vercel Blob uses a different pattern for client uploads - they require
+     * the handleUpload API which handles token generation server-side.
+     *
+     * This method is not implemented because Vercel Blob's client upload flow
+     * requires server-side route handlers with handleUpload().
+     *
+     * @see https://vercel.com/docs/storage/vercel-blob/client-upload
+     * @throws Error always - client uploads require handleUpload API
+     */
+    getPresignedUploadUrl(_key: string, _mimeType: string, _expiresIn?: number): Promise<ClientUploadData>;
+    /**
+     * List blobs with optional prefix filter.
+     *
+     * Useful for browsing or batch operations on stored files.
+     *
+     * @param prefix - Optional prefix to filter results
+     * @param options - List options (limit, cursor)
+     * @returns List of blob metadata
+     */
+    listBlobs(prefix?: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        blobs: Array<{
+            url: string;
+            pathname: string;
+            size: number;
+            uploadedAt: Date;
+        }>;
+        hasMore: boolean;
+        cursor?: string;
+    }>;
+    /**
+     * Build pathname for Vercel Blob upload.
+     *
+     * Creates pathname in format: {folder}/{filename}
+     * If no folder is provided, uses the filename directly.
+     *
+     * @param filename - Original filename (will be sanitized)
+     * @param folder - Optional folder/prefix for organizing uploads
+     * @returns Generated pathname
+     * @throws Error if folder fails sanitization
+     */
+    private buildPathname;
+    /**
+     * Sanitize filename to prevent path traversal issues.
+     *
+     * @param filename - Original filename
+     * @returns Sanitized filename
+     */
+    private sanitizeFilename;
+    /**
+     * Reject folder values that would let a caller
+     * escape the configured prefix via path traversal or weird
+     * separators. Vercel Blob is flat-keyed so `/` is just part of the
+     * pathname, but an attacker who controls `folder` could still:
+     *
+     *   - Use `..` to chain a relative-traversal-style key.
+     *   - Use `\` (Windows separator) to confuse downstream tooling.
+     *   - Use control chars / null bytes to truncate the key.
+     *   - Use a leading `/` to look like an absolute path.
+     *
+     * Internal `/` segments stay allowed because callers legitimately
+     * use nested folders (`docs/2026/...`); a leading `/`, empty
+     * segments (`docs//x`), or `..` segments are rejected.
+     *
+     * @throws Error with a stable message so the storage facade can
+     *   surface a 400 instead of a 500.
+     */
+    private sanitizeFolder;
+    /**
+     * Get the configured token (masked for logging).
+     */
+    getTokenMasked(): string;
+    /**
+     * Check if random suffix is enabled.
+     */
+    hasRandomSuffix(): boolean;
+    /**
+     * Get configured cache control max age.
+     */
+    getCacheControlMaxAge(): number;
+}
+
+/**
+ * @nextly/storage-vercel-blob
+ *
+ * Vercel Blob storage adapter for Nextly CMS.
+ * Optimized for Vercel deployments with client-side upload support
+ * to bypass serverless function size limits (4.5MB).
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { vercelBlobStorage } from '@nextly/storage-vercel-blob'
+ * import { defineConfig } from 'nextly/config'
+ *
+ * export default defineConfig({
+ *   storage: [
+ *     vercelBlobStorage({
+ *       token: process.env.BLOB_READ_WRITE_TOKEN,
+ *       collections: {
+ *         media: true
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example With client uploads (recommended for Vercel)
+ * ```typescript
+ * vercelBlobStorage({
+ *   collections: {
+ *     media: {
+ *       clientUploads: true // Bypass 4.5MB serverless limit
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+declare const PACKAGE_NAME = "@nextly/storage-vercel-blob";
+declare const PACKAGE_VERSION = "0.1.0";
+
+export { PACKAGE_NAME, PACKAGE_VERSION, type ResolvedVercelBlobConfig, type VercelBlobCollectionConfig, type VercelBlobCollectionStorageMap, VercelBlobStorageAdapter, type VercelBlobStorageConfig, vercelBlobStorage };