@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

npm install @fatagnus/convex-filesystem

Peer Dependencies

Required:

npm install convex @convex-dev/agent

Optional (for React components):

npm install react @mantine/core @mantine/hooks @tabler/icons-react

Setup

1. Mount the Component

In your convex/convex.config.ts:

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:

# 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

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

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

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

React Hooks

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