ocel 0.0.0 → 0.0.1-alpha.1

package/src/blob/integrations/client.ts

@@ -0,0 +1,127 @@
+import type z from "zod";
+import type { Bucket } from "../bucket";
+import type { PresignUploadBody, PresignUploadResponse } from "../types";
+
+type PollResponse = {
+  files: Array<{
+    fileKey: string;
+    status: "PENDING" | "SUCCESS" | "FAILED";
+    file?: { path: string; contentDisposition: string; contentType: string };
+    metadata?: unknown;
+  }>;
+  completed: boolean;
+};
+
+type InferReturn<TRouter, K extends keyof TRouter> = TRouter[K] extends {
+  _def: { output: infer R };
+}
+  ? R
+  : never;
+
+type InferInput<TRouter, K extends keyof TRouter> = TRouter[K] extends {
+  _def: { input: infer R };
+}
+  ? R
+  : never;
+
+export function createUploadClient<TBucket extends Bucket<any>>(opts: {
+  url: string;
+}) {
+  return {
+    upload: async <K extends keyof TBucket["_shape"]>(
+      uploader: K,
+      args: InferInput<TBucket["_shape"], K> extends never
+        ? {
+            files: File[];
+            onClientUploadComplete?: (
+              res: InferReturn<TBucket["_shape"], K>,
+            ) => void;
+          }
+        : {
+            files: File[];
+            input: z.infer<InferInput<TBucket["_shape"], K>>;
+            onClientUploadComplete?: (
+              res: InferReturn<TBucket["_shape"], K>,
+            ) => void;
+          },
+    ) => {
+      const url = opts.url;
+      const searchParams = new URLSearchParams();
+      searchParams.append("action", "presign");
+      searchParams.append("uploader", String(uploader));
+
+      // get presign urls
+      const result = (await fetch(`${url}?${searchParams.toString()}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          files: args.files.map((f) => {
+            return {
+              name: f.name,
+              size: f.size,
+              type: f.type,
+              lastModified: f.lastModified,
+              mimeType: f.type,
+            };
+          }),
+          ...("input" in args ? { input: args.input } : {}),
+        } satisfies PresignUploadBody),
+      }).then((r) => r.json())) as PresignUploadResponse;
+
+      // upload files to presign urls (sessionId required for S3 listener to update DynamoDB)
+      await Promise.all(
+        args.files.map((file, index) => {
+          if (!result.files[index]?.url) {
+            throw new Error(`No presign URL returned for file index ${index}`);
+          }
+
+          return fetch(result.files[index].url, {
+            method: "PUT",
+            headers: {
+              "Content-Type": file.type,
+              "Content-Disposition": "inline",
+            },
+            body: file,
+          });
+        }),
+      );
+
+      // poll for completion (S3 listener Lambda updates DynamoDB when upload lands)
+      const pollParams = new URLSearchParams();
+      pollParams.append("action", "poll");
+      pollParams.append("uploader", String(uploader));
+      pollParams.append("sessionId", result.sessionId);
+
+      const pollUntilComplete = async (): Promise<PollResponse> => {
+        const res = await fetch(`${url}?${pollParams.toString()}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({}),
+        });
+        const data = (await res.json()) as PollResponse;
+        if (data.completed) return data;
+        await new Promise((r) => setTimeout(r, 1000));
+        return pollUntilComplete();
+      };
+
+      const pollResult = await pollUntilComplete();
+
+      if (args.onClientUploadComplete && pollResult.files) {
+        const completedFiles = pollResult.files.filter(
+          (f) => f.status === "SUCCESS" && f.file,
+        );
+        const results = completedFiles.map((f) => ({
+          file: f.file!,
+          metadata: f.metadata ?? {},
+        }));
+        if (results.length > 0) {
+          args.onClientUploadComplete(
+            results.length === 1 ? results[0] : (results as any),
+          );
+        }
+      }
+    },
+  };
+}

package/src/blob/integrations/hono.ts

@@ -0,0 +1,16 @@
+import type { Context } from "hono";
+import type { Bucket } from "../bucket";
+
+export function createRouteHandler(bucket: Bucket<any>) {
+  return async (c: Context) => {
+    const req = c.req.raw;
+    const body = (await req.json()) as any;
+
+    const result = await bucket.handleUpload({
+      body,
+      request: req,
+    });
+
+    return c.json(result);
+  };
+}

package/src/blob/mime-types.ts

