ocel 0.0.0 → 0.0.1-alpha.1

package/dist/blob/upload-error.js

@@ -0,0 +1,54 @@
+export class UploadError extends Error {
+    statusCode;
+    code;
+    constructor(message, 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");
+    }
+}

package/dist/blob/uploader.d.ts

@@ -0,0 +1,67 @@
+import type { HandleUploadBody, PathConfig, PathGenerator, TUploaderConfig, UploadFileBody } from "./types";
+import type { IncomingMessage } from "node:http";
+import type { Bucket } from "./bucket";
+export declare class Uploader<TMeta = unknown> {
+    private bucket;
+    private name;
+    private config;
+    private pathGenerator;
+    constructor(bucket: Bucket<any>, name: string, config: TUploaderConfig<any, TMeta>);
+    handleUpload({ action, body, request, sessionId, }: {
+        request: Request | IncomingMessage;
+        body: HandleUploadBody;
+        action: "presign" | "callback" | "poll";
+        sessionId?: string;
+    }): 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: TMeta;
+        }[];
+        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;
+    }>;
+    private startPolling;
+    getProvider(): {
+        presign: (files: UploadFileBody[]) => Promise<{
+            files: {
+                url: string;
+                key: string;
+                name: string;
+            }[];
+            sessionId: string;
+        }>;
+    };
+    createConfigBasedGenerator(config: PathConfig): PathGenerator<any>;
+    private validateFiles;
+}

package/dist/blob/uploader.js

