# @manacore/bot-services Shared business logic services for Matrix bots and the Gateway. ## Purpose This package provides **transport-agnostic** services that contain all business logic for the Matrix bot ecosystem. Services in this package: - Have no Matrix-specific code - Can be used by individual bots OR the unified Gateway - Support pluggable storage (file-based, in-memory, database) - Are fully testable in isolation ## Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ @manacore/bot-services │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ TodoService │ │ CalendarSvc │ │ AiService │ │ ClockService│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ Pure business logic - no Matrix code! │ └─────────────────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Gateway │ │ Todo Bot │ │ CLI │ │ (Matrix) │ │ (Matrix) │ │ Tool │ └──────────┘ └──────────┘ └──────────┘ ``` ## Available Services ### Business Logic Services | Service | Storage | Description | |---------|---------|-------------| | `TodoService` | File (JSON) | Task management with projects, priorities, dates | | `CalendarService` | File (JSON) | Events, calendars, reminders | | `AiService` | In-memory | Ollama LLM integration, chat sessions, vision | | `ClockService` | External API | Timers, alarms, world clocks | ### Infrastructure Services | Service | Storage | Description | |---------|---------|-------------| | `SessionService` | In-memory | User authentication via mana-core-auth | | `TranscriptionService` | External API | Speech-to-text via mana-stt service | ### Placeholder Services (to be implemented) | Service | Description | |---------|-------------| | `NutritionService` | Meal tracking | | `QuotesService` | Daily quotes | | `StatsService` | Analytics reports | | `DocsService` | Documentation generation | ## Usage ### In NestJS (Bot or Gateway) ```typescript import { Module } from '@nestjs/common'; import { TodoModule, CalendarModule, AiModule, ClockModule, SessionModule, TranscriptionModule, } from '@manacore/bot-services'; @Module({ imports: [ // File-based storage (default) TodoModule.register({ storagePath: './data/todos.json' }), CalendarModule.register({ storagePath: './data/calendar.json' }), // External services AiModule.register({ baseUrl: 'http://ollama:11434' }), ClockModule.register({ apiUrl: 'http://clock-backend:3017/api/v1' }), // Infrastructure services (use ConfigService by default) SessionModule.forRoot(), TranscriptionModule.forRoot(), ], }) export class AppModule {} ``` ### Session Service (Authentication) ```typescript import { SessionService } from '@manacore/bot-services'; // Login a Matrix user const result = await sessionService.login( '@user:matrix.org', 'email@example.com', 'password' ); if (result.success) { // Get token for API calls const token = sessionService.getToken('@user:matrix.org'); // Check if logged in const isLoggedIn = sessionService.isLoggedIn('@user:matrix.org'); } // Logout sessionService.logout('@user:matrix.org'); // Store custom session data sessionService.setSessionData('@user:matrix.org', 'currentConversationId', 'abc123'); const convId = sessionService.getSessionData('@user:matrix.org', 'currentConversationId'); ``` ### Transcription Service (Speech-to-Text) ```typescript import { TranscriptionService, TranscriptionModule } from '@manacore/bot-services'; // Module registration with API key TranscriptionModule.register({ sttUrl: 'http://mana-stt:3020', apiKey: process.env.STT_API_KEY, // Optional: for authenticated STT service defaultLanguage: 'de' }) // Or use forRoot() which reads from config: // - stt.url / STT_URL // - stt.apiKey / STT_API_KEY // Transcribe audio buffer const text = await transcriptionService.transcribe(audioBuffer, { language: 'de' }); // Get full response with metadata const result = await transcriptionService.transcribeWithMetadata(audioBuffer); console.log(result.text, result.language, result.model); // Health check const isHealthy = await transcriptionService.checkHealth(); ``` ### Direct Service Usage ```typescript import { TodoService } from '@manacore/bot-services/todo'; import { AiService } from '@manacore/bot-services/ai'; // Create task const task = await todoService.createTask('@user:matrix.org', { title: 'Buy groceries', priority: 2, dueDate: '2025-01-30', }); // AI chat const response = await aiService.chatSimple('@user:matrix.org', 'What is TypeScript?'); ``` ### Custom Storage Provider ```typescript import { TodoModule, StorageProvider, TodoData } from '@manacore/bot-services'; // PostgreSQL storage example class PostgresTodoStorage implements StorageProvider { async load(): Promise { // Load from database } async save(data: TodoData): Promise { // Save to database } } // Use custom storage TodoModule.forRoot(new PostgresTodoStorage()); ``` ## Input Parsing Services include German-language natural input parsing: ### Todo ```typescript const parsed = todoService.parseTaskInput('Einkaufen !p1 @morgen #haushalt'); // { title: 'Einkaufen', priority: 1, dueDate: '2025-01-30', project: 'haushalt' } ``` ### Calendar ```typescript const parsed = calendarService.parseEventInput('Meeting morgen um 14:30'); // { title: 'Meeting', startTime: Date, endTime: Date, isAllDay: false } ``` ### Clock ```typescript const seconds = clockService.parseDuration('1h30m'); // 5400 const time = clockService.parseAlarmTime('14 Uhr 30'); // '14:30:00' ``` ## Development ```bash # Type check pnpm --filter @manacore/bot-services type-check # Install in a bot pnpm --filter matrix-todo-bot add @manacore/bot-services ``` ## Adding New Services 1. Create directory: `src/{service}/` 2. Add files: - `types.ts` - Interfaces and types - `{service}.service.ts` - Business logic - `{service}.module.ts` - NestJS module - `index.ts` - Exports 3. Export from `src/index.ts` 4. Update `package.json` exports ## File Structure ``` packages/bot-services/ ├── src/ │ ├── index.ts # Main exports │ ├── shared/ │ │ ├── types.ts # Common types │ │ ├── storage.ts # Storage providers │ │ ├── utils.ts # Utility functions │ │ └── index.ts │ ├── todo/ │ ├── calendar/ │ ├── ai/ │ ├── clock/ │ ├── session/ # NEW: User authentication │ │ ├── types.ts │ │ ├── session.service.ts │ │ ├── session.module.ts │ │ └── index.ts │ ├── transcription/ # NEW: Speech-to-text │ │ ├── types.ts │ │ ├── transcription.service.ts │ │ ├── transcription.module.ts │ │ └── index.ts │ └── ... ├── package.json ├── tsconfig.json └── CLAUDE.md ``` ## Migrating Bots to Shared Services To migrate a bot from local services to shared services: ### 1. Add dependency ```bash # In package.json "dependencies": { "@manacore/bot-services": "workspace:*", ... } ``` ### 2. Update module imports ```typescript // bot.module.ts - BEFORE import { SessionModule } from '../session/session.module'; import { TranscriptionModule } from '../transcription/transcription.module'; @Module({ imports: [SessionModule, TranscriptionModule], }) // bot.module.ts - AFTER import { SessionModule, TranscriptionModule } from '@manacore/bot-services'; @Module({ imports: [SessionModule.forRoot(), TranscriptionModule.forRoot()], }) ``` ### 3. Update service imports ```typescript // matrix.service.ts - BEFORE import { SessionService } from '../session/session.service'; import { TranscriptionService } from '../transcription/transcription.service'; // matrix.service.ts - AFTER import { SessionService, TranscriptionService } from '@manacore/bot-services'; ``` ### 4. Delete local modules ```bash rm -rf src/session/ rm -rf src/transcription/ ``` ### Migrated Bots | Bot | SessionService | TranscriptionService | |-----|----------------|---------------------| | matrix-todo-bot | - | ✅ | | matrix-picture-bot | ✅ | - | | matrix-clock-bot | - | ✅ | | matrix-zitare-bot | ✅ | ✅ | | matrix-chat-bot | ✅ | - | | matrix-contacts-bot | ✅ | - | | matrix-nutriphi-bot | ✅ | ✅ | | matrix-project-doc-bot | - | ✅ | | matrix-skilltree-bot | ✅ | - | | matrix-presi-bot | ✅ | - | | matrix-questions-bot | ✅ | - | | matrix-storage-bot | ✅ | - | | matrix-planta-bot | ✅ | - | | matrix-manadeck-bot | ✅ | - | **All bots with SessionService and TranscriptionService have been migrated.**