@uploadbox/core 0.1.0

package/src/server-api.ts

@@ -0,0 +1,81 @@
+import type { S3Client } from "@aws-sdk/client-s3";
+import type { UploadboxConfig, ACL } from "./types.js";
+import {
+  listObjects,
+  deleteObject,
+  deleteObjects,
+  generatePresignedGetUrl,
+  headObject,
+} from "./s3.js";
+import { serverUpload, serverUploadMany, type ServerUploadInput, type ServerUploadResult } from "./server-upload.js";
+
+export interface FileRecord {
+  id: string;
+  key: string;
+  name: string;
+  size: number;
+  type: string;
+  url: string;
+  acl: ACL;
+  status: "pending" | "complete";
+  createdAt: Date;
+}
+
+export class UploadboxApi {
+  constructor(
+    private s3Client: S3Client,
+    private config: UploadboxConfig
+  ) {}
+
+  private getFileUrl(key: string): string {
+    if (this.config.cdnBaseUrl) {
+      return `${this.config.cdnBaseUrl.replace(/\/$/, "")}/${key}`;
+    }
+    if (this.config.endpoint) {
+      const base = this.config.endpoint.replace(/\/$/, "");
+      if (this.config.forcePathStyle) {
+        return `${base}/${this.config.bucket}/${key}`;
+      }
+      return `${base}/${key}`;
+    }
+    return `https://${this.config.bucket}.s3.${this.config.region ?? "us-east-1"}.amazonaws.com/${key}`;
+  }
+
+  async listFiles(opts?: { prefix?: string; limit?: number; continuationToken?: string }) {
+    return listObjects(
+      this.s3Client,
+      this.config.bucket,
+      opts?.prefix,
+      opts?.limit,
+      opts?.continuationToken
+    );
+  }
+
+  async deleteFile(key: string): Promise<void> {
+    await deleteObject(this.s3Client, this.config.bucket, key);
+  }
+
+  async deleteFiles(keys: string[]): Promise<void> {
+    await deleteObjects(this.s3Client, this.config.bucket, keys);
+  }
+
+  async getSignedUrl(key: string, expiresIn?: number): Promise<string> {
+    return generatePresignedGetUrl(this.s3Client, this.config.bucket, key, expiresIn);
+  }
+
+  async verifyUpload(key: string): Promise<{ contentLength: number; contentType: string } | null> {
+    return headObject(this.s3Client, this.config.bucket, key);
+  }
+
+  buildFileUrl(key: string): string {
+    return this.getFileUrl(key);
+  }
+
+  async uploadFile(input: ServerUploadInput): Promise<ServerUploadResult> {
+    return serverUpload(this.s3Client, this.config, input);
+  }
+
+  async uploadFiles(inputs: ServerUploadInput[], concurrency?: number): Promise<ServerUploadResult[]> {
+    return serverUploadMany(this.s3Client, this.config, inputs, concurrency);
+  }
+}

package/src/server-upload.ts

@@ -0,0 +1,88 @@
+import { PutObjectCommand } from "@aws-sdk/client-s3";
+import type { S3Client } from "@aws-sdk/client-s3";
+import type { UploadboxConfig } from "./types.js";
+import { generateFileKey, getContentTypeFromExt } from "./utils.js";
+import { UploadboxError } from "./errors.js";
+import type { Readable } from "stream";
+
+export interface ServerUploadInput {
+  name: string;
+  body: Buffer | Uint8Array | Readable;
+  contentType?: string;
+  metadata?: Record<string, string>;
+  acl?: "public-read" | "private";
+}
+
+export interface ServerUploadResult {
+  key: string;
+  name: string;
+  url: string;
+  contentType: string;
+}
+
+function buildUrl(config: UploadboxConfig, key: string): string {
+  if (config.cdnBaseUrl) {
+    return `${config.cdnBaseUrl.replace(/\/$/, "")}/${key}`;
+  }
+  if (config.endpoint) {
+    const base = config.endpoint.replace(/\/$/, "");
+    if (config.forcePathStyle) {
+      return `${base}/${config.bucket}/${key}`;
+    }
+    return `${base}/${key}`;
+  }
+  return `https://${config.bucket}.s3.${config.region ?? "us-east-1"}.amazonaws.com/${key}`;
+}
+
+export async function serverUpload(
+  s3Client: S3Client,
+  config: UploadboxConfig,
+  input: ServerUploadInput
+): Promise<ServerUploadResult> {
+  const key = generateFileKey(input.name);
+  const contentType = input.contentType ?? getContentTypeFromExt(input.name);
+
+  try {
+    await s3Client.send(
+      new PutObjectCommand({
+        Bucket: config.bucket,
+        Key: key,
+        Body: input.body,
+        ContentType: contentType,
+        ...(input.acl ? { ACL: input.acl } : {}),
+        ...(input.metadata ? { Metadata: input.metadata } : {}),
+      })
+    );
+  } catch (err) {
+    throw UploadboxError.s3Error((err as Error).message);
+  }
+
+  return {
+    key,
+    name: input.name,
+    url: buildUrl(config, key),
+    contentType,
+  };
+}
+
+export async function serverUploadMany(
+  s3Client: S3Client,
+  config: UploadboxConfig,
+  inputs: ServerUploadInput[],
+  concurrency: number = 5
+): Promise<ServerUploadResult[]> {
+  const results: ServerUploadResult[] = [];
+  const queue = [...inputs];
+
+  async function worker() {
+    while (queue.length > 0) {
+      const input = queue.shift()!;
+      results.push(await serverUpload(s3Client, config, input));
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, inputs.length) }, () => worker());
+  await Promise.all(workers);
+
+  return results;
+}

