managarten/services/matrix-storage-bot/CLAUDE.md

Matrix Storage Bot - Claude Code Guidelines

Overview

Matrix Storage Bot provides cloud storage management via Matrix chat. It integrates with the Storage backend for file/folder management, sharing, favorites, search, and trash operations.

Tech Stack

• Framework: NestJS 10
• Matrix: matrix-bot-sdk
• Backend: Storage API (port 3016)
• Auth: Mana Core Auth (JWT)

Commands

# Development
pnpm install
pnpm start:dev        # Start with hot reload

# Build
pnpm build            # Production build

# Type check
pnpm type-check       # Check TypeScript types

Project Structure

services/matrix-storage-bot/
├── src/
│   ├── main.ts               # Application entry point (port 3323)
│   ├── app.module.ts         # Root module
│   ├── health.controller.ts  # Health check endpoint
│   ├── config/
│   │   └── configuration.ts  # Configuration & help messages
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── matrix.service.ts # Matrix client & command handlers
│   ├── storage/
│   │   ├── storage.module.ts
│   │   └── storage.service.ts # Storage Backend API client
│   └── session/
│       ├── session.module.ts
│       └── session.service.ts  # User session & auth management
├── Dockerfile
└── package.json

Bot Commands

Command	Aliases	Description
!help	hilfe	Show help message
!login email pass	-	Login
!logout	-	Logout
!status	-	Bot status

File Management

Command	Aliases	Description
!dateien	files, ls	List files in root
!dateien [ordner-nr]	-	List files in folder
!datei [nr]	file, info	Show file details
!download [nr]	dl	Get download link
!loeschen [nr]	delete, rm	Move file to trash
!umbenennen [nr] name	rename, mv	Rename file
!verschieben [nr] [ordner-nr]	move	Move to folder

Folder Management

Command	Aliases	Description
!ordner	folders, dir	List root folders
!ordner [nr]	-	List subfolders
!neuordner Name	mkdir, newfolder	Create folder
!neuordner Name [in-nr]	-	Create subfolder
!ordnerloeschen [nr]	rmdir	Delete folder

Sharing

Command	Options	Description
!teilen [nr]	share	Share file (create link)
--tage N	-	Expire in N days
--passwort abc	-	Password protect
--downloads N	-	Limit downloads
!links	shares	List share links
!linkloeschen [nr]	unshare	Delete share link

Organization

Command	Aliases	Description
!suche Begriff	search, find	Search files/folders
!favoriten	favorites, favs	Show favorites
!fav [nr]	favorit	Toggle favorite

Trash

Command	Aliases	Description
!papierkorb	trash	Show trash
!wiederherstellen [nr]	restore	Restore from trash
!leeren	emptytrash	Empty trash

Example Usage

# Login
!login max@example.com mypassword

# List files
!dateien

# Create a folder
!neuordner Dokumente

# List folders
!ordner

# Move file to folder
!verschieben 1 1

# Share a file with expiration
!teilen 1 --tage 7 --passwort geheim

# Search for files
!suche bericht

# View favorites
!favoriten

# Toggle favorite
!fav 1

# View trash
!papierkorb

# Restore from trash
!wiederherstellen 1

Environment Variables

# Server
PORT=3323

# Matrix
MATRIX_HOMESERVER_URL=http://localhost:8008
MATRIX_ACCESS_TOKEN=syt_xxx
MATRIX_ALLOWED_ROOMS=#storage:matrix.mana.how
MATRIX_STORAGE_PATH=./data/bot-storage.json

# Storage Backend
STORAGE_BACKEND_URL=http://localhost:3016
STORAGE_API_PREFIX=/api/v1

# Mana Core Auth
MANA_CORE_AUTH_URL=http://localhost:3001

Docker

# Build locally
docker build -f services/matrix-storage-bot/Dockerfile -t matrix-storage-bot services/matrix-storage-bot

# Run
docker run -p 3323:3323 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e STORAGE_BACKEND_URL=http://storage-backend:3016 \
  -e MANA_CORE_AUTH_URL=http://mana-core-auth:3001 \
  -v matrix-storage-bot-data:/app/data \
  matrix-storage-bot

Health Check

curl http://localhost:3323/health

Storage Backend API Endpoints Used

Endpoint	Method	Description
/api/v1/health	GET	Health check
/api/v1/files	GET	List files
/api/v1/files/:id	GET	Get file details
/api/v1/files/:id/download	GET	Get download URL
/api/v1/files/:id	PATCH	Rename file
/api/v1/files/:id/move	PATCH	Move file
/api/v1/files/:id	DELETE	Delete file
/api/v1/files/:id/favorite	POST	Toggle favorite
/api/v1/folders	GET	List folders
/api/v1/folders	POST	Create folder
/api/v1/folders/:id	DELETE	Delete folder
/api/v1/folders/:id/favorite	POST	Toggle favorite
/api/v1/shares	GET	List shares
/api/v1/shares	POST	Create share
/api/v1/shares/:id	DELETE	Delete share
/api/v1/search	GET	Search files/folders
/api/v1/favorites	GET	Get favorites
/api/v1/trash	GET	List trash
/api/v1/trash/:id/restore	POST	Restore from trash
/api/v1/trash	DELETE	Empty trash

Number-Based Reference System

The bot uses a number-based reference system for ease of use:

1. User runs !dateien or !ordner to get a list
2. Bot stores the list internally for the user
3. User can reference items by their list number
4. Numbers are valid until the user runs a new list command

This allows simple commands like:

• !datei 3 - Show details for file #3
• !download 1 - Get download link for file #1
• !dateien 2 - List files in folder #2
• !verschieben 1 3 - Move file #1 to folder #3