@muhgholy/next-drive 0.1.0

package/README.md

@@ -0,0 +1,230 @@
+# @muhgholy/next-drive
+
+Robust file storage and management solution for Next.js applications, featuring a responsive UI, advanced search, trash management, and secure file handling.
+
+## Features
+
+-    **File Management**: Upload, rename, move, and organize files and folders.
+-    **Advanced Search**: Search both active files and the trash bin with real-time filtering.
+-    **Trash System**: specialized trash view with soft delete, restore, and empty trash capabilities.
+-    **Responsive UI**: optimized layouts for both desktop (single toolbar) and mobile (search-focused header).
+-    **Video Support**: Auto-generates thumbnails for video files (requires FFmpeg).
+-    **Security**: Signed URLs for secure file access and configurable upload limits.
+-    **View Modes**: Toggle between Grid and List views with custom sorting and grouping.
+
+## Installation
+
+```bash
+npm install @muhgholy/next-drive
+```
+
+**Peer Dependencies:**
+
+-    Next.js >= 14
+-    React >= 18
+-    Mongoose >= 7
+
+**System Requirements:**
+
+-    **FFmpeg**: Required for generating thumbnails from video files.
+     -    MacOS: `brew install ffmpeg`
+     -    Ubuntu: `sudo apt install ffmpeg`
+     -    Windows: Download from official site and add to PATH.
+
+## Quick Start
+
+### 1. Configure Server
+
+Create a configuration file (e.g., `lib/drive.ts`) to set up storage paths, database connection, and security rules.
+
+```typescript
+// lib/drive.ts
+import { driveConfiguration } from "@muhgholy/next-drive/server";
+import type { TDriveConfigInformation } from "@muhgholy/next-drive/server";
+
+export const drive = driveConfiguration({
+	database: "MONGOOSE",
+	storage: { path: "/var/data/drive" },
+	security: {
+		maxUploadSize: 50 * 1024 * 1024, // 50MB
+		allowedMimeTypes: ["image/*", "video/*", "application/pdf"],
+		signedUrls: {
+			enabled: true,
+			secret: process.env.DRIVE_SECRET!,
+			expiresIn: 3600, // 1 hour
+		},
+	},
+	image: {
+		formats: ["webp", "jpeg", "png"],
+		qualities: ["ultralow", "low", "medium", "high", "normal"],
+	},
+	information: async (req): Promise<TDriveConfigInformation> => {
+		// Implement your auth verification here
+		const auth = await verifyAuth(req);
+		return {
+			key: auth ? { userId: auth.userId } : null,
+			storage: { quotaInBytes: 1024 * 1024 * 1024 }, // 1GB limit
+		};
+	},
+});
+```
+
+### 2. Create API Route
+
+Set up the API route handler that `next-drive` will use to communicate with the client.
+
+```typescript
+// pages/api/drive.ts (Pages Router)
+// or app/api/drive/route.ts (App Router)
+
+import { drive } from "@/lib/drive";
+import { driveAPIHandler } from "@muhgholy/next-drive/server";
+
+export default function handler(req, res) {
+	return driveAPIHandler(drive, req, res);
+}
+```
+
+### 3. Add Provider
+
+Wrap your application or the specific route with `DriveProvider`.
+
+```typescript
+// app/layout.tsx
+import { DriveProvider } from "@muhgholy/next-drive/client";
+
+export default function RootLayout({ children }) {
+	return <DriveProvider apiEndpoint="/api/drive">{children}</DriveProvider>;
+}
+```
+
+### 4. Implement UI Components
+
+You can use the built-in `DriveExplorer` for a full file manager experience or `DriveFileChooser` for form inputs.
+
+**Full File Explorer:**
+
+```typescript
+import { DriveExplorer } from "@muhgholy/next-drive/client";
+
+export default function DrivePage() {
+	return <DriveExplorer />;
+}
+```
+
+**File Picker:**
+
+```typescript
+import { DriveFileChooser } from "@muhgholy/next-drive/client";
+import type { TDriveFile } from "@muhgholy/next-drive/client";
+
+function MyForm() {
+	const [file, setFile] = useState<TDriveFile | null>(null);
+
+	return <DriveFileChooser value={file} onChange={setFile} accept="image/*" />;
+}
+```
+
+## Key Capabilities
+
+### Server-Side File Access
+
+**Get File URL:**
+
+```typescript
+import { driveGetUrl } from "@muhgholy/next-drive/server";
+
+// Generate a secure URL
+const url = driveGetUrl(fileId);
+// Returns: /api/drive?action=serve&id={fileId}&token={signedToken}
+
+// With custom expiry (in seconds)
+const url = driveGetUrl(fileId, { expiry: 7200 }); // 2 hours
+
+// With specific expiry date
+const url = driveGetUrl(fileId, { expiry: new Date("2025-12-31") });
+```
+
+**Read File Stream:**
+
+```typescript
+import { driveReadFile } from "@muhgholy/next-drive/server";
+
+// Using file ID
+const { stream, mime, size } = await driveReadFile(fileId);
+stream.pipe(response);
+
+// Using database document
+const drive = await Drive.findById(fileId);
+const { stream, mime, size } = await driveReadFile(drive);
+
+// Example: Send file via email
+const { stream } = await driveReadFile(fileId);
+await sendEmail({
+	attachments: [{ filename: "report.pdf", content: stream }],
+});
+
+// Example: Process file contents
+const { stream } = await driveReadFile(fileId);
+const chunks = [];
+for await (const chunk of stream) {
+	chunks.push(chunk);
+}
+const buffer = Buffer.concat(chunks);
+```
+
+**Get Local File Path:**
+
+For scenarios requiring direct file system access, `driveFilePath()` provides the absolute path. Google Drive files are automatically downloaded to a local cache.
+
+```typescript
+import { driveFilePath } from "@muhgholy/next-drive/server";
+import fs from "fs";
+
+// Get local path (downloads Google Drive files automatically)
+const { path, mime, size, provider } = await driveFilePath(fileId);
+
+// Use with synchronous file operations
+const buffer = fs.readFileSync(path);
+
+// Use with libraries requiring file paths
+await sharp(path).resize(800, 600).toFile("output.jpg");
+await ffmpeg(path).format("mp4").save("output.mp4");
+
+// Google Drive files are cached at: storage/library/google/{fileId}.ext
+// Local files use their original location
+```
+
+### Search & Trash
+
+-    **Search Scope**: Search automatically adapts to your current view. If you are browsing the Trash, searches will query deleted items. In the main Browser, searches query active files.
+-    **Trash Management**: "Delete" moves items to Trash. From Trash, you can "Restore" items or "Delete Forever". A dedicated "Empty Trash" button is available to clear all deleted items.
+
+### Responsive Design
+
+-    **Desktop**: Features a unified single-row header containing Search, Group, Delete, Sort, View, and Trash controls.
+-    **Mobile**: Optimizes for small screens by separating the Search bar into a full-width top row and grouping action buttons in a scrollable toolbar below.
+
+## API Endpoints
+
+All operations use the `?action=` query parameter on your configured API endpoint:
+
+| Action            | Method | Description                                              |
+| ----------------- | ------ | -------------------------------------------------------- |
+| `upload`          | POST   | Chunked file upload handling                             |
+| `list`            | GET    | List files in a folder (supports `trashed` param)        |
+| `serve`           | GET    | Serve file content (supports resizing/format conversion) |
+| `thumbnail`       | GET    | specific endpoint for file thumbnails                    |
+| `rename`          | PATCH  | Rename a file or folder                                  |
+| `trash`           | POST   | Move items to trash (soft delete)                        |
+| `deletePermanent` | DELETE | Permanently remove items                                 |
+| `restore`         | POST   | Restore items from trash                                 |
+| `emptyTrash`      | DELETE | Permanently remove all trashed items                     |
+| `createFolder`    | POST   | Create a new directory                                   |
+| `move`            | POST   | Move files/folders to a new parent                       |
+| `search`          | GET    | Search by name (supports `trashed=true`)                 |
+| `quota`           | GET    | Get current storage usage                                |
+
+## License
+
+MIT