package/src/types.ts

@@ -0,0 +1,105 @@
+export type FileType = "image" | "video" | "audio" | "pdf" | "text" | "blob";
+export type FileSize = `${number}${"B" | "KB" | "MB" | "GB"}`;
+export type ACL = "public-read" | "private";
+export type ContentDisposition = "inline" | "attachment";
+
+export type FileRouteConfig = {
+  [K in FileType]?: {
+    maxFileSize?: FileSize;
+    maxFileCount?: number;
+    minFileCount?: number;
+    acl?: ACL;
+    contentDisposition?: ContentDisposition;
+    presignedUrlExpiry?: number;
+    defaultTtlSeconds?: number;
+    maxTtlSeconds?: number;
+  };
+};
+
+export interface FileInfo {
+  name: string;
+  size: number;
+  type: string;
+  customMetadata?: Record<string, string>;
+  ttlSeconds?: number;
+}
+
+export interface UploadedFileData {
+  key: string;
+  name: string;
+  size: number;
+  type: string;
+  url: string;
+  acl: ACL;
+  customMetadata?: Record<string, string>;
+}
+
+export interface AuthContext {
+  apiKeyId: string;
+  apiKeyName: string;
+  projectId?: string;
+}
+
+export type MiddlewareFn<TMetadata> = (ctx: {
+  req: Request;
+  files: FileInfo[];
+  auth?: AuthContext;
+}) => Promise<TMetadata> | TMetadata;
+
+export type OnUploadCompleteFn<TMetadata, TReturn> = (ctx: {
+  metadata: TMetadata;
+  file: UploadedFileData;
+}) => Promise<TReturn> | TReturn;
+
+export interface FileRoute<TMetadata = Record<string, unknown>, TReturn = unknown> {
+  _config: FileRouteConfig;
+  _middleware: MiddlewareFn<TMetadata>;
+  _onUploadComplete: OnUploadCompleteFn<TMetadata, TReturn>;
+}
+
+export type FileRouter = Record<string, FileRoute<any, any>>;
+
+export interface PresignedUrlResponse {
+  uploadId: string;
+  key: string;
+  url: string;
+  fields?: Record<string, string>;
+}
+
+export interface UploadCompleteResponse<TReturn = unknown> {
+  file: UploadedFileData;
+  serverData: TReturn;
+}
+
+export interface UploadboxConfig {
+  region?: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  cdnBaseUrl?: string;
+  endpoint?: string;
+  forcePathStyle?: boolean;
+  presignedUrlExpiry?: number;
+}
+
+export type RouterConfig = {
+  [routeKey: string]: {
+    config: FileRouteConfig;
+  };
+};
+
+export const MULTIPART_THRESHOLD = 10 * 1024 * 1024; // 10MB
+export const DEFAULT_PART_SIZE = 10 * 1024 * 1024; // 10MB
+
+export interface MultipartPresignedResponse {
+  fileKey: string;
+  uploadId: string;
+  parts: { partNumber: number; url: string }[];
+  partSize: number;
+  totalParts: number;
+}
+
+export interface CompletedPartInfo {
+  partNumber: number;
+  etag: string;
+}

