@nebutra/uploads 0.1.0 → 0.1.2

package/dist/providers/s3.js

@@ -0,0 +1,260 @@
+/**
+ * S3/R2 upload provider
+ * Supports both AWS S3 and Cloudflare R2 (S3-compatible)
+ */
+import { randomUUID } from "node:crypto";
+import { AbortMultipartUploadCommand, CompleteMultipartUploadCommand, CreateMultipartUploadCommand, DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client, UploadPartCommand, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { logger } from "@nebutra/logger";
+export class S3UploadProvider {
+    client;
+    config;
+    uploadTracking;
+    constructor(config) {
+        this.uploadTracking = new Map();
+        this.config = {
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            region: config.region,
+            endpoint: config.endpoint,
+            publicUrl: config.publicUrl ?? "https://cdn.example.com",
+            forcePathStyle: config.forcePathStyle ?? false,
+        };
+        this.client = new S3Client({
+            region: this.config.region,
+            ...(this.config.endpoint !== undefined ? { endpoint: this.config.endpoint } : {}),
+            credentials: {
+                accessKeyId: this.config.accessKeyId,
+                secretAccessKey: this.config.secretAccessKey,
+            },
+            forcePathStyle: this.config.forcePathStyle,
+        });
+        logger.info("S3 upload provider initialized", { provider: "s3", region: this.config.region });
+    }
+    /**
+     * Build object key with tenant prefix
+     */
+    buildKey(target) {
+        const id = randomUUID();
+        if (target.tenantId) {
+            return `${target.tenantId}/${id}/${target.key.split("/").pop()}`;
+        }
+        return `${id}/${target.key.split("/").pop()}`;
+    }
+    /**
+     * Generate presigned PUT URL for simple uploads
+     */
+    async createPresignedUpload(target) {
+        const key = this.buildKey(target);
+        const expiresIn = 3600; // 1 hour
+        const command = new PutObjectCommand({
+            Bucket: target.bucket,
+            Key: key,
+            ContentType: target.contentType,
+            Metadata: target.metadata,
+            ...(target.acl !== undefined ? { ACL: target.acl } : {}),
+        });
+        const url = await getSignedUrl(this.client, command, { expiresIn });
+        logger.debug("Presigned upload URL generated", { key, bucket: target.bucket });
+        return {
+            url,
+            method: "PUT",
+            headers: {
+                "Content-Type": target.contentType,
+            },
+            expiresAt: new Date(Date.now() + expiresIn * 1000),
+            uploadId: key,
+        };
+    }
+    /**
+     * Initiate multipart upload for large files
+     */
+    async createMultipartUpload(target, partCount) {
+        const key = this.buildKey(target);
+        const createCmd = new CreateMultipartUploadCommand({
+            Bucket: target.bucket,
+            Key: key,
+            ContentType: target.contentType,
+            Metadata: target.metadata,
+            ...(target.acl !== undefined ? { ACL: target.acl } : {}),
+        });
+        const response = await this.client.send(createCmd);
+        if (!response.UploadId) {
+            throw new Error("Failed to initiate multipart upload: no UploadId returned");
+        }
+        // Track upload for completion
+        this.uploadTracking.set(response.UploadId, {
+            bucket: target.bucket,
+            key,
+        });
+        // Generate presigned URLs for each part
+        const uploadId = response.UploadId;
+        const parts = await Promise.all(Array.from({ length: partCount }, async (_, i) => {
+            const partNumber = i + 1;
+            const uploadPartCmd = new UploadPartCommand({
+                Bucket: target.bucket,
+                Key: key,
+                PartNumber: partNumber,
+                UploadId: uploadId,
+            });
+            const presignedUrl = await getSignedUrl(this.client, uploadPartCmd, {
+                expiresIn: 3600,
+            });
+            return {
+                partNumber,
+                presignedUrl,
+            };
+        }));
+        const completeUrl = await this.generateCompleteUrl(target.bucket, key, uploadId);
+        logger.info("Multipart upload initiated", {
+            key,
+            bucket: target.bucket,
+            uploadId,
+            partCount,
+        });
+        return {
+            uploadId,
+            key,
+            bucket: target.bucket,
+            parts,
+            completeUrl,
+        };
+    }
+    /**
+     * Generate a presigned URL for the complete multipart upload operation
+     */
+    async generateCompleteUrl(bucket, key, uploadId) {
+        // This is a simplified implementation
+        // In production, you'd implement a callback endpoint on your server
+        return `https://api.example.com/uploads/complete?bucket=${bucket}&key=${encodeURIComponent(key)}&uploadId=${uploadId}`;
+    }
+    /**
+     * Complete a multipart upload
+     */
+    async completeMultipartUpload(uploadId, key, parts) {
+        const uploadInfo = this.uploadTracking.get(uploadId);
+        if (!uploadInfo) {
+            throw new Error(`Upload not found or already completed: ${uploadId}`);
+        }
+        const { bucket } = uploadInfo;
+        this.uploadTracking.delete(uploadId);
+        const completedParts = parts.map((part) => ({
+            ETag: part.etag,
+            PartNumber: part.partNumber,
+        }));
+        const command = new CompleteMultipartUploadCommand({
+            Bucket: bucket,
+            Key: key,
+            UploadId: uploadId,
+            MultipartUpload: {
+                Parts: completedParts,
+            },
+        });
+        const response = await this.client.send(command);
+        const url = this.generateDownloadUrl(key);
+        logger.info("Multipart upload completed", { key, bucket, uploadId, etag: response.ETag });
+        return {
+            key,
+            bucket,
+            url,
+            size: 0, // S3 doesn't provide size in complete response
+            contentType: "application/octet-stream",
+            ...(response.ETag !== undefined ? { etag: response.ETag } : {}),
+        };
+    }
+    /**
+     * Abort a multipart upload
+     */
+    async abortMultipartUpload(uploadId, key) {
+        const uploadInfo = this.uploadTracking.get(uploadId);
+        const bucket = uploadInfo?.bucket ?? "unknown";
+        const command = new AbortMultipartUploadCommand({
+            Bucket: bucket,
+            Key: key,
+            UploadId: uploadId,
+        });
+        await this.client.send(command);
+        this.uploadTracking.delete(uploadId);
+        logger.info("Multipart upload aborted", { key, bucket, uploadId });
+    }
+    /**
+     * Get Tus protocol endpoint configuration
+     */
+    async getTusEndpoint(target) {
+        const key = this.buildKey(target);
+        // Initiate multipart upload for Tus
+        const createCmd = new CreateMultipartUploadCommand({
+            Bucket: target.bucket,
+            Key: key,
+            ContentType: target.contentType,
+        });
+        const response = await this.client.send(createCmd);
+        if (!response.UploadId) {
+            throw new Error("Failed to create Tus upload session");
+        }
+        return {
+            endpoint: `${this.config.endpoint ?? "https://s3.amazonaws.com"}/${target.bucket}/${key}?uploadId=${response.UploadId}`,
+            chunkSize: 5 * 1024 * 1024, // 5MB chunks
+            retryDelays: [0, 1000, 3000, 5000],
+            metadata: {
+                ...target.metadata,
+                filename: target.key,
+                uploadId: response.UploadId,
+            },
+        };
+    }
+    /**
+     * Delete a file from S3
+     */
+    async deleteFile(bucket, key) {
+        const command = new DeleteObjectCommand({
+            Bucket: bucket,
+            Key: key,
+        });
+        await this.client.send(command);
+        logger.debug("File deleted from S3", { key, bucket });
+    }
+    /**
+     * Generate a presigned download URL
+     */
+    async getDownloadUrl(bucket, key, expiresInSec = 3600) {
+        const command = new GetObjectCommand({
+            Bucket: bucket,
+            Key: key,
+        });
+        return getSignedUrl(this.client, command, { expiresIn: expiresInSec });
+    }
+    /**
+     * Generate public CDN URL for assets
+     */
+    generateDownloadUrl(key) {
+        return `${this.config.publicUrl}/${key}`;
+    }
+    /**
+     * Clean up resources
+     */
+    async close() {
+        this.uploadTracking.clear();
+        this.client.destroy();
+        logger.debug("S3 upload provider closed");
+    }
+}
+/**
+ * Create S3 provider from environment variables
+ */
+export function createS3Provider() {
+    const endpoint = process.env.S3_ENDPOINT;
+    const publicUrl = process.env.S3_PUBLIC_URL ?? process.env.R2_PUBLIC_URL;
+    const config = {
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? process.env.R2_ACCESS_KEY_ID ?? "",
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? process.env.R2_SECRET_ACCESS_KEY ?? "",
+        region: process.env.AWS_REGION ?? "auto",
+        ...(endpoint !== undefined ? { endpoint } : {}),
+        ...(publicUrl !== undefined ? { publicUrl } : {}),
+        forcePathStyle: process.env.S3_FORCE_PATH_STYLE === "true",
+    };
+    if (!config.accessKeyId || !config.secretAccessKey) {
+        throw new Error("AWS credentials not found. Set AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or R2_ACCESS_KEY_ID/R2_SECRET_ACCESS_KEY");
+    }
+    return new S3UploadProvider(config);
+}

package/dist/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Core types for large file uploads
+ */
+export type UploadProviderType = "s3" | "blob" | "local";
+export type UploadMethod = "PUT" | "POST";
+export type ACLType = "private" | "public-read";
+/**
+ * Target location and metadata for an upload
+ */
+export interface UploadTarget {
+    bucket: string;
+    key: string;
+    contentType: string;
+    maxSize?: number;
+    metadata?: Record<string, string>;
+    tenantId?: string;
+    acl?: ACLType;
+}
+/**
+ * Presigned upload response for simple PUT uploads
+ */
+export interface PresignedUpload {
+    url: string;
+    method: UploadMethod;
+    headers: Record<string, string>;
+    expiresAt: Date;
+    uploadId?: string;
+}
+/**
+ * Part configuration for multipart upload
+ */
+export interface UploadPart {
+    partNumber: number;
+    presignedUrl: string;
+}
+/**
+ * Multipart upload response
+ */
+export interface MultipartUpload {
+    uploadId: string;
+    key: string;
+    bucket: string;
+    parts: UploadPart[];
+    completeUrl: string;
+}
+/**
+ * Tus protocol upload configuration
+ */
+export interface TusUploadConfig {
+    endpoint: string;
+    chunkSize: number;
+    retryDelays: number[];
+    metadata?: Record<string, string>;
+}
+/**
+ * Completed upload response
+ */
+export interface UploadComplete {
+    key: string;
+    bucket: string;
+    url: string;
+    size: number;
+    contentType: string;
+    etag?: string;
+    tenantId?: string;
+}
+/**
+ * Part metadata for completing multipart upload
+ */
+export interface CompletePart {
+    partNumber: number;
+    etag: string;
+}
+/**
+ * Upload provider interface
+ */
+export interface UploadProvider {
+    /**
+     * Generate a presigned URL for direct client upload
+     */
+    createPresignedUpload(target: UploadTarget): Promise<PresignedUpload>;
+    /**
+     * Initiate a multipart upload and return part configurations
+     */
+    createMultipartUpload(target: UploadTarget, partCount: number): Promise<MultipartUpload>;
+    /**
+     * Complete a multipart upload after all parts are uploaded
+     */
+    completeMultipartUpload(uploadId: string, key: string, parts: CompletePart[]): Promise<UploadComplete>;
+    /**
+     * Abort/cancel a multipart upload
+     */
+    abortMultipartUpload(uploadId: string, key: string): Promise<void>;
+    /**
+     * Get Tus protocol endpoint configuration for resumable uploads
+     */
+    getTusEndpoint(target: UploadTarget): Promise<TusUploadConfig>;
+    /**
+     * Delete a file from storage
+     */
+    deleteFile(bucket: string, key: string): Promise<void>;
+    /**
+     * Generate a presigned download URL
+     */
+    getDownloadUrl(bucket: string, key: string, expiresInSec?: number): Promise<string>;
+    /**
+     * Clean up resources
+     */
+    close(): Promise<void>;
+}
+/**
+ * S3 provider configuration
+ */
+export interface S3ProviderConfig {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    endpoint?: string;
+    publicUrl?: string;
+    forcePathStyle?: boolean;
+}
+/**
+ * Local filesystem provider configuration
+ */
+export interface LocalProviderConfig {
+    uploadDir: string;
+    httpBaseUrl: string;
+    maxConcurrency?: number;
+}
+/**
+ * Factory configuration for auto-detection
+ */
+export interface ProviderConfig {
+    type?: UploadProviderType;
+    s3?: S3ProviderConfig;
+    local?: LocalProviderConfig;
+}
+/**
+ * Validation rules for uploads
+ */
+export interface ValidationRules {
+    maxSize: number;
+    allowedTypes: string[];
+    blockedExtensions: string[];
+    imageDimensions?: {
+        maxWidth: number;
+        maxHeight: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core types for large file uploads
+ */
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Upload validation utilities
+ */
+import type { ValidationRules } from "./types";
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+    code: "size_exceeded" | "type_not_allowed" | "extension_blocked" | "invalid_image";
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Validate file before upload
+ */
+export declare function validateUpload(filename: string, fileSize: number, mimeType: string, rules?: Partial<ValidationRules>): ValidationError | null;
+/**
+ * Validate image dimensions
+ */
+export declare function validateImageDimensions(dimensions: {
+    width: number;
+    height: number;
+}, maxDimensions?: {
+    maxWidth: number;
+    maxHeight: number;
+}): ValidationError | null;
+/**
+ * Create validation rules for images
+ */
+export declare function createImageValidationRules(options?: {
+    maxSize?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}): ValidationRules;
+/**
+ * Create validation rules for documents
+ */
+export declare function createDocumentValidationRules(options?: {
+    maxSize?: number;
+}): ValidationRules;
+/**
+ * Log validation error
+ */
+export declare function logValidationError(error: ValidationError, filename: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAqC/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,eAAe,GAAG,kBAAkB,GAAG,mBAAmB,GAAG,eAAe,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,OAAO,CAAC,eAAe,CAAM,GACnC,eAAe,GAAG,IAAI,CAgDxB;AAUD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC7C,aAAa,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACtD,eAAe,GAAG,IAAI,CA8BxB;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,eAAe,CAUlB;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,eAAe,CAc7F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMjF"}

package/dist/validation.js

@@ -0,0 +1,167 @@
+/**
+ * Upload validation utilities
+ */
+import { logger } from "@nebutra/logger";
+import { z } from "zod";
+const DEFAULT_RULES = {
+    maxSize: 100 * 1024 * 1024, // 100MB default
+    allowedTypes: ["*/*"], // Allow all by default
+    blockedExtensions: [
+        // Executable files
+        ".exe",
+        ".bat",
+        ".cmd",
+        ".com",
+        ".pif",
+        ".scr",
+        ".vbs",
+        ".js", // Note: JavaScript can be dangerous depending on context
+        ".jar",
+        ".zip", // Often used to distribute executables
+        ".rar",
+        ".7z",
+        ".tar",
+        ".gz",
+        // Scripts
+        ".sh",
+        ".bash",
+        ".zsh",
+        ".ksh",
+        ".csh",
+        ".ps1",
+        ".psm1",
+        ".psd1",
+        ".msi",
+        ".dll",
+        ".so",
+        ".dylib",
+    ],
+};
+/**
+ * Validate file before upload
+ */
+export function validateUpload(filename, fileSize, mimeType, rules = {}) {
+    const mergedRules = {
+        ...DEFAULT_RULES,
+        ...rules,
+    };
+    // Check file size
+    if (fileSize > mergedRules.maxSize) {
+        const maxSizeMB = Math.round(mergedRules.maxSize / (1024 * 1024));
+        const fileSizeMB = Math.round(fileSize / (1024 * 1024));
+        return {
+            code: "size_exceeded",
+            message: `File size (${fileSizeMB}MB) exceeds maximum allowed size (${maxSizeMB}MB)`,
+            details: { maxSize: mergedRules.maxSize, fileSize },
+        };
+    }
+    // Check MIME type
+    if (mergedRules.allowedTypes.length > 0 && !mergedRules.allowedTypes.includes("*/*")) {
+        const isAllowed = mergedRules.allowedTypes.some((type) => {
+            if (type.endsWith("/*")) {
+                const [category] = type.split("/");
+                const [fileMimeCategory] = mimeType.split("/");
+                return fileMimeCategory === category;
+            }
+            return type === mimeType;
+        });
+        if (!isAllowed) {
+            return {
+                code: "type_not_allowed",
+                message: `MIME type '${mimeType}' is not allowed. Allowed types: ${mergedRules.allowedTypes.join(", ")}`,
+                details: { mimeType, allowedTypes: mergedRules.allowedTypes },
+            };
+        }
+    }
+    // Check file extension
+    const ext = filename.toLowerCase().split(".").pop();
+    if (ext && mergedRules.blockedExtensions.includes(`.${ext}`)) {
+        return {
+            code: "extension_blocked",
+            message: `File extension '.${ext}' is not allowed`,
+            details: { extension: ext },
+        };
+    }
+    return null;
+}
+/**
+ * Image validation schema
+ */
+const ImageDimensionsSchema = z.object({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+});
+/**
+ * Validate image dimensions
+ */
+export function validateImageDimensions(dimensions, maxDimensions) {
+    try {
+        ImageDimensionsSchema.parse(dimensions);
+    }
+    catch (error) {
+        return {
+            code: "invalid_image",
+            message: "Invalid image dimensions",
+            details: { error: String(error) },
+        };
+    }
+    if (maxDimensions) {
+        if (dimensions.width > maxDimensions.maxWidth) {
+            return {
+                code: "invalid_image",
+                message: `Image width (${dimensions.width}px) exceeds maximum (${maxDimensions.maxWidth}px)`,
+                details: { width: dimensions.width, maxWidth: maxDimensions.maxWidth },
+            };
+        }
+        if (dimensions.height > maxDimensions.maxHeight) {
+            return {
+                code: "invalid_image",
+                message: `Image height (${dimensions.height}px) exceeds maximum (${maxDimensions.maxHeight}px)`,
+                details: { height: dimensions.height, maxHeight: maxDimensions.maxHeight },
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Create validation rules for images
+ */
+export function createImageValidationRules(options) {
+    return {
+        maxSize: options?.maxSize ?? 10 * 1024 * 1024, // 10MB default for images
+        allowedTypes: ["image/jpeg", "image/png", "image/webp", "image/gif", "image/svg+xml"],
+        blockedExtensions: DEFAULT_RULES.blockedExtensions,
+        imageDimensions: {
+            maxWidth: options?.maxWidth ?? 4096,
+            maxHeight: options?.maxHeight ?? 4096,
+        },
+    };
+}
+/**
+ * Create validation rules for documents
+ */
+export function createDocumentValidationRules(options) {
+    return {
+        maxSize: options?.maxSize ?? 50 * 1024 * 1024, // 50MB default for documents
+        allowedTypes: [
+            "application/pdf",
+            "application/msword",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            "application/vnd.ms-excel",
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            "text/plain",
+            "text/csv",
+        ],
+        blockedExtensions: DEFAULT_RULES.blockedExtensions,
+    };
+}
+/**
+ * Log validation error
+ */
+export function logValidationError(error, filename) {
+    logger.warn(`Upload validation failed: ${error.message}`, {
+        code: error.code,
+        filename,
+        details: error.details,
+    });
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nebutra/uploads",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "status": "foundation",
@@ -43,7 +43,7 @@
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/s3-request-presigner": "^3.700.0",
     "zod": "^4.3.6",
-    "@nebutra/logger": "0.1.0"
+    "@nebutra/logger": "0.1.2"
   },
   "peerDependencies": {
     "@vercel/blob": ">=0.23.0",