package/dist/client/index.css

@@ -0,0 +1,48 @@
+/* src/client/styles.css */
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 222.2 84% 4.9%;
+  --popover: 0 0% 100%;
+  --popover-foreground: 222.2 84% 4.9%;
+  --primary: 222.2 47.4% 11.2%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  --secondary-foreground: 222.2 47.4% 11.2%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --accent: 210 40% 96.1%;
+  --accent-foreground: 222.2 47.4% 11.2%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 214.3 31.8% 91.4%;
+  --input: 214.3 31.8% 91.4%;
+  --ring: 222.2 84% 4.9%;
+  --radius: 0.5rem;
+}
+.dark {
+  --background: 222.2 84% 4.9%;
+  --foreground: 210 40% 98%;
+  --card: 222.2 84% 4.9%;
+  --card-foreground: 210 40% 98%;
+  --popover: 222.2 84% 4.9%;
+  --popover-foreground: 210 40% 98%;
+  --primary: 210 40% 98%;
+  --primary-foreground: 222.2 47.4% 11.2%;
+  --secondary: 217.2 32.6% 17.5%;
+  --secondary-foreground: 210 40% 98%;
+  --muted: 217.2 32.6% 17.5%;
+  --muted-foreground: 215 20.2% 65.1%;
+  --accent: 217.2 32.6% 17.5%;
+  --accent-foreground: 210 40% 98%;
+  --destructive: 0 62.8% 30.6%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 217.2 32.6% 17.5%;
+  --input: 217.2 32.6% 17.5%;
+  --ring: 212.7 26.8% 83.9%;
+}
+* {
+  border-color: hsl(var(--border));
+}
+/*# sourceMappingURL=index.css.map */

