@uploadbox/nextjs 0.1.0

package/src/hosted-hooks.ts

@@ -0,0 +1,132 @@
+import type { LifecycleHooks } from "./types.js";
+import type { AuthContext } from "@uploadbox/core";
+
+export interface HostedModeConfig {
+  /** URL of the Uploadbox platform, e.g. "https://uploadbox.dev" */
+  platformUrl: string;
+  /** Project ID on the platform */
+  projectId: string;
+}
+
+async function callPlatformHook(
+  config: HostedModeConfig,
+  hook: string,
+  payload: Record<string, unknown>
+): Promise<{ ok: boolean; data?: unknown; error?: string }> {
+  const url = `${config.platformUrl.replace(/\/$/, "")}/api/platform/hooks`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Uploadbox-Project-Id": config.projectId,
+    },
+    body: JSON.stringify({ hook, payload }),
+  });
+  return res.json() as Promise<{ ok: boolean; data?: unknown; error?: string }>;
+}
+
+function serializeDates(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value instanceof Date) {
+      result[key] = value.toISOString();
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      result[key] = serializeDates(value as Record<string, unknown>);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+export function createHostedHooks(config: HostedModeConfig): LifecycleHooks {
+  return {
+    onAuthenticate: async (request) => {
+      const authHeader = request.headers.get("authorization");
+      if (!authHeader) return undefined;
+
+      const result = await callPlatformHook(config, "authenticate", {
+        authorizationHeader: authHeader,
+      });
+
+      if (!result.ok) {
+        const { UploadboxError } = await import("@uploadbox/core");
+        throw UploadboxError.unauthorized(result.error ?? "Authentication failed");
+      }
+
+      return result.data as AuthContext;
+    },
+
+    onQuotaCheck: async ({ auth, totalSize }) => {
+      const result = await callPlatformHook(config, "quota-check", {
+        apiKeyId: auth?.apiKeyId,
+        totalSize,
+      });
+
+      if (!result.ok) {
+        const { UploadboxError } = await import("@uploadbox/core");
+        throw UploadboxError.quotaExceeded();
+      }
+    },
+
+    onUploadStarted: async (events) => {
+      callPlatformHook(config, "upload-started", {
+        events: events.map((e) => ({
+          ...serializeDates(e as unknown as Record<string, unknown>),
+          apiKeyId: e.auth?.apiKeyId,
+        })),
+      }).catch(console.error);
+    },
+
+    onFileVerified: async (fileKey) => {
+      const result = await callPlatformHook(config, "file-verified", {
+        key: fileKey,
+      });
+      if (!result.ok || !result.data) return null;
+      return result.data as any;
+    },
+
+    onUploadCompleted: async (event) => {
+      callPlatformHook(config, "upload-completed", {
+        file: event.file,
+        routeKey: event.routeKey,
+        apiKeyId: event.auth?.apiKeyId,
+        metadata: event.metadata,
+      }).catch(console.error);
+    },
+
+    onUploadFailed: async (event) => {
+      callPlatformHook(config, "upload-failed", {
+        key: event.key,
+        routeKey: event.routeKey,
+        apiKeyId: event.auth?.apiKeyId,
+      }).catch(console.error);
+    },
+
+    onMultipartStarted: async (event) => {
+      callPlatformHook(
+        config,
+        "multipart-started",
+        serializeDates({
+          ...event,
+          apiKeyId: event.auth?.apiKeyId,
+        } as unknown as Record<string, unknown>)
+      ).catch(console.error);
+    },
+
+    onMultipartCompleted: async (event) => {
+      callPlatformHook(config, "multipart-completed", {
+        key: event.key,
+        s3UploadId: event.s3UploadId,
+        parts: event.parts,
+      }).catch(console.error);
+    },
+
+    onMultipartAborted: async (event) => {
+      callPlatformHook(config, "multipart-aborted", {
+        key: event.key,
+        s3UploadId: event.s3UploadId,
+      }).catch(console.error);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { createRouteHandler } from "./create-route-handler.js";
+export type {
+  RouteHandlerOpts,
+  LifecycleHooks,
+  UploadStartedEvent,
+  FileVerifiedData,
+  UploadCompletedEvent,
+  UploadFailedEvent,
+  MultipartStartedEvent,
+  MultipartCompletedEvent,
+  MultipartAbortedEvent,
+} from "./types.js";
+export { extractRouterConfig } from "./extract-router-config.js";
+export { RateLimiter } from "./rate-limiter.js";
+export type { RateLimitConfig } from "./rate-limiter.js";
+export { runProcessingPipeline } from "./processing-pipeline.js";
+export { createHostedHandler } from "./create-hosted-handler.js";
+export { createHostedHooks } from "./hosted-hooks.js";
+export type { HostedModeConfig } from "./hosted-hooks.js";

package/src/processing-pipeline.ts

@@ -0,0 +1,77 @@
+import type { ProcessingPipelineConfig, ProcessingContext, ProcessingHookResult, UploadedFileData, UploadboxConfig } from "@uploadbox/core";
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(() => reject(new Error(`Processing hook timed out after ${ms}ms`)), ms)
+    ),
+  ]);
+}
+
+export async function runProcessingPipeline(
+  config: ProcessingPipelineConfig,
+  file: UploadedFileData,
+  metadata: Record<string, unknown>,
+  s3Client: unknown,
+  uploadboxConfig: UploadboxConfig
+): Promise<ProcessingHookResult[]> {
+  const ctx: ProcessingContext = {
+    file,
+    metadata,
+    s3Client: s3Client as any,
+    config: uploadboxConfig,
+  };
+
+  const applicableHooks = config.hooks.filter((hook) => hook.shouldRun(ctx));
+
+  if (applicableHooks.length === 0) return [];
+
+  const results: ProcessingHookResult[] = [];
+
+  if (config.mode === "parallel") {
+    const promises = applicableHooks.map(async (hook) => {
+      try {
+        const timeout = hook.timeoutMs ?? 30000;
+        return await withTimeout(hook.run(ctx), timeout);
+      } catch (err) {
+        const result: ProcessingHookResult = {
+          success: false,
+          error: `Hook "${hook.name}" failed: ${(err as Error).message}`,
+        };
+        if (!config.continueOnError) throw err;
+        return result;
+      }
+    });
+
+    const settled = await Promise.allSettled(promises);
+    for (const result of settled) {
+      if (result.status === "fulfilled") {
+        results.push(result.value);
+      } else {
+        results.push({
+          success: false,
+          error: result.reason?.message ?? "Unknown error",
+        });
+      }
+    }
+  } else {
+    // Sequential (default)
+    for (const hook of applicableHooks) {
+      try {
+        const timeout = hook.timeoutMs ?? 30000;
+        const result = await withTimeout(hook.run(ctx), timeout);
+        results.push(result);
+      } catch (err) {
+        const result: ProcessingHookResult = {
+          success: false,
+          error: `Hook "${hook.name}" failed: ${(err as Error).message}`,
+        };
+        results.push(result);
+        if (!config.continueOnError) break;
+      }
+    }
+  }
+
+  return results;
+}

