@digibuffer/file-manager-core 1.0.0

package/README.md

@@ -0,0 +1,240 @@
+# @digibuffer/file-manager-core
+
+Complete file management library for cloud storage (R2/S3) with optional PostgreSQL database integration.
+
+## Features
+
+- ✅ **Full CRUD Operations**: List, Move, Rename, Copy, Delete files
+- ✅ **Dual Mode**: Storage-only or Database-backed operations
+- ✅ **PostgreSQL Integration**: Store file metadata in database
+- ✅ **Auto-Sync**: Automatic synchronization between cloud and database
+- ✅ **Batch Operations**: Efficient batch delete and operations
+- ✅ **Presigned URLs**: Generate secure download links
+- ✅ **Pagination**: Built-in cursor-based pagination
+- ✅ **TypeScript**: Full type safety
+- ✅ **Next.js Adapter**: Easy integration with Next.js
+
+## Installation
+
+```bash
+npm install @digibuffer/file-manager-core
+# Optional: for database support
+npm install postgres
+```
+
+## Quick Start
+
+### Storage-Only Mode
+
+```typescript
+import { FileManager } from '@digibuffer/file-manager-core';
+
+const fileManager = new FileManager({
+  storage: {
+    bucket: 'my-bucket',
+    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+    endpoint: process.env.R2_ENDPOINT!,
+  },
+});
+
+// List files
+const files = await fileManager.list({ prefix: 'uploads/' });
+
+// Move file
+await fileManager.move({
+  sourceKey: 'old/path/file.pdf',
+  destinationKey: 'new/path/file.pdf',
+});
+
+// Copy file
+await fileManager.copy({
+  sourceKey: 'original.pdf',
+  destinationKey: 'copy.pdf',
+});
+
+// Delete file
+await fileManager.delete('file-to-delete.pdf');
+```
+
+### Database Mode (with PostgreSQL)
+
+```typescript
+import { FileManager } from '@digibuffer/file-manager-core';
+
+const fileManager = new FileManager({
+  storage: {
+    bucket: 'my-bucket',
+    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+    endpoint: process.env.R2_ENDPOINT!,
+  },
+  database: {
+    connectionString: process.env.DATABASE_URL,
+    tableName: 'files', // optional, defaults to 'files'
+  },
+  defaultSource: 'database', // 'storage' | 'database' | 'both'
+  autoSync: true, // auto-sync storage changes to database
+});
+
+// List from database (faster)
+const files = await fileManager.list({ prefix: 'uploads/' });
+
+// List from both and merge
+const allFiles = await fileManager.list({}, 'both');
+
+// Sync storage to database
+await fileManager.syncToDatabase();
+```
+
+## API Reference
+
+### Core Methods
+
+#### `list(options, source?)`
+List files with pagination and filtering.
+
+```typescript
+const result = await fileManager.list({
+  prefix: 'folder/',
+  maxKeys: 100,
+  sortBy: 'lastModified',
+  sortOrder: 'desc',
+});
+```
+
+#### `move(options)`
+Move a file to a new location.
+
+```typescript
+await fileManager.move({
+  sourceKey: 'old/file.pdf',
+  destinationKey: 'new/file.pdf',
+});
+```
+
+#### `copy(options)`
+Copy a file to a new location.
+
+```typescript
+await fileManager.copy({
+  sourceKey: 'original.pdf',
+  destinationKey: 'copy.pdf',
+  metadata: { copied: 'true' },
+});
+```
+
+#### `rename(oldKey, newKey)`
+Rename a file (alias for move).
+
+```typescript
+await fileManager.rename('old-name.pdf', 'new-name.pdf');
+```
+
+#### `delete(key)`
+Delete a single file.
+
+```typescript
+await fileManager.delete('file.pdf');
+```
+
+#### `deleteBatch(keys)`
+Delete multiple files.
+
+```typescript
+await fileManager.deleteBatch(['file1.pdf', 'file2.pdf']);
+```
+
+#### `getDownloadUrl(key, options?)`
+Generate presigned download URL.
+
+```typescript
+const url = await fileManager.getDownloadUrl('file.pdf', {
+  expiresIn: 3600,
+  disposition: 'attachment',
+  filename: 'download.pdf',
+});
+```
+
+#### `exists(key, source?)`
+Check if file exists.
+
+```typescript
+const exists = await fileManager.exists('file.pdf');
+```
+
+#### `getMetadata(key, source?)`
+Get file metadata.
+
+```typescript
+const metadata = await fileManager.getMetadata('file.pdf');
+```
+
+### Next.js Integration
+
+```typescript
+// app/api/files/route.ts
+import { FileManager, createFileManagerRouter } from '@digibuffer/file-manager-core';
+import { toRouteHandler, withCors } from '@digibuffer/file-manager-core/adapters/next';
+
+const fileManager = new FileManager({
+  storage: { /* config */ },
+  database: { /* config */ },
+});
+
+const router = createFileManagerRouter({
+  fileManager,
+  authorize: async (context, operation, resource) => {
+    // Your authorization logic
+    return true;
+  },
+  getAuthContext: async (request) => {
+    // Extract user from session/token
+    return { userId: 'user-123' };
+  },
+});
+
+export const POST = withCors(toRouteHandler(router));
+```
+
+### Operation Hooks
+
+```typescript
+const fileManager = new FileManager(config, {
+  beforeDelete: async (keys) => {
+    console.log('About to delete:', keys);
+  },
+  afterDelete: async (keys) => {
+    console.log('Deleted:', keys);
+  },
+  beforeMove: async (options) => {
+    console.log('Moving:', options);
+  },
+  afterMove: async (options) => {
+    console.log('Moved:', options);
+  },
+});
+```
+
+## Database Schema
+
+The library automatically creates this table:
+
+```sql
+CREATE TABLE files (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  key TEXT NOT NULL UNIQUE,
+  size BIGINT NOT NULL,
+  content_type TEXT,
+  etag TEXT,
+  user_id TEXT,
+  custom_metadata JSONB,
+  last_modified TIMESTAMP NOT NULL,
+  uploaded_at TIMESTAMP NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+```
+
+## License
+
+MIT

