@uploadbox/core 0.1.0

package/src/builder.ts

@@ -0,0 +1,39 @@
+import type {
+  FileRouteConfig,
+  FileRoute,
+  MiddlewareFn,
+  OnUploadCompleteFn,
+} from "./types.js";
+
+export class UploadBuilder<TMetadata = Record<string, unknown>, TReturn = unknown> {
+  /** @internal */ _config: FileRouteConfig;
+  /** @internal */ _middleware: MiddlewareFn<TMetadata>;
+  /** @internal */ _onUploadComplete: OnUploadCompleteFn<TMetadata, TReturn>;
+
+  constructor(config: FileRouteConfig) {
+    this._config = config;
+    this._middleware = (async () => ({}) as TMetadata) as MiddlewareFn<TMetadata>;
+    this._onUploadComplete = (async () => undefined) as unknown as OnUploadCompleteFn<TMetadata, TReturn>;
+  }
+
+  middleware<TNewMetadata>(fn: MiddlewareFn<TNewMetadata>): UploadBuilder<TNewMetadata, TReturn> {
+    const builder = new UploadBuilder<TNewMetadata, TReturn>(this._config);
+    builder._middleware = fn;
+    builder._onUploadComplete = this._onUploadComplete as unknown as OnUploadCompleteFn<TNewMetadata, TReturn>;
+    return builder;
+  }
+
+  onUploadComplete<TNewReturn>(
+    fn: OnUploadCompleteFn<TMetadata, TNewReturn>
+  ): FileRoute<TMetadata, TNewReturn> {
+    return {
+      _config: this._config,
+      _middleware: this._middleware,
+      _onUploadComplete: fn,
+    };
+  }
+}
+
+export function createUploadBuilder(config: FileRouteConfig): UploadBuilder {
+  return new UploadBuilder(config);
+}

package/src/create-uploadbox.ts

@@ -0,0 +1,46 @@
+import type { FileRouter, FileRouteConfig, UploadboxConfig } from "./types.js";
+import { createUploadBuilder } from "./builder.js";
+import { createS3Client } from "./s3.js";
+import type { S3Client } from "@aws-sdk/client-s3";
+
+export interface UploadboxInstance<TRouter extends FileRouter> {
+  router: TRouter;
+  s3Client: S3Client;
+  config: UploadboxConfig;
+}
+
+function getConfigFromEnv(): UploadboxConfig {
+  return {
+    region: process.env.UPLOADBOX_AWS_REGION ?? "us-east-1",
+    bucket: process.env.UPLOADBOX_S3_BUCKET ?? "",
+    accessKeyId: process.env.UPLOADBOX_AWS_ACCESS_KEY_ID ?? "",
+    secretAccessKey: process.env.UPLOADBOX_AWS_SECRET_ACCESS_KEY ?? "",
+    cdnBaseUrl: process.env.UPLOADBOX_CDN_BASE_URL,
+    endpoint: process.env.UPLOADBOX_S3_ENDPOINT,
+    forcePathStyle: process.env.UPLOADBOX_S3_FORCE_PATH_STYLE === "true",
+    presignedUrlExpiry: process.env.UPLOADBOX_PRESIGNED_URL_EXPIRY
+      ? parseInt(process.env.UPLOADBOX_PRESIGNED_URL_EXPIRY, 10)
+      : undefined,
+  };
+}
+
+export function createUploadbox<TRouter extends FileRouter>(opts: {
+  router: TRouter;
+  config?: Partial<UploadboxConfig>;
+}): UploadboxInstance<TRouter> {
+  const envConfig = getConfigFromEnv();
+  const config: UploadboxConfig = { ...envConfig, ...opts.config };
+
+  const s3Client = createS3Client(config);
+
+  return {
+    router: opts.router,
+    s3Client,
+    config,
+  };
+}
+
+// The `f` function — shorthand for creating a file route builder
+export function f(config: FileRouteConfig) {
+  return createUploadBuilder(config);
+}

package/src/errors.ts