package/dist/client/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/styles.css"],"sourcesContent":[":root {\n    --background: 0 0% 100%;\n    --foreground: 222.2 84% 4.9%;\n\n    --card: 0 0% 100%;\n    --card-foreground: 222.2 84% 4.9%;\n\n    --popover: 0 0% 100%;\n    --popover-foreground: 222.2 84% 4.9%;\n\n    --primary: 222.2 47.4% 11.2%;\n    --primary-foreground: 210 40% 98%;\n\n    --secondary: 210 40% 96.1%;\n    --secondary-foreground: 222.2 47.4% 11.2%;\n\n    --muted: 210 40% 96.1%;\n    --muted-foreground: 215.4 16.3% 46.9%;\n\n    --accent: 210 40% 96.1%;\n    --accent-foreground: 222.2 47.4% 11.2%;\n\n    --destructive: 0 84.2% 60.2%;\n    --destructive-foreground: 210 40% 98%;\n\n    --border: 214.3 31.8% 91.4%;\n    --input: 214.3 31.8% 91.4%;\n    --ring: 222.2 84% 4.9%;\n\n    --radius: 0.5rem;\n}\n\n.dark {\n    --background: 222.2 84% 4.9%;\n    --foreground: 210 40% 98%;\n\n    --card: 222.2 84% 4.9%;\n    --card-foreground: 210 40% 98%;\n\n    --popover: 222.2 84% 4.9%;\n    --popover-foreground: 210 40% 98%;\n\n    --primary: 210 40% 98%;\n    --primary-foreground: 222.2 47.4% 11.2%;\n\n    --secondary: 217.2 32.6% 17.5%;\n    --secondary-foreground: 210 40% 98%;\n\n    --muted: 217.2 32.6% 17.5%;\n    --muted-foreground: 215 20.2% 65.1%;\n\n    --accent: 217.2 32.6% 17.5%;\n    --accent-foreground: 210 40% 98%;\n\n    --destructive: 0 62.8% 30.6%;\n    --destructive-foreground: 210 40% 98%;\n\n    --border: 217.2 32.6% 17.5%;\n    --input: 217.2 32.6% 17.5%;\n    --ring: 212.7 26.8% 83.9%;\n}\n\n* {\n    border-color: hsl(var(--border));\n}"],"mappings":";AAAA;AACI,gBAAc,EAAE,GAAG;AACnB,gBAAc,MAAM,IAAI;AAExB,UAAQ,EAAE,GAAG;AACb,qBAAmB,MAAM,IAAI;AAE7B,aAAW,EAAE,GAAG;AAChB,wBAAsB,MAAM,IAAI;AAEhC,aAAW,MAAM,MAAM;AACvB,wBAAsB,IAAI,IAAI;AAE9B,eAAa,IAAI,IAAI;AACrB,0BAAwB,MAAM,MAAM;AAEpC,WAAS,IAAI,IAAI;AACjB,sBAAoB,MAAM,MAAM;AAEhC,YAAU,IAAI,IAAI;AAClB,uBAAqB,MAAM,MAAM;AAEjC,iBAAe,EAAE,MAAM;AACvB,4BAA0B,IAAI,IAAI;AAElC,YAAU,MAAM,MAAM;AACtB,WAAS,MAAM,MAAM;AACrB,UAAQ,MAAM,IAAI;AAElB,YAAU;AACd;AAEA,CAAC;AACG,gBAAc,MAAM,IAAI;AACxB,gBAAc,IAAI,IAAI;AAEtB,UAAQ,MAAM,IAAI;AAClB,qBAAmB,IAAI,IAAI;AAE3B,aAAW,MAAM,IAAI;AACrB,wBAAsB,IAAI,IAAI;AAE9B,aAAW,IAAI,IAAI;AACnB,wBAAsB,MAAM,MAAM;AAElC,eAAa,MAAM,MAAM;AACzB,0BAAwB,IAAI,IAAI;AAEhC,WAAS,MAAM,MAAM;AACrB,sBAAoB,IAAI,MAAM;AAE9B,YAAU,MAAM,MAAM;AACtB,uBAAqB,IAAI,IAAI;AAE7B,iBAAe,EAAE,MAAM;AACvB,4BAA0B,IAAI,IAAI;AAElC,YAAU,MAAM,MAAM;AACtB,WAAS,MAAM,MAAM;AACrB,UAAQ,MAAM,MAAM;AACxB;AAEA;AACI,gBAAc,IAAI,IAAI;AAC1B;","names":[]}

