npm package: @fatagnus/convex-filesystem
Description: Convex component for collaborative filesystem management with folders, file uploads, granular sharing permissions, Google Drive link integration, and AI-powered semantic search
Author: Ozan Turksever
Latest version: 0.1.0

# @fatagnus/convex-filesystem

A standalone Convex component that provides collaborative filesystem management with folders, file uploads, granular sharing permissions, Google Drive link integration, and AI-powered semantic search.

## Features

- **Folder Management**: Create, rename, move, and delete folders with unlimited nesting
- **File Storage**: Upload files to Convex storage with CDN support
- **File Versioning**: Automatic version history with configurable retention
- **Sharing & Permissions**: Granular permissions (view, comment, edit, admin) with inheritance
- **Google Drive Integration**: Link Google Drive documents with content caching
- **Semantic Search**: AI-powered search using embeddings for content discovery
- **Comments**: Threaded comments on files for collaboration
- **React Components**: Ready-to-use UI components built with Mantine

## Installation

```bash
npm install @fatagnus/convex-filesystem
```

### Peer Dependencies

Required:
```bash
npm install convex @convex-dev/agent
```

Optional (for React components):
```bash
npm install react @mantine/core @mantine/hooks @tabler/icons-react
```

## Setup

### 1. Mount the Component

In your `convex/convex.config.ts`:

```typescript
import { defineApp } from "convex/server";
import filesystem from "@fatagnus/convex-filesystem/convex.config";

const app = defineApp();
app.use(filesystem);

export default app;
```

### 2. Configure API Keys (Optional)

For semantic search and Google Drive content fetching, set environment variables:

```bash
# For semantic search embeddings
OPENROUTER_API_KEY=your_openrouter_key

# For Google Drive content fetching
GOOGLE_API_KEY=your_google_api_key
```

## Usage

### Convex Functions

```typescript
import { api } from "./_generated/api";

// Create a folder
await ctx.runMutation(api.filesystem.folders.create, {
  name: "Documents",
  organizationId: "org_123",
});

// Upload a file
const uploadUrl = await ctx.runMutation(api.filesystem.files.generateUploadUrl);
// ... upload file to URL ...
await ctx.runMutation(api.filesystem.files.create, {
  name: "report.pdf",
  folderId: folderId,
  storageId: storageId,
  size: fileSize,
  mimeType: "application/pdf",
});

// Share a folder
await ctx.runMutation(api.filesystem.sharing.share, {
  resourceType: "folder",
  resourceId: folderId,
  shareType: "organization",
  targetId: "org_456",
  permission: "view",
});
```

### React Components

```tsx
import { FileManager } from "@fatagnus/convex-filesystem/react";

function App() {
  return (
    <FileManager
      organizationId="org_123"
      userId="user_456"
    />
  );
}
```

### React Hooks

```tsx
import { useFiles, useFolders, useSharing } from "@fatagnus/convex-filesystem/react";

function MyFileList({ folderId }) {
  const { files, isLoading, upload, deleteFile } = useFiles(folderId);
  const { folders, createFolder } = useFolders(folderId);
  const { shares, permission, canEdit } = useSharing("folder", folderId);

  // ... your UI
}
```

## API Reference

### Folders

- `folders.create` - Create a new folder
- `folders.rename` - Rename a folder
- `folders.move` - Move a folder to a new parent
- `folders.delete` - Soft delete a folder and its contents
- `folders.list` - List folders in a parent
- `folders.get` - Get a folder by ID
- `folders.getPath` - Get folder ancestors for breadcrumbs

### Files

- `files.generateUploadUrl` - Get a signed upload URL
- `files.create` - Create file record after upload
- `files.getDownloadUrl` - Get a signed download URL
- `files.rename` - Rename a file
- `files.move` - Move a file to a new folder
- `files.delete` - Soft delete a file
- `files.restore` - Restore a soft-deleted file
- `files.permanentDelete` - Permanently delete a file
- `files.list` - List files in a folder
- `files.listDeleted` - List soft-deleted files (trash)
- `files.listVersions` - List file versions
- `files.restoreVersion` - Restore a previous version

### Sharing

- `sharing.share` - Share a resource with a user or organization
- `sharing.unshare` - Remove a share
- `sharing.updatePermission` - Update share permission level
- `sharing.listShares` - List shares for a resource
- `sharing.getEffectivePermission` - Get user's effective permission

### Comments

- `comments.create` - Add a comment to a file
- `comments.update` - Update own comment
- `comments.delete` - Delete a comment
- `comments.list` - List comments on a file

### Google Drive

- `googleDrive.create` - Link a Google Drive document
- `googleDrive.delete` - Remove a link
- `googleDrive.list` - List links in a folder
- `googleDrive.fetchContent` - Fetch and cache document content

### Search

- `search.searchByName` - Search files by name
- `search.semanticSearch` - AI-powered semantic search

## License

Apache-2.0