@artu-ai/compliance-sdk 0.0.6 → 0.3.0

package/src/utils/upload.ts

@@ -0,0 +1,388 @@
+/**
+ * Document Upload Utilities
+ *
+ * Provides browser and Node.js compatible file upload with progress tracking.
+ * Handles the complete upload flow: presigned URL → S3 upload → confirmation.
+ */
+
+import type { PresignedUploadUrl } from "@artu-ai/shared";
+import {
+  UploadError,
+  UploadAbortedError,
+  UploadTimeoutError,
+  FileTooLargeError,
+} from "../errors/upload";
+
+// ─────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Maximum file size in bytes (25 MB).
+ * Must match the server-side limit.
+ */
+export const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024;
+
+/**
+ * Default upload timeout in milliseconds (5 minutes).
+ */
+export const DEFAULT_UPLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+
+// ─────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * File-like object that can be uploaded.
+ * Compatible with browser File, Blob, and Node.js Buffer.
+ */
+export interface UploadableFile {
+  /** File name */
+  name: string;
+  /** MIME type */
+  type: string;
+  /** File size in bytes */
+  size: number;
+  /** For browser: the file/blob itself. For Node: Buffer or stream. */
+  data: Blob | Buffer | ArrayBuffer;
+}
+
+/**
+ * Progress callback function.
+ * @param progress - Upload progress from 0 to 1
+ */
+export type ProgressCallback = (progress: number) => void;
+
+/**
+ * Options for uploading a file to S3.
+ */
+export interface UploadToS3Options {
+  /** Progress callback (0-1) */
+  onProgress?: ProgressCallback;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+  /** Timeout in milliseconds */
+  timeout?: number;
+}
+
+/**
+ * Result of a successful S3 upload.
+ */
+export interface UploadToS3Result {
+  /** Whether the upload was successful */
+  success: true;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Environment Detection
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Detects if we're running in a browser environment.
+ */
+function isBrowser(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.XMLHttpRequest !== "undefined"
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────
+// File Normalization
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Normalizes a file input to an UploadableFile.
+ * Accepts browser File/Blob or Node.js Buffer with metadata.
+ */
+export function normalizeFile(
+  file:
+    | File
+    | Blob
+    | UploadableFile
+    | { buffer: Buffer; name: string; type: string }
+): UploadableFile {
+  // Browser File
+  if (typeof File !== "undefined" && file instanceof File) {
+    return {
+      name: file.name,
+      type: file.type,
+      size: file.size,
+      data: file,
+    };
+  }
+
+  // Browser Blob (no name)
+  if (
+    typeof Blob !== "undefined" &&
+    file instanceof Blob &&
+    !("name" in file)
+  ) {
+    return {
+      name: "upload",
+      type: file.type || "application/octet-stream",
+      size: file.size,
+      data: file,
+    };
+  }
+
+  // Node.js Buffer with metadata
+  if ("buffer" in file && Buffer.isBuffer(file.buffer)) {
+    return {
+      name: file.name,
+      type: file.type,
+      size: file.buffer.length,
+      data: file.buffer,
+    };
+  }
+
+  // Already normalized
+  if ("data" in file && "name" in file && "type" in file && "size" in file) {
+    return file as UploadableFile;
+  }
+
+  throw new UploadError(
+    "Invalid file input. Expected File, Blob, or UploadableFile.",
+    "request"
+  );
+}
+
+/**
+ * Validates file size before upload.
+ * @throws FileTooLargeError if file exceeds limit
+ */
+export function validateFileSize(size: number): void {
+  if (size > MAX_FILE_SIZE_BYTES) {
+    throw new FileTooLargeError(size, MAX_FILE_SIZE_BYTES);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────
+// S3 Upload Implementation
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Uploads a file to S3 using a presigned POST URL.
+ *
+ * Uses XMLHttpRequest in browsers for progress tracking,
+ * falls back to fetch in Node.js (no progress).
+ *
+ * @param file - The file to upload
+ * @param presigned - Presigned URL info from the API
+ * @param options - Upload options
+ * @returns Upload result
+ * @throws UploadError on failure
+ */
+export async function uploadToS3(
+  file: UploadableFile,
+  presigned: PresignedUploadUrl,
+  options: UploadToS3Options = {}
+): Promise<UploadToS3Result> {
+  const { onProgress, signal, timeout = DEFAULT_UPLOAD_TIMEOUT_MS } = options;
+
+  // Check if already aborted
+  if (signal?.aborted) {
+    throw new UploadAbortedError();
+  }
+
+  // Use XHR in browser for progress, fetch in Node.js
+  if (isBrowser() && onProgress) {
+    return uploadWithXHR(file, presigned, { onProgress, signal, timeout });
+  } else {
+    return uploadWithFetch(file, presigned, { signal, timeout });
+  }
+}
+
+/**
+ * Uploads using XMLHttpRequest (browser only).
+ * Provides progress tracking.
+ */
+async function uploadWithXHR(
+  file: UploadableFile,
+  presigned: PresignedUploadUrl,
+  options: Required<Pick<UploadToS3Options, "onProgress" | "timeout">> & {
+    signal?: AbortSignal;
+  }
+): Promise<UploadToS3Result> {
+  const { onProgress, signal, timeout } = options;
+
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+
+    // Build FormData
+    const formData = new FormData();
+
+    // Add presigned fields first (order matters for S3)
+    for (const [key, value] of Object.entries(presigned.fields)) {
+      formData.append(key, value);
+    }
+
+    // Add content-type and file last
+    formData.append("Content-Type", file.type);
+    formData.append("file", file.data as Blob, file.name);
+
+    // Manual timeout (XHR timeout doesn't include upload time)
+    const timeoutId = setTimeout(() => {
+      xhr.abort();
+      reject(new UploadTimeoutError(timeout));
+    }, timeout);
+
+    // Progress tracking
+    xhr.upload.onprogress = (event) => {
+      if (event.lengthComputable) {
+        onProgress(event.loaded / event.total);
+      }
+    };
+
+    // Success handler
+    xhr.onload = () => {
+      clearTimeout(timeoutId);
+
+      if (xhr.status >= 200 && xhr.status < 300) {
+        onProgress(1); // Ensure we report 100%
+        resolve({ success: true });
+      } else {
+        reject(
+          new UploadError(
+            `S3 upload failed with status ${xhr.status}: ${xhr.statusText}`,
+            "upload"
+          )
+        );
+      }
+    };
+
+    // Error handler
+    xhr.onerror = () => {
+      clearTimeout(timeoutId);
+      reject(new UploadError("Network error during upload", "upload"));
+    };
+
+    // Abort handler
+    xhr.onabort = () => {
+      clearTimeout(timeoutId);
+      reject(new UploadAbortedError());
+    };
+
+    // Timeout handler
+    xhr.ontimeout = () => {
+      clearTimeout(timeoutId);
+      reject(new UploadTimeoutError(timeout));
+    };
+
+    // AbortSignal support
+    if (signal) {
+      signal.addEventListener("abort", () => {
+        xhr.abort();
+      });
+    }
+
+    // Configure and send
+    xhr.open("POST", presigned.url);
+    xhr.timeout = timeout;
+    xhr.send(formData);
+  });
+}
+
+/**
+ * Uploads using fetch (Node.js compatible).
+ * No progress tracking available.
+ */
+async function uploadWithFetch(
+  file: UploadableFile,
+  presigned: PresignedUploadUrl,
+  options: { signal?: AbortSignal; timeout: number }
+): Promise<UploadToS3Result> {
+  const { signal, timeout } = options;
+
+  // Create timeout signal
+  const timeoutController = new AbortController();
+  const timeoutId = setTimeout(() => timeoutController.abort(), timeout);
+
+  // Combine with user signal if provided
+  const combinedSignal = signal
+    ? anySignal([signal, timeoutController.signal])
+    : timeoutController.signal;
+
+  try {
+    // Build FormData
+    // In Node.js 18+, FormData is available globally
+    const formData = new FormData();
+
+    // Add presigned fields first
+    for (const [key, value] of Object.entries(presigned.fields)) {
+      formData.append(key, value);
+    }
+
+    // Add content-type and file
+    formData.append("Content-Type", file.type);
+
+    // Handle different data types - convert to Blob for FormData compatibility
+    let blob: Blob;
+    if (file.data instanceof Blob) {
+      blob = file.data;
+    } else if (file.data instanceof ArrayBuffer) {
+      blob = new Blob([file.data], { type: file.type });
+    } else {
+      // Buffer - convert to Uint8Array first for cross-platform compatibility
+      const uint8 = new Uint8Array(file.data);
+      blob = new Blob([uint8], { type: file.type });
+    }
+    formData.append("file", blob, file.name);
+
+    const response = await fetch(presigned.url, {
+      method: "POST",
+      body: formData,
+      signal: combinedSignal,
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new UploadError(
+        `S3 upload failed with status ${response.status}: ${text}`,
+        "upload"
+      );
+    }
+
+    return { success: true };
+  } catch (error) {
+    if (error instanceof UploadError) {
+      throw error;
+    }
+
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        // Check which signal caused the abort
+        if (signal?.aborted) {
+          throw new UploadAbortedError();
+        }
+        throw new UploadTimeoutError(timeout);
+      }
+      throw new UploadError(error.message, "upload");
+    }
+
+    throw new UploadError("Unknown upload error", "upload");
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Combines multiple AbortSignals into one.
+ * Aborts when any of the input signals abort.
+ */
+function anySignal(signals: AbortSignal[]): AbortSignal {
+  const controller = new AbortController();
+
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+
+    signal.addEventListener("abort", () => controller.abort(signal.reason), {
+      once: true,
+    });
+  }
+
+  return controller.signal;
+}