@@ -0,0 +1,65 @@
+export class UploadboxError extends Error {
+  public readonly code: string;
+  public readonly statusCode: number;
+
+  constructor(code: string, message: string, statusCode: number = 400) {
+    super(message);
+    this.name = "UploadboxError";
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+
+  static fileTooLarge(maxSize: string) {
+    return new UploadboxError("FILE_TOO_LARGE", `File exceeds maximum size of ${maxSize}`, 413);
+  }
+
+  static invalidFileType(type: string) {
+    return new UploadboxError("INVALID_FILE_TYPE", `File type "${type}" is not allowed`, 415);
+  }
+
+  static tooManyFiles(max: number) {
+    return new UploadboxError("TOO_MANY_FILES", `Maximum ${max} files allowed`, 400);
+  }
+
+  static tooFewFiles(min: number) {
+    return new UploadboxError("TOO_FEW_FILES", `Minimum ${min} files required`, 400);
+  }
+
+  static routeNotFound(route: string) {
+    return new UploadboxError("ROUTE_NOT_FOUND", `Upload route "${route}" not found`, 404);
+  }
+
+  static uploadFailed(reason: string) {
+    return new UploadboxError("UPLOAD_FAILED", `Upload failed: ${reason}`, 500);
+  }
+
+  static unauthorized(message = "Unauthorized") {
+    return new UploadboxError("UNAUTHORIZED", message, 401);
+  }
+
+  static rateLimited(retryAfter: number) {
+    const err = new UploadboxError("RATE_LIMITED", `Rate limit exceeded. Retry after ${retryAfter} seconds`, 429);
+    (err as any).retryAfter = retryAfter;
+    return err;
+  }
+
+  static forbidden(message = "Forbidden") {
+    return new UploadboxError("FORBIDDEN", message, 403);
+  }
+
+  static quotaExceeded() {
+    return new UploadboxError("QUOTA_EXCEEDED", "Storage or upload quota exceeded", 413);
+  }
+
+  static s3Error(message: string) {
+    return new UploadboxError("S3_ERROR", `S3 error: ${message}`, 500);
+  }
+
+  toJSON() {
+    return {
+      error: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+    };
+  }
+}

package/src/file-types.ts

@@ -0,0 +1,37 @@
+import type { FileType } from "./types.js";
+
+export const FILE_TYPE_MIME_MAP: Record<FileType, string[]> = {
+  image: ["image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml", "image/avif", "image/heic", "image/heif"],
+  video: ["video/mp4", "video/webm", "video/ogg", "video/quicktime", "video/x-msvideo"],
+  audio: ["audio/mpeg", "audio/ogg", "audio/wav", "audio/webm", "audio/aac", "audio/flac"],
+  pdf: ["application/pdf"],
+  text: ["text/plain", "text/csv", "text/html", "text/css", "text/javascript", "application/json", "application/xml"],
+  blob: ["application/octet-stream"],
+};
+
+export const DEFAULT_MAX_FILE_SIZES: Record<FileType, string> = {
+  image: "4MB",
+  video: "64MB",
+  audio: "16MB",
+  pdf: "16MB",
+  text: "1MB",
+  blob: "8MB",
+};
+
+export function getFileTypeFromMime(mimeType: string): FileType | null {
+  for (const [fileType, mimes] of Object.entries(FILE_TYPE_MIME_MAP)) {
+    if (mimes.includes(mimeType)) return fileType as FileType;
+  }
+  // Fallback: check prefix
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("video/")) return "video";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("text/")) return "text";
+  return null;
+}
+
+export function isFileTypeAllowed(mimeType: string, allowedTypes: FileType[]): boolean {
+  if (allowedTypes.includes("blob")) return true;
+  const fileType = getFileTypeFromMime(mimeType);
+  return fileType !== null && allowedTypes.includes(fileType);
+}

package/src/hooks/image-resize.ts

