@od-oneapp/storage 2026.1.1301

package/src/client-next.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Client-side storage exports for Next.js
+ *
+ * This file provides client-side storage functionality specifically for Next.js applications.
+ * NO REACT HOOKS - keep in consuming apps to avoid React peer dependency.
+ *
+ * Features:
+ * - File upload with progress tracking
+ * - Next.js-specific upload helpers
+ * - Client-side validation
+ *
+ * @module @repo/storage/client/next
+ */
+
+'use client';
+
+// Import for internal use
+import { uploadFile } from './client';
+import { validateMimeType } from './validation';
+
+// Re-export all client functionality
+export * from './client';
+
+// Next.js-specific upload helpers (no hooks)
+export async function uploadFileWithProgress(
+  pathname: string,
+  file: File | Blob,
+  options?: {
+    access?: 'public' | 'private';
+    addRandomSuffix?: boolean;
+    allowOverwrite?: boolean;
+    cacheControlMaxAge?: number;
+    clientPayload?: string;
+    contentType?: string;
+    multipart?: boolean;
+    onUploadProgress?: (event: { loaded: number; total?: number; percentage?: number }) => void;
+    handleUploadUrl?: string;
+  },
+): Promise<{ url: string; pathname: string }> {
+  // Use the base uploadFile function
+  return await uploadFile(pathname, file, options);
+}
+
+/**
+ * Upload multiple files with progress tracking
+ *
+ * @param files - Array of files to upload
+ * @param getPathname - Function to generate pathname for each file
+ * @param options - Upload options
+ * @returns Array of upload results
+ *
+ * @example
+ * ```typescript
+ * const results = await uploadMultipleFiles(
+ *   files,
+ *   (file, index) => `uploads/${index}-${file.name}`,
+ *   {
+ *     onUploadProgress: (event) => {
+ *       logInfo(`Uploaded ${event.percentage}%`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export async function uploadMultipleFiles(
+  files: File[],
+  getPathname: (file: File, index: number) => string,
+  options?: {
+    access?: 'public' | 'private';
+    addRandomSuffix?: boolean;
+    allowOverwrite?: boolean;
+    cacheControlMaxAge?: number;
+    clientPayload?: string;
+    contentType?: string;
+    multipart?: boolean;
+    onUploadProgress?: (event: { loaded: number; total?: number; percentage?: number }) => void;
+    handleUploadUrl?: string;
+    onFileProgress?: (
+      fileIndex: number,
+      progress: { loaded: number; total?: number; percentage?: number },
+    ) => void;
+  },
+): Promise<Array<{ url: string; pathname: string; success: boolean; error?: string }>> {
+  const results: Array<{ url: string; pathname: string; success: boolean; error?: string }> = [];
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    if (!file) continue;
+    const pathname = getPathname(file, i);
+
+    try {
+      const result = await uploadFile(pathname, file, {
+        ...options,
+        onUploadProgress: options?.onFileProgress
+          ? (event: { loaded: number; total?: number; percentage?: number }) =>
+              options.onFileProgress?.(i, event)
+          : options?.onUploadProgress,
+      });
+
+      results.push({
+        ...result,
+        success: true,
+      });
+    } catch (error) {
+      results.push({
+        url: '',
+        pathname,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Validate file before upload
+ *
+ * @param file - File to validate
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const validation = await validateFileForUpload(file, {
+ *   maxFileSize: 10 * 1024 * 1024, // 10MB
+ *   allowedMimeTypes: ['image/jpeg', 'image/png'],
+ * });
+ *
+ * if (!validation.valid) {
+ *   logError('Validation failed:', validation.errors);
+ * }
+ * ```
+ */
+export async function validateFileForUpload(
+  file: File,
+  options: {
+    maxFileSize?: number;
+    allowedMimeTypes?: string[];
+    allowedExtensions?: string[];
+  } = {},
+): Promise<{ valid: boolean; errors: string[] }> {
+  const errors: string[] = [];
+
+  // Validate file size
+  if (options.maxFileSize && file.size > options.maxFileSize) {
+    errors.push(`File size ${file.size} bytes exceeds maximum ${options.maxFileSize} bytes`);
+  }
+
+  // Validate MIME type
+  if (options.allowedMimeTypes && options.allowedMimeTypes.length > 0) {
+    const mimeValidation = validateMimeType(file.type, options.allowedMimeTypes);
+    if (!mimeValidation.valid) {
+      if (mimeValidation.error) {
+        errors.push(mimeValidation.error);
+      }
+    }
+  }
+
+  // Validate file extension
+  if (options.allowedExtensions && options.allowedExtensions.length > 0) {
+    const extension = file.name.match(/\.[^/.]+$/)?.[0]?.toLowerCase();
+    if (extension && !options.allowedExtensions.includes(extension)) {
+      errors.push(
+        `File extension ${extension} is not allowed. Allowed: ${options.allowedExtensions.join(', ')}`,
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+// Re-export validation utilities for convenience
+export {
+  formatFileSize,
+  parseFileSize,
+  validateFileSize,
+  validateMimeType,
+  validateStorageKey,
+} from './validation';

package/src/client-utils.ts

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview Client-side utilities for storage operations
+ *
+ * These work with server-side APIs to enable client uploads without exposing credentials.
+ * Provides presigned URL uploads and progress tracking.
+ *
+ * Features:
+ * - Presigned URL uploads
+ * - Upload progress tracking
+ * - Client-side file handling
+ *
+ * @module @repo/storage/client-utils
+ */
+
+import type { PresignedUploadUrl as BasePresignedUploadUrl } from '../types';
+
+/**
+ * Extended presigned upload URL configuration for client-side use
+ * Includes the storage key for tracking uploads
+ */
+export interface ClientPresignedUploadUrl extends BasePresignedUploadUrl {
+  key: string;
+}
+
+/**
+ * Upload progress information for client-side tracking
+ * Uses 'percentage' to align with types.ts UploadProgress
+ */
+export interface ClientUploadProgress {
+  loaded: number;
+  total: number;
+  percentage: number;
+}
+
+/**
+ * Upload a file using a presigned URL (works with R2, S3, etc.)
+ */
+export async function uploadWithPresignedUrl(
+  presignedData: ClientPresignedUploadUrl,
+  file: File | Blob,
+  options?: {
+    onProgress?: (progress: ClientUploadProgress) => void;
+  },
+): Promise<void> {
+  const formData = new FormData();
+
+  // Add any required fields first (for POST uploads)
+  if (presignedData.fields) {
+    Object.entries(presignedData.fields).forEach(([key, value]) => {
+      formData.append(key, value);
+    });
+  }
+
+  // Add the file last
+  formData.append('file', file);
+
+  // For progress tracking, we need XMLHttpRequest
+  if (options?.onProgress) {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+
+      xhr.upload.addEventListener('progress', event => {
+        if (event.lengthComputable && options.onProgress) {
+          options.onProgress({
+            loaded: event.loaded,
+            total: event.total,
+            percentage: (event.loaded / event.total) * 100,
+          });
+        }
+      });
+
+      xhr.addEventListener('load', () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          resolve();
+        } else {
+          reject(new Error(`Upload failed with status ${xhr.status}`));
+        }
+      });
+
+      xhr.addEventListener('error', () => {
+        reject(new Error('Upload failed'));
+      });
+
+      xhr.open('POST', presignedData.url);
+      xhr.send(formData);
+    });
+  }
+
+  // Simple fetch for no progress tracking
+  const response = await fetch(presignedData.url, {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Upload failed with status ${response.status}`);
+  }
+}
+
+/**
+ * Upload directly to a URL (PUT method, typically for presigned PUT URLs)
+ */
+export async function uploadDirectToUrl(
+  url: string,
+  file: File | Blob,
+  options?: {
+    headers?: Record<string, string>;
+    onProgress?: (progress: ClientUploadProgress) => void;
+  },
+): Promise<void> {
+  // For progress tracking, we need XMLHttpRequest
+  if (options?.onProgress) {
+    return new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+
+      xhr.upload.addEventListener('progress', event => {
+        if (event.lengthComputable && options.onProgress) {
+          options.onProgress({
+            loaded: event.loaded,
+            total: event.total,
+            percentage: (event.loaded / event.total) * 100,
+          });
+        }
+      });
+
+      xhr.addEventListener('load', () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          resolve();
+        } else {
+          reject(new Error(`Upload failed with status ${xhr.status}`));
+        }
+      });
+
+      xhr.addEventListener('error', () => {
+        reject(new Error('Upload failed'));
+      });
+
+      xhr.open('PUT', url);
+
+      // Set headers
+      if (options?.headers) {
+        Object.entries(options.headers).forEach(([key, value]) => {
+          xhr.setRequestHeader(key, value);
+        });
+      }
+
+      xhr.send(file);
+    });
+  }
+
+  // Simple fetch for no progress tracking
+  const response = await fetch(url, {
+    method: 'PUT',
+    body: file,
+    headers: options?.headers,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Upload failed with status ${response.status}`);
+  }
+}
+
+/**
+ * Client-side multipart upload coordinator
+ * Works with server-side APIs to manage multipart uploads
+ */
+export class ClientMultipartUpload {
+  private uploadId: string;
+  private key: string;
+  private parts: Array<{ PartNumber: number; ETag: string }> = [];
+
+  constructor(uploadId: string, key: string) {
+    this.uploadId = uploadId;
+    this.key = key;
+  }
+
+  async uploadPart(
+    partNumber: number,
+    presignedUrl: string,
+    data: Blob,
+    _onProgress?: (progress: ClientUploadProgress) => void,
+  ): Promise<void> {
+    // Note: onProgress tracking for presigned URL uploads requires XMLHttpRequest
+    // This is a simplified implementation using fetch
+    const response = await fetch(presignedUrl, {
+      method: 'PUT',
+      body: data,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Part upload failed with status ${response.status}`);
+    }
+
+    const etag = response.headers.get('ETag') ?? '';
+    this.parts.push({ PartNumber: partNumber, ETag: etag });
+  }
+
+  getParts() {
+    return this.parts.sort((a, b) => a.PartNumber - b.PartNumber);
+  }
+
+  getUploadId() {
+    return this.uploadId;
+  }
+
+  getKey() {
+    return this.key;
+  }
+}
+
+/**
+ * Split a file into chunks for multipart upload
+ */
+export async function* splitFileIntoChunks(
+  file: File | Blob,
+  chunkSize: number = 5 * 1024 * 1024, // 5MB default
+): AsyncGenerator<{ chunk: Blob; partNumber: number; start: number; end: number }> {
+  const totalSize = file.size;
+  let partNumber = 1;
+
+  for (let start = 0; start < totalSize; start += chunkSize) {
+    const end = Math.min(start + chunkSize, totalSize);
+    const chunk = file.slice(start, end);
+
+    yield {
+      chunk,
+      partNumber,
+      start,
+      end,
+    };
+
+    partNumber++;
+  }
+}
+
+/**
+ * Download a file from a URL with progress tracking
+ */
+export async function downloadFromUrl(
+  url: string,
+  options?: {
+    onProgress?: (progress: ClientUploadProgress) => void;
+  },
+): Promise<Blob> {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Download failed with status ${response.status}`);
+  }
+
+  // If no progress tracking needed, just return blob
+  if (!options?.onProgress || !response.body) {
+    return response.blob();
+  }
+
+  // Stream with progress tracking
+  const contentLength = response.headers.get('content-length');
+  const total = contentLength ? parseInt(contentLength, 10) : 0;
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let loaded = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+
+    if (done) break;
+
+    chunks.push(value);
+    loaded += value.length;
+
+    if (total > 0) {
+      options.onProgress({
+        loaded,
+        total,
+        percentage: (loaded / total) * 100,
+      });
+    }
+  }
+
+  const blob = new Blob(
+    chunks.map(
+      chunk =>
+        chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength) as ArrayBuffer,
+    ),
+    {
+      type: response.headers.get('content-type') ?? 'application/octet-stream',
+    },
+  );
+
+  return blob;
+}