package/src/rate-limiter.ts

@@ -0,0 +1,64 @@
+export interface RateLimitConfig {
+  requestsPerMinute?: number;
+  uploadsPerHour?: number;
+}
+
+interface SlidingWindow {
+  timestamps: number[];
+}
+
+export class RateLimiter {
+  private windows = new Map<string, SlidingWindow>();
+  private config: RateLimitConfig;
+  private cleanupInterval: ReturnType<typeof setInterval>;
+
+  constructor(config: RateLimitConfig) {
+    this.config = config;
+    // Cleanup stale entries every 5 minutes
+    this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
+  }
+
+  check(key: string, type: "request" | "upload"): { allowed: boolean; retryAfter: number } {
+    const limit = type === "request" ? this.config.requestsPerMinute : this.config.uploadsPerHour;
+    if (!limit) return { allowed: true, retryAfter: 0 };
+
+    const windowMs = type === "request" ? 60_000 : 3_600_000;
+    const windowKey = `${key}:${type}`;
+    const now = Date.now();
+
+    let window = this.windows.get(windowKey);
+    if (!window) {
+      window = { timestamps: [] };
+      this.windows.set(windowKey, window);
+    }
+
+    // Remove expired timestamps
+    const cutoff = now - windowMs;
+    window.timestamps = window.timestamps.filter((t) => t > cutoff);
+
+    if (window.timestamps.length >= limit) {
+      const oldestInWindow = window.timestamps[0]!;
+      const retryAfter = Math.ceil((oldestInWindow + windowMs - now) / 1000);
+      return { allowed: false, retryAfter };
+    }
+
+    window.timestamps.push(now);
+    return { allowed: true, retryAfter: 0 };
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    const maxWindow = 3_600_000; // 1 hour
+
+    for (const [key, window] of this.windows.entries()) {
+      window.timestamps = window.timestamps.filter((t) => t > now - maxWindow);
+      if (window.timestamps.length === 0) {
+        this.windows.delete(key);
+      }
+    }
+  }
+
+  destroy(): void {
+    clearInterval(this.cleanupInterval);
+  }
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+import type {
+  AuthContext,
+  UploadedFileData,
+  FileRouter,
+  UploadboxConfig,
+  CompletedPartInfo,
+} from "@uploadbox/core";
+import type { ProcessingPipelineConfig } from "@uploadbox/core";
+import type { RateLimitConfig } from "./rate-limiter.js";
+
+// ---------- Event types ----------
+
+export interface UploadStartedEvent {
+  key: string;
+  name: string;
+  size: number;
+  type: string;
+  url: string;
+  routeKey: string;
+  auth?: AuthContext;
+  metadata: Record<string, unknown>;
+  customMetadata?: Record<string, string> | null;
+  expiresAt: Date | null;
+}
+
+export interface FileVerifiedData {
+  key: string;
+  name: string;
+  size: number;
+  type: string;
+  url: string;
+  acl: string;
+  metadata: Record<string, unknown>;
+  customMetadata?: Record<string, string>;
+}
+
+export interface UploadCompletedEvent {
+  file: UploadedFileData;
+  routeKey: string;
+  auth?: AuthContext;
+  metadata: Record<string, unknown>;
+  serverData: unknown;
+}
+
+export interface UploadFailedEvent {
+  key: string;
+  routeKey: string;
+  auth?: AuthContext;
+}
+
+export interface MultipartStartedEvent {
+  key: string;
+  name: string;
+  size: number;
+  type: string;
+  url: string;
+  routeKey: string;
+  s3UploadId: string;
+  bucket: string;
+  totalParts: number;
+  partSize: number;
+  auth?: AuthContext;
+  metadata: Record<string, unknown>;
+  customMetadata?: Record<string, string> | null;
+  expiresAt: Date | null;
+  uploadExpiresAt: Date;
+}
+
+export interface MultipartCompletedEvent {
+  key: string;
+  s3UploadId: string;
+  routeKey: string;
+  auth?: AuthContext;
+  parts: CompletedPartInfo[];
+}
+
+export interface MultipartAbortedEvent {
+  key: string;
+  s3UploadId: string;
+}
+
+// ---------- Lifecycle hooks ----------
+
+export interface LifecycleHooks {
+  /** Custom authentication. Return AuthContext or undefined for anonymous. Throw UploadboxError to deny. */
+  onAuthenticate?: (request: Request) => Promise<AuthContext | undefined>;
+
+  /** Quota check before upload. Throw UploadboxError.quotaExceeded() to deny. */
+  onQuotaCheck?: (ctx: { auth?: AuthContext; totalSize: number; fileCount: number }) => Promise<void>;
+
+  /** Called after presigned URLs are generated (fire-and-forget). */
+  onUploadStarted?: (events: UploadStartedEvent[]) => Promise<void>;
+
+  /** Fallback to look up file data when in-memory state is lost (e.g. multi-instance). */
+  onFileVerified?: (fileKey: string) => Promise<FileVerifiedData | null>;
+
+  /** Called after onUploadComplete runs successfully (fire-and-forget). */
+  onUploadCompleted?: (event: UploadCompletedEvent) => Promise<void>;
+
+  /** Called when an upload fails (fire-and-forget). */
+  onUploadFailed?: (event: UploadFailedEvent) => Promise<void>;
+
+  /** Called when multipart upload is created (fire-and-forget). */
+  onMultipartStarted?: (event: MultipartStartedEvent) => Promise<void>;
+
+  /** Called when multipart upload completes (fire-and-forget). */
+  onMultipartCompleted?: (event: MultipartCompletedEvent) => Promise<void>;
+
+  /** Called when multipart upload is aborted (fire-and-forget). */
+  onMultipartAborted?: (event: MultipartAbortedEvent) => Promise<void>;
+
+  /** Resolve per-request S3 config (e.g. per-region or BYOB). Return null to use default. */
+  onResolveConfig?: (auth?: AuthContext) => Promise<{
+    config: UploadboxConfig;
+    keyPrefix?: string;
+  } | null>;
+}
+
+// ---------- Route handler options ----------
+
+export interface RouteHandlerOpts<TRouter extends FileRouter> {
+  router: TRouter;
+  config?: Partial<UploadboxConfig>;
+  hooks?: LifecycleHooks;
+  rateLimit?: RateLimitConfig;
+  processing?: ProcessingPipelineConfig;
+  /** Custom S3 client factory (e.g. for caching). Must return an S3Client instance. */
+  s3ClientFactory?: (config: UploadboxConfig) => unknown;
+}