@@ -0,0 +1,102 @@
+import type { ProcessingHook, ProcessingContext, ProcessingHookResult } from "../processing.js";
+
+interface ImageResizeOptions {
+  maxWidth?: number;
+  maxHeight?: number;
+  quality?: number;
+  format?: "jpeg" | "png" | "webp";
+}
+
+/**
+ * Example image resize hook using sharp.
+ * Install sharp as a dependency to use this hook:
+ *   npm install sharp
+ *
+ * Usage:
+ *   import { createImageResizeHook } from "@uploadbox/core/hooks/image-resize";
+ *
+ *   const resizeHook = createImageResizeHook({
+ *     maxWidth: 1920,
+ *     maxHeight: 1080,
+ *     quality: 80,
+ *   });
+ */
+export function createImageResizeHook(options: ImageResizeOptions = {}): ProcessingHook {
+  const {
+    maxWidth = 1920,
+    maxHeight = 1080,
+    quality = 80,
+    format = "webp",
+  } = options;
+
+  return {
+    name: "image-resize",
+    timeoutMs: 60000,
+
+    shouldRun(ctx: ProcessingContext): boolean {
+      return ctx.file.type.startsWith("image/");
+    },
+
+    async run(ctx: ProcessingContext): Promise<ProcessingHookResult> {
+      try {
+        // Dynamic import to make sharp optional
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        let sharp: any;
+        try {
+          sharp = await (Function('return import("sharp")')() as Promise<any>);
+        } catch {
+          return {
+            success: false,
+            error: "sharp is not installed. Run: npm install sharp",
+          };
+        }
+
+        const { GetObjectCommand, PutObjectCommand } = await import("@aws-sdk/client-s3");
+
+        // Download file from S3
+        const response = await ctx.s3Client.send(
+          new GetObjectCommand({
+            Bucket: ctx.config.bucket,
+            Key: ctx.file.key,
+          })
+        );
+
+        const body = await response.Body?.transformToByteArray();
+        if (!body) {
+          return { success: false, error: "Failed to download file from S3" };
+        }
+
+        // Resize image
+        const sharpFn = sharp.default ?? sharp;
+        const resized = await sharpFn(Buffer.from(body))
+          .resize(maxWidth, maxHeight, { fit: "inside", withoutEnlargement: true })
+          .toFormat(format, { quality })
+          .toBuffer();
+
+        // Upload resized image back to S3
+        await ctx.s3Client.send(
+          new PutObjectCommand({
+            Bucket: ctx.config.bucket,
+            Key: ctx.file.key,
+            Body: resized,
+            ContentType: `image/${format}`,
+          })
+        );
+
+        return {
+          success: true,
+          data: {
+            originalSize: body.length,
+            resizedSize: resized.length,
+            format,
+          },
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: (err as Error).message,
+        };
+      }
+    },
+  };
+}

package/src/hooks/virus-scan.ts