@@ -0,0 +1,68 @@
+export type KnownMimeType =
+  // --- APPLICATION ---
+  | "application/json"
+  | "application/xml"
+  | "application/octet-stream" // Generic binary data
+  | "application/zip"
+  | "application/gzip"
+  | "application/x-tar"
+  | "application/wasm"
+  | "application/x-7z-compressed" // 7z files
+  | "application/x-sh" // Shell script
+  | "application/*"
+
+  // --- DOCUMENTS / TEXT ---
+  | "text/plain"
+  | "text/csv"
+  | "text/html"
+  | "text/css"
+  | "text/javascript" // Use application/javascript in production
+  | "application/javascript"
+  | "application/typescript"
+  | "application/pdf"
+  | "application/rtf"
+  | "text/*"
+
+  // --- IMAGES ---
+  | "image/jpeg"
+  | "image/png"
+  | "image/gif"
+  | "image/webp"
+  | "image/svg+xml"
+  | "image/bmp"
+  | "image/tiff"
+  | "image/avif"
+  | "image/vnd.microsoft.icon" // ICO files
+  | "image/*"
+
+  // --- AUDIO ---
+  | "audio/mpeg" // MP3
+  | "audio/wav"
+  | "audio/ogg"
+  | "audio/aac"
+  | "audio/flac"
+  | "audio/*"
+
+  // --- VIDEO ---
+  | "video/mp4"
+  | "video/webm"
+  | "video/ogg"
+  | "video/quicktime" // MOV
+  | "video/x-msvideo" // AVI
+  | "video/*"
+
+  // --- MICROSOFT OFFICE / OPEN OFFICE (Crucial for Business Apps) ---
+  | "application/msword" // .doc
+  | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" // .docx
+  | "application/vnd.ms-excel" // .xls
+  | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" // .xlsx
+  | "application/vnd.ms-powerpoint" // .ppt
+  | "application/vnd.openxmlformats-officedocument.presentationml.presentation" // .pptx
+  | "application/vnd.oasis.opendocument.text" // .odt
+  | "application/vnd.oasis.opendocument.spreadsheet" // .ods
+
+  // --- FONT ---
+  | "font/otf"
+  | "font/ttf"
+  | "font/woff"
+  | "font/woff2";

package/src/blob/parse.ts

@@ -0,0 +1,93 @@
+import type { IncomingMessage } from "node:http";
+import type { FileSize } from "./types";
+import { UploadError } from "./upload-error";
+
+export function parseReq(req: Request | IncomingMessage): {
+  headers: Record<string, string>;
+  method: string;
+  url: string;
+  path: string;
+  query: URLSearchParams;
+} {
+  if (req instanceof Request) {
+    const headers: Record<string, string> = {};
+    req.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    return {
+      headers,
+      method: req.method,
+      url: req.url,
+      path: new URL(req.url).pathname,
+      query: new URL(req.url).searchParams,
+    };
+  }
+
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") {
+      headers[key] = value;
+    } else if (Array.isArray(value)) {
+      headers[key] = value.join(", ");
+    }
+  }
+
+  const url = new URL(req.url || "", "http://localhost");
+
+  return {
+    headers,
+    method: req.method || "GET",
+    url: req.url || "",
+    path: url.pathname,
+    query: url.searchParams,
+  };
+}
+
+/**
+ * Converts a human-readable file size string (e.g., "10MB", "2.5GB") into bytes.
+ * Throws an error for invalid input formats.
+ * * @param size The file size represented as a number (bytes) or a string with units (KB, MB, GB, B).
+ * @returns The size in bytes (number).
+ */
+export function parseFileSize(size: FileSize): number {
+  if (typeof size === "number") {
+    if (size < 0) {
+      throw UploadError.badRequest("File size cannot be negative.");
+    }
+    return size;
+  }
+
+  // Convert the input to uppercase to handle 'mb', 'MB', 'Mb' uniformly
+  const cleanSize = size.toUpperCase().trim();
+
+  // Regular expression to extract the numeric value and the unit
+  // Captures: (1) The number part, (2) The unit part (B, KB, MB, GB)
+  const match = cleanSize.match(/^(\d+(\.\d+)?)([A-Z]+)$/);
+
+  if (!match) {
+    throw UploadError.badRequest(
+      `Invalid file size format: "${size}". Expected formats: "10MB", "2GB", "512KB", or raw bytes.`
+    );
+  }
+
+  const numericValue = Number.parseFloat(match[1] ?? "0");
+  const unit = match[3] ?? "";
+
+  const byteConversionMap: Record<string, number> = {
+    B: 1,
+    KB: 1024,
+    MB: 1024 ** 2, // 1,048,576
+    GB: 1024 ** 3, // 1,073,741,824
+  };
+
+  const multiplier = byteConversionMap[unit];
+
+  if (!multiplier) {
+    throw new Error(
+      `Invalid file size unit: "${unit}". Must be B, KB, MB, or GB.`
+    );
+  }
+
+  // Return the size rounded to the nearest integer byte
+  return Math.round(numericValue * multiplier);
+}