@@ -0,0 +1,323 @@
+import slugify from "@sindresorhus/slugify";
+import { UploadError } from "./upload-error";
+import path from "node:path";
+import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { getNanoid } from "../utils/nanoid";
+import { UploadSession } from "../internal/db";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { parseFileSize, parseReq } from "./parse";
+export class Uploader {
+    bucket;
+    name;
+    config;
+    pathGenerator = null;
+    constructor(bucket, name, config) {
+        this.bucket = bucket;
+        this.name = name;
+        this.config = config;
+        const path = this.config.path;
+        if (path) {
+            if (typeof path === "function") {
+                this.pathGenerator = path;
+            }
+            else {
+                this.pathGenerator = this.createConfigBasedGenerator(path);
+            }
+        }
+    }
+    async handleUpload({ action, body, request, sessionId, }) {
+        try {
+            const req = parseReq(request);
+            switch (action) {
+                case "presign": {
+                    if (!("files" in body)) {
+                        throw UploadError.badRequest("Invalid presign body");
+                    }
+                    const presignBody = body;
+                    const rawInput = presignBody.input || {};
+                    const parser = this.config.input;
+                    let parsedInput;
+                    // TODO: error handling
+                    if (parser) {
+                        const parsed = parser.safeParse(rawInput);
+                        if (!parsed.success) {
+                            throw UploadError.badRequest(parsed.error.issues[0]?.message);
+                        }
+                        parsedInput = parsed.data;
+                    }
+                    const middleware = this.config.onBeforeUpload;
+                    const customMeta = await middleware?.({
+                        req: request,
+                        input: parsedInput,
+                        files: presignBody.files,
+                    });
+                    const metadata = {
+                        "x-ocel-path": req.path,
+                        "x-ocel-uploader": this.name,
+                        ...(customMeta
+                            ? { "x-ocel-metadata": JSON.stringify(customMeta) }
+                            : {}),
+                    };
+                    // TODO: validate files against uploader config (size, count, types, etc)
+                    this.validateFiles(presignBody.files, customMeta);
+                    const files = body.files.map((f) => {
+                        const name = slugify(f.name, { preserveCharacters: ["."] });
+                        return {
+                            ...f,
+                            key: this.pathGenerator?.({
+                                fileNameWithExt: name,
+                                metadata: customMeta,
+                                fileNameWithoutExt: name.replace(path.extname(name), ""),
+                                ext: path.extname(name),
+                            }) || name,
+                            disposition: "inline",
+                            metadata: {
+                                ...metadata,
+                                "x-ocel-original-filename": f.name,
+                            },
+                        };
+                    });
+                    const provider = this.getProvider();
+                    return provider.presign(files);
+                }
+                case "poll": {
+                    if (!sessionId) {
+                        throw UploadError.badRequest("sessionId is required for poll");
+                    }
+                    const result = await UploadSession.query
+                        .sessions({ sessionId })
+                        .go();
+                    const files = result.data.map((record) => {
+                        let parsedMeta = {};
+                        try {
+                            if (record.metadata) {
+                                parsedMeta = JSON.parse(record.metadata);
+                            }
+                        }
+                        catch {
+                            // ignore parse errors
+                        }
+                        return {
+                            fileKey: record.fileKey,
+                            status: record.status,
+                            file: record.status === "SUCCESS"
+                                ? {
+                                    path: record.fileKey,
+                                    contentDisposition: record.contentDisposition || "inline",
+                                    contentType: record.contentType,
+                                }
+                                : undefined,
+                            metadata: parsedMeta,
+                        };
+                    });
+                    const allComplete = files.every((f) => f.status === "SUCCESS" || f.status === "FAILED");
+                    return {
+                        files,
+                        completed: allComplete,
+                    };
+                }
+                case "callback": {
+                    // TODO: validate callback body
+                    if (!("metadata" in body)) {
+                        throw UploadError.badRequest("Invalid callback body");
+                    }
+                    const data = body;
+                    await this.config.onUploadComplete?.(data);
+                    return {
+                        type: "UPLOAD_COMPLETED",
+                        response: "ok",
+                    };
+                }
+                default:
+                    throw UploadError.badRequest(`Unhandled action type: ${action}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof UploadError) {
+                this.config.onUploadError?.({ error: err });
+                return {
+                    error: {
+                        message: err.message,
+                        code: err.code, // e.g. "FORBIDDEN"
+                        status: err.statusCode, // e.g. 403
+                    },
+                };
+            }
+            return {
+                error: {
+                    message: "Internal Server Error",
+                    code: "INTERNAL_SERVER_ERROR",
+                    status: 500,
+                },
+            };
+        }
+    }
+    startPolling(sessionId) {
+        const POLL_INTERVAL_MS = 1000;
+        const MAX_DURATION_MS = 10 * 60 * 1000; // 10 minutes
+        const startTime = Date.now();
+        const tick = async () => {
+            if (Date.now() - startTime > MAX_DURATION_MS) {
+                return true;
+            }
+            const result = await UploadSession.query
+                .sessions({ sessionId })
+                .go();
+            const allComplete = result.data.every((r) => r.status === "SUCCESS" || r.status === "FAILED");
+            if (!allComplete) {
+                return false;
+            }
+            // Session complete - invoke callbacks
+            for (const record of result.data) {
+                let parsedMeta = {};
+                try {
+                    if (record.metadata) {
+                        parsedMeta = JSON.parse(record.metadata);
+                    }
+                }
+                catch {
+                    // ignore
+                }
+                if (record.status === "SUCCESS") {
+                    await this.config.onUploadComplete?.({
+                        metadata: parsedMeta,
+                        file: {
+                            path: record.fileKey,
+                            contentDisposition: record.contentDisposition || "inline",
+                            contentType: record.contentType,
+                        },
+                    });
+                }
+                else if (record.status === "FAILED" && this.config.onUploadError) {
+                    this.config.onUploadError({
+                        error: new UploadError(`Upload failed for ${record.fileKey}`, 500, "UPLOAD_FAILED"),
+                    });
+                }
+            }
+            return true;
+        };
+        const intervalId = setInterval(async () => {
+            try {
+                const done = await tick();
+                if (done) {
+                    clearInterval(intervalId);
+                }
+            }
+            catch {
+                clearInterval(intervalId);
+            }
+        }, POLL_INTERVAL_MS);
+    }
+    getProvider() {
+        const bucket = this.bucket;
+        const bucketId = bucket.__name();
+        return {
+            presign: async (files) => {
+                const s3Client = new S3Client();
+                const sessionId = getNanoid(8);
+                const presignedFiles = await Promise.all(files.map(async (file) => {
+                    const metadataWithSession = {
+                        ...file.metadata,
+                        "x-ocel-session-id": sessionId,
+                    };
+                    await UploadSession.create({
+                        sessionId,
+                        bucketName: bucketId,
+                        fileKey: file.key,
+                        createdAt: new Date().toISOString(),
+                        status: "PENDING",
+                        contentType: file.mimeType,
+                        contentDisposition: file.disposition,
+                        fileSize: file.size,
+                        metadata: file.metadata
+                            ? JSON.stringify(file.metadata)
+                            : undefined,
+                    }).go();
+                    const url = await getSignedUrl(s3Client, new PutObjectCommand({
+                        Key: file.key,
+                        Bucket: bucketId,
+                        ContentType: file.mimeType,
+                        Metadata: metadataWithSession,
+                    }), { expiresIn: 3600 });
+                    return {
+                        url,
+                        key: file.key,
+                        name: file.name,
+                    };
+                }));
+                this.startPolling(sessionId);
+                return {
+                    files: presignedFiles,
+                    sessionId,
+                };
+            },
+        };
+    }
+    createConfigBasedGenerator(config) {
+        return (ctx) => {
+            let key = ctx.fileNameWithoutExt;
+            // random suffix
+            if (config.randomSuffix) {
+                key += `-${Math.random().toString(36).slice(2, 10)}`;
+            }
+            // static suffix
+            else if (config.suffix) {
+                key += `-${config.suffix}`;
+            }
+            // add extension
+            key += ctx.ext;
+            // prefix
+            if (config.prefix) {
+                return `${config.prefix.replace(/\/$/, "")}/${key}`;
+            }
+            return key;
+        };
+    }
+    validateFiles(files, metadata) {
+        const { accept, limits } = this.config;
+        if (limits?.maxFileCount !== undefined) {
+            const max = typeof limits.maxFileCount === "function"
+                ? limits.maxFileCount({ metadata })
+                : limits.maxFileCount;
+            if (files.length > max) {
+                throw UploadError.badRequest(`File limit exceeded. Maximum files allowed: ${max}.`);
+            }
+        }
+        if (limits?.minFileCount !== undefined) {
+            const min = typeof limits.minFileCount === "function"
+                ? limits.minFileCount({ metadata })
+                : limits.minFileCount;
+            if (files.length < min) {
+                throw UploadError.badRequest(`File limit not met. Minimum files required: ${min}.`);
+            }
+        }
+        // 2. Per-File Validation (Size and MIME Type)
+        for (const file of files) {
+            // MIME Type Validation
+            if (accept && accept.length > 0) {
+                const isAccepted = accept.some((allowedType) => {
+                    // Simple check for wildcards (*/*) and direct matches (image/png)
+                    if (allowedType.endsWith("/*")) {
+                        const typeGroup = allowedType.slice(0, -2);
+                        return file.mimeType.startsWith(typeGroup);
+                    }
+                    return file.mimeType === allowedType;
+                });
+                if (!isAccepted) {
+                    throw UploadError.badRequest(`File type not allowed: ${file.mimeType}. Must be one of: ${accept.join(", ")}.`);
+                }
+            }
+            // Max File Size Validation
+            if (limits?.maxFileSize !== undefined) {
+                const sizeValue = typeof limits.maxFileSize === "function"
+                    ? limits.maxFileSize({ metadata })
+                    : limits.maxFileSize;
+                const maxSizeInBytes = parseFileSize(sizeValue);
+                if (file.size > maxSizeInBytes) {
+                    // You might want to convert maxSize from bytes to KB/MB for a better error message
+                    throw UploadError.badRequest(`File size too large. Maximum size: ${maxSizeInBytes} bytes.`);
+                }
+            }
+        }
+    }
+}

package/dist/internal/db/index.d.ts

@@ -0,0 +1,68 @@
+import { Entity } from "electrodb";
+export declare const UploadSession: Entity<string, string, string, {
+    model: {
+        entity: string;
+        version: string;
+        service: string;
+    };
+    attributes: {
+        sessionId: {
+            type: "string";
+            required: true;
+        };
+        bucketName: {
+            type: "string";
+            required: true;
+        };
+        fileKey: {
+            type: "string";
+            required: true;
+        };
+        contentType: {
+            type: "string";
+            required: true;
+        };
+        contentDisposition: {
+            type: "string";
+            required: false;
+        };
+        fileSize: {
+            type: "number";
+            required: true;
+        };
+        createdAt: {
+            type: "string";
+            required: true;
+            default: () => string;
+        };
+        updatedAt: {
+            type: "string";
+            required: true;
+            default: () => string;
+            set: () => string;
+        };
+        status: {
+            type: readonly ["PENDING", "SUCCESS", "FAILED"];
+            required: true;
+            default: string;
+        };
+        metadata: {
+            type: "string";
+            required: false;
+        };
+    };
+    indexes: {
+        sessions: {
+            pk: {
+                field: string;
+                composite: "sessionId"[];
+                template: string;
+            };
+            sk: {
+                field: string;
+                composite: ("bucketName" | "fileKey")[];
+                template: string;
+            };
+        };
+    };
+}>;

package/dist/internal/db/index.js

@@ -0,0 +1,73 @@
+import { Entity } from "electrodb";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+const client = new DynamoDBClient({});
+export const UploadSession = new Entity({
+    model: {
+        entity: "upload-session",
+        version: "1",
+        service: "blob",
+    },
+    attributes: {
+        sessionId: {
+            type: "string",
+            required: true,
+        },
+        bucketName: {
+            type: "string",
+            required: true,
+        },
+        fileKey: {
+            type: "string",
+            required: true,
+        },
+        contentType: {
+            type: "string",
+            required: true,
+        },
+        contentDisposition: {
+            type: "string",
+            required: false,
+        },
+        fileSize: {
+            type: "number",
+            required: true,
+        },
+        createdAt: {
+            type: "string",
+            required: true,
+            default: () => new Date().toISOString(),
+        },
+        updatedAt: {
+            type: "string",
+            required: true,
+            default: () => new Date().toISOString(),
+            set: () => new Date().toISOString(),
+        },
+        status: {
+            type: ["PENDING", "SUCCESS", "FAILED"],
+            required: true,
+            default: "PENDING",
+        },
+        metadata: {
+            type: "string",
+            required: false,
+        },
+    },
+    indexes: {
+        sessions: {
+            pk: {
+                field: "pk",
+                composite: ["sessionId"],
+                template: "SESSION#${sessionId}",
+            },
+            sk: {
+                field: "sk",
+                composite: ["bucketName", "fileKey"],
+                template: "FILE#${bucketName}#${fileKey}",
+            },
+        },
+    },
+}, {
+    client,
+    table: "OcelTable", // required for all ocel logic
+});

package/dist/lambda/index.d.ts

@@ -0,0 +1,2 @@
+import { Lambda, type LambdaConfig, type TriggerMap } from "./lambda";
+export declare function lambda<T extends keyof TriggerMap>(id: string, config: LambdaConfig<T>): Lambda<T>;

package/dist/lambda/index.js

@@ -0,0 +1,4 @@
+import { Lambda } from "./lambda";
+export function lambda(id, config) {
+    return new Lambda(id, config);
+}

package/dist/lambda/integrations/express.d.ts

@@ -0,0 +1,3 @@
+import { Lambda, type LambdaConfig, type TriggerMap } from "../lambda";
+import type { Express } from "express";
+export declare function lambda<T extends keyof TriggerMap>(id: string, app: Express, config?: Omit<LambdaConfig<T>, "trigger" | "handler">): Lambda<T>;

package/dist/lambda/integrations/express.js

@@ -0,0 +1,13 @@
+import { Lambda, } from "../lambda";
+import sls from "serverless-http";
+export function lambda(id, app, config) {
+    const handler = sls(app);
+    return new Lambda(id, {
+        ...config,
+        handler: handler,
+        trigger: {
+            type: "url",
+            config: {},
+        },
+    });
+}

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

@@ -0,0 +1,3 @@
+import { Lambda, type LambdaConfig, type TriggerMap } from "../lambda";
+import type { Hono } from "hono";
+export declare function lambda<T extends keyof TriggerMap>(id: string, app: Hono, config?: Omit<LambdaConfig<T>, "trigger" | "handler">): Lambda<T>;

package/dist/lambda/integrations/hono.js

@@ -0,0 +1,13 @@
+import { Lambda, } from "../lambda";
+import { handle } from "hono/aws-lambda";
+export function lambda(id, app, config) {
+    const handler = handle(app);
+    return new Lambda(id, {
+        ...config,
+        handler: handler,
+        trigger: {
+            type: "url",
+            config: {},
+        },
+    });
+}

package/dist/lambda/lambda.d.ts

@@ -0,0 +1,43 @@
+import type { Component } from "../utils/component";
+import type { Context, APIGatewayEvent, S3Event, LambdaFunctionURLEvent } from "aws-lambda";
+export type TriggerMap = {
+    s3: {
+        bucket: string;
+        events: string[];
+    };
+    cron: {
+        schedule: string;
+    };
+    url: {
+        streaming?: boolean;
+    };
+    api: {
+        id?: string;
+        path: string;
+        method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "*";
+    };
+};
+export type TriggerUnion = {
+    [K in keyof TriggerMap]: {
+        type: K;
+        config: TriggerMap[K];
+    };
+}[keyof TriggerMap];
+export type LambdaHandlerOutput<T extends keyof TriggerMap> = T extends "api" ? {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+} : any;
+export type LambdaEvent<T extends keyof TriggerMap> = T extends "s3" ? S3Event : T extends "api" ? APIGatewayEvent : T extends "url" ? LambdaFunctionURLEvent : any;
+export interface LambdaConfig<T extends keyof TriggerMap> {
+    handler: (event: LambdaEvent<T>, context: Context) => Promise<LambdaHandlerOutput<T>> | LambdaHandlerOutput<T>;
+    trigger: Extract<TriggerUnion, {
+        type: T;
+    }>;
+    link?: Component[];
+}
+export declare class Lambda<T extends keyof TriggerMap> implements Component {
+    id: string;
+    constructor(id: string, config: LambdaConfig<T>);
+    __id(): string;
+}