✨ feat(bot-services): add API key support to TranscriptionService

- Add apiKey option to TranscriptionModuleOptions
- Send X-API-Key header in all STT requests when configured
- Support config via module options, stt.apiKey, or STT_API_KEY env var
- Update CLAUDE.md documentation with API key usage example

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

packages/bot-services/CLAUDE.md

@@ -124,7 +124,18 @@ const convId = sessionService.getSessionData<string>('@user:matrix.org', 'curren
 ### Transcription Service (Speech-to-Text)
 
 ```typescript
-import { TranscriptionService } from '@manacore/bot-services';
+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' });

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

@@ -27,6 +27,7 @@ export class TranscriptionService {
 	private readonly logger = new Logger(TranscriptionService.name);
 	private readonly sttUrl: string;
 	private readonly defaultLanguage: string;
+	private readonly apiKey: string;
 
 	constructor(
 		@Optional() private configService: ConfigService,
@@ -41,6 +42,12 @@ export class TranscriptionService {
 
 		this.defaultLanguage = options?.defaultLanguage || 'de';
 
+		this.apiKey =
+			options?.apiKey ||
+			this.configService?.get<string>('stt.apiKey') ||
+			this.configService?.get<string>('STT_API_KEY') ||
+			'';
+
 		this.logger.log(`STT Service URL: ${this.sttUrl}`);
 	}
 
@@ -64,8 +71,14 @@ export class TranscriptionService {
 		}
 
 		try {
+			const headers: Record<string, string> = {};
+			if (this.apiKey) {
+				headers['X-API-Key'] = this.apiKey;
+			}
+
 			const response = await fetch(`${this.sttUrl}/transcribe`, {
 				method: 'POST',
+				headers,
 				body: formData,
 			});
 
@@ -102,8 +115,14 @@ export class TranscriptionService {
 		}
 
 		try {
+			const headers: Record<string, string> = {};
+			if (this.apiKey) {
+				headers['X-API-Key'] = this.apiKey;
+			}
+
 			const response = await fetch(`${this.sttUrl}/transcribe`, {
 				method: 'POST',
+				headers,
 				body: formData,
 			});
 
@@ -124,7 +143,12 @@ export class TranscriptionService {
 	 */
 	async checkHealth(): Promise<boolean> {
 		try {
-			const response = await fetch(`${this.sttUrl}/health`);
+			const headers: Record<string, string> = {};
+			if (this.apiKey) {
+				headers['X-API-Key'] = this.apiKey;
+			}
+
+			const response = await fetch(`${this.sttUrl}/health`, { headers });
 			return response.ok;
 		} catch {
 			return false;

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

@@ -17,6 +17,7 @@ export interface TranscriptionOptions {
 export interface TranscriptionModuleOptions {
 	sttUrl?: string;
 	defaultLanguage?: string;
+	apiKey?: string;
 }
 
 export const STT_MODULE_OPTIONS = 'STT_MODULE_OPTIONS';