@@ -0,0 +1,95 @@
+import type { ProcessingHook, ProcessingContext, ProcessingHookResult } from "../processing.js";
+
+interface VirusScanOptions {
+  /** ClamAV REST API endpoint (e.g., http://localhost:3310/scan) */
+  clamavUrl: string;
+  /** Whether to delete the file if a virus is found */
+  deleteOnDetection?: boolean;
+  /** Timeout in ms for the scan request */
+  timeoutMs?: number;
+}
+
+/**
+ * Example virus scan hook using ClamAV REST API.
+ * Requires a running ClamAV REST service.
+ *
+ * Usage:
+ *   import { createVirusScanHook } from "@uploadbox/core/hooks/virus-scan";
+ *
+ *   const scanHook = createVirusScanHook({
+ *     clamavUrl: "http://localhost:3310/scan",
+ *     deleteOnDetection: true,
+ *   });
+ */
+export function createVirusScanHook(options: VirusScanOptions): ProcessingHook {
+  const {
+    clamavUrl,
+    deleteOnDetection = true,
+    timeoutMs = 30000,
+  } = options;
+
+  return {
+    name: "virus-scan",
+    timeoutMs,
+
+    shouldRun(): boolean {
+      // Scan all uploaded files
+      return true;
+    },
+
+    async run(ctx: ProcessingContext): Promise<ProcessingHookResult> {
+      try {
+        const { GetObjectCommand, DeleteObjectCommand } = await import("@aws-sdk/client-s3");
+
+        // Download file from S3
+        const response = await ctx.s3Client.send(
+          new GetObjectCommand({
+            Bucket: ctx.config.bucket,
+            Key: ctx.file.key,
+          })
+        );
+
+        const body = await response.Body?.transformToByteArray();
+        if (!body) {
+          return { success: false, error: "Failed to download file from S3" };
+        }
+
+        // Send to ClamAV for scanning
+        const scanResponse = await fetch(clamavUrl, {
+          method: "POST",
+          body: Buffer.from(body),
+          headers: {
+            "Content-Type": "application/octet-stream",
+          },
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+
+        const scanResult = await scanResponse.text();
+        const isClean = scanResponse.ok && !scanResult.toLowerCase().includes("found");
+
+        if (!isClean && deleteOnDetection) {
+          await ctx.s3Client.send(
+            new DeleteObjectCommand({
+              Bucket: ctx.config.bucket,
+              Key: ctx.file.key,
+            })
+          );
+        }
+
+        return {
+          success: isClean,
+          data: {
+            clean: isClean,
+            scanResult: scanResult.slice(0, 500),
+          },
+          error: isClean ? undefined : `Virus detected: ${scanResult.slice(0, 200)}`,
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: `Virus scan failed: ${(err as Error).message}`,
+        };
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export { createUploadbox, f } from "./create-uploadbox.js";
+export { UploadboxApi } from "./server-api.js";
+export { UploadboxError } from "./errors.js";
+export { createUploadBuilder } from "./builder.js";
+export { validateFiles } from "./validation.js";
+export { createS3Client, generatePresignedPutUrl, generatePresignedGetUrl, headObject, deleteObject, deleteObjects, listObjects } from "./s3.js";
+export { parseFileSize, formatFileSize, generateFileKey, generateUploadId } from "./utils.js";
+export { FILE_TYPE_MIME_MAP, DEFAULT_MAX_FILE_SIZES, getFileTypeFromMime, isFileTypeAllowed } from "./file-types.js";
+export { serverUpload, serverUploadMany } from "./server-upload.js";
+export type { ServerUploadInput, ServerUploadResult } from "./server-upload.js";
+export {
+  createMultipartUpload,
+  generatePresignedPartUrls,
+  completeMultipartUpload,
+  abortMultipartUpload,
+} from "./s3-multipart.js";
+export type {
+  FileType,
+  FileSize,
+  ACL,
+  ContentDisposition,
+  FileRouteConfig,
+  FileInfo,
+  UploadedFileData,
+  MiddlewareFn,
+  OnUploadCompleteFn,
+  FileRoute,
+  FileRouter,
+  PresignedUrlResponse,
+  UploadCompleteResponse,
+  UploadboxConfig,
+  RouterConfig,
+  AuthContext,
+  MultipartPresignedResponse,
+  CompletedPartInfo,
+} from "./types.js";
+export { MULTIPART_THRESHOLD, DEFAULT_PART_SIZE } from "./types.js";
+export type { ProcessingHook, ProcessingContext, ProcessingHookResult, ProcessingPipelineConfig } from "./processing.js";

package/src/processing.ts

@@ -0,0 +1,28 @@
+import type { UploadedFileData, UploadboxConfig } from "./types.js";
+import type { S3Client } from "@aws-sdk/client-s3";
+
+export interface ProcessingContext {
+  file: UploadedFileData;
+  metadata: Record<string, unknown>;
+  s3Client: S3Client;
+  config: UploadboxConfig;
+}
+
+export interface ProcessingHookResult {
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: string;
+}
+
+export interface ProcessingHook {
+  name: string;
+  shouldRun: (ctx: ProcessingContext) => boolean;
+  run: (ctx: ProcessingContext) => Promise<ProcessingHookResult>;
+  timeoutMs?: number;
+}
+
+export interface ProcessingPipelineConfig {
+  hooks: ProcessingHook[];
+  mode?: "sequential" | "parallel";
+  continueOnError?: boolean;
+}

package/src/s3-multipart.ts

@@ -0,0 +1,107 @@
+import {
+  S3Client,
+  CreateMultipartUploadCommand,
+  UploadPartCommand,
+  CompleteMultipartUploadCommand,
+  AbortMultipartUploadCommand,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { UploadboxError } from "./errors.js";
+
+export async function createMultipartUpload(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  contentType: string
+): Promise<string> {
+  try {
+    const response = await client.send(
+      new CreateMultipartUploadCommand({
+        Bucket: bucket,
+        Key: key,
+        ContentType: contentType,
+      })
+    );
+    if (!response.UploadId) {
+      throw new Error("No UploadId returned from S3");
+    }
+    return response.UploadId;
+  } catch (err) {
+    if (err instanceof UploadboxError) throw err;
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}
+
+export async function generatePresignedPartUrls(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  uploadId: string,
+  partNumbers: number[],
+  expiresIn: number = 3600
+): Promise<{ partNumber: number; url: string }[]> {
+  try {
+    return await Promise.all(
+      partNumbers.map(async (partNumber) => {
+        const command = new UploadPartCommand({
+          Bucket: bucket,
+          Key: key,
+          UploadId: uploadId,
+          PartNumber: partNumber,
+        });
+        const url = await getSignedUrl(client, command, { expiresIn });
+        return { partNumber, url };
+      })
+    );
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}
+
+export async function completeMultipartUpload(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  uploadId: string,
+  parts: { partNumber: number; etag: string }[]
+): Promise<void> {
+  try {
+    await client.send(
+      new CompleteMultipartUploadCommand({
+        Bucket: bucket,
+        Key: key,
+        UploadId: uploadId,
+        MultipartUpload: {
+          Parts: parts
+            .sort((a, b) => a.partNumber - b.partNumber)
+            .map((p) => ({
+              PartNumber: p.partNumber,
+              ETag: p.etag,
+            })),
+        },
+      })
+    );
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}
+
+export async function abortMultipartUpload(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  uploadId: string
+): Promise<void> {
+  try {
+    await client.send(
+      new AbortMultipartUploadCommand({
+        Bucket: bucket,
+        Key: key,
+        UploadId: uploadId,
+      })
+    );
+  } catch (err) {
+    // Ignore errors when aborting — the upload may already be aborted
+    console.warn("[uploadbox] Failed to abort multipart upload:", (err as Error).message);
+  }
+}

package/src/s3.ts

@@ -0,0 +1,142 @@
+import {
+  S3Client,
+  PutObjectCommand,
+  HeadObjectCommand,
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  ListObjectsV2Command,
+  GetObjectCommand,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import type { UploadboxConfig } from "./types.js";
+import { UploadboxError } from "./errors.js";
+
+export function createS3Client(config: UploadboxConfig): S3Client {
+  return new S3Client({
+    region: config.region ?? "us-east-1",
+    credentials: {
+      accessKeyId: config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+    },
+    ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+    ...(config.forcePathStyle ? { forcePathStyle: true } : {}),
+  });
+}
+
+export async function generatePresignedPutUrl(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  contentType: string,
+  contentLength: number,
+  expiresIn: number = 3600
+): Promise<string> {
+  try {
+    const command = new PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      ContentType: contentType,
+      ContentLength: contentLength,
+    });
+    return await getSignedUrl(client, command, { expiresIn });
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}
+
+export async function generatePresignedGetUrl(
+  client: S3Client,
+  bucket: string,
+  key: string,
+  expiresIn: number = 3600
+): Promise<string> {
+  try {
+    const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+    return await getSignedUrl(client, command, { expiresIn });
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}
+
+export async function headObject(
+  client: S3Client,
+  bucket: string,
+  key: string
+): Promise<{ contentLength: number; contentType: string } | null> {
+  try {
+    const response = await client.send(
+      new HeadObjectCommand({ Bucket: bucket, Key: key })
+    );
+    return {
+      contentLength: response.ContentLength ?? 0,
+      contentType: response.ContentType ?? "application/octet-stream",
+    };
+  } catch (err: any) {
+    if (err.name === "NotFound" || err.$metadata?.httpStatusCode === 404) {
+      return null;
+    }
+    throw UploadboxError.s3Error(err.message);
+  }
+}
+
+export async function deleteObject(
+  client: S3Client,
+  bucket: string,
+  key: string
+): Promise<void> {
+  try {
+    await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}
+
+export async function deleteObjects(
+  client: S3Client,
+  bucket: string,
+  keys: string[]
+): Promise<void> {
+  if (keys.length === 0) return;
+  try {
+    await client.send(
+      new DeleteObjectsCommand({
+        Bucket: bucket,
+        Delete: { Objects: keys.map((Key) => ({ Key })) },
+      })
+    );
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}
+
+export async function listObjects(
+  client: S3Client,
+  bucket: string,
+  prefix?: string,
+  limit: number = 1000,
+  continuationToken?: string
+): Promise<{
+  keys: { key: string; size: number; lastModified: Date }[];
+  nextToken?: string;
+}> {
+  try {
+    const response = await client.send(
+      new ListObjectsV2Command({
+        Bucket: bucket,
+        Prefix: prefix,
+        MaxKeys: limit,
+        ContinuationToken: continuationToken,
+      })
+    );
+    return {
+      keys: (response.Contents ?? []).map((obj) => ({
+        key: obj.Key!,
+        size: obj.Size ?? 0,
+        lastModified: obj.LastModified ?? new Date(),
+      })),
+      nextToken: response.NextContinuationToken,
+    };
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+}