@digibuffer/file-manager 1.0.1

package/README.md

@@ -0,0 +1,213 @@
+# @digibuffer/file-manager
+
+File management library for fetching, deleting, and managing files in R2/S3 with database operations and pagination support.
+
+## Features
+
+- 📂 **List files** with pagination from R2/S3 or database
+- 🗑️ **Delete files** with database sync callbacks
+- 🔗 **Generate download URLs** with presigned URLs
+- 📊 **Pagination support** with cursor-based navigation
+- 🔄 **Database integration** with flexible callbacks
+- 🎯 **Type-safe** with full TypeScript support
+- ⚛️ **React hooks** for easy client-side integration
+- 🚀 **Next.js adapter** for serverless functions
+
+## Installation
+
+```bash
+npm install @digibuffer/file-manager @digibuffer/upload-lib-server
+# or
+pnpm add @digibuffer/file-manager @digibuffer/upload-lib-server
+```
+
+## Quick Start
+
+### Server Setup
+
+```typescript
+import { cloudflareClient } from '@digibuffer/upload-lib-server/clients';
+import { FileManager, createFileManagerRouter } from '@digibuffer/file-manager/server';
+import { toRouteHandler } from '@digibuffer/file-manager/adapters/next';
+
+// Create S3 client
+const client = cloudflareClient({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
+  accessKeyId: process.env.CLOUDFLARE_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.CLOUDFLARE_SECRET_ACCESS_KEY!,
+});
+
+// Create file manager with database callbacks
+const fileManager = new FileManager({
+  client,
+  bucketName: 'my-bucket',
+  database: {
+    onAfterDelete: async ({ key, success }) => {
+      if (success) {
+        await db.file.delete({ where: { key } });
+      }
+    },
+    getFiles: async ({ limit, cursor }) => {
+      const files = await db.file.findMany({
+        take: limit,
+        skip: cursor ? 1 : 0,
+        cursor: cursor ? { id: cursor } : undefined,
+      });
+      return {
+        items: files,
+        hasMore: files.length === limit,
+        nextCursor: files[files.length - 1]?.id,
+      };
+    },
+  },
+});
+
+// Create router
+const router = createFileManagerRouter();
+router.route('default', {
+  fileManager,
+  onAuthorize: async (request) => {
+    // Add your auth logic here
+    return true;
+  },
+});
+
+// Export Next.js handler
+export const POST = toRouteHandler(router);
+```
+
+### Client Setup
+
+```typescript
+import { FileManagerProvider } from '@digibuffer/file-manager/client';
+
+function App() {
+  return (
+    <FileManagerProvider
+      config={{
+        endpoint: '/api/files',
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      }}
+    >
+      <FileList />
+    </FileManagerProvider>
+  );
+}
+```
+
+### Using Hooks
+
+```typescript
+import { useListFiles, useDeleteFile, useDownloadUrl } from '@digibuffer/file-manager/client';
+
+function FileList() {
+  const { data, list, loadMore, hasMore, isLoading } = useListFiles();
+  const { deleteFile } = useDeleteFile();
+  const { download } = useDownloadUrl();
+
+  useEffect(() => {
+    list({ limit: 20 });
+  }, []);
+
+  return (
+    <div>
+      {data?.items.map((file) => (
+        <div key={file.key}>
+          <span>{file.key}</span>
+          <button onClick={() => download(file.key)}>Download</button>
+          <button onClick={() => deleteFile(file.key)}>Delete</button>
+        </div>
+      ))}
+      {hasMore && <button onClick={() => loadMore()}>Load More</button>}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### FileManager
+
+Main server-side class for managing files.
+
+```typescript
+const fileManager = new FileManager({
+  client: Client, // S3 client from upload-lib-server
+  bucketName: string,
+  database?: DatabaseCallbacks,
+  defaultLimit?: number, // Default: 50
+  maxLimit?: number, // Default: 1000
+});
+```
+
+#### Methods
+
+- `list(options)` - List files with pagination
+- `delete(key)` - Delete a single file
+- `deleteBatch(keys)` - Delete multiple files
+- `getDownloadUrl(key, options)` - Generate presigned download URL
+- `exists(key)` - Check if file exists
+- `getMetadata(key)` - Get file metadata
+
+### Database Callbacks
+
+```typescript
+type DatabaseCallbacks = {
+  onAfterDelete?: (params) => Promise<void>;
+  onBeforeDelete?: (params) => Promise<boolean>;
+  onAfterBatchDelete?: (params) => Promise<void>;
+  getFileByKey?: (key) => Promise<File | null>;
+  getFiles?: (options) => Promise<PaginatedResponse<File>>;
+  updateFile?: (key, data) => Promise<File>;
+};
+```
+
+### Client Hooks
+
+#### useListFiles()
+
+```typescript
+const {
+  data, // PaginatedResponse<File> | null
+  list, // (options) => Promise<PaginatedResponse>
+  loadMore, // () => Promise<PaginatedResponse>
+  hasMore, // boolean
+  isLoading,
+  isError,
+  error,
+  reset,
+} = useListFiles();
+```
+
+#### useDeleteFile()
+
+```typescript
+const {
+  deleteFile, // (key) => Promise<DeleteResult>
+  deleteBatch, // (keys) => Promise<BatchDeleteResult>
+  isLoading,
+  isError,
+  error,
+  reset,
+} = useDeleteFile();
+```
+
+#### useDownloadUrl()
+
+```typescript
+const {
+  getUrl, // (key, options) => Promise<string>
+  download, // (key, options) => Promise<string>
+  url,
+  isLoading,
+  isError,
+  error,
+  reset,
+} = useDownloadUrl();
+```
+
+## License
+
+MIT

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+import { c as ManagedFile, d as StorageFile, i as DownloadUrlOptions, l as PaginatedResponse, r as DeleteResult, s as ListFilesOptions, t as BatchDeleteResult, u as PaginationOptions } from "../types-Brk9aR7c.js";
+import { a as useFileManagerConfig, c as ApiSuccessResponse, d as UseDeleteFileState, f as UseDownloadUrlState, i as FileManagerProvider, l as FileManagerClientConfig, n as useDeleteFile, o as ApiErrorResponse, p as UseListFilesState, r as useListFiles, s as ApiResponse, t as useDownloadUrl, u as HookStatus } from "../index-pUAG6PPj.js";
+export { ApiErrorResponse, ApiResponse, ApiSuccessResponse, BatchDeleteResult, DeleteResult, DownloadUrlOptions, FileManagerClientConfig, FileManagerProvider, HookStatus, ListFilesOptions, ManagedFile, PaginatedResponse, PaginationOptions, StorageFile, UseDeleteFileState, UseDownloadUrlState, UseListFilesState, useDeleteFile, useDownloadUrl, useFileManagerConfig, useListFiles };

package/dist/client/index.js

@@ -0,0 +1,3 @@
+import { a as useFileManagerConfig, i as FileManagerProvider, n as useDeleteFile, r as useListFiles, t as useDownloadUrl } from "../client-DTkToHgY.js";
+
+export { FileManagerProvider, useDeleteFile, useDownloadUrl, useFileManagerConfig, useListFiles };

package/dist/client-DTkToHgY.js

@@ -0,0 +1,347 @@
+import React, { createContext, useCallback, useContext, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/client/context.tsx
+const FileManagerContext = createContext(null);
+/**
+* Provider for file manager client configuration
+*/
+function FileManagerProvider({ children, config }) {
+	return /* @__PURE__ */ jsx(FileManagerContext.Provider, {
+		value: config,
+		children
+	});
+}
+/**
+* Hook to get file manager client configuration
+*/
+function useFileManagerConfig() {
+	const config = useContext(FileManagerContext);
+	if (!config) throw new Error("useFileManagerConfig must be used within FileManagerProvider");
+	return config;
+}
+
+//#endregion
+//#region src/client/hooks/useListFiles.ts
+/**
+* Hook for listing files with pagination
+*/
+function useListFiles() {
+	const config = useFileManagerConfig();
+	const [state, setState] = useState({
+		data: null,
+		status: "idle",
+		error: null,
+		isLoading: false,
+		isError: false,
+		isSuccess: false
+	});
+	const [lastOptions, setLastOptions] = useState({});
+	const list = useCallback(async (options = {}) => {
+		const { cursor,...optionsWithoutCursor } = options;
+		if (!cursor) setLastOptions(optionsWithoutCursor);
+		setState((prev) => ({
+			...prev,
+			status: "loading",
+			isLoading: true,
+			isError: false,
+			error: null
+		}));
+		try {
+			const json = await (await (config.fetch ?? fetch)(config.endpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...config.headers
+				},
+				body: JSON.stringify({
+					action: "list",
+					...options
+				})
+			})).json();
+			if (!json.success) throw new Error(json.error?.message ?? "Failed to list files");
+			const data = json.data;
+			setState({
+				data,
+				status: "success",
+				error: null,
+				isLoading: false,
+				isError: false,
+				isSuccess: true
+			});
+			return data;
+		} catch (error) {
+			const err = error instanceof Error ? error : /* @__PURE__ */ new Error("Unknown error");
+			setState({
+				data: null,
+				status: "error",
+				error: err,
+				isLoading: false,
+				isError: true,
+				isSuccess: false
+			});
+			throw err;
+		}
+	}, [config]);
+	const loadMore = useCallback(async (options = {}) => {
+		if (!state.data?.nextCursor) throw new Error("No more pages to load");
+		const newData = await list({
+			...lastOptions,
+			...options,
+			cursor: state.data.nextCursor
+		});
+		setState((prev) => {
+			if (!prev.data) return {
+				...prev,
+				data: newData
+			};
+			const itemsMap = /* @__PURE__ */ new Map();
+			prev.data.items.forEach((item) => {
+				itemsMap.set(item.key, item);
+			});
+			newData.items.forEach((item) => {
+				itemsMap.set(item.key, item);
+			});
+			return {
+				...prev,
+				data: {
+					...newData,
+					items: Array.from(itemsMap.values())
+				}
+			};
+		});
+		return newData;
+	}, [
+		state.data,
+		list,
+		lastOptions
+	]);
+	const reset = useCallback(() => {
+		setState({
+			data: null,
+			status: "idle",
+			error: null,
+			isLoading: false,
+			isError: false,
+			isSuccess: false
+		});
+	}, []);
+	return {
+		...state,
+		list,
+		loadMore,
+		reset,
+		hasMore: state.data?.hasMore ?? false
+	};
+}
+
+//#endregion
+//#region src/client/hooks/useDeleteFile.ts
+/**
+* Hook for deleting files
+*/
+function useDeleteFile() {
+	const config = useFileManagerConfig();
+	const [state, setState] = useState({
+		status: "idle",
+		error: null,
+		isLoading: false,
+		isError: false,
+		isSuccess: false
+	});
+	const deleteFile = useCallback(async (key) => {
+		setState({
+			status: "loading",
+			error: null,
+			isLoading: true,
+			isError: false,
+			isSuccess: false
+		});
+		try {
+			const json = await (await (config.fetch ?? fetch)(config.endpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...config.headers
+				},
+				body: JSON.stringify({
+					action: "delete",
+					key
+				})
+			})).json();
+			if (!json.success) throw new Error(json.error?.message ?? "Failed to delete file");
+			const result = json.data;
+			if (!result.success) throw new Error(result.error ?? "Failed to delete file");
+			setState({
+				status: "success",
+				error: null,
+				isLoading: false,
+				isError: false,
+				isSuccess: true
+			});
+			return result;
+		} catch (error) {
+			const err = error instanceof Error ? error : /* @__PURE__ */ new Error("Unknown error");
+			setState({
+				status: "error",
+				error: err,
+				isLoading: false,
+				isError: true,
+				isSuccess: false
+			});
+			throw err;
+		}
+	}, [config]);
+	const deleteBatch = useCallback(async (keys) => {
+		setState({
+			status: "loading",
+			error: null,
+			isLoading: true,
+			isError: false,
+			isSuccess: false
+		});
+		try {
+			const json = await (await (config.fetch ?? fetch)(config.endpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...config.headers
+				},
+				body: JSON.stringify({
+					action: "batchDelete",
+					keys
+				})
+			})).json();
+			if (!json.success) throw new Error(json.error?.message ?? "Failed to delete files");
+			const result = json.data;
+			setState({
+				status: "success",
+				error: null,
+				isLoading: false,
+				isError: false,
+				isSuccess: true
+			});
+			return result;
+		} catch (error) {
+			const err = error instanceof Error ? error : /* @__PURE__ */ new Error("Unknown error");
+			setState({
+				status: "error",
+				error: err,
+				isLoading: false,
+				isError: true,
+				isSuccess: false
+			});
+			throw err;
+		}
+	}, [config]);
+	const reset = useCallback(() => {
+		setState({
+			status: "idle",
+			error: null,
+			isLoading: false,
+			isError: false,
+			isSuccess: false
+		});
+	}, []);
+	return {
+		...state,
+		deleteFile,
+		deleteBatch,
+		reset
+	};
+}
+
+//#endregion
+//#region src/client/hooks/useDownloadUrl.ts
+/**
+* Hook for generating download URLs
+*/
+function useDownloadUrl() {
+	const config = useFileManagerConfig();
+	const [state, setState] = useState({
+		url: null,
+		status: "idle",
+		error: null,
+		isLoading: false,
+		isError: false,
+		isSuccess: false
+	});
+	const getUrl = useCallback(async (key, options = {}) => {
+		setState({
+			url: null,
+			status: "loading",
+			error: null,
+			isLoading: true,
+			isError: false,
+			isSuccess: false
+		});
+		try {
+			const json = await (await (config.fetch ?? fetch)(config.endpoint, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					...config.headers
+				},
+				body: JSON.stringify({
+					action: "getUrl",
+					key,
+					...options
+				})
+			})).json();
+			if (!json.success) throw new Error(json.error?.message ?? "Failed to get download URL");
+			const url = json.data.url;
+			setState({
+				url,
+				status: "success",
+				error: null,
+				isLoading: false,
+				isError: false,
+				isSuccess: true
+			});
+			return url;
+		} catch (error) {
+			const err = error instanceof Error ? error : /* @__PURE__ */ new Error("Unknown error");
+			setState({
+				url: null,
+				status: "error",
+				error: err,
+				isLoading: false,
+				isError: true,
+				isSuccess: false
+			});
+			throw err;
+		}
+	}, [config]);
+	const download = useCallback(async (key, options = {}) => {
+		const url = await getUrl(key, {
+			disposition: "attachment",
+			...options
+		});
+		const link = document.createElement("a");
+		link.href = url;
+		link.download = options.filename ?? key.split("/").pop() ?? "download";
+		document.body.appendChild(link);
+		link.click();
+		document.body.removeChild(link);
+		return url;
+	}, [getUrl]);
+	const reset = useCallback(() => {
+		setState({
+			url: null,
+			status: "idle",
+			error: null,
+			isLoading: false,
+			isError: false,
+			isSuccess: false
+		});
+	}, []);
+	return {
+		...state,
+		getUrl,
+		download,
+		reset
+	};
+}
+
+//#endregion
+export { useFileManagerConfig as a, FileManagerProvider as i, useDeleteFile as n, useListFiles as r, useDownloadUrl as t };

package/dist/index-CHmsNSsb.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/index-pUAG6PPj.d.ts

@@ -0,0 +1,132 @@
+import { c as ManagedFile, d as StorageFile, i as DownloadUrlOptions, l as PaginatedResponse, r as DeleteResult, s as ListFilesOptions, t as BatchDeleteResult } from "./types-Brk9aR7c.js";
+import React, { ReactNode } from "react";
+
+//#region src/client/types.d.ts
+/**
+ * API client configuration
+ */
+type FileManagerClientConfig = {
+  /** API endpoint URL */
+  endpoint: string;
+  /** Custom headers (e.g., authorization) */
+  headers?: Record<string, string>;
+  /** Custom fetch function */
+  fetch?: typeof fetch;
+};
+/**
+ * Hook status type
+ */
+type HookStatus = 'idle' | 'loading' | 'success' | 'error';
+/**
+ * List files hook state
+ */
+type UseListFilesState<TFile = ManagedFile | StorageFile> = {
+  data: PaginatedResponse<TFile> | null;
+  status: HookStatus;
+  error: Error | null;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+};
+/**
+ * Delete file hook state
+ */
+type UseDeleteFileState = {
+  status: HookStatus;
+  error: Error | null;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+};
+/**
+ * Download URL hook state
+ */
+type UseDownloadUrlState = {
+  url: string | null;
+  status: HookStatus;
+  error: Error | null;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+};
+/**
+ * API response types
+ */
+type ApiSuccessResponse<T> = {
+  success: true;
+  data: T;
+};
+type ApiErrorResponse = {
+  success: false;
+  error: {
+    message: string;
+    details?: any;
+  };
+};
+type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+//#endregion
+//#region src/client/context.d.ts
+/**
+ * Provider for file manager client configuration
+ */
+declare function FileManagerProvider({
+  children,
+  config
+}: {
+  children: ReactNode;
+  config: FileManagerClientConfig;
+}): React.JSX.Element;
+/**
+ * Hook to get file manager client configuration
+ */
+declare function useFileManagerConfig(): FileManagerClientConfig;
+//#endregion
+//#region src/client/hooks/useListFiles.d.ts
+/**
+ * Hook for listing files with pagination
+ */
+declare function useListFiles<TFile extends ManagedFile | StorageFile = ManagedFile>(): {
+  list: (options?: ListFilesOptions) => Promise<PaginatedResponse<TFile>>;
+  loadMore: (options?: Omit<ListFilesOptions, "cursor">) => Promise<PaginatedResponse<TFile>>;
+  reset: () => void;
+  hasMore: boolean;
+  data: PaginatedResponse<TFile> | null;
+  status: HookStatus;
+  error: Error | null;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+};
+//#endregion
+//#region src/client/hooks/useDeleteFile.d.ts
+/**
+ * Hook for deleting files
+ */
+declare function useDeleteFile(): {
+  deleteFile: (key: string) => Promise<DeleteResult>;
+  deleteBatch: (keys: string[]) => Promise<BatchDeleteResult>;
+  reset: () => void;
+  status: HookStatus;
+  error: Error | null;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+};
+//#endregion
+//#region src/client/hooks/useDownloadUrl.d.ts
+/**
+ * Hook for generating download URLs
+ */
+declare function useDownloadUrl(): {
+  getUrl: (key: string, options?: DownloadUrlOptions) => Promise<string>;
+  download: (key: string, options?: DownloadUrlOptions) => Promise<string>;
+  reset: () => void;
+  url: string | null;
+  status: HookStatus;
+  error: Error | null;
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+};
+//#endregion
+export { useFileManagerConfig as a, ApiSuccessResponse as c, UseDeleteFileState as d, UseDownloadUrlState as f, FileManagerProvider as i, FileManagerClientConfig as l, useDeleteFile as n, ApiErrorResponse as o, UseListFilesState as p, useListFiles as r, ApiResponse as s, useDownloadUrl as t, HookStatus as u };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { a as FileManagerConfig, c as ManagedFile, d as StorageFile, i as DownloadUrlOptions, l as PaginatedResponse, n as DatabaseCallbacks, o as FileManagerError, r as DeleteResult, s as ListFilesOptions, t as BatchDeleteResult, u as PaginationOptions } from "./types-Brk9aR7c.js";
+import { a as useFileManagerConfig, c as ApiSuccessResponse, d as UseDeleteFileState, f as UseDownloadUrlState, i as FileManagerProvider, l as FileManagerClientConfig, n as useDeleteFile, o as ApiErrorResponse, p as UseListFilesState, r as useListFiles, s as ApiResponse, t as useDownloadUrl, u as HookStatus } from "./index-pUAG6PPj.js";
+import { a as FileManager, i as createFileManagerRouter, n as FileManagerRouter, r as RouteConfig, t as FileManagerRequest } from "./router-CD_RQnlx.js";
+import "./index-CHmsNSsb.js";
+export { ApiErrorResponse, ApiResponse, ApiSuccessResponse, BatchDeleteResult, DatabaseCallbacks, DeleteResult, DownloadUrlOptions, FileManager, FileManagerClientConfig, FileManagerConfig, FileManagerError, FileManagerProvider, FileManagerRequest, FileManagerRouter, HookStatus, ListFilesOptions, ManagedFile, PaginatedResponse, PaginationOptions, RouteConfig, StorageFile, UseDeleteFileState, UseDownloadUrlState, UseListFilesState, createFileManagerRouter, useDeleteFile, useDownloadUrl, useFileManagerConfig, useListFiles };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { n as createFileManagerRouter, r as FileManager, t as FileManagerRouter } from "./server-CZrPOP0h.js";
+import { a as useFileManagerConfig, i as FileManagerProvider, n as useDeleteFile, r as useListFiles, t as useDownloadUrl } from "./client-DTkToHgY.js";
+
+export { FileManager, FileManagerProvider, FileManagerRouter, createFileManagerRouter, useDeleteFile, useDownloadUrl, useFileManagerConfig, useListFiles };