@nebutra/uploads 0.1.0 → 0.1.2

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"}