package/src/client.ts

@@ -0,0 +1,102 @@
+/**
+ * @fileoverview Client-side storage exports (non-Next.js)
+ *
+ * This file provides client-side storage functionality for non-Next.js environments.
+ * For Next.js applications, use '@od-oneapp/storage/client/next' instead.
+ *
+ * CLEAN BREAK: Removed legacy wrappers, direct Vercel SDK re-exports only.
+ *
+ * Features:
+ * - File upload utilities
+ * - Client-side validation
+ * - Key generation utilities
+ *
+ * @module @od-oneapp/storage/client
+ */
+
+// Re-export core Vercel Blob client utilities
+// Import for internal use
+import { upload as vercelUpload } from '@vercel/blob/client';
+
+export {
+  generateClientTokenFromReadWriteToken,
+  handleUpload,
+  upload,
+} from '@vercel/blob/client';
+
+// Export client-side validation utilities
+export {
+  formatFileSize,
+  parseFileSize,
+  validateFileSize,
+  validateMimeType,
+  validateStorageKey,
+  type ValidationOptions,
+} from './validation';
+
+// Export key generation utilities (validateStorageKey is exported from './validation')
+export {
+  generateMultipleKeys,
+  generateStorageKey,
+  isKeyPattern,
+  normalizeStorageKey,
+  parseStorageKey,
+  sanitizeStorageKey,
+  type KeyGenerationOptions,
+  type KeyPattern,
+} from '../keys';
+
+// Export client-side utilities for presigned URLs (R2, S3, etc.)
+export * from './client-utils';
+
+// Type-safe wrapper for Vercel's upload function
+export async function uploadFile(
+  pathname: string,
+  file: File | Blob,
+  options?: {
+    access?: 'public' | 'private';
+    addRandomSuffix?: boolean;
+    allowOverwrite?: boolean;
+    cacheControlMaxAge?: number;
+    clientPayload?: string;
+    contentType?: string;
+    multipart?: boolean;
+    onUploadProgress?: (event: { loaded: number; total?: number; percentage?: number }) => void;
+    handleUploadUrl?: string;
+  },
+): Promise<{ url: string; pathname: string }> {
+  const { handleUploadUrl, ...vercelOptions } = options ?? {};
+
+  if (handleUploadUrl) {
+    // Use handleUpload pattern for server-side processing
+    return await vercelUpload(pathname, file, {
+      ...vercelOptions,
+      access: 'public' as const,
+      handleUploadUrl,
+    });
+  } else {
+    // Use direct upload with client token
+    return await vercelUpload(pathname, file, {
+      ...vercelOptions,
+      access: 'public' as const,
+      handleUploadUrl: '/api/upload', // Default upload URL
+    });
+  }
+}
+
+// Export types that are safe for client-side use
+export type {
+  BlobListResponse,
+  ClientUploadOptions,
+  CloudflareImagesBatchToken,
+  CloudflareImagesListOptions,
+  CloudflareImagesTransformOptions,
+  CloudflareImagesVariant,
+  DirectUploadResponse,
+  ListOptions,
+  PresignedUploadUrl,
+  StorageObject,
+  UploadOptions,
+  UploadProgress,
+  VercelBlobOptions,
+} from '../types';