package/dist/client/index.d.ts

@@ -0,0 +1,128 @@
+import React, { ReactNode } from 'react';
+import { l as TDrivePathItem, d as TDatabaseDrive, m as TDriveQuota, i as TDriveAPIResponse, n as TDriveUploadState, e as TDriveFile } from '../index-DE7-rwJm.js';
+
+type TDriveContext = {
+    apiEndpoint: string;
+    currentFolderId: string | null;
+    path: TDrivePathItem[];
+    items: TDatabaseDrive[];
+    allItems: Record<string, TDatabaseDrive[]>;
+    isLoading: boolean;
+    error: string | null;
+    quota: TDriveQuota | null;
+    accounts: {
+        id: string;
+        name: string;
+        email: string;
+        provider: 'GOOGLE';
+    }[];
+    activeAccountId: string | null;
+    setActiveAccountId: (id: string | null) => void;
+    refreshAccounts: () => Promise<void>;
+    viewMode: 'GRID' | 'LIST';
+    setViewMode: (mode: 'GRID' | 'LIST') => void;
+    currentView: 'BROWSE' | 'TRASH' | 'SEARCH';
+    setCurrentView: (view: 'BROWSE' | 'TRASH' | 'SEARCH') => void;
+    searchQuery: string;
+    setSearchQuery: (query: string) => void;
+    searchScope: 'ACTIVE' | 'TRASH';
+    setSearchScope: (scope: 'ACTIVE' | 'TRASH') => void;
+    groupBy: 'NONE' | 'CREATED_AT';
+    setGroupBy: (group: 'NONE' | 'CREATED_AT') => void;
+    sortBy: {
+        field: string;
+        order: number;
+    };
+    setSortBy: (sort: {
+        field: string;
+        order: number;
+    }) => void;
+    selectionMode: {
+        type: 'SINGLE';
+    } | {
+        type: 'MULTIPLE';
+        maxFile?: number;
+    };
+    selectedFileIds: string[];
+    setSelectedFileIds: React.Dispatch<React.SetStateAction<string[]>>;
+    navigateToFolder: (item: {
+        id: string | null;
+        name: string;
+    } | null) => void;
+    navigateUp: () => void;
+    refreshItems: () => Promise<void>;
+    refreshQuota: () => Promise<void>;
+    moveItem: (itemId: string, targetFolderId: string) => Promise<void>;
+    deleteItems: (ids: string[]) => Promise<void>;
+    callAPI: <T>(action: string, options?: RequestInit & {
+        query?: Record<string, string>;
+    }) => Promise<TDriveAPIResponse<T>>;
+    setItems: (updater: React.SetStateAction<TDatabaseDrive[]>) => void;
+    setAllItems: React.Dispatch<React.SetStateAction<Record<string, TDatabaseDrive[]>>>;
+    loadMore: () => Promise<void>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+};
+declare const DriveProvider: (props: Readonly<{
+    children: ReactNode;
+    apiEndpoint: string;
+    initialActiveAccountId?: string | null;
+    initialSelectionMode?: {
+        type: "SINGLE";
+    } | {
+        type: "MULTIPLE";
+        maxFile?: number;
+    };
+    defaultSelectedFileIds?: string[];
+}>) => React.JSX.Element;
+declare const useDrive: () => TDriveContext;
+
+declare const useUpload: (apiEndpoint: string, activeAccountId: string | null, onUploadComplete?: (item: any) => void) => {
+    uploads: TDriveUploadState[];
+    uploadFiles: (files: File[], folderId: string | null) => Promise<void>;
+    cancelUpload: (id: string) => Promise<void>;
+    cancelAllUploads: () => Promise<void>;
+};
+
+declare const DriveFileChooser: (props: Readonly<{
+    value: TDriveFile | TDriveFile[] | null;
+    onChange: (files: TDriveFile | TDriveFile[] | null) => void;
+    multiple?: boolean;
+    accept?: string;
+    placeholder?: string;
+    className?: string;
+    disabled?: boolean;
+    error?: boolean;
+    helperText?: string;
+}>) => React.JSX.Element;
+
+declare const DriveExplorer: (props: Readonly<{
+    onItemClick?: (item: TDatabaseDrive) => void;
+    onItemDoubleClick?: (item: TDatabaseDrive) => void;
+    mimeFilter?: string;
+    className?: string;
+    selectableFolders?: boolean;
+}>) => React.JSX.Element;
+
+declare const DrivePathBar: () => React.JSX.Element;
+
+declare const DriveUpload: (props: Readonly<{
+    compact?: boolean;
+    onComplete?: (item: unknown) => void;
+}>) => React.JSX.Element;
+
+declare const DriveFilePreview: (props: Readonly<{
+    item: TDatabaseDrive;
+    onClose: () => void;
+}>) => React.JSX.Element | null;
+
+declare const DriveStorageIndicator: (props: Readonly<{
+    compact?: boolean;
+    className?: string;
+}>) => React.JSX.Element | null;
+
+declare const DriveHeader: () => React.JSX.Element;
+
+declare const DriveSidebar: () => React.JSX.Element;
+
+export { DriveExplorer, DriveFileChooser, DriveFilePreview, DriveHeader, DrivePathBar, DriveProvider, DriveSidebar, DriveStorageIndicator, DriveUpload, type TDriveContext, TDriveFile, useDrive, useUpload };