package/src/blob/s3-listener.ts

@@ -0,0 +1,48 @@
+/**
+ * S3 event listener Lambda for ocel/blob.
+ * Receives ObjectCreated events, reads x-ocel-session-id from object metadata,
+ * and updates the UploadSession in DynamoDB to SUCCESS.
+ */
+import type { S3Handler, S3Event } from "aws-lambda";
+import { HeadObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { UpdateItemCommand, DynamoDBClient } from "@aws-sdk/client-dynamodb";
+
+const s3 = new S3Client({});
+const dynamo = new DynamoDBClient({});
+const TABLE_NAME = process.env.OCEL_TABLE_NAME || "OcelTable";
+
+export const handler: S3Handler = async (event: S3Event) => {
+  for (const record of event.Records) {
+    const bucket = record.s3.bucket.name;
+    const key = decodeURIComponent(record.s3.object.key.replace(/\+/g, " "));
+
+    try {
+      const head = await s3.send(
+        new HeadObjectCommand({ Bucket: bucket, Key: key }),
+      );
+      const sessionId = head.Metadata?.["x-ocel-session-id"];
+      if (!sessionId) continue;
+
+      const pk = `SESSION#${sessionId}`.toLowerCase();
+      const sk = `FILE#${bucket}#${key}`.toLowerCase();
+
+      await dynamo.send(
+        new UpdateItemCommand({
+          TableName: TABLE_NAME,
+          Key: {
+            pk: { S: pk },
+            sk: { S: sk },
+          },
+          UpdateExpression: "SET #status = :status, updatedAt = :now",
+          ExpressionAttributeNames: { "#status": "status" },
+          ExpressionAttributeValues: {
+            ":status": { S: "SUCCESS" },
+            ":now": { S: new Date().toISOString() },
+          },
+        }),
+      );
+    } catch (err) {
+      console.error(`Failed to update session for ${bucket}/${key}:`, err);
+    }
+  }
+};

package/src/blob/types.ts

@@ -0,0 +1,142 @@
+import type { IncomingMessage } from "node:http";
+import z, { type ZodType } from "zod";
+import type { KnownMimeType } from "./mime-types";
+import type { UploadError } from "./upload-error";
+
+type SuggestedSize = "1KB" | "100KB" | "1MB" | "10MB" | "100MB" | "1GB";
+export type FileSizeUnit = "B" | "KB" | "MB" | "GB";
+export type UnitAutocomplete<TUnit extends string> = `${number}${TUnit}`;
+export type FileSize =
+  | SuggestedSize
+  | UnitAutocomplete<FileSizeUnit>
+  | number
+  | (string & {});
+
+export type StringWithAutocomplete<T extends string> = T | (string & {});
+export type HandleUploadBody = PresignUploadBody | CallbackBody<any>;
+export type HandleUploadResult = PresignUploadResponse;
+
+export type PresignUploadBody = {
+  files: {
+    name: string;
+    size: number;
+    mimeType: string;
+    lastModified: number;
+  }[];
+  input?: Record<string, any>;
+};
+
+export type PresignUploadResponse = {
+  files: {
+    url: string;
+    key: string;
+    name: string;
+  }[];
+  sessionId: string;
+};
+
+export type CallbackBody<TMeta> = {
+  metadata: TMeta;
+  file: {
+    path: string;
+    contentDisposition: string;
+    contentType: string;
+  };
+};
+
+export type UploadFileBody = {
+  key: string;
+  name: string;
+  size: number;
+  mimeType: string;
+  disposition: string;
+  lastModified: number;
+  metadata?: Record<string, string>;
+};
+
+export type PathConfig = {
+  prefix?: string;
+  suffix?: string;
+  randomSuffix?: boolean;
+};
+
+export type PathContext<TMeta> = [TMeta] extends [never]
+  ? {
+      /**
+       * File extension including the dot (e.g., .jpg, .png)
+       */
+      ext: string;
+      /**
+       * File name without extension
+       */
+      fileNameWithoutExt: string;
+      /**
+       * Original file name as uploaded by user
+       */
+      fileNameWithExt: string;
+    }
+  : {
+      /**
+       * File extension including the dot (e.g., .jpg, .png)
+       */
+      ext: string;
+      /**
+       * File name without extension
+       */
+      fileNameWithoutExt: string;
+      /**
+       * Original file name as uploaded by user
+       */
+      fileNameWithExt: string;
+      /**
+       * Any metadata returned by middleware function
+       */
+      metadata: TMeta;
+    };
+
+export type PathGenerator<TMeta> = (ctx: PathContext<TMeta>) => string;
+export type PathInput<TMeta> = PathConfig | PathGenerator<TMeta>;
+
+export type TUploaderConfig<
+  TInput extends ZodType = never,
+  TMeta = never,
+  TReturn = unknown
+> = {
+  path?: PathInput<TMeta>;
+  input?: TInput;
+  accept?: StringWithAutocomplete<KnownMimeType>[];
+  limits?: {
+    maxFileSize?: FileSize | ((ctx: { metadata?: TMeta }) => FileSize);
+    maxFileCount?: number | ((ctx: { metadata?: TMeta }) => number);
+    minFileCount?: number | ((ctx: { metadata?: TMeta }) => number);
+  };
+  contentDisposition?: "inline" | "attachment";
+
+  onBeforeUpload: (
+    opts: [TInput] extends [never]
+      ? {
+          files: PresignUploadBody["files"];
+          req: Request | IncomingMessage;
+        }
+      : {
+          files: PresignUploadBody["files"];
+          input: z.infer<TInput>;
+          req: Request | IncomingMessage;
+        }
+  ) => TMeta | Promise<TMeta>;
+  onUploadError?: (args: { error: UploadError }) => void | Promise<void>;
+  onUploadComplete?: (args: {
+    metadata: TMeta;
+    file: { path: string; contentDisposition: string; contentType: string };
+  }) => TReturn | Promise<TReturn>;
+
+  _def: {
+    meta: TMeta;
+    input: TInput;
+    output: TReturn;
+  };
+};
+
+export type TBucketConfig<TUploaderShape> = {
+  uploaders: TUploaderShape;
+};

package/src/blob/upload-error.ts

@@ -0,0 +1,67 @@
+export class UploadError extends Error {
+  public readonly statusCode: number;
+  public readonly code: string;
+
+  constructor(
+    message: string,
+    statusCode = 500,
+    code = "INTERNAL_SERVER_ERROR"
+  ) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+
+    // Essential for 'instanceof' to work correctly when extending built-in classes in TypeScript
+    Object.setPrototypeOf(this, UploadError.prototype);
+  }
+
+  // --- Static Factory Helpers (The DX Magic) ---
+
+  /**
+   * 400 Bad Request
+   * Use when the input is invalid (e.g. file too big, wrong extension)
+   */
+  static badRequest(message = "Bad Request") {
+    return new UploadError(message, 400, "BAD_REQUEST");
+  }
+
+  /**
+   * 401 Unauthorized
+   * Use when the user is not logged in or missing headers
+   */
+  static unauthorized(message = "Unauthorized") {
+    return new UploadError(message, 401, "UNAUTHORIZED");
+  }
+
+  /**
+   * 403 Forbidden
+   * Use when the user is logged in but doesn't have permission (e.g. wrong plan)
+   */
+  static forbidden(message = "Forbidden") {
+    return new UploadError(message, 403, "FORBIDDEN");
+  }
+
+  /**
+   * 404 Not Found
+   * Use when a resource required for the upload is missing
+   */
+  static notFound(message = "Not Found") {
+    return new UploadError(message, 404, "NOT_FOUND");
+  }
+
+  /**
+   * 429 Too Many Requests
+   * Use for rate limiting logic
+   */
+  static tooManyRequests(message = "Too many requests") {
+    return new UploadError(message, 429, "TOO_MANY_REQUESTS");
+  }
+
+  /**
+   * 500 Internal Server Error
+   * Use for unexpected crashes or database failures
+   */
+  static internal(message = "Internal Server Error") {
+    return new UploadError(message, 500, "INTERNAL_SERVER_ERROR");
+  }
+}