package/dist/adapters/next.d.ts

@@ -0,0 +1,24 @@
+import { t as FileManagerRouter } from "../router-CY6g7nWy.js";
+import { NextRequest } from "next/server";
+
+//#region src/adapters/next.d.ts
+
+/**
+ * Convert FileManagerRouter to Next.js App Router handler
+ */
+declare function toRouteHandler(router: FileManagerRouter): (request: NextRequest) => Promise<Response>;
+/**
+ * CORS options
+ */
+interface CorsOptions {
+  origin?: string | string[];
+  methods?: string[];
+  allowedHeaders?: string[];
+  credentials?: boolean;
+}
+/**
+ * Add CORS headers to handler
+ */
+declare function withCors<T extends Request = Request>(handler: (request: T) => Promise<Response>, options?: CorsOptions): (request: T) => Promise<Response>;
+//#endregion
+export { toRouteHandler, withCors };

package/dist/adapters/next.js

@@ -0,0 +1,46 @@
+import "../router-De_vaLLo.js";
+
+//#region src/adapters/next.ts
+/**
+* Convert FileManagerRouter to Next.js App Router handler
+*/
+function toRouteHandler(router) {
+	return async (request) => {
+		return router.handle(request);
+	};
+}
+/**
+* Add CORS headers to handler
+*/
+function withCors(handler, options = {}) {
+	const { origin = "*", methods = [
+		"GET",
+		"POST",
+		"PUT",
+		"DELETE",
+		"OPTIONS"
+	], allowedHeaders = ["Content-Type", "Authorization"], credentials = false } = options;
+	return async (request) => {
+		if (request.method === "OPTIONS") return new Response(null, {
+			status: 204,
+			headers: {
+				"Access-Control-Allow-Origin": Array.isArray(origin) ? origin[0] : origin,
+				"Access-Control-Allow-Methods": methods.join(", "),
+				"Access-Control-Allow-Headers": allowedHeaders.join(", "),
+				...credentials && { "Access-Control-Allow-Credentials": "true" }
+			}
+		});
+		const response = await handler(request);
+		const corsHeaders = new Headers(response.headers);
+		corsHeaders.set("Access-Control-Allow-Origin", Array.isArray(origin) ? origin[0] : origin);
+		if (credentials) corsHeaders.set("Access-Control-Allow-Credentials", "true");
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: corsHeaders
+		});
+	};
+}
+
+//#endregion
+export { toRouteHandler, withCors };

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { C as PaginatedResponse, D as StorageFile, E as StorageConfig, O as StorageProvider, S as OperationResult, T as RequestAction, _ as FileOperationResponse, a as AuthorizationCallback, b as MoveOptions, c as DataSource, d as DatabaseProvider, f as DownloadUrlOptions, g as FileOperationRequest, h as FileMetadata, i as AuthContext, l as DatabaseConfig, m as FileManagerError, n as createFileManagerRouter, o as BatchOperationResult, p as FileManagerConfig, r as FileManager, s as CopyOptions, t as FileManagerRouter, u as DatabaseFile, v as ListOptions, w as PaginationCursor, x as OperationHooks, y as ManagedFile } from "./router-CY6g7nWy.js";
+
+//#region src/storage/s3-provider.d.ts
+
+/**
+ * S3/R2 Storage Provider Implementation
+ */
+declare class S3StorageProvider implements StorageProvider {
+  private config;
+  constructor(config: StorageConfig);
+  /**
+   * List files from S3/R2 storage
+   */
+  list(options?: ListOptions): Promise<PaginatedResponse<StorageFile>>;
+  /**
+   * Delete a single file
+   */
+  delete(key: string): Promise<OperationResult>;
+  /**
+   * Delete multiple files in batch
+   */
+  deleteBatch(keys: string[]): Promise<BatchOperationResult>;
+  /**
+   * Check if file exists
+   */
+  exists(key: string): Promise<boolean>;
+  /**
+   * Get file metadata
+   */
+  getMetadata(key: string): Promise<StorageFile | null>;
+  /**
+   * Generate presigned download URL
+   */
+  getDownloadUrl(key: string, options?: DownloadUrlOptions): Promise<string>;
+  /**
+   * Move a file (copy + delete source)
+   */
+  move(options: MoveOptions): Promise<OperationResult>;
+  /**
+   * Copy a file to a new location
+   */
+  copy(options: CopyOptions): Promise<OperationResult>;
+  /**
+   * Rename a file (same as move)
+   */
+  rename(oldKey: string, newKey: string): Promise<OperationResult>;
+  /**
+   * Parse XML list response
+   */
+  private parseListResponse;
+  /**
+   * Extract continuation token from XML
+   */
+  private extractContinuationToken;
+  /**
+   * Extract value from XML tag
+   */
+  private extractXmlValue;
+  /**
+   * Sort files by specified field
+   */
+  private sortFiles;
+}
+//#endregion
+//#region src/database/postgres-provider.d.ts
+/**
+ * PostgreSQL Database Provider Implementation
+ */
+declare class PostgresDatabaseProvider implements DatabaseProvider {
+  private sql;
+  private tableName;
+  constructor(config: DatabaseConfig);
+  /**
+   * Initialize PostgreSQL connection
+   */
+  private initializeConnection;
+  /**
+   * Create files table if it doesn't exist
+   */
+  private ensureTableExists;
+  /**
+   * List files from database
+   */
+  list(options?: ListOptions): Promise<PaginatedResponse<DatabaseFile>>;
+  /**
+   * Get a single file by key
+   */
+  get(key: string): Promise<DatabaseFile | null>;
+  /**
+   * Create a new file record
+   */
+  create(file: Omit<DatabaseFile, 'id' | 'uploadedAt' | 'updatedAt'>): Promise<DatabaseFile>;
+  /**
+   * Update file metadata
+   */
+  update(key: string, data: Partial<DatabaseFile>): Promise<DatabaseFile | null>;
+  /**
+   * Delete a file record
+   */
+  delete(key: string): Promise<OperationResult>;
+  /**
+   * Delete multiple file records
+   */
+  deleteBatch(keys: string[]): Promise<BatchOperationResult>;
+  /**
+   * Check if file exists
+   */
+  exists(key: string): Promise<boolean>;
+  /**
+   * Sync storage files to database
+   */
+  sync(storageFiles: StorageFile[]): Promise<void>;
+  /**
+   * Get sort column for SQL query
+   */
+  private getSortColumn;
+  /**
+   * Close database connection
+   */
+  close(): Promise<void>;
+}
+//#endregion
+export { type AuthContext, type AuthorizationCallback, type BatchOperationResult, type CopyOptions, type DataSource, type DatabaseConfig, type DatabaseFile, type DatabaseProvider, type DownloadUrlOptions, FileManager, type FileManagerConfig, FileManagerError, FileManagerRouter, type FileMetadata, type FileOperationRequest, type FileOperationResponse, type ListOptions, type ManagedFile, type MoveOptions, type OperationHooks, type OperationResult, type PaginatedResponse, type PaginationCursor, PostgresDatabaseProvider, type RequestAction, S3StorageProvider, type StorageConfig, type StorageFile, type StorageProvider, createFileManagerRouter };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { a as S3StorageProvider, i as PostgresDatabaseProvider, n as createFileManagerRouter, o as FileManagerError, r as FileManager, t as FileManagerRouter } from "./router-De_vaLLo.js";
+
+export { FileManager, FileManagerError, FileManagerRouter, PostgresDatabaseProvider, S3StorageProvider, createFileManagerRouter };