@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/services/speech/providers/whisper.provider.js

@@ -0,0 +1,240 @@
+/**
+ * @fileoverview OpenAI Whisper speech-to-text provider implementation.
+ * Wraps the OpenAI audio transcriptions API (`POST /audio/transcriptions`) to provide
+ * STT transcription in multiple languages. TTS is not supported and will throw `MethodNotFound`.
+ * Audio is submitted as multipart `FormData`; the 25 MB Whisper file-size limit is enforced
+ * before the network call.
+ * @module src/services/speech/providers/whisper.provider
+ */
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { logger } from '../../../utils/internal/logger.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { fetchWithTimeout } from '../../../utils/network/fetchWithTimeout.js';
+/**
+ * OpenAI Whisper STT provider.
+ * Implements {@link ISpeechProvider} for speech-to-text only (`supportsSTT = true`,
+ * `supportsTTS = false`). Submits audio to the OpenAI transcriptions endpoint via
+ * multipart form upload using `fetchWithTimeout`.
+ *
+ * Default model: `whisper-1`
+ * Default timeout: 60 000 ms (audio processing is slower than typical API calls)
+ * Maximum audio size: 25 MB (enforced locally before the network call)
+ */
+export class WhisperProvider {
+    name = 'openai-whisper';
+    supportsTTS = false;
+    supportsSTT = true;
+    apiKey;
+    baseUrl;
+    defaultModelId;
+    timeout;
+    /**
+     * Construct a WhisperProvider.
+     *
+     * @param config - Provider configuration. `config.apiKey` is required; other fields
+     *   fall back to OpenAI API defaults.
+     * @throws {McpError} With `InvalidParams` if `config.apiKey` is absent.
+     */
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new McpError(JsonRpcErrorCode.InvalidParams, 'OpenAI API key is required');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? 'https://api.openai.com/v1';
+        this.defaultModelId = config.defaultModelId ?? 'whisper-1';
+        this.timeout = config.timeout ?? 60000; // Longer timeout for audio processing
+        logger.info(`OpenAI Whisper STT provider initialized: ${this.baseUrl}, model=${this.defaultModelId}`);
+    }
+    /**
+     * Not supported — Whisper is an STT-only provider.
+     *
+     * @param _options - Unused.
+     * @throws {McpError} Always, with `MethodNotFound`.
+     */
+    textToSpeech(_options) {
+        throw new McpError(JsonRpcErrorCode.MethodNotFound, 'Text-to-speech is not supported by Whisper provider');
+    }
+    /**
+     * Transcribe audio to text using the OpenAI Whisper API.
+     * Audio may be provided as a raw `Buffer` or a base64-encoded string. The data is
+     * submitted to `POST /audio/transcriptions` as multipart `FormData`. When
+     * `options.timestamps` is `true`, the request uses `verbose_json` format and requests
+     * word-level granularity, populating `result.words`.
+     *
+     * @param options - Transcription options. `options.audio` is required. Optional fields:
+     *   `format` (determines MIME type/filename), `language` (ISO-639-1 hint),
+     *   `modelId` (overrides provider default), `prompt` (style guide), `temperature`,
+     *   and `timestamps` (enables word-level output).
+     * @returns Resolved {@link SpeechToTextResult} with `text`, optional `language`,
+     *   `duration`, `words` (if timestamps were requested), and `metadata` containing
+     *   `modelId`, `provider`, and `task`.
+     * @throws {McpError} With `InvalidParams` for missing audio, invalid base64, or audio > 25 MB.
+     * @throws {McpError} With `InternalError` if the Whisper API call fails.
+     */
+    async speechToText(options) {
+        const context = requestContextService.createRequestContext({
+            operation: 'whisper-stt',
+            ...(options.context ?? {}),
+        });
+        const modelId = options.modelId ?? this.defaultModelId;
+        logger.debug('Converting speech to text with Whisper', context);
+        // Validate audio input
+        if (!options.audio) {
+            throw new McpError(JsonRpcErrorCode.InvalidParams, 'Audio data is required', context);
+        }
+        // Convert audio to Buffer if it's a base64 string
+        let audioBuffer;
+        if (typeof options.audio === 'string') {
+            try {
+                audioBuffer = Buffer.from(options.audio, 'base64');
+            }
+            catch (_error) {
+                throw new McpError(JsonRpcErrorCode.InvalidParams, 'Invalid base64 audio data', context);
+            }
+        }
+        else {
+            audioBuffer = options.audio;
+        }
+        // Check file size (Whisper has a 25MB limit)
+        const maxSize = 25 * 1024 * 1024; // 25MB
+        if (audioBuffer.length > maxSize) {
+            throw new McpError(JsonRpcErrorCode.InvalidParams, `Audio file exceeds maximum size of 25MB (got ${Math.round(audioBuffer.length / 1024 / 1024)}MB)`, context);
+        }
+        const url = `${this.baseUrl}/audio/transcriptions`;
+        // Build form data
+        const formData = new FormData();
+        // Determine filename with appropriate extension
+        const extension = this.getFileExtension(options.format);
+        const blob = new Blob([audioBuffer], {
+            type: this.getMimeType(options.format),
+        });
+        formData.append('file', blob, `audio.${extension}`);
+        formData.append('model', modelId);
+        if (options.language) {
+            formData.append('language', options.language);
+        }
+        if (options.temperature !== undefined) {
+            formData.append('temperature', options.temperature.toString());
+        }
+        if (options.prompt) {
+            formData.append('prompt', options.prompt);
+        }
+        // Request verbose JSON format to get timestamps and metadata
+        formData.append('response_format', options.timestamps ? 'verbose_json' : 'json');
+        if (options.timestamps) {
+            formData.append('timestamp_granularities[]', 'word');
+        }
+        try {
+            const response = await fetchWithTimeout(url, this.timeout, context, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    // Don't set Content-Type - let fetch set it with boundary for FormData
+                },
+                body: formData,
+            });
+            // fetchWithTimeout already throws McpError on non-ok responses
+            const data = (await response.json());
+            // Convert word timestamps if present
+            const words = data.words?.map((w) => ({
+                word: w.word,
+                start: w.start,
+                end: w.end,
+            }));
+            logger.info(`Speech-to-text transcription successful (${data.text.length} chars)`, context);
+            return {
+                text: data.text,
+                ...(data.language !== undefined && { language: data.language }),
+                ...(data.duration !== undefined && { duration: data.duration }),
+                ...(words !== undefined && { words }),
+                metadata: {
+                    modelId,
+                    provider: this.name,
+                    ...(data.task !== undefined && { task: data.task }),
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError) {
+                throw error;
+            }
+            logger.error('Failed to transcribe audio', error instanceof Error ? error : new Error(String(error)), context);
+            throw new McpError(JsonRpcErrorCode.InternalError, `Failed to transcribe audio: ${error instanceof Error ? error.message : 'Unknown error'}`, context);
+        }
+    }
+    /**
+     * Not applicable — Whisper is an STT-only provider with no voice concept.
+     *
+     * @throws {McpError} Always, with `MethodNotFound`.
+     */
+    getVoices() {
+        throw new McpError(JsonRpcErrorCode.MethodNotFound, 'Voice listing is not supported by Whisper provider (STT only)');
+    }
+    /**
+     * Verify OpenAI API connectivity by fetching the models list (`GET /models`).
+     * Uses a 5-second timeout regardless of the provider's configured `timeout`,
+     * to keep health checks lightweight.
+     *
+     * @returns `true` if the models endpoint responds with HTTP 200, `false` otherwise.
+     *   Never rejects.
+     */
+    async healthCheck() {
+        try {
+            // Simple health check: verify API key by making a models list request
+            const context = requestContextService.createRequestContext({
+                operation: 'whisper-healthCheck',
+            });
+            const response = await fetchWithTimeout(`${this.baseUrl}/models`, 5000, context, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+            });
+            return response.ok;
+        }
+        catch (error) {
+            const context = requestContextService.createRequestContext({
+                operation: 'whisper-healthCheck',
+            });
+            logger.error('Whisper health check failed', error instanceof Error ? error : new Error(String(error)), context);
+            return false;
+        }
+    }
+    /**
+     * Map an {@link AudioFormat} string to a file extension for the multipart upload filename.
+     * Defaults to `'mp3'` for unrecognized or absent formats.
+     *
+     * @param format - Audio format string (e.g., `'wav'`, `'ogg'`).
+     * @returns File extension without leading dot (e.g., `'wav'`).
+     */
+    getFileExtension(format) {
+        const formatMap = {
+            mp3: 'mp3',
+            wav: 'wav',
+            ogg: 'ogg',
+            flac: 'flac',
+            webm: 'webm',
+            m4a: 'm4a',
+        };
+        return format && formatMap[format] ? formatMap[format] : 'mp3';
+    }
+    /**
+     * Map an {@link AudioFormat} string to the corresponding MIME type for the `Blob`
+     * used in the multipart upload. Defaults to `'audio/mpeg'` for unrecognized formats.
+     *
+     * @param format - Audio format string (e.g., `'wav'`, `'ogg'`).
+     * @returns MIME type string (e.g., `'audio/wav'`).
+     */
+    getMimeType(format) {
+        const mimeMap = {
+            mp3: 'audio/mpeg',
+            wav: 'audio/wav',
+            ogg: 'audio/ogg',
+            flac: 'audio/flac',
+            webm: 'audio/webm',
+            m4a: 'audio/mp4',
+        };
+        return format && mimeMap[format] ? mimeMap[format] : 'audio/mpeg';
+    }
+}
+//# sourceMappingURL=whisper.provider.js.map

