@digibuffer/file-manager 1.0.1

package/dist/server-CZrPOP0h.js

@@ -0,0 +1,490 @@
+import { deleteObject } from "@digibuffer/upload-lib-server/helpers";
+import { z } from "zod";
+
+//#region src/server/file-manager.ts
+/**
+* S3 List Objects V2 XML response parser
+*/
+function parseListObjectsV2(xml) {
+	const objects = [];
+	const contentRegex = /<Contents>([\s\S]*?)<\/Contents>/g;
+	let match;
+	while ((match = contentRegex.exec(xml)) !== null) {
+		const content = match[1];
+		const key = content.match(/<Key>(.*?)<\/Key>/)?.[1];
+		const size = content.match(/<Size>(.*?)<\/Size>/)?.[1];
+		const lastModified = content.match(/<LastModified>(.*?)<\/LastModified>/)?.[1];
+		const etag = content.match(/<ETag>(.*?)<\/ETag>/)?.[1];
+		const storageClass = content.match(/<StorageClass>(.*?)<\/StorageClass>/)?.[1];
+		if (key && size && lastModified && etag) objects.push({
+			key,
+			size: parseInt(size, 10),
+			lastModified,
+			etag: etag.replace(/"/g, ""),
+			storageClass
+		});
+	}
+	return {
+		objects,
+		isTruncated: xml.includes("<IsTruncated>true</IsTruncated>"),
+		nextContinuationToken: xml.match(/<NextContinuationToken>(.*?)<\/NextContinuationToken>/)?.[1]
+	};
+}
+/**
+* File Manager for managing files in R2/S3
+*/
+var FileManager = class {
+	client;
+	bucketName;
+	database;
+	defaultLimit;
+	maxLimit;
+	constructor(config) {
+		this.client = config.client;
+		this.bucketName = config.bucketName;
+		this.database = config.database;
+		this.defaultLimit = config.defaultLimit ?? 50;
+		this.maxLimit = config.maxLimit ?? 1e3;
+	}
+	/**
+	* List files from storage with pagination
+	*/
+	async listFromStorage(options = {}) {
+		const limit = Math.min(options.limit ?? this.defaultLimit, this.maxLimit);
+		const params = new URLSearchParams({
+			"list-type": "2",
+			"max-keys": limit.toString()
+		});
+		if (options.cursor) params.append("continuation-token", options.cursor);
+		if (options.prefix) params.append("prefix", options.prefix);
+		if (options.delimiter) params.append("delimiter", options.delimiter);
+		const url = this.buildUrl(void 0, params);
+		try {
+			const response = await this.client.fetch(url, { method: "GET" });
+			if (!response.ok) {
+				const text = await response.text();
+				throw this.createError("Failed to list files from storage", "STORAGE_LIST_ERROR", {
+					status: response.status,
+					statusText: response.statusText,
+					body: text
+				});
+			}
+			const parsed = parseListObjectsV2(await response.text());
+			const items = parsed.objects.map((obj) => ({
+				key: obj.key,
+				size: obj.size,
+				lastModified: new Date(obj.lastModified),
+				etag: obj.etag,
+				storageClass: obj.storageClass
+			}));
+			if (options.sortBy) this.sortFiles(items, options.sortBy, options.sortOrder);
+			return {
+				items,
+				nextCursor: parsed.nextContinuationToken,
+				hasMore: parsed.isTruncated
+			};
+		} catch (error) {
+			if (error instanceof Error && error.name === "FileManagerError") throw error;
+			throw this.createError("Failed to list files", "LIST_ERROR", { originalError: error });
+		}
+	}
+	/**
+	* List files from database with pagination
+	*/
+	async listFromDatabase(options = {}) {
+		if (!this.database?.getFiles) throw this.createError("Database getFiles callback not configured", "DATABASE_NOT_CONFIGURED");
+		try {
+			const limit = Math.min(options.limit ?? this.defaultLimit, this.maxLimit);
+			const result = await this.database.getFiles({
+				limit,
+				cursor: options.cursor,
+				prefix: options.prefix,
+				delimiter: options.delimiter
+			});
+			if (options.sortBy && result.items.length > 0) this.sortFiles(result.items, options.sortBy, options.sortOrder);
+			return result;
+		} catch (error) {
+			throw this.createError("Failed to list files from database", "DATABASE_LIST_ERROR", { originalError: error });
+		}
+	}
+	/**
+	* List files from both database and storage, merging results
+	*/
+	async listFromBoth(options = {}) {
+		const [dbResult, storageResult] = await Promise.all([this.listFromDatabase(options).catch(() => ({
+			items: [],
+			hasMore: false
+		})), this.listFromStorage(options).catch(() => ({
+			items: [],
+			hasMore: false
+		}))]);
+		const storageMap = new Map(storageResult.items.map((file) => [file.key, file]));
+		return {
+			items: dbResult.items.map((dbFile) => {
+				const storageFile = storageMap.get(dbFile.key);
+				if (storageFile) return {
+					...dbFile,
+					...storageFile,
+					id: dbFile.id
+				};
+				return dbFile;
+			}),
+			nextCursor: dbResult.nextCursor,
+			hasMore: dbResult.hasMore,
+			totalCount: dbResult.totalCount
+		};
+	}
+	/**
+	* List files with automatic source selection
+	*/
+	async list(options = {}) {
+		const source = options.source ?? (this.database?.getFiles ? "database" : "storage");
+		switch (source) {
+			case "database": return this.listFromDatabase(options);
+			case "storage": return this.listFromStorage(options);
+			case "both": return this.listFromBoth(options);
+			default: throw this.createError("Invalid source option", "INVALID_SOURCE", { source });
+		}
+	}
+	/**
+	* Delete a single file
+	*/
+	async delete(key) {
+		let file;
+		try {
+			if (this.database?.getFileByKey) file = await this.database.getFileByKey(key);
+			if (this.database?.onBeforeDelete) {
+				if (!await this.database.onBeforeDelete({
+					key,
+					file: file ?? void 0
+				})) return {
+					success: false,
+					key,
+					error: "Delete prevented by onBeforeDelete hook"
+				};
+			}
+			await deleteObject(this.client, {
+				bucket: this.bucketName,
+				key
+			});
+			if (this.database?.onAfterDelete) await this.database.onAfterDelete({
+				key,
+				file: file ?? void 0,
+				success: true
+			});
+			return {
+				success: true,
+				key
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : "Unknown error";
+			if (this.database?.onAfterDelete) await this.database.onAfterDelete({
+				key,
+				file: file ?? void 0,
+				success: false,
+				error: errorMessage
+			});
+			return {
+				success: false,
+				key,
+				error: errorMessage
+			};
+		}
+	}
+	/**
+	* Delete multiple files in batch
+	*/
+	async deleteBatch(keys) {
+		if (keys.length === 0) return {
+			deleted: [],
+			errors: []
+		};
+		const results = await Promise.allSettled(keys.map((key) => this.delete(key)));
+		const deleted = [];
+		const errors = [];
+		results.forEach((result, index) => {
+			const key = keys[index];
+			if (result.status === "fulfilled" && result.value.success) deleted.push(key);
+			else {
+				const error = result.status === "fulfilled" ? result.value.error ?? "Unknown error" : result.reason instanceof Error ? result.reason.message : "Unknown error";
+				errors.push({
+					key,
+					error
+				});
+			}
+		});
+		if (this.database?.onAfterBatchDelete) await this.database.onAfterBatchDelete({
+			deleted,
+			errors
+		});
+		return {
+			deleted,
+			errors
+		};
+	}
+	/**
+	* Generate a presigned download URL
+	*/
+	async getDownloadUrl(key, options = {}) {
+		const expiresIn = options.expiresIn ?? 3600;
+		const params = new URLSearchParams();
+		if (options.filename || options.disposition) {
+			const disposition = options.disposition ?? "attachment";
+			const filename = options.filename ?? key.split("/").pop();
+			params.append("response-content-disposition", `${disposition}; filename="${filename}"`);
+		}
+		const url = this.buildUrl(key, params.toString() ? params : void 0);
+		Math.floor(Date.now() / 1e3) + expiresIn;
+		const request = new Request(url, { method: "GET" });
+		return (await this.client.sign(request, { aws: {
+			signQuery: true,
+			allHeaders: true
+		} })).url;
+	}
+	/**
+	* Check if a file exists
+	*/
+	async exists(key) {
+		try {
+			const url = this.buildUrl(key);
+			return (await this.client.fetch(url, { method: "HEAD" })).ok;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Get file metadata from storage
+	*/
+	async getMetadata(key) {
+		try {
+			const url = this.buildUrl(key);
+			const response = await this.client.fetch(url, { method: "HEAD" });
+			if (!response.ok) return null;
+			return {
+				key,
+				size: parseInt(response.headers.get("content-length") ?? "0", 10),
+				lastModified: new Date(response.headers.get("last-modified") ?? Date.now()),
+				etag: response.headers.get("etag")?.replace(/"/g, "") ?? "",
+				contentType: response.headers.get("content-type") ?? void 0
+			};
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Build URL helper - supports both path-style and virtual-hosted-style
+	*/
+	buildUrl(key, params) {
+		const baseHost = this.client.host.startsWith("http") ? this.client.host : `https://${this.client.host}`;
+		let url;
+		if (key) url = this.bucketName ? `${baseHost}/${this.bucketName}/${key}` : `${baseHost}/${key}`;
+		else url = this.bucketName ? `${baseHost}/${this.bucketName}` : baseHost;
+		if (params) url += `?${params.toString()}`;
+		return url;
+	}
+	/**
+	* Sort files helper
+	*/
+	sortFiles(files, sortBy, sortOrder = "desc") {
+		files.sort((a, b) => {
+			let comparison = 0;
+			switch (sortBy) {
+				case "lastModified":
+					comparison = a.lastModified.getTime() - b.lastModified.getTime();
+					break;
+				case "size":
+					comparison = a.size - b.size;
+					break;
+				case "name":
+					comparison = a.key.localeCompare(b.key);
+					break;
+			}
+			return sortOrder === "asc" ? comparison : -comparison;
+		});
+	}
+	/**
+	* Create a FileManagerError
+	*/
+	createError(message, code, details) {
+		const error = new Error(message);
+		error.name = "FileManagerError";
+		error.code = code;
+		error.details = details;
+		return error;
+	}
+};
+
+//#endregion
+//#region src/server/router.ts
+/**
+* Request schemas
+*/
+const ListRequestSchema = z.object({
+	action: z.literal("list"),
+	limit: z.number().int().positive().optional(),
+	cursor: z.string().optional(),
+	prefix: z.string().optional(),
+	delimiter: z.string().optional(),
+	source: z.enum([
+		"storage",
+		"database",
+		"both"
+	]).optional(),
+	sortBy: z.enum([
+		"lastModified",
+		"size",
+		"name"
+	]).optional(),
+	sortOrder: z.enum(["asc", "desc"]).optional()
+});
+const DeleteRequestSchema = z.object({
+	action: z.literal("delete"),
+	key: z.string().min(1)
+});
+const BatchDeleteRequestSchema = z.object({
+	action: z.literal("batchDelete"),
+	keys: z.array(z.string().min(1)).min(1)
+});
+const GetUrlRequestSchema = z.object({
+	action: z.literal("getUrl"),
+	key: z.string().min(1),
+	expiresIn: z.number().int().positive().optional(),
+	filename: z.string().optional(),
+	disposition: z.enum(["attachment", "inline"]).optional()
+});
+const ExistsRequestSchema = z.object({
+	action: z.literal("exists"),
+	key: z.string().min(1)
+});
+const GetMetadataRequestSchema = z.object({
+	action: z.literal("getMetadata"),
+	key: z.string().min(1)
+});
+const FileManagerRequestSchema = z.discriminatedUnion("action", [
+	ListRequestSchema,
+	DeleteRequestSchema,
+	BatchDeleteRequestSchema,
+	GetUrlRequestSchema,
+	ExistsRequestSchema,
+	GetMetadataRequestSchema
+]);
+/**
+* Router for file management operations
+*/
+var FileManagerRouter = class {
+	routes = /* @__PURE__ */ new Map();
+	/**
+	* Register a route
+	*/
+	route(path, config) {
+		this.routes.set(path, config);
+		return this;
+	}
+	/**
+	* Handle a request
+	*/
+	async handle(path, body, context) {
+		const route = this.routes.get(path);
+		if (!route) return this.errorResponse("Route not found", 404);
+		try {
+			const request = FileManagerRequestSchema.parse(body);
+			if (route.onAuthorize) {
+				if (!await route.onAuthorize(request, context)) return this.errorResponse("Unauthorized", 403);
+			}
+			switch (request.action) {
+				case "list": {
+					let options = {
+						limit: request.limit,
+						cursor: request.cursor,
+						prefix: request.prefix,
+						delimiter: request.delimiter,
+						source: request.source,
+						sortBy: request.sortBy,
+						sortOrder: request.sortOrder
+					};
+					if (route.onBeforeList) {
+						const result$1 = await route.onBeforeList(options, context);
+						if (result$1 === false) return this.errorResponse("List operation denied", 403);
+						options = result$1;
+					}
+					const result = await route.fileManager.list(options);
+					return this.successResponse(result);
+				}
+				case "delete": {
+					if (route.onBeforeDelete) {
+						if (!await route.onBeforeDelete(request.key, context)) return this.errorResponse("Delete operation denied", 403);
+					}
+					const result = await route.fileManager.delete(request.key);
+					return this.successResponse(result);
+				}
+				case "batchDelete": {
+					let keys = request.keys;
+					if (route.onBeforeBatchDelete) {
+						const result$1 = await route.onBeforeBatchDelete(keys, context);
+						if (result$1 === false) return this.errorResponse("Batch delete operation denied", 403);
+						keys = result$1;
+					}
+					const result = await route.fileManager.deleteBatch(keys);
+					return this.successResponse(result);
+				}
+				case "getUrl": {
+					const url = await route.fileManager.getDownloadUrl(request.key, {
+						expiresIn: request.expiresIn,
+						filename: request.filename,
+						disposition: request.disposition
+					});
+					return this.successResponse({ url });
+				}
+				case "exists": {
+					const exists = await route.fileManager.exists(request.key);
+					return this.successResponse({ exists });
+				}
+				case "getMetadata": {
+					const metadata = await route.fileManager.getMetadata(request.key);
+					return this.successResponse({ metadata });
+				}
+				default: return this.errorResponse("Invalid action", 400);
+			}
+		} catch (error) {
+			if (error instanceof z.ZodError) return this.errorResponse("Invalid request", 400, { errors: error.errors });
+			if (error instanceof Error) return this.errorResponse(error.message, 500, { name: error.name });
+			return this.errorResponse("Internal server error", 500);
+		}
+	}
+	/**
+	* Success response helper
+	*/
+	successResponse(data) {
+		return new Response(JSON.stringify({
+			success: true,
+			data
+		}), {
+			status: 200,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* Error response helper
+	*/
+	errorResponse(message, status, details) {
+		return new Response(JSON.stringify({
+			success: false,
+			error: {
+				message,
+				details
+			}
+		}), {
+			status,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+};
+/**
+* Create a file manager router
+*/
+function createFileManagerRouter() {
+	return new FileManagerRouter();
+}
+
+//#endregion
+export { createFileManagerRouter as n, FileManager as r, FileManagerRouter as t };

package/dist/types-Brk9aR7c.d.ts

@@ -0,0 +1,177 @@
+import { Client } from "@digibuffer/upload-lib-server/clients";
+
+//#region src/shared/types.d.ts
+
+/**
+ * Pagination options for listing files
+ */
+type PaginationOptions = {
+  /** Maximum number of items to return per page */
+  limit?: number;
+  /** Pagination cursor (continuation token from previous response) */
+  cursor?: string;
+  /** Optional prefix to filter files by key prefix */
+  prefix?: string;
+  /** Optional delimiter for grouping keys (commonly '/') */
+  delimiter?: string;
+};
+/**
+ * Paginated response wrapper
+ */
+type PaginatedResponse<T> = {
+  /** Array of items for current page */
+  items: T[];
+  /** Cursor for next page, undefined if no more pages */
+  nextCursor?: string;
+  /** Whether there are more pages available */
+  hasMore: boolean;
+  /** Total count if available (may not be accurate for large datasets) */
+  totalCount?: number;
+};
+/**
+ * File metadata from storage
+ */
+type StorageFile = {
+  /** Object key in storage */
+  key: string;
+  /** File size in bytes */
+  size: number;
+  /** Last modified timestamp */
+  lastModified: Date;
+  /** ETag for the object */
+  etag: string;
+  /** Content type */
+  contentType?: string;
+  /** Storage class */
+  storageClass?: string;
+  /** Custom metadata */
+  metadata?: Record<string, string>;
+};
+/**
+ * File with database information
+ */
+type ManagedFile = StorageFile & {
+  /** Database ID */
+  id: string;
+  /** User ID who owns the file */
+  userId?: string;
+  /** Original filename */
+  originalName?: string;
+  /** Additional database fields */
+  [key: string]: any;
+};
+/**
+ * Delete operation result
+ */
+type DeleteResult = {
+  /** Whether the delete was successful */
+  success: boolean;
+  /** The key that was deleted */
+  key: string;
+  /** Error message if failed */
+  error?: string;
+};
+/**
+ * Batch delete result
+ */
+type BatchDeleteResult = {
+  /** Successfully deleted keys */
+  deleted: string[];
+  /** Failed deletions with errors */
+  errors: Array<{
+    key: string;
+    error: string;
+  }>;
+};
+/**
+ * Download URL options
+ */
+type DownloadUrlOptions = {
+  /** Expiration time in seconds (default: 3600) */
+  expiresIn?: number;
+  /** Optional filename for Content-Disposition header */
+  filename?: string;
+  /** Whether to force download (attachment) vs inline */
+  disposition?: 'attachment' | 'inline';
+};
+/**
+ * Database callbacks for file operations
+ */
+type DatabaseCallbacks<TFile = ManagedFile> = {
+  /**
+   * Called after a file is deleted from storage
+   * Use this to update your database
+   */
+  onAfterDelete?: (params: {
+    key: string;
+    file?: TFile;
+    success: boolean;
+    error?: string;
+  }) => Promise<void> | void;
+  /**
+   * Called before a file is deleted from storage
+   * Return false to prevent deletion
+   */
+  onBeforeDelete?: (params: {
+    key: string;
+    file?: TFile;
+  }) => Promise<boolean> | boolean;
+  /**
+   * Called after batch delete operation
+   */
+  onAfterBatchDelete?: (params: {
+    deleted: string[];
+    errors: Array<{
+      key: string;
+      error: string;
+    }>;
+  }) => Promise<void> | void;
+  /**
+   * Fetch file metadata from database by key
+   */
+  getFileByKey?: (key: string) => Promise<TFile | null> | TFile | null;
+  /**
+   * Fetch files from database with pagination
+   */
+  getFiles?: (options: PaginationOptions) => Promise<PaginatedResponse<TFile>> | PaginatedResponse<TFile>;
+  /**
+   * Update file metadata in database
+   */
+  updateFile?: (key: string, data: Partial<TFile>) => Promise<TFile> | TFile;
+};
+/**
+ * File manager configuration
+ */
+type FileManagerConfig<TFile = ManagedFile> = {
+  /** S3 client instance */
+  client: Client;
+  /** Default bucket name */
+  bucketName: string;
+  /** Database callbacks */
+  database?: DatabaseCallbacks<TFile>;
+  /** Default pagination limit */
+  defaultLimit?: number;
+  /** Maximum pagination limit */
+  maxLimit?: number;
+};
+/**
+ * List files options
+ */
+type ListFilesOptions = PaginationOptions & {
+  /** Whether to fetch from database or storage */
+  source?: 'storage' | 'database' | 'both';
+  /** Sort order */
+  sortBy?: 'lastModified' | 'size' | 'name';
+  /** Sort direction */
+  sortOrder?: 'asc' | 'desc';
+};
+/**
+ * File operation error
+ */
+declare class FileManagerError extends Error {
+  code: string;
+  details?: Record<string, any> | undefined;
+  constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+//#endregion
+export { FileManagerConfig as a, ManagedFile as c, StorageFile as d, DownloadUrlOptions as i, PaginatedResponse as l, DatabaseCallbacks as n, FileManagerError as o, DeleteResult as r, ListFilesOptions as s, BatchDeleteResult as t, PaginationOptions as u };