ocel 0.0.0 → 0.0.1-alpha.1

package/bin/run.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+import { join } from "path";
+import { createRequire } from "node:module";
+
+const { platform, arch } = process;
+const require = createRequire(import.meta.url);
+
+let packageName = "";
+
+switch (platform) {
+  case "win32":
+    packageName = `win32-${arch}`;
+    break;
+  case "darwin":
+    packageName = `darwin-${arch}`;
+    break;
+  case "linux":
+    packageName = `linux-${arch}`;
+    break;
+  default:
+    throw new Error(`Unsupported platform: ${platform}`);
+}
+
+const binaryPkg = `@ocel/${packageName}`;
+
+try {
+  const binary = process.platform === "win32" ? "ocel.exe" : "ocel";
+  const binaryPath = require.resolve(join(binaryPkg, "bin", binary));
+
+  const { spawnSync } = require("child_process");
+  const result = spawnSync(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+  process.exit(result.status);
+} catch (e) {
+  console.error(`Failed to locate binary for ${binaryPkg}.`);
+  process.exit(1);
+}

package/dist/blob/bucket.d.ts

@@ -0,0 +1,55 @@
+import type { IncomingMessage } from "node:http";
+import type { HandleUploadBody, TBucketConfig, TUploaderConfig } from "./types";
+import type { Component } from "../utils/component";
+export declare class Bucket<TUploaderShape extends Record<string, TUploaderConfig<any, any>>> implements Component {
+    readonly name: string;
+    readonly _shape: TUploaderShape;
+    private uploaders;
+    constructor(name: string, args: TBucketConfig<TUploaderShape>);
+    __id(): string;
+    __name(): string;
+    upload: () => Promise<void>;
+    uploadExternal: () => Promise<void>;
+    handleUpload: ({ body, request, }: {
+        request: Request | IncomingMessage;
+        body: HandleUploadBody;
+    }) => Promise<{
+        files: {
+            url: string;
+            key: string;
+            name: string;
+        }[];
+        sessionId: string;
+    } | {
+        files: {
+            fileKey: string;
+            status: "PENDING" | "SUCCESS" | "FAILED";
+            file: {
+                path: string;
+                contentDisposition: string;
+                contentType: string;
+            } | undefined;
+            metadata: any;
+        }[];
+        completed: boolean;
+        type?: undefined;
+        response?: undefined;
+        error?: undefined;
+    } | {
+        type: "UPLOAD_COMPLETED";
+        response: "ok";
+        files?: undefined;
+        completed?: undefined;
+        error?: undefined;
+    } | {
+        error: {
+            message: string;
+            code: string;
+            status: number;
+        };
+        files?: undefined;
+        completed?: undefined;
+        type?: undefined;
+        response?: undefined;
+    }>;
+}

package/dist/blob/bucket.js

@@ -0,0 +1,65 @@
+import z from "zod";
+import { getCallerFile } from "../utils/stack";
+import { rpc } from "../utils/rpc";
+import { Uploader } from "./uploader";
+import { parseReq } from "./parse";
+export class Bucket {
+    name;
+    _shape = {};
+    uploaders = {};
+    constructor(name, args) {
+        this.name = name;
+        if (process.env.OCEL_PHASE === "discovery") {
+            rpc.register({
+                id: name,
+                type: "bucket",
+                source: getCallerFile() || "unknown",
+                // TODO:
+                config: {},
+            });
+        }
+        this._shape = args.uploaders;
+        Object.entries(args.uploaders).forEach(([key, config]) => {
+            this.uploaders[key] = new Uploader(this, key, config);
+        });
+    }
+    __id() {
+        return this.name;
+    }
+    __name() {
+        const id = process.env[`RESOURCE_${this.name}_BUCKET_NAME`];
+        if (!id) {
+            throw new Error(`Bucket ID for bucket "${this.name}" is not defined. Make sure the bucket is properly configured in your Ocel project.`);
+        }
+        return id;
+    }
+    upload = async () => { };
+    uploadExternal = async () => { };
+    handleUpload = async ({ body, request, }) => {
+        const parsedReq = parseReq(request);
+        const hasUploaders = Object.keys(this._shape).length > 0;
+        if (!hasUploaders) {
+            throw new Error("No uploaders configured for this bucket");
+        }
+        const querySchema = z.object({
+            action: z.enum(["presign", "callback", "poll"]),
+            uploader: z.enum(Object.keys(this._shape)),
+            sessionId: z.string().optional(),
+        });
+        const queryRes = querySchema.safeParse(Object.fromEntries(parsedReq.query));
+        if (!queryRes.success) {
+            throw new Error(`Invalid query parameters: ${queryRes.error.message}`);
+        }
+        const query = queryRes.data;
+        const uploader = this.uploaders[query.uploader];
+        if (!uploader) {
+            throw new Error(`Uploader not found: ${query.uploader}`);
+        }
+        return uploader.handleUpload({
+            body,
+            request,
+            action: query.action,
+            sessionId: query.sessionId,
+        });
+    };
+}

package/dist/blob/index.d.ts

@@ -0,0 +1,8 @@
+import { type ZodType } from "zod";
+import type { TBucketConfig, TUploaderConfig } from "./types";
+import { Bucket } from "./bucket";
+export declare function bucket<TUploaderShape extends Record<string, TUploaderConfig<any, any>>>(name: string, args: TBucketConfig<TUploaderShape>): Bucket<TUploaderShape>;
+export declare function uploader<TInput extends ZodType = never, TMeta = never, TReturn = void>({ middleware, input, }: {
+    input?: TInput;
+    middleware: TUploaderConfig<TInput, TMeta, TReturn>["onBeforeUpload"];
+}, config: Omit<TUploaderConfig<TInput, TMeta, TReturn>, "onBeforeUpload" | "_def" | "input">): TUploaderConfig<TInput, TMeta, TReturn>;

package/dist/blob/index.js

@@ -0,0 +1,13 @@
+import {} from "zod";
+import { Bucket } from "./bucket";
+export function bucket(name, args) {
+    return new Bucket(name, args);
+}
+export function uploader({ middleware, input, }, config) {
+    return {
+        ...config,
+        input,
+        onBeforeUpload: middleware,
+        _def: {},
+    };
+}

package/dist/blob/integrations/client.d.ts

@@ -0,0 +1,25 @@
+import type z from "zod";
+import type { Bucket } from "../bucket";
+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 declare function createUploadClient<TBucket extends Bucket<any>>(opts: {
+    url: string;
+}): {
+    upload: <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;
+    }) => Promise<void>;
+};
+export {};