package/dist/services/speech/providers/whisper.provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whisper.provider.js","sourceRoot":"","sources":["../../../../src/services/speech/providers/whisper.provider.ts"],"names":[],"mappings":"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"}

package/dist/services/speech/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @fileoverview Type definitions for the Speech service.
+ * Provides shared interfaces and types for Text-to-Speech (TTS) and Speech-to-Text (STT)
+ * operations across all speech provider implementations.
+ * @module src/services/speech/types
+ */
+/**
+ * Supported audio formats for speech operations.
+ * - `mp3` — MPEG Audio Layer III, widely compatible
+ * - `wav` — Waveform Audio, uncompressed PCM
+ * - `ogg` — Ogg Vorbis container
+ * - `flac` — Free Lossless Audio Codec
+ * - `pcm` — Raw pulse-code modulation samples
+ * - `webm` — WebM container (typically Opus codec)
+ */
+export type AudioFormat = 'mp3' | 'wav' | 'ogg' | 'flac' | 'pcm' | 'webm';
+/**
+ * Voice settings for text-to-speech synthesis.
+ */
+export interface VoiceSettings {
+    /** Voice pitch (-20.0 to 20.0, where 0 is normal) */
+    pitch?: number;
+    /** Similarity boost (0.0 to 1.0, provider-specific) */
+    similarityBoost?: number;
+    /** Speech rate/speed (0.5 to 2.0, where 1.0 is normal) */
+    speed?: number;
+    /** Stability setting (0.0 to 1.0, provider-specific) */
+    stability?: number;
+    /** Style exaggeration (0.0 to 1.0, provider-specific) */
+    style?: number;
+    /** Voice ID or name (provider-specific) */
+    voiceId?: string;
+    /** Volume level (0.0 to 1.0) */
+    volume?: number;
+}
+/**
+ * Options for text-to-speech synthesis.
+ */
+export interface TextToSpeechOptions {
+    /** Optional context for request tracing */
+    context?: {
+        requestId?: string;
+        traceId?: string;
+        tenantId?: string;
+    };
+    /** Output audio format */
+    format?: AudioFormat;
+    /** Language code (e.g., 'en-US', 'es-ES') */
+    language?: string;
+    /** Model ID (provider-specific) */
+    modelId?: string;
+    /** Text to convert to speech */
+    text: string;
+    /** Voice settings */
+    voice?: VoiceSettings;
+}
+/**
+ * Result from text-to-speech synthesis.
+ */
+export interface TextToSpeechResult {
+    /** Audio data as Buffer or base64 string */
+    audio: Buffer | string;
+    /** Character count of input text */
+    characterCount: number;
+    /** Duration in seconds (if available) */
+    duration?: number;
+    /** Audio format */
+    format: AudioFormat;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for speech-to-text transcription.
+ */
+export interface SpeechToTextOptions {
+    /** Audio data as Buffer or base64 string */
+    audio: Buffer | string;
+    /** Optional context for request tracing */
+    context?: {
+        requestId?: string;
+        traceId?: string;
+        tenantId?: string;
+    };
+    /** Audio format */
+    format?: AudioFormat;
+    /** Language code hint (e.g., 'en', 'es') */
+    language?: string;
+    /** Model ID (provider-specific) */
+    modelId?: string;
+    /** Prompt to guide transcription style */
+    prompt?: string;
+    /** Temperature for sampling (0.0 to 1.0) */
+    temperature?: number;
+    /** Enable word-level timestamps */
+    timestamps?: boolean;
+}
+/**
+ * Word-level timestamp information.
+ */
+export interface WordTimestamp {
+    /** Confidence score (0.0 to 1.0) */
+    confidence?: number;
+    /** End time in seconds */
+    end: number;
+    /** Start time in seconds */
+    start: number;
+    /** The word or token */
+    word: string;
+}
+/**
+ * Result from speech-to-text transcription.
+ */
+export interface SpeechToTextResult {
+    /** Overall confidence score (0.0 to 1.0) */
+    confidence?: number;
+    /** Duration in seconds */
+    duration?: number;
+    /** Detected language code */
+    language?: string;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+    /** Transcribed text */
+    text: string;
+    /** Word-level timestamps (if requested) */
+    words?: WordTimestamp[];
+}
+/**
+ * Available voices from a provider.
+ */
+export interface Voice {
+    /** Voice category (e.g., 'premade', 'cloned', 'professional') */
+    category?: string;
+    /** Voice description */
+    description?: string;
+    /** Gender (if applicable) */
+    gender?: 'male' | 'female' | 'neutral';
+    /** Voice ID */
+    id: string;
+    /** Language codes supported */
+    languages?: string[];
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+    /** Voice name */
+    name: string;
+    /** Preview URL (if available) */
+    previewUrl?: string;
+}
+/**
+ * Configuration for speech service providers.
+ * Passed to `createSpeechProvider` to instantiate the appropriate provider.
+ */
+export interface SpeechProviderConfig {
+    /** API key for authenticating with the provider's API */
+    apiKey?: string;
+    /** Base URL override; defaults to the provider's public API endpoint */
+    baseUrl?: string;
+    /** Default model ID to use when none is specified per-request */
+    defaultModelId?: string;
+    /** Default voice ID for TTS when none is specified per-request */
+    defaultVoiceId?: string;
+    /** Additional provider-specific options passed through as-is */
+    options?: Record<string, unknown>;
+    /**
+     * Provider implementation to use.
+     * - `'elevenlabs'` — ElevenLabs TTS (no STT)
+     * - `'openai-whisper'` — OpenAI Whisper STT (no TTS)
+     * - `'mock'` — Not yet implemented; throws on instantiation
+     */
+    provider: 'elevenlabs' | 'openai-whisper' | 'mock';
+    /** Request timeout in milliseconds (provider defaults vary) */
+    timeout?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/speech/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/speech/types.ts"],"names":[],"mappings":"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"}

package/dist/services/speech/types.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Type definitions for the Speech service.
+ * Provides shared interfaces and types for Text-to-Speech (TTS) and Speech-to-Text (STT)
+ * operations across all speech provider implementations.
+ * @module src/services/speech/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/speech/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/speech/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/storage/core/IStorageProvider.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Defines the core interface for a generic storage provider.
+ * This contract ensures that any storage implementation (e.g., in-memory, filesystem, database)
+ * can be used interchangeably throughout the application.
+ * @module src/storage/core/IStorageProvider
+ */
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Options for storage operations.
+ *
+ * @property ttl - Time-to-live for the stored item, in seconds. If not provided, the item is stored indefinitely.
+ *   Provider-specific behaviors:
+ *   - `in-memory`: TTL enforced by `setTimeout` for proactive deletion.
+ *   - `filesystem`: TTL stored in a metadata envelope; expired items are filtered on `get()` and `list()`.
+ *   - `supabase`: TTL managed via an `expires_at` column; expired rows are handled by database queries.
+ *   - `cloudflare-kv`: TTL is a native feature of the KV store.
+ *   - `cloudflare-r2`: TTL stored in a metadata envelope; expired items are filtered on `get()`. `list()` does not filter expired items due to performance cost.
+ */
+export interface StorageOptions {
+    /**
+     * Time-to-live for the stored item, in seconds.
+     * If not provided, the item will be stored indefinitely.
+     */
+    ttl?: number;
+}
+/**
+ * Options for list operations with pagination support.
+ *
+ * @property limit - Maximum number of keys to return per page. If not provided, returns all keys.
+ * @property cursor - Opaque cursor for pagination. Provider-specific format.
+ */
+export interface ListOptions {
+    /**
+     * Pagination cursor from a previous list operation.
+     * Format is provider-specific (opaque string).
+     */
+    cursor?: string;
+    /**
+     * Maximum number of keys to return. Defaults to provider-specific limit.
+     */
+    limit?: number;
+}
+/**
+ * Result of a list operation with pagination support.
+ *
+ * @property keys - Array of matching keys.
+ * @property nextCursor - Cursor for the next page, or undefined if no more results.
+ */
+export interface ListResult {
+    /**
+     * Array of keys matching the prefix.
+     */
+    keys: string[];
+    /**
+     * Cursor for fetching the next page of results.
+     * Undefined if there are no more results.
+     */
+    nextCursor?: string | undefined;
+}
+/**
+ * Defines the contract for a generic storage provider.
+ * All methods must be asynchronous and accept a RequestContext for tracing and logging.
+ */
+export interface IStorageProvider {
+    /**
+     * Clears all keys for a given tenant.
+     * WARNING: This is a destructive operation that cannot be undone.
+     * Useful for testing or tenant cleanup operations.
+     * @param tenantId The unique identifier for the tenant.
+     * @param context The request context for logging and tracing.
+     * @returns A promise that resolves to the number of keys deleted.
+     */
+    clear(tenantId: string, context: RequestContext): Promise<number>;
+    /**
+     * Deletes a value from the storage.
+     * @param key The unique key for the item to delete.
+     * @param context The request context for logging and tracing.
+     * @returns A promise that resolves to true if the item was deleted, false if not found.
+     */
+    delete(tenantId: string, key: string, context: RequestContext): Promise<boolean>;
+    /**
+     * Deletes multiple keys in a single operation.
+     * More efficient than multiple individual delete() calls.
+     *
+     * Performance characteristics by provider:
+     * - Cloudflare KV/R2: Parallel deletes (fast)
+     * - Supabase: Single SQL DELETE with IN clause (fast, database-optimized)
+     * - In-Memory: Parallel Map deletes (fastest, no I/O)
+     * - FileSystem: Parallel file deletes (I/O bound, benefits from concurrency)
+     *
+     * @param tenantId The unique identifier for the tenant.
+     * @param keys Array of keys to delete. Empty array returns 0.
+     * @param context The request context for logging and tracing.
+     * @returns A promise that resolves to the number of keys successfully deleted.
+     */
+    deleteMany(tenantId: string, keys: string[], context: RequestContext): Promise<number>;
+    /**
+     * Retrieves a value from the storage.
+     * @param tenantId The unique identifier for the tenant.
+     * @param key The unique key for the item.
+     * @param context The request context for logging and tracing.
+     * @returns A promise that resolves to the stored value, or null if not found.
+     */
+    get<T>(tenantId: string, key: string, context: RequestContext): Promise<T | null>;
+    /**
+     * Retrieves multiple values from storage in a single operation.
+     * More efficient than multiple individual get() calls.
+     *
+     * Performance characteristics by provider:
+     * - Cloudflare KV/R2: Parallel fetches (fast for large batches)
+     * - Supabase: Single SQL query with IN clause (fast, database-optimized)
+     * - In-Memory: Parallel Map lookups (fastest, no I/O)
+     * - FileSystem: Parallel file reads (I/O bound, benefits from concurrency)
+     *
+     * @param tenantId The unique identifier for the tenant.
+     * @param keys Array of keys to retrieve. Empty array returns empty Map.
+     * @param context The request context for logging and tracing.
+     * @returns A promise that resolves to a Map of key-value pairs. Missing keys are not included.
+     */
+    getMany<T>(tenantId: string, keys: string[], context: RequestContext): Promise<Map<string, T>>;
+    /**
+     * Lists all keys that match a given prefix.
+     * Note: This may be an expensive operation on some backends.
+     * TTL Behavior: This operation may or may not filter expired keys depending on the provider's capabilities.
+     * Refer to `StorageOptions` for provider-specific TTL documentation.
+     * @param prefix The prefix to match keys against.
+     * @param context The request context for logging and tracing.
+     * @param options Optional pagination settings.
+     * @returns A promise that resolves to a ListResult with keys and optional pagination cursor.
+     */
+    list(tenantId: string, prefix: string, context: RequestContext, options?: ListOptions): Promise<ListResult>;
+    /**
+     * Stores a value in the storage.
+     * @param key The unique key for the item.
+     * @param value The value to store. Can be any serializable object.
+     * @param context The request context for logging and tracing.
+     * @param options Optional settings like TTL.
+     * @returns A promise that resolves when the operation is complete.
+     */
+    set(tenantId: string, key: string, value: unknown, context: RequestContext, options?: StorageOptions): Promise<void>;
+    /**
+     * Stores multiple values in a single operation.
+     * More efficient than multiple individual set() calls.
+     *
+     * Performance characteristics by provider:
+     * - Cloudflare KV/R2: Parallel writes (fast, eventually consistent)
+     * - Supabase: Single SQL batch upsert (fast, immediately consistent)
+     * - In-Memory: Parallel Map inserts (fastest, no I/O)
+     * - FileSystem: Parallel file writes (I/O bound, benefits from concurrency)
+     *
+     * @param tenantId The unique identifier for the tenant.
+     * @param entries Map of key-value pairs to store. Empty map is a no-op.
+     * @param context The request context for logging and tracing.
+     * @param options Optional settings like TTL (applied to all entries).
+     * @returns A promise that resolves when all operations are complete.
+     */
+    setMany(tenantId: string, entries: Map<string, unknown>, context: RequestContext, options?: StorageOptions): Promise<void>;
+}
+//# sourceMappingURL=IStorageProvider.d.ts.map

package/dist/storage/core/IStorageProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStorageProvider.d.ts","sourceRoot":"","sources":["../../../src/storage/core/IStorageProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElE;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjF;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvF;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAElF;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAE/F;;;;;;;;;OASG;IACH,IAAI,CACF,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB;;;;;;;OAOG;IACH,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CACL,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/storage/core/IStorageProvider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IStorageProvider.js.map

package/dist/storage/core/IStorageProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStorageProvider.js","sourceRoot":"","sources":["../../../src/storage/core/IStorageProvider.ts"],"names":[],"mappings":""}

package/dist/storage/core/StorageService.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Provides a singleton service for interacting with the application's storage layer.
+ * This service acts as a proxy to the configured storage provider, ensuring a consistent
+ * interface for all storage operations throughout the application. It receives its concrete
+ * provider via dependency injection.
+ * @module src/storage/core/StorageService
+ */
+import type { IStorageProvider, ListOptions, ListResult, StorageOptions } from '../../storage/core/IStorageProvider.js';
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+export declare class StorageService {
+    private provider;
+    constructor(provider: IStorageProvider);
+    get<T>(key: string, context: RequestContext): Promise<T | null>;
+    set(key: string, value: unknown, context: RequestContext, options?: StorageOptions): Promise<void>;
+    delete(key: string, context: RequestContext): Promise<boolean>;
+    list(prefix: string, context: RequestContext, options?: ListOptions): Promise<ListResult>;
+    getMany<T>(keys: string[], context: RequestContext): Promise<Map<string, T>>;
+    setMany(entries: Map<string, unknown>, context: RequestContext, options?: StorageOptions): Promise<void>;
+    deleteMany(keys: string[], context: RequestContext): Promise<number>;
+    clear(context: RequestContext): Promise<number>;
+}
+//# sourceMappingURL=StorageService.d.ts.map

package/dist/storage/core/StorageService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageService.d.ts","sourceRoot":"","sources":["../../../src/storage/core/StorageService.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,cAAc,EACf,MAAM,oCAAoC,CAAC;AAU5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAsCzE,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ;gBAAR,QAAQ,EAAE,gBAAgB;IAK9C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAc/D,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAiBhB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAc9D,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBzF,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAiB5E,OAAO,CACL,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAoBhB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBpE,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;CAWhD"}