@nebutra/uploads 0.1.0 → 0.1.1

package/dist/factory.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Upload provider factory with auto-detection
+ */
+import type { ProviderConfig, UploadProvider, UploadProviderType } from "./types";
+/**
+ * Create an upload provider with auto-detection
+ */
+export declare function createUploadProvider(config?: ProviderConfig): UploadProvider;
+/**
+ * Get or create singleton instance
+ */
+export declare function getUploadProvider(config?: ProviderConfig): Promise<UploadProvider>;
+/**
+ * Reset singleton instance (for testing)
+ */
+export declare function resetUploadProvider(): void;
+/**
+ * Determine which provider is active
+ */
+export declare function getActiveProviderType(): UploadProviderType;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAIlF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,cAAc,CAM5E;AAkFD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAOxF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAO1C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAyB1D"}

package/dist/factory.js

@@ -0,0 +1,129 @@
+/**
+ * Upload provider factory with auto-detection
+ */
+import { logger } from "@nebutra/logger";
+import { createVercelBlobProvider, VercelBlobProvider } from "./providers/blob";
+import { createLocalProvider, LocalUploadProvider } from "./providers/local";
+import { createS3Provider, S3UploadProvider } from "./providers/s3";
+let instance = null;
+/**
+ * Create an upload provider with auto-detection
+ */
+export function createUploadProvider(config) {
+    if (config?.type) {
+        return createUploadProviderByType(config.type, config);
+    }
+    return autoDetectProvider(config);
+}
+/**
+ * Create provider by explicit type
+ */
+function createUploadProviderByType(type, config) {
+    if (type === "s3") {
+        if (!config?.s3) {
+            return createS3Provider();
+        }
+        return new S3UploadProvider(config.s3);
+    }
+    if (type === "blob") {
+        return createVercelBlobProvider();
+    }
+    if (type === "local") {
+        if (!config?.local) {
+            return createLocalProvider();
+        }
+        return new LocalUploadProvider(config.local);
+    }
+    throw new Error(`Unknown upload provider type: ${type}`);
+}
+/**
+ * Auto-detect provider based on environment
+ */
+function autoDetectProvider(config) {
+    // Priority 1: Check explicit UPLOAD_PROVIDER
+    const explicitProvider = process.env.UPLOAD_PROVIDER;
+    if (explicitProvider) {
+        logger.info("Using explicit upload provider", { provider: explicitProvider });
+        return createUploadProviderByType(explicitProvider, config);
+    }
+    // Priority 2: Check for Vercel Blob token (zero-config on Vercel)
+    if (process.env.BLOB_READ_WRITE_TOKEN) {
+        logger.info("Auto-detected Vercel Blob token, using Blob provider");
+        return createVercelBlobProvider();
+    }
+    // Priority 3: Check for R2 credentials
+    if (process.env.R2_ACCESS_KEY_ID || process.env.R2_SECRET_ACCESS_KEY) {
+        logger.info("Auto-detected R2 credentials, using S3 provider");
+        return new S3UploadProvider({
+            accessKeyId: process.env.R2_ACCESS_KEY_ID || "",
+            secretAccessKey: process.env.R2_SECRET_ACCESS_KEY || "",
+            region: "auto",
+            ...(process.env.R2_ENDPOINT !== undefined ? { endpoint: process.env.R2_ENDPOINT } : {}),
+            ...(process.env.R2_PUBLIC_URL !== undefined ? { publicUrl: process.env.R2_PUBLIC_URL } : {}),
+        });
+    }
+    // Priority 3: Check for AWS S3 credentials
+    if (process.env.AWS_ACCESS_KEY_ID || process.env.AWS_SECRET_ACCESS_KEY) {
+        logger.info("Auto-detected AWS credentials, using S3 provider");
+        return createS3Provider();
+    }
+    // Priority 4: Check for custom S3 endpoint (Minio, etc.)
+    if (process.env.S3_ENDPOINT) {
+        logger.info("Using custom S3 endpoint", { endpoint: process.env.S3_ENDPOINT });
+        return new S3UploadProvider({
+            accessKeyId: process.env.AWS_ACCESS_KEY_ID || process.env.S3_ACCESS_KEY_ID || "",
+            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || process.env.S3_SECRET_ACCESS_KEY || "",
+            region: process.env.AWS_REGION || "us-east-1",
+            ...(process.env.S3_ENDPOINT !== undefined ? { endpoint: process.env.S3_ENDPOINT } : {}),
+            ...(process.env.S3_PUBLIC_URL !== undefined ? { publicUrl: process.env.S3_PUBLIC_URL } : {}),
+        });
+    }
+    // Fallback: Local filesystem
+    logger.info("No cloud credentials found, using local filesystem provider");
+    return createLocalProvider();
+}
+/**
+ * Get or create singleton instance
+ */
+export async function getUploadProvider(config) {
+    if (instance) {
+        return instance;
+    }
+    instance = createUploadProvider(config);
+    return instance;
+}
+/**
+ * Reset singleton instance (for testing)
+ */
+export function resetUploadProvider() {
+    if (instance) {
+        instance.close().catch((error) => {
+            logger.warn("Failed to close upload provider", { error });
+        });
+    }
+    instance = null;
+}
+/**
+ * Determine which provider is active
+ */
+export function getActiveProviderType() {
+    if (instance instanceof S3UploadProvider) {
+        return "s3";
+    }
+    if (instance instanceof VercelBlobProvider) {
+        return "blob";
+    }
+    if (instance instanceof LocalUploadProvider) {
+        return "local";
+    }
+    if (process.env.UPLOAD_PROVIDER === "blob" || process.env.BLOB_READ_WRITE_TOKEN) {
+        return "blob";
+    }
+    if (process.env.UPLOAD_PROVIDER === "s3" ||
+        process.env.R2_ACCESS_KEY_ID ||
+        process.env.AWS_ACCESS_KEY_ID ||
+        process.env.S3_ENDPOINT) {
+        return "s3";
+    }
+    return "local";
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @nebutra/uploads — Large file upload service
+ * Handles presigned, multipart, and Tus protocol uploads
+ */
+export { createUploadProvider, getActiveProviderType, getUploadProvider, resetUploadProvider, } from "./factory";
+export { createVercelBlobProvider, VercelBlobProvider } from "./providers/blob";
+export { createLocalProvider, LocalUploadProvider } from "./providers/local";
+export { createS3Provider, S3UploadProvider } from "./providers/s3";
+export type { ACLType, CompletePart, LocalProviderConfig, MultipartUpload, PresignedUpload, ProviderConfig, S3ProviderConfig, TusUploadConfig, UploadComplete, UploadMethod, UploadPart, UploadProvider, UploadProviderType, UploadTarget, ValidationRules, } from "./types";
+export { createDocumentValidationRules, createImageValidationRules, logValidationError, type ValidationError, validateImageDimensions, validateUpload, } from "./validation";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEpE,YAAY,EACV,OAAO,EACP,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,kBAAkB,EAClB,KAAK,eAAe,EACpB,uBAAuB,EACvB,cAAc,GACf,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @nebutra/uploads — Large file upload service
+ * Handles presigned, multipart, and Tus protocol uploads
+ */
+// Factory
+export { createUploadProvider, getActiveProviderType, getUploadProvider, resetUploadProvider, } from "./factory";
+// Providers
+export { createVercelBlobProvider, VercelBlobProvider } from "./providers/blob";
+export { createLocalProvider, LocalUploadProvider } from "./providers/local";
+export { createS3Provider, S3UploadProvider } from "./providers/s3";
+// Validation
+export { createDocumentValidationRules, createImageValidationRules, logValidationError, validateImageDimensions, validateUpload, } from "./validation";

package/dist/providers/blob.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Vercel Blob upload provider — zero-config file uploads on Vercel.
+ *
+ * Uses @vercel/blob for server-side uploads with public URLs.
+ * Requires BLOB_READ_WRITE_TOKEN env var (auto-provisioned on Vercel).
+ *
+ * Note: Vercel Blob doesn't support true multipart uploads or Tus protocol.
+ * For files > 500MB, use the S3 provider instead.
+ */
+import type { CompletePart, MultipartUpload, PresignedUpload, TusUploadConfig, UploadComplete, UploadProvider, UploadTarget } from "../types";
+export interface VercelBlobConfig {
+    token?: string;
+}
+export declare class VercelBlobProvider implements UploadProvider {
+    private token;
+    constructor(config?: VercelBlobConfig);
+    private buildPathname;
+    createPresignedUpload(target: UploadTarget): Promise<PresignedUpload>;
+    createMultipartUpload(target: UploadTarget, _partCount: number): Promise<MultipartUpload>;
+    completeMultipartUpload(_uploadId: string, key: string, _parts: CompletePart[]): Promise<UploadComplete>;
+    abortMultipartUpload(_uploadId: string, key: string): Promise<void>;
+    getTusEndpoint(_target: UploadTarget): Promise<TusUploadConfig>;
+    deleteFile(_bucket: string, key: string): Promise<void>;
+    getDownloadUrl(_bucket: string, key: string, _expiresInSec?: number): Promise<string>;
+    close(): Promise<void>;
+}
+export declare function createVercelBlobProvider(config?: VercelBlobConfig): VercelBlobProvider;
+//# sourceMappingURL=blob.d.ts.map

package/dist/providers/blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../../src/providers/blob.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,YAAY,EACb,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,GAAE,gBAAqB;IAIzC,OAAO,CAAC,aAAa;IAKf,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAyBrE,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAazF,uBAAuB,CAC3B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EAAE,GACrB,OAAO,CAAC,cAAc,CAAC;IAWpB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnE,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAM/D,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvD,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQrF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,kBAAkB,CAEtF"}

package/dist/providers/blob.js

@@ -0,0 +1,88 @@
+/**
+ * Vercel Blob upload provider — zero-config file uploads on Vercel.
+ *
+ * Uses @vercel/blob for server-side uploads with public URLs.
+ * Requires BLOB_READ_WRITE_TOKEN env var (auto-provisioned on Vercel).
+ *
+ * Note: Vercel Blob doesn't support true multipart uploads or Tus protocol.
+ * For files > 500MB, use the S3 provider instead.
+ */
+export class VercelBlobProvider {
+    token;
+    constructor(config = {}) {
+        this.token = config.token ?? process.env.BLOB_READ_WRITE_TOKEN ?? "";
+    }
+    buildPathname(target) {
+        const prefix = target.tenantId ? `${target.tenantId}/` : "";
+        return `${prefix}${target.key}`;
+    }
+    async createPresignedUpload(target) {
+        // Vercel Blob uses server-side put() — we generate a URL that the client
+        // can PUT to via the handleUpload client helper, or we return the blob URL
+        // after server-side upload.
+        const blob = await import("@vercel/blob");
+        const pathname = this.buildPathname(target);
+        const result = await blob.put(pathname, "", {
+            access: "public",
+            contentType: target.contentType,
+            token: this.token,
+            addRandomSuffix: true,
+        });
+        return {
+            url: result.url,
+            method: "PUT",
+            headers: {
+                "Content-Type": target.contentType,
+                "x-vercel-blob-token": this.token,
+            },
+            expiresAt: new Date(Date.now() + 3600 * 1000), // 1 hour
+        };
+    }
+    async createMultipartUpload(target, _partCount) {
+        // Vercel Blob handles large files internally — no client-side multipart needed
+        // We simulate the interface for compatibility
+        const presigned = await this.createPresignedUpload(target);
+        return {
+            uploadId: `blob_${Date.now()}`,
+            key: this.buildPathname(target),
+            bucket: target.bucket,
+            parts: [{ partNumber: 1, presignedUrl: presigned.url }],
+            completeUrl: presigned.url,
+        };
+    }
+    async completeMultipartUpload(_uploadId, key, _parts) {
+        // Vercel Blob uploads are atomic — no completion step needed
+        return {
+            key,
+            bucket: "vercel-blob",
+            url: `https://blob.vercel-storage.com/${key}`,
+            size: 0,
+            contentType: "application/octet-stream",
+        };
+    }
+    async abortMultipartUpload(_uploadId, key) {
+        // Clean up the blob if partially uploaded
+        await this.deleteFile("vercel-blob", key);
+    }
+    async getTusEndpoint(_target) {
+        throw new Error("Vercel Blob does not support Tus protocol. Use S3 provider for resumable uploads.");
+    }
+    async deleteFile(_bucket, key) {
+        const blob = await import("@vercel/blob");
+        const url = key.startsWith("http") ? key : `https://blob.vercel-storage.com/${key}`;
+        await blob.del(url, { token: this.token });
+    }
+    async getDownloadUrl(_bucket, key, _expiresInSec) {
+        // Vercel Blob URLs are public by default — no signed URL needed
+        const blob = await import("@vercel/blob");
+        const url = key.startsWith("http") ? key : `https://blob.vercel-storage.com/${key}`;
+        const meta = await blob.head(url, { token: this.token });
+        return meta.url;
+    }
+    async close() {
+        // No-op — Vercel Blob has no persistent connections
+    }
+}
+export function createVercelBlobProvider(config) {
+    return new VercelBlobProvider(config);
+}

package/dist/providers/local.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Local filesystem upload provider
+ * For development and testing
+ */
+import type { CompletePart, LocalProviderConfig, MultipartUpload, PresignedUpload, TusUploadConfig, UploadComplete, UploadProvider, UploadTarget } from "../types";
+export declare class LocalUploadProvider implements UploadProvider {
+    private config;
+    private pendingUploads;
+    constructor(config: LocalProviderConfig);
+    /**
+     * Build object key with tenant prefix and UUID
+     */
+    private buildKey;
+    /**
+     * Generate presigned URL for simple uploads
+     */
+    createPresignedUpload(target: UploadTarget): Promise<PresignedUpload>;
+    /**
+     * Initiate multipart upload
+     */
+    createMultipartUpload(target: UploadTarget, partCount: number): Promise<MultipartUpload>;
+    /**
+     * Complete a multipart upload
+     */
+    completeMultipartUpload(uploadId: string, key: string, _parts: CompletePart[]): Promise<UploadComplete>;
+    /**
+     * Abort a multipart upload
+     */
+    abortMultipartUpload(uploadId: string, _key: string): Promise<void>;
+    /**
+     * Get Tus protocol endpoint configuration
+     */
+    getTusEndpoint(target: UploadTarget): Promise<TusUploadConfig>;
+    /**
+     * Delete a file
+     */
+    deleteFile(_bucket: string, key: string): Promise<void>;
+    /**
+     * Generate a download URL
+     */
+    getDownloadUrl(_bucket: string, key: string, _expiresInSec?: number): Promise<string>;
+    /**
+     * Ensure directory exists
+     */
+    private ensureDir;
+    /**
+     * Generate a simple ETag from content
+     */
+    private generateETag;
+    /**
+     * Clean up resources
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create local provider from environment variables
+ */
+export declare function createLocalProvider(): LocalUploadProvider;
+//# sourceMappingURL=local.d.ts.map

package/dist/providers/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/providers/local.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,YAAY,EACb,MAAM,UAAU,CAAC;AAElB,qBAAa,mBAAoB,YAAW,cAAc;IACxD,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,cAAc,CAA2D;gBAErE,MAAM,EAAE,mBAAmB;IAcvC;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAqB3E;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAmC9F;;OAEG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EAAE,GACrB,OAAO,CAAC,cAAc,CAAC;IAsC1B;;OAEG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzE;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IAcpE;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7D;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3F;;OAEG;YACW,SAAS;IAUvB;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,mBAAmB,CAUzD"}

package/dist/providers/local.js

@@ -0,0 +1,201 @@
+/**
+ * Local filesystem upload provider
+ * For development and testing
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { logger } from "@nebutra/logger";
+export class LocalUploadProvider {
+    config;
+    pendingUploads;
+    constructor(config) {
+        this.config = {
+            uploadDir: config.uploadDir,
+            httpBaseUrl: config.httpBaseUrl,
+            maxConcurrency: config.maxConcurrency || 10,
+        };
+        this.pendingUploads = new Map();
+        logger.info("Local upload provider initialized", {
+            uploadDir: this.config.uploadDir,
+            httpBaseUrl: this.config.httpBaseUrl,
+        });
+    }
+    /**
+     * Build object key with tenant prefix and UUID
+     */
+    buildKey(target) {
+        const id = randomUUID();
+        if (target.tenantId) {
+            return `${target.tenantId}/${id}/${target.key.split("/").pop()}`;
+        }
+        return `${id}/${target.key.split("/").pop()}`;
+    }
+    /**
+     * Generate presigned URL for simple uploads
+     */
+    async createPresignedUpload(target) {
+        const key = this.buildKey(target);
+        // Ensure directory exists
+        await this.ensureDir(target.bucket);
+        const expiresIn = 3600; // 1 hour
+        logger.debug("Local presigned upload URL generated", { key, bucket: target.bucket });
+        return {
+            url: `${this.config.httpBaseUrl}/upload?bucket=${encodeURIComponent(target.bucket)}&key=${encodeURIComponent(key)}`,
+            method: "PUT",
+            headers: {
+                "Content-Type": target.contentType,
+            },
+            expiresAt: new Date(Date.now() + expiresIn * 1000),
+            uploadId: key,
+        };
+    }
+    /**
+     * Initiate multipart upload
+     */
+    async createMultipartUpload(target, partCount) {
+        const key = this.buildKey(target);
+        const uploadId = randomUUID();
+        // Ensure directory exists
+        await this.ensureDir(target.bucket);
+        // Initialize upload tracking
+        this.pendingUploads.set(uploadId, {
+            key,
+            parts: new Map(),
+        });
+        // Generate presigned URLs for each part
+        const parts = Array.from({ length: partCount }, (_, i) => ({
+            partNumber: i + 1,
+            presignedUrl: `${this.config.httpBaseUrl}/upload/multipart?bucket=${encodeURIComponent(target.bucket)}&uploadId=${encodeURIComponent(uploadId)}&partNumber=${i + 1}`,
+        }));
+        logger.info("Local multipart upload initiated", {
+            key,
+            bucket: target.bucket,
+            uploadId,
+            partCount,
+        });
+        return {
+            uploadId,
+            key,
+            bucket: target.bucket,
+            parts,
+            completeUrl: `${this.config.httpBaseUrl}/upload/multipart/complete?bucket=${encodeURIComponent(target.bucket)}&uploadId=${encodeURIComponent(uploadId)}`,
+        };
+    }
+    /**
+     * Complete a multipart upload
+     */
+    async completeMultipartUpload(uploadId, key, _parts) {
+        const upload = this.pendingUploads.get(uploadId);
+        if (!upload) {
+            throw new Error(`Upload not found: ${uploadId}`);
+        }
+        // For local storage, etag is a simple hash of part data
+        // In production, this would be the actual S3 etag
+        const filePath = join(this.config.uploadDir, key);
+        // Ensure directory exists
+        const dir = filePath.substring(0, filePath.lastIndexOf("/"));
+        await this.ensureDir(dir);
+        // Combine parts in order
+        const parts_array = Array.from(upload.parts.entries())
+            .sort(([a], [b]) => a - b)
+            .map(([, buffer]) => buffer);
+        const combined = Buffer.concat(parts_array);
+        await writeFile(filePath, combined);
+        this.pendingUploads.delete(uploadId);
+        logger.info("Local multipart upload completed", { key, uploadId, size: combined.length });
+        return {
+            key,
+            bucket: "local",
+            url: `${this.config.httpBaseUrl}/files/${key}`,
+            size: combined.length,
+            contentType: "application/octet-stream",
+            etag: this.generateETag(combined),
+        };
+    }
+    /**
+     * Abort a multipart upload
+     */
+    async abortMultipartUpload(uploadId, _key) {
+        this.pendingUploads.delete(uploadId);
+        logger.info("Local multipart upload aborted", { uploadId });
+    }
+    /**
+     * Get Tus protocol endpoint configuration
+     */
+    async getTusEndpoint(target) {
+        await this.ensureDir(target.bucket);
+        return {
+            endpoint: `${this.config.httpBaseUrl}/upload/tus`,
+            chunkSize: 1 * 1024 * 1024, // 1MB chunks for local testing
+            retryDelays: [0, 1000, 3000],
+            metadata: {
+                ...target.metadata,
+                filename: target.key,
+            },
+        };
+    }
+    /**
+     * Delete a file
+     */
+    async deleteFile(_bucket, key) {
+        const filePath = join(this.config.uploadDir, key);
+        try {
+            await rm(filePath, { force: true });
+            logger.debug("Local file deleted", { key });
+        }
+        catch (error) {
+            logger.warn("Failed to delete local file", { key, error });
+        }
+    }
+    /**
+     * Generate a download URL
+     */
+    async getDownloadUrl(_bucket, key, _expiresInSec) {
+        return `${this.config.httpBaseUrl}/files/${key}`;
+    }
+    /**
+     * Ensure directory exists
+     */
+    async ensureDir(dirPath) {
+        const fullPath = join(this.config.uploadDir, dirPath);
+        try {
+            await mkdir(fullPath, { recursive: true });
+        }
+        catch (error) {
+            logger.warn("Failed to create directory", { path: fullPath, error });
+        }
+    }
+    /**
+     * Generate a simple ETag from content
+     */
+    generateETag(buffer) {
+        // Simple hash implementation
+        let hash = 0;
+        for (let i = 0; i < buffer.length; i++) {
+            hash = (hash << 5) - hash + (buffer[i] ?? 0);
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return `"${Math.abs(hash).toString(16)}"`;
+    }
+    /**
+     * Clean up resources
+     */
+    async close() {
+        this.pendingUploads.clear();
+        logger.debug("Local upload provider closed");
+    }
+}
+/**
+ * Create local provider from environment variables
+ */
+export function createLocalProvider() {
+    const config = {
+        uploadDir: process.env.UPLOAD_DIR || "/tmp/nebutra-uploads",
+        httpBaseUrl: process.env.UPLOAD_HTTP_BASE_URL || "http://localhost:3000",
+        maxConcurrency: process.env.UPLOAD_MAX_CONCURRENCY
+            ? parseInt(process.env.UPLOAD_MAX_CONCURRENCY, 10)
+            : 10,
+    };
+    return new LocalUploadProvider(config);
+}

package/dist/providers/s3.d.ts

@@ -0,0 +1,60 @@
+/**
+ * S3/R2 upload provider
+ * Supports both AWS S3 and Cloudflare R2 (S3-compatible)
+ */
+import type { CompletePart, MultipartUpload, PresignedUpload, S3ProviderConfig, TusUploadConfig, UploadComplete, UploadProvider, UploadTarget } from "../types";
+export declare class S3UploadProvider implements UploadProvider {
+    private client;
+    private config;
+    private uploadTracking;
+    constructor(config: S3ProviderConfig);
+    /**
+     * Build object key with tenant prefix
+     */
+    private buildKey;
+    /**
+     * Generate presigned PUT URL for simple uploads
+     */
+    createPresignedUpload(target: UploadTarget): Promise<PresignedUpload>;
+    /**
+     * Initiate multipart upload for large files
+     */
+    createMultipartUpload(target: UploadTarget, partCount: number): Promise<MultipartUpload>;
+    /**
+     * Generate a presigned URL for the complete multipart upload operation
+     */
+    private generateCompleteUrl;
+    /**
+     * Complete a multipart upload
+     */
+    completeMultipartUpload(uploadId: string, key: string, parts: CompletePart[]): Promise<UploadComplete>;
+    /**
+     * Abort a multipart upload
+     */
+    abortMultipartUpload(uploadId: string, key: string): Promise<void>;
+    /**
+     * Get Tus protocol endpoint configuration
+     */
+    getTusEndpoint(target: UploadTarget): Promise<TusUploadConfig>;
+    /**
+     * Delete a file from S3
+     */
+    deleteFile(bucket: string, key: string): Promise<void>;
+    /**
+     * Generate a presigned download URL
+     */
+    getDownloadUrl(bucket: string, key: string, expiresInSec?: number): Promise<string>;
+    /**
+     * Generate public CDN URL for assets
+     */
+    private generateDownloadUrl;
+    /**
+     * Clean up resources
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create S3 provider from environment variables
+ */
+export declare function createS3Provider(): S3UploadProvider;
+//# sourceMappingURL=s3.d.ts.map

package/dist/providers/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/providers/s3.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,cAAc,EACd,YAAY,EACb,MAAM,UAAU,CAAC;AAElB,qBAAa,gBAAiB,YAAW,cAAc;IACrD,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAOZ;IACF,OAAO,CAAC,cAAc,CAA+C;gBAEzD,MAAM,EAAE,gBAAgB;IAwBpC;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IA2B3E;;OAEG;IACG,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAgE9F;;OAEG;YACW,mBAAmB;IAUjC;;OAEG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,YAAY,EAAE,GACpB,OAAO,CAAC,cAAc,CAAC;IAuC1B;;OAEG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBxE;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC;IA4BpE;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW5D;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAS/F;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,CAoBnD"}

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.1",
   "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.1"
   },
   "peerDependencies": {
     "@vercel/blob": ">=0.23.0",