package/dist/blob/integrations/client.js

@@ -0,0 +1,71 @@
+export function createUploadClient(opts) {
+    return {
+        upload: async (uploader, args) => {
+            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 } : {}),
+                }),
+            }).then((r) => r.json()));
+            // 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 () => {
+                const res = await fetch(`${url}?${pollParams.toString()}`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({}),
+                });
+                const data = (await res.json());
+                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);
+                }
+            }
+        },
+    };
+}

package/dist/blob/integrations/hono.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from "hono";
+import type { Bucket } from "../bucket";
+export declare function createRouteHandler(bucket: Bucket<any>): (c: Context) => Promise<Response & import("hono").TypedResponse<{
+    files: {
+        url: string;
+        key: string;
+        name: string;
+    }[];
+    sessionId: string;
+} | {
+    files: {
+        fileKey: string;
+        status: "PENDING" | "SUCCESS" | "FAILED";
+        file: {
+            path: string;
+            contentDisposition: string;
+            contentType: string;
+        } | undefined;
+        metadata: any;
+    }[];
+    completed: boolean;
+} | {
+    type: "UPLOAD_COMPLETED";
+    response: "ok";
+} | {
+    error: {
+        message: string;
+        code: string;
+        status: number;
+    };
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">>;

package/dist/blob/integrations/hono.js

@@ -0,0 +1,11 @@
+export function createRouteHandler(bucket) {
+    return async (c) => {
+        const req = c.req.raw;
+        const body = (await req.json());
+        const result = await bucket.handleUpload({
+            body,
+            request: req,
+        });
+        return c.json(result);
+    };
+}

package/dist/blob/mime-types.d.ts

@@ -0,0 +1 @@
+export type KnownMimeType = "application/json" | "application/xml" | "application/octet-stream" | "application/zip" | "application/gzip" | "application/x-tar" | "application/wasm" | "application/x-7z-compressed" | "application/x-sh" | "application/*" | "text/plain" | "text/csv" | "text/html" | "text/css" | "text/javascript" | "application/javascript" | "application/typescript" | "application/pdf" | "application/rtf" | "text/*" | "image/jpeg" | "image/png" | "image/gif" | "image/webp" | "image/svg+xml" | "image/bmp" | "image/tiff" | "image/avif" | "image/vnd.microsoft.icon" | "image/*" | "audio/mpeg" | "audio/wav" | "audio/ogg" | "audio/aac" | "audio/flac" | "audio/*" | "video/mp4" | "video/webm" | "video/ogg" | "video/quicktime" | "video/x-msvideo" | "video/*" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.ms-excel" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.ms-powerpoint" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.oasis.opendocument.text" | "application/vnd.oasis.opendocument.spreadsheet" | "font/otf" | "font/ttf" | "font/woff" | "font/woff2";

package/dist/blob/mime-types.js

@@ -0,0 +1 @@
+export {};

package/dist/blob/parse.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage } from "node:http";
+import type { FileSize } from "./types";
+export declare function parseReq(req: Request | IncomingMessage): {
+    headers: Record<string, string>;
+    method: string;
+    url: string;
+    path: string;
+    query: URLSearchParams;
+};
+/**
+ * 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 declare function parseFileSize(size: FileSize): number;

package/dist/blob/parse.js

@@ -0,0 +1,69 @@
+import { UploadError } from "./upload-error";
+export function parseReq(req) {
+    if (req instanceof Request) {
+        const headers = {};
+        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 = {};
+    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) {
+    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 = {
+        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/dist/blob/s3-listener.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 } from "aws-lambda";
+export declare const handler: S3Handler;

package/dist/blob/s3-listener.js

@@ -0,0 +1,35 @@
+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 = async (event) => {
+    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/dist/blob/types.d.ts

@@ -0,0 +1,128 @@
+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;
+};
+export {};

package/dist/blob/types.js

@@ -0,0 +1 @@
+import z, {} from "zod";

package/dist/blob/upload-error.d.ts

@@ -0,0 +1,35 @@
+export declare class UploadError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(message: string, statusCode?: number, code?: string);
+    /**
+     * 400 Bad Request
+     * Use when the input is invalid (e.g. file too big, wrong extension)
+     */
+    static badRequest(message?: string): UploadError;
+    /**
+     * 401 Unauthorized
+     * Use when the user is not logged in or missing headers
+     */
+    static unauthorized(message?: string): UploadError;
+    /**
+     * 403 Forbidden
+     * Use when the user is logged in but doesn't have permission (e.g. wrong plan)
+     */
+    static forbidden(message?: string): UploadError;
+    /**
+     * 404 Not Found
+     * Use when a resource required for the upload is missing
+     */
+    static notFound(message?: string): UploadError;
+    /**
+     * 429 Too Many Requests
+     * Use for rate limiting logic
+     */
+    static tooManyRequests(message?: string): UploadError;
+    /**
+     * 500 Internal Server Error
+     * Use for unexpected crashes or database failures
+     */
+    static internal(message?: string): UploadError;
+}