♻️ refactor: consolidate SessionService & TranscriptionService in @manacore/bot-services

Created shared services to eliminate code duplication across Matrix bots:

**New Services in @manacore/bot-services:**
- SessionService: User authentication via mana-core-auth (was duplicated in 11 bots)
- TranscriptionService: Speech-to-text via mana-stt (was duplicated in 6 bots)

**Migrated Bots:**
- matrix-todo-bot: uses TranscriptionService
- matrix-picture-bot: uses SessionService
- matrix-clock-bot: uses TranscriptionService
- matrix-zitare-bot: uses both SessionService & TranscriptionService

**Code Reduction:**
- Removed ~300 lines of duplicate code from migrated bots
- Centralized service configuration via NestJS modules
- Added comprehensive documentation in CLAUDE.md

Remaining bots can be migrated following the same pattern documented
in packages/bot-services/CLAUDE.md.

Note: @storage/backend type-check fails due to pre-existing drizzle-orm issue

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

packages/bot-services/src/index.ts

@@ -40,7 +40,12 @@ export type {
 } from './todo';
 
 // Calendar
-export { CalendarModule, CalendarModuleOptions, CalendarService, CALENDAR_STORAGE_PROVIDER } from './calendar';
+export {
+	CalendarModule,
+	CalendarModuleOptions,
+	CalendarService,
+	CALENDAR_STORAGE_PROVIDER,
+} from './calendar';
 export type {
 	CalendarEvent,
 	Calendar,
@@ -79,6 +84,23 @@ export type {
 	TimeTrackingSummary,
 } from './clock';
 
+// Session (User authentication via mana-core-auth)
+export {
+	SessionModule,
+	SessionService,
+	SESSION_MODULE_OPTIONS,
+	DEFAULT_SESSION_EXPIRY_MS,
+} from './session';
+export type { UserSession, LoginResult, SessionStats, SessionModuleOptions } from './session';
+
+// Transcription (Speech-to-Text via mana-stt)
+export { TranscriptionModule, TranscriptionService, STT_MODULE_OPTIONS } from './transcription';
+export type {
+	SttResponse,
+	TranscriptionOptions,
+	TranscriptionModuleOptions,
+} from './transcription';
+
 // ===== Placeholder Services (to be implemented) =====
 
 export { NutritionModule } from './nutrition';
@@ -96,7 +118,18 @@ export type { DocsServiceConfig, ProjectDoc } from './docs';
 // ===== Shared Utilities =====
 
 export { FileStorageProvider, MemoryStorageProvider } from './shared';
-export type { StorageProvider, BaseEntity, UserEntity, ServiceConfig, Result, PaginationOptions, PaginatedResult, DateRange, Priority, ServiceStats } from './shared';
+export type {
+	StorageProvider,
+	BaseEntity,
+	UserEntity,
+	ServiceConfig,
+	Result,
+	PaginationOptions,
+	PaginatedResult,
+	DateRange,
+	Priority,
+	ServiceStats,
+} from './shared';
 export {
 	generateId,
 	getTodayISO,

packages/bot-services/src/session/index.ts

@@ -0,0 +1,4 @@
+export { SessionService } from './session.service';
+export { SessionModule } from './session.module';
+export type { UserSession, LoginResult, SessionStats, SessionModuleOptions } from './types';
+export { SESSION_MODULE_OPTIONS, DEFAULT_SESSION_EXPIRY_MS } from './types';

packages/bot-services/src/session/session.module.ts

@@ -0,0 +1,62 @@
+import { Module, DynamicModule, Global } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { SessionService } from './session.service';
+import { SessionModuleOptions, SESSION_MODULE_OPTIONS } from './types';
+
+/**
+ * Shared session management module for Matrix bots
+ *
+ * Provides SessionService for managing user authentication sessions.
+ * Links Matrix user IDs to mana-core-auth JWT tokens.
+ *
+ * @example
+ * ```typescript
+ * // With explicit configuration
+ * @Module({
+ *   imports: [
+ *     SessionModule.register({
+ *       authUrl: 'http://mana-core-auth:3001',
+ *       sessionExpiryMs: 7 * 24 * 60 * 60 * 1000 // 7 days
+ *     })
+ *   ]
+ * })
+ *
+ * // With ConfigService (reads from auth.url or MANA_CORE_AUTH_URL)
+ * @Module({
+ *   imports: [SessionModule.forRoot()]
+ * })
+ * ```
+ */
+@Global()
+@Module({})
+export class SessionModule {
+	/**
+	 * Register module with explicit options
+	 */
+	static register(options: SessionModuleOptions = {}): DynamicModule {
+		return {
+			module: SessionModule,
+			imports: [ConfigModule],
+			providers: [
+				{
+					provide: SESSION_MODULE_OPTIONS,
+					useValue: options,
+				},
+				SessionService,
+			],
+			exports: [SessionService],
+		};
+	}
+
+	/**
+	 * Register module with ConfigService (reads auth.url or MANA_CORE_AUTH_URL from config)
+	 */
+	static forRoot(): DynamicModule {
+		return {
+			module: SessionModule,
+			imports: [ConfigModule],
+			providers: [SessionService],
+			exports: [SessionService],
+		};
+	}
+}

packages/bot-services/src/session/session.service.ts

@@ -0,0 +1,235 @@
+import { Injectable, Inject, Logger, Optional } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import {
+	UserSession,
+	LoginResult,
+	SessionStats,
+	SessionModuleOptions,
+	SESSION_MODULE_OPTIONS,
+	DEFAULT_SESSION_EXPIRY_MS,
+} from './types';
+
+/**
+ * Shared session management service for Matrix bots
+ *
+ * Manages user authentication sessions linking Matrix user IDs to mana-core-auth JWT tokens.
+ * Sessions are stored in-memory and automatically expire.
+ *
+ * @example
+ * ```typescript
+ * // In NestJS module
+ * imports: [SessionModule.register({ authUrl: 'http://mana-core-auth:3001' })]
+ *
+ * // In service/controller
+ * const result = await sessionService.login(matrixUserId, email, password);
+ * const token = sessionService.getToken(matrixUserId);
+ * ```
+ */
+@Injectable()
+export class SessionService {
+	private readonly logger = new Logger(SessionService.name);
+	private sessions: Map<string, UserSession> = new Map();
+	private readonly authUrl: string;
+	private readonly sessionExpiryMs: number;
+	private readonly loginPath: string;
+
+	constructor(
+		@Optional() private configService: ConfigService,
+		@Optional() @Inject(SESSION_MODULE_OPTIONS) private options?: SessionModuleOptions
+	) {
+		// Priority: module options > config > environment > default
+		this.authUrl =
+			options?.authUrl ||
+			this.configService?.get<string>('auth.url') ||
+			this.configService?.get<string>('MANA_CORE_AUTH_URL') ||
+			'http://localhost:3001';
+
+		this.sessionExpiryMs = options?.sessionExpiryMs || DEFAULT_SESSION_EXPIRY_MS;
+		this.loginPath = options?.loginPath || '/api/v1/auth/login';
+
+		this.logger.log(`Auth URL: ${this.authUrl}`);
+	}
+
+	/**
+	 * Login a Matrix user with mana-core-auth credentials
+	 *
+	 * @param matrixUserId - Matrix user ID (e.g., "@user:matrix.mana.how")
+	 * @param email - User's email
+	 * @param password - User's password
+	 * @returns Login result with success status
+	 */
+	async login(matrixUserId: string, email: string, password: string): Promise<LoginResult> {
+		try {
+			const response = await fetch(`${this.authUrl}${this.loginPath}`, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify({ email, password }),
+			});
+
+			if (!response.ok) {
+				const errorData = (await response.json().catch(() => ({}))) as { message?: string };
+				return {
+					success: false,
+					error: errorData.message || 'Authentifizierung fehlgeschlagen',
+				};
+			}
+
+			const data = (await response.json()) as { accessToken?: string; token?: string };
+			const token = data.accessToken || data.token;
+
+			if (!token) {
+				return { success: false, error: 'Kein Token erhalten' };
+			}
+
+			// Store session with expiry
+			this.sessions.set(matrixUserId, {
+				token,
+				email,
+				expiresAt: new Date(Date.now() + this.sessionExpiryMs),
+			});
+
+			this.logger.log(`User ${matrixUserId} logged in as ${email}`);
+			return { success: true, email };
+		} catch (error) {
+			this.logger.error(`Login failed for ${matrixUserId}:`, error);
+			return {
+				success: false,
+				error: 'Verbindung zum Auth-Server fehlgeschlagen',
+			};
+		}
+	}
+
+	/**
+	 * Logout a Matrix user
+	 */
+	logout(matrixUserId: string): void {
+		this.sessions.delete(matrixUserId);
+		this.logger.log(`User ${matrixUserId} logged out`);
+	}
+
+	/**
+	 * Get JWT token for a Matrix user (null if not logged in or expired)
+	 */
+	getToken(matrixUserId: string): string | null {
+		const session = this.sessions.get(matrixUserId);
+
+		if (!session) return null;
+
+		// Check if token expired
+		if (session.expiresAt < new Date()) {
+			this.sessions.delete(matrixUserId);
+			return null;
+		}
+
+		return session.token;
+	}
+
+	/**
+	 * Check if a Matrix user is logged in
+	 */
+	isLoggedIn(matrixUserId: string): boolean {
+		return this.getToken(matrixUserId) !== null;
+	}
+
+	/**
+	 * Get the full session object for a Matrix user
+	 */
+	getSession(matrixUserId: string): UserSession | null {
+		const token = this.getToken(matrixUserId); // This handles expiry check
+		if (!token) return null;
+		return this.sessions.get(matrixUserId) || null;
+	}
+
+	/**
+	 * Get email for a logged-in Matrix user
+	 */
+	getEmail(matrixUserId: string): string | null {
+		const session = this.getSession(matrixUserId);
+		return session?.email || null;
+	}
+
+	/**
+	 * Store custom data in a user's session
+	 */
+	setSessionData(matrixUserId: string, key: string, value: unknown): void {
+		const session = this.sessions.get(matrixUserId);
+		if (session) {
+			session.data = session.data || {};
+			session.data[key] = value;
+		}
+	}
+
+	/**
+	 * Get custom data from a user's session
+	 */
+	getSessionData<T = unknown>(matrixUserId: string, key: string): T | null {
+		const session = this.getSession(matrixUserId);
+		return (session?.data?.[key] as T) || null;
+	}
+
+	/**
+	 * Get total session count (including expired)
+	 */
+	getSessionCount(): number {
+		return this.sessions.size;
+	}
+
+	/**
+	 * Get count of active (non-expired) sessions
+	 */
+	getActiveSessionCount(): number {
+		const now = new Date();
+		let count = 0;
+		for (const session of this.sessions.values()) {
+			if (session.expiresAt > now) count++;
+		}
+		return count;
+	}
+
+	/**
+	 * Get session statistics
+	 */
+	getStats(): SessionStats {
+		return {
+			total: this.getSessionCount(),
+			active: this.getActiveSessionCount(),
+		};
+	}
+
+	/**
+	 * Clean up expired sessions (can be called periodically)
+	 */
+	cleanupExpiredSessions(): number {
+		const now = new Date();
+		let cleaned = 0;
+
+		for (const [userId, session] of this.sessions.entries()) {
+			if (session.expiresAt < now) {
+				this.sessions.delete(userId);
+				cleaned++;
+			}
+		}
+
+		if (cleaned > 0) {
+			this.logger.log(`Cleaned up ${cleaned} expired sessions`);
+		}
+
+		return cleaned;
+	}
+
+	/**
+	 * Get all active session user IDs
+	 */
+	getActiveUserIds(): string[] {
+		const now = new Date();
+		const userIds: string[] = [];
+
+		for (const [userId, session] of this.sessions.entries()) {
+			if (session.expiresAt > now) {
+				userIds.push(userId);
+			}
+		}
+
+		return userIds;
+	}
+}

packages/bot-services/src/session/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Types for Matrix user session management
+ */
+
+/**
+ * User session data stored per Matrix user
+ */
+export interface UserSession {
+	/** JWT token from mana-core-auth */
+	token: string;
+	/** User's email address */
+	email: string;
+	/** Token expiration time */
+	expiresAt: Date;
+	/** Additional session data (bot-specific) */
+	data?: Record<string, unknown>;
+}
+
+/**
+ * Login result
+ */
+export interface LoginResult {
+	success: boolean;
+	error?: string;
+	email?: string;
+}
+
+/**
+ * Session statistics
+ */
+export interface SessionStats {
+	/** Total sessions (including expired) */
+	total: number;
+	/** Active (non-expired) sessions */
+	active: number;
+}
+
+/**
+ * Session module configuration options
+ */
+export interface SessionModuleOptions {
+	/** Mana Core Auth URL */
+	authUrl?: string;
+	/** Session expiry in milliseconds (default: 7 days) */
+	sessionExpiryMs?: number;
+	/** Custom login endpoint path */
+	loginPath?: string;
+}
+
+export const SESSION_MODULE_OPTIONS = 'SESSION_MODULE_OPTIONS';
+
+/**
+ * Default session expiry: 7 days in milliseconds
+ */
+export const DEFAULT_SESSION_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;

packages/bot-services/src/transcription/index.ts

@@ -0,0 +1,4 @@
+export { TranscriptionService } from './transcription.service';
+export { TranscriptionModule } from './transcription.module';
+export type { SttResponse, TranscriptionOptions, TranscriptionModuleOptions } from './types';
+export { STT_MODULE_OPTIONS } from './types';

packages/bot-services/src/transcription/transcription.module.ts

@@ -0,0 +1,61 @@
+import { Module, DynamicModule, Global } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { TranscriptionService } from './transcription.service';
+import { TranscriptionModuleOptions, STT_MODULE_OPTIONS } from './types';
+
+/**
+ * Shared Speech-to-Text transcription module
+ *
+ * Provides TranscriptionService for voice command processing in Matrix bots.
+ *
+ * @example
+ * ```typescript
+ * // With explicit configuration
+ * @Module({
+ *   imports: [
+ *     TranscriptionModule.register({
+ *       sttUrl: 'http://mana-stt:3020',
+ *       defaultLanguage: 'de'
+ *     })
+ *   ]
+ * })
+ *
+ * // With ConfigService (reads from stt.url or STT_URL)
+ * @Module({
+ *   imports: [TranscriptionModule.forRoot()]
+ * })
+ * ```
+ */
+@Global()
+@Module({})
+export class TranscriptionModule {
+	/**
+	 * Register module with explicit options
+	 */
+	static register(options: TranscriptionModuleOptions = {}): DynamicModule {
+		return {
+			module: TranscriptionModule,
+			imports: [ConfigModule],
+			providers: [
+				{
+					provide: STT_MODULE_OPTIONS,
+					useValue: options,
+				},
+				TranscriptionService,
+			],
+			exports: [TranscriptionService],
+		};
+	}
+
+	/**
+	 * Register module with ConfigService (reads stt.url or STT_URL from config)
+	 */
+	static forRoot(): DynamicModule {
+		return {
+			module: TranscriptionModule,
+			imports: [ConfigModule],
+			providers: [TranscriptionService],
+			exports: [TranscriptionService],
+		};
+	}
+}

packages/bot-services/src/transcription/transcription.service.ts

@@ -0,0 +1,140 @@
+import { Injectable, Inject, Logger, Optional } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import {
+	SttResponse,
+	TranscriptionOptions,
+	STT_MODULE_OPTIONS,
+	TranscriptionModuleOptions,
+} from './types';
+
+/**
+ * Shared Speech-to-Text transcription service
+ *
+ * Connects to mana-stt service to transcribe audio files.
+ * Used by Matrix bots for voice command processing.
+ *
+ * @example
+ * ```typescript
+ * // In NestJS module
+ * imports: [TranscriptionModule.register({ sttUrl: 'http://mana-stt:3020' })]
+ *
+ * // In service
+ * const text = await transcriptionService.transcribe(audioBuffer, { language: 'de' });
+ * ```
+ */
+@Injectable()
+export class TranscriptionService {
+	private readonly logger = new Logger(TranscriptionService.name);
+	private readonly sttUrl: string;
+	private readonly defaultLanguage: string;
+
+	constructor(
+		@Optional() private configService: ConfigService,
+		@Optional() @Inject(STT_MODULE_OPTIONS) private options?: TranscriptionModuleOptions
+	) {
+		// Priority: module options > config > environment > default
+		this.sttUrl =
+			options?.sttUrl ||
+			this.configService?.get<string>('stt.url') ||
+			this.configService?.get<string>('STT_URL') ||
+			'http://localhost:3020';
+
+		this.defaultLanguage = options?.defaultLanguage || 'de';
+
+		this.logger.log(`STT Service URL: ${this.sttUrl}`);
+	}
+
+	/**
+	 * Transcribe audio buffer to text
+	 *
+	 * @param audioBuffer - Audio data (supports ogg, wav, mp3, etc.)
+	 * @param options - Transcription options (language, model)
+	 * @returns Transcribed text
+	 */
+	async transcribe(audioBuffer: Buffer, options?: TranscriptionOptions): Promise<string> {
+		const language = options?.language || this.defaultLanguage;
+
+		const formData = new FormData();
+		const blob = new Blob([new Uint8Array(audioBuffer)], { type: 'audio/ogg' });
+		formData.append('file', blob, 'audio.ogg');
+		formData.append('language', language);
+
+		if (options?.model) {
+			formData.append('model', options.model);
+		}
+
+		try {
+			const response = await fetch(`${this.sttUrl}/transcribe`, {
+				method: 'POST',
+				body: formData,
+			});
+
+			if (!response.ok) {
+				const errorText = await response.text();
+				throw new Error(`STT service error: ${response.status} - ${errorText}`);
+			}
+
+			const result = (await response.json()) as SttResponse;
+			this.logger.log(`Transcription completed: ${result.text.substring(0, 50)}...`);
+			return result.text;
+		} catch (error) {
+			this.logger.error('Transcription failed:', error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Transcribe audio and return full response with metadata
+	 */
+	async transcribeWithMetadata(
+		audioBuffer: Buffer,
+		options?: TranscriptionOptions
+	): Promise<SttResponse> {
+		const language = options?.language || this.defaultLanguage;
+
+		const formData = new FormData();
+		const blob = new Blob([new Uint8Array(audioBuffer)], { type: 'audio/ogg' });
+		formData.append('file', blob, 'audio.ogg');
+		formData.append('language', language);
+
+		if (options?.model) {
+			formData.append('model', options.model);
+		}
+
+		try {
+			const response = await fetch(`${this.sttUrl}/transcribe`, {
+				method: 'POST',
+				body: formData,
+			});
+
+			if (!response.ok) {
+				const errorText = await response.text();
+				throw new Error(`STT service error: ${response.status} - ${errorText}`);
+			}
+
+			return (await response.json()) as SttResponse;
+		} catch (error) {
+			this.logger.error('Transcription failed:', error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Check if STT service is healthy
+	 */
+	async checkHealth(): Promise<boolean> {
+		try {
+			const response = await fetch(`${this.sttUrl}/health`);
+			return response.ok;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Get STT service URL (for debugging/logging)
+	 */
+	getSttUrl(): string {
+		return this.sttUrl;
+	}
+}

packages/bot-services/src/transcription/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Types for Speech-to-Text transcription service
+ */
+
+export interface SttResponse {
+	text: string;
+	language?: string;
+	model?: string;
+	duration?: number;
+}
+
+export interface TranscriptionOptions {
+	language?: string;
+	model?: string;
+}
+
+export interface TranscriptionModuleOptions {
+	sttUrl?: string;
+	defaultLanguage?: string;
+}
+
+export const STT_MODULE_OPTIONS = 'STT_MODULE_OPTIONS';