package/src/utils.ts

@@ -0,0 +1,54 @@
+import type { FileSize } from "./types.js";
+import { randomBytes } from "crypto";
+
+const SIZE_UNITS: Record<string, number> = {
+  B: 1,
+  KB: 1024,
+  MB: 1024 * 1024,
+  GB: 1024 * 1024 * 1024,
+};
+
+export function parseFileSize(size: FileSize): number {
+  const match = size.match(/^(\d+(?:\.\d+)?)(B|KB|MB|GB)$/);
+  if (!match) throw new Error(`Invalid file size format: ${size}`);
+  const value = parseFloat(match[1]!);
+  const unit = match[2]!;
+  return Math.floor(value * SIZE_UNITS[unit]!);
+}
+
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const value = bytes / Math.pow(1024, i);
+  return `${value.toFixed(value % 1 === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+export function generateFileKey(originalName: string): string {
+  const id = randomBytes(16).toString("hex");
+  const ext = originalName.includes(".") ? originalName.slice(originalName.lastIndexOf(".")) : "";
+  const safeName = originalName
+    .replace(/\.[^.]+$/, "")
+    .replace(/[^a-zA-Z0-9-_]/g, "-")
+    .replace(/-+/g, "-")
+    .slice(0, 100);
+  return `${safeName}-${id}${ext}`;
+}
+
+export function generateUploadId(): string {
+  return randomBytes(12).toString("base64url");
+}
+
+export function getContentTypeFromExt(filename: string): string {
+  const ext = filename.slice(filename.lastIndexOf(".") + 1).toLowerCase();
+  const map: Record<string, string> = {
+    jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
+    webp: "image/webp", svg: "image/svg+xml", avif: "image/avif",
+    mp4: "video/mp4", webm: "video/webm", ogg: "video/ogg", mov: "video/quicktime",
+    mp3: "audio/mpeg", wav: "audio/wav", flac: "audio/flac", aac: "audio/aac",
+    pdf: "application/pdf",
+    txt: "text/plain", csv: "text/csv", html: "text/html", css: "text/css",
+    js: "text/javascript", json: "application/json", xml: "application/xml",
+  };
+  return map[ext] || "application/octet-stream";
+}

package/src/validation.ts

@@ -0,0 +1,52 @@
+import type { FileRouteConfig, FileInfo, FileType } from "./types.js";
+import { UploadboxError } from "./errors.js";
+import { parseFileSize } from "./utils.js";
+import { DEFAULT_MAX_FILE_SIZES, getFileTypeFromMime, FILE_TYPE_MIME_MAP } from "./file-types.js";
+
+export function validateFiles(files: FileInfo[], config: FileRouteConfig): void {
+  const allowedTypes = Object.keys(config) as FileType[];
+
+  // Compute total max/min file count across all types
+  let totalMaxCount = 0;
+  let totalMinCount = 0;
+  for (const type of allowedTypes) {
+    const typeConfig = config[type]!;
+    totalMaxCount += typeConfig.maxFileCount ?? 1;
+    totalMinCount += typeConfig.minFileCount ?? 0;
+  }
+
+  if (files.length > totalMaxCount) {
+    throw UploadboxError.tooManyFiles(totalMaxCount);
+  }
+
+  if (files.length < totalMinCount) {
+    throw UploadboxError.tooFewFiles(totalMinCount);
+  }
+
+  for (const file of files) {
+    const fileType = getFileTypeFromMime(file.type);
+
+    // If blob is allowed, any type is OK
+    if (!allowedTypes.includes("blob")) {
+      if (!fileType || !allowedTypes.includes(fileType)) {
+        throw UploadboxError.invalidFileType(file.type);
+      }
+    }
+
+    // Find the matching config for this file's type
+    const matchedType = fileType && allowedTypes.includes(fileType) ? fileType : "blob";
+    const typeConfig = config[matchedType];
+    if (!typeConfig && !config.blob) {
+      throw UploadboxError.invalidFileType(file.type);
+    }
+
+    const effectiveConfig = typeConfig || config.blob!;
+    const maxSize = effectiveConfig.maxFileSize ?? (DEFAULT_MAX_FILE_SIZES[matchedType] as any);
+    if (maxSize) {
+      const maxBytes = parseFileSize(maxSize);
+      if (file.size > maxBytes) {
+        throw UploadboxError.fileTooLarge(maxSize);
+      }
+    }
+  }
+}