package/src/constants.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Storage Package Constants
+ *
+ * Centralized constants for storage operations to avoid magic numbers
+ * and improve maintainability.
+ *
+ * Includes:
+ * - URL expiration times
+ * - File size limits
+ * - Multipart upload thresholds
+ * - Retry configuration
+ * - Rate limiting settings
+ *
+ * @module @repo/storage/constants
+ */
+
+export const STORAGE_CONSTANTS = {
+  // URL Expiration Times (seconds)
+  DEFAULT_URL_EXPIRY_SECONDS: 3600, // 1 hour
+  PRODUCT_URL_EXPIRY_SECONDS: 3600, // 1 hour for product photos
+  UPLOAD_URL_EXPIRY_SECONDS: 1800, // 30 minutes for uploads
+  ADMIN_URL_EXPIRY_SECONDS: 7200, // 2 hours for admin operations
+
+  // File Size Limits (bytes)
+  MULTIPART_THRESHOLD_BYTES: 100 * 1024 * 1024, // 100MB - use multipart above this
+  DEFAULT_PART_SIZE_BYTES: 5 * 1024 * 1024, // 5MB default part size
+  DEFAULT_MAX_PART_SIZE_BYTES: 25 * 1024 * 1024, // 25MB max part size
+  DEFAULT_QUEUE_SIZE: 4, // Concurrent upload parts
+
+  // Batch Operations
+  DEFAULT_BATCH_SIZE: 5, // Process 5 items concurrently
+  MAX_BATCH_SIZE: 50, // Maximum batch size
+
+  // Timeouts (milliseconds)
+  DEFAULT_REQUEST_TIMEOUT_MS: 30000, // 30 seconds
+  DEFAULT_UPLOAD_TIMEOUT_MS: 300000, // 5 minutes for uploads
+  DEFAULT_DOWNLOAD_TIMEOUT_MS: 60000, // 1 minute for downloads
+
+  // Retry Configuration
+  DEFAULT_MAX_RETRIES: 3,
+  RETRY_BASE_DELAY_MS: 1000, // 1 second base delay
+
+  // Key Validation
+  MAX_KEY_LENGTH: 1024,
+  MAX_FILENAME_LENGTH: 255,
+
+  // Rate Limiting (requests per window)
+  DEFAULT_RATE_LIMIT_REQUESTS: 100,
+  DEFAULT_RATE_LIMIT_WINDOW_MS: 60 * 1000, // 1 minute
+
+  // Health Check
+  HEALTH_CHECK_KEY: '__health_check__',
+} as const;
+
+/**
+ * File size thresholds for multipart upload decisions
+ */
+export const MULTIPART_THRESHOLDS = {
+  SMALL_FILE: 100 * 1024 * 1024, // < 100MB - use simple upload
+  MEDIUM_FILE: 1024 * 1024 * 1024, // < 1GB - use 10MB parts
+  LARGE_FILE: Infinity, // >= 1GB - use 25MB parts
+} as const;
+
+/**
+ * Part sizes based on file size
+ */
+export const PART_SIZES = {
+  SMALL: 5 * 1024 * 1024, // 5MB for files < 100MB
+  MEDIUM: 10 * 1024 * 1024, // 10MB for files < 1GB
+  LARGE: 25 * 1024 * 1024, // 25MB for files >= 1GB
+} as const;
+
+/**
+ * Default storage capabilities for providers that don't implement getCapabilities()
+ * Single source of truth for capability defaults
+ */
+export const DEFAULT_STORAGE_CAPABILITIES = {
+  multipart: false,
+  presignedUrls: false,
+  progressTracking: false,
+  abortSignal: false,
+  metadata: false,
+  customDomains: false,
+  edgeCompatible: false,
+  versioning: false,
+  encryption: false,
+  directoryListing: false,
+} as const;