@juspay/neurolink 11.2.3 → 11.2.4

package/dist/core/handlerRegistry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export declare class HandlerRegistry<THandler> {
+    private readonly scopeName;
+    private readonly handlers;
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName: string);
+    register(providerName: string, handler: THandler): void;
+    supports(providerName: string): boolean;
+    get(providerName: string): THandler | undefined;
+    list(): string[];
+    clear(): void;
+}

package/dist/core/handlerRegistry.js

@@ -0,0 +1,61 @@
+import { logger } from "../utils/logger.js";
+import { sanitizeForLog } from "../utils/logSanitize.js";
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export class HandlerRegistry {
+    scopeName;
+    handlers = new Map();
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName) {
+        this.scopeName = scopeName;
+    }
+    register(providerName, handler) {
+        if (!providerName) {
+            throw new Error("Provider name is required");
+        }
+        if (!handler) {
+            throw new Error("Handler is required");
+        }
+        const key = providerName.toLowerCase();
+        if (this.handlers.has(key)) {
+            // Every caller today passes a literal provider slug, but this class is
+            // generic over an arbitrary string — sanitize before logging it so a
+            // future caller building the key from untrusted input can't leak a
+            // bearer token/API key through this warning.
+            logger.warn(`[${this.scopeName}] Overwriting existing handler for provider: ${sanitizeForLog(key)}`);
+        }
+        this.handlers.set(key, handler);
+    }
+    supports(providerName) {
+        if (!providerName) {
+            return false;
+        }
+        return this.handlers.has(providerName.toLowerCase());
+    }
+    get(providerName) {
+        return this.handlers.get(providerName.toLowerCase());
+    }
+    list() {
+        return Array.from(this.handlers.keys());
+    }
+    clear() {
+        this.handlers.clear();
+        logger.debug(`[${this.scopeName}] Cleared all handlers`);
+    }
+}

package/dist/factories/providerRegistry.d.ts

@@ -1,14 +1,4 @@
 import type { ProviderRegistryOptions } from "../types/index.js";
-import { AIProviderName } from "../constants/enums.js";
-/**
- * Static module -> provider-ID manifest for every provider registered below.
- * Module names (file/dir under src/lib/providers/) intentionally differ from
- * their canonical IDs (e.g. amazonBedrock -> "bedrock", googleVertex ->
- * "vertex"); static scanners that cannot resolve the dynamic import() calls
- * use this mapping to confirm a module is registered. Enforced at runtime so
- * the registry cannot silently drift from this manifest.
- */
-export declare const PROVIDER_MODULE_TO_ID: Readonly<Record<string, AIProviderName>>;
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -43,12 +33,10 @@ export declare class ProviderRegistry {
      * (avoids circular dependencies; see CLAUDE.md).
      *
      * Not registered (by design): index.ts, providerTypeUtils.ts,
-     * openaiChatCompletionsBase.ts, openaiChatCompletionsClient.ts,
-     * anthropicImageBlocks.ts (shared base/helper modules), anthropicBaseProvider.ts
-     * (legacy; anthropic.ts is live), googleNativeGemini3.ts (shared helpers).
-     * Filename != provider ID (e.g. amazonBedrock -> "bedrock"); the
-     * statically-scannable PROVIDER_MODULE_TO_ID manifest maps every registered
-     * module to its provider ID and is enforced below (Pattern Analysis #1178/#1317).
+     * anthropicBaseProvider.ts (legacy; anthropic.ts is live),
+     * googleNativeGemini3.ts (shared helpers). Filename != provider ID
+     * (e.g. amazonBedrock -> "bedrock"); static scanners that miss dynamic
+     * imports may false-positive (Pattern Analysis #1178).
      */
     private static _doRegister;
     /**

package/dist/factories/providerRegistry.js

@@ -3,46 +3,6 @@ import { logger } from "../utils/logger.js";
 import { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, HuggingFaceModels, DeepSeekModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "./providerDescriptors.js";
 import { OPENAI_COMPAT_CATALOG } from "../providers/openaiCompatCatalog.js";
-/**
- * Static module -> provider-ID manifest for every provider registered below.
- * Module names (file/dir under src/lib/providers/) intentionally differ from
- * their canonical IDs (e.g. amazonBedrock -> "bedrock", googleVertex ->
- * "vertex"); static scanners that cannot resolve the dynamic import() calls
- * use this mapping to confirm a module is registered. Enforced at runtime so
- * the registry cannot silently drift from this manifest.
- */
-export const PROVIDER_MODULE_TO_ID = {
-    amazonBedrock: AIProviderName.BEDROCK,
-    amazonSagemaker: AIProviderName.SAGEMAKER,
-    anthropic: AIProviderName.ANTHROPIC,
-    azureOpenai: AIProviderName.AZURE,
-    cloudflare: AIProviderName.CLOUDFLARE,
-    cohere: AIProviderName.COHERE,
-    deepseek: AIProviderName.DEEPSEEK,
-    fireworks: AIProviderName.FIREWORKS,
-    googleAiStudio: AIProviderName.GOOGLE_AI,
-    googleVertex: AIProviderName.VERTEX,
-    groq: AIProviderName.GROQ,
-    huggingFace: AIProviderName.HUGGINGFACE,
-    ideogram: AIProviderName.IDEOGRAM,
-    jina: AIProviderName.JINA,
-    litellm: AIProviderName.LITELLM,
-    llamaCpp: AIProviderName.LLAMACPP,
-    lmStudio: AIProviderName.LM_STUDIO,
-    mistral: AIProviderName.MISTRAL,
-    nvidiaNim: AIProviderName.NVIDIA_NIM,
-    ollama: AIProviderName.OLLAMA,
-    openAI: AIProviderName.OPENAI,
-    openaiCompatible: AIProviderName.OPENAI_COMPATIBLE,
-    openRouter: AIProviderName.OPENROUTER,
-    perplexity: AIProviderName.PERPLEXITY,
-    recraft: AIProviderName.RECRAFT,
-    replicate: AIProviderName.REPLICATE,
-    stability: AIProviderName.STABILITY,
-    togetherAi: AIProviderName.TOGETHER_AI,
-    voyage: AIProviderName.VOYAGE,
-    xai: AIProviderName.XAI,
-};
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -94,12 +54,10 @@ export class ProviderRegistry {
      * (avoids circular dependencies; see CLAUDE.md).
      *
      * Not registered (by design): index.ts, providerTypeUtils.ts,
-     * openaiChatCompletionsBase.ts, openaiChatCompletionsClient.ts,
-     * anthropicImageBlocks.ts (shared base/helper modules), anthropicBaseProvider.ts
-     * (legacy; anthropic.ts is live), googleNativeGemini3.ts (shared helpers).
-     * Filename != provider ID (e.g. amazonBedrock -> "bedrock"); the
-     * statically-scannable PROVIDER_MODULE_TO_ID manifest maps every registered
-     * module to its provider ID and is enforced below (Pattern Analysis #1178/#1317).
+     * anthropicBaseProvider.ts (legacy; anthropic.ts is live),
+     * googleNativeGemini3.ts (shared helpers). Filename != provider ID
+     * (e.g. amazonBedrock -> "bedrock"); static scanners that miss dynamic
+     * imports may false-positive (Pattern Analysis #1178).
      */
     // eslint-disable-next-line max-lines-per-function
     static async _doRegister() {
@@ -270,16 +228,6 @@ export class ProviderRegistry {
                 const { RecraftProvider } = await import("../providers/recraft.js");
                 return new RecraftProvider(modelName, sdk, undefined, recraftCreds);
             }, process.env.RECRAFT_MODEL || RecraftModels.RECRAFT_V3, ["recraft"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.RECRAFT));
-            const unregistered = Object.entries(PROVIDER_MODULE_TO_ID).filter(([module, id]) => {
-                if (!ProviderFactory.hasProvider(id)) {
-                    logger.error(`[ProviderRegistry] drift: module "${module}" not registered as "${id}"`);
-                    return true;
-                }
-                return false;
-            });
-            if (unregistered.length > 0) {
-                throw new Error(`ProviderRegistry drift: ${unregistered.length} module(s) in PROVIDER_MODULE_TO_ID are not registered`);
-            }
             logger.debug("All AI providers registered successfully");
             // ===== TTS HANDLER REGISTRATION =====
             try {

package/dist/lib/core/handlerRegistry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export declare class HandlerRegistry<THandler> {
+    private readonly scopeName;
+    private readonly handlers;
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName: string);
+    register(providerName: string, handler: THandler): void;
+    supports(providerName: string): boolean;
+    get(providerName: string): THandler | undefined;
+    list(): string[];
+    clear(): void;
+}

package/dist/lib/core/handlerRegistry.js

@@ -0,0 +1,62 @@
+import { logger } from "../utils/logger.js";
+import { sanitizeForLog } from "../utils/logSanitize.js";
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export class HandlerRegistry {
+    scopeName;
+    handlers = new Map();
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName) {
+        this.scopeName = scopeName;
+    }
+    register(providerName, handler) {
+        if (!providerName) {
+            throw new Error("Provider name is required");
+        }
+        if (!handler) {
+            throw new Error("Handler is required");
+        }
+        const key = providerName.toLowerCase();
+        if (this.handlers.has(key)) {
+            // Every caller today passes a literal provider slug, but this class is
+            // generic over an arbitrary string — sanitize before logging it so a
+            // future caller building the key from untrusted input can't leak a
+            // bearer token/API key through this warning.
+            logger.warn(`[${this.scopeName}] Overwriting existing handler for provider: ${sanitizeForLog(key)}`);
+        }
+        this.handlers.set(key, handler);
+    }
+    supports(providerName) {
+        if (!providerName) {
+            return false;
+        }
+        return this.handlers.has(providerName.toLowerCase());
+    }
+    get(providerName) {
+        return this.handlers.get(providerName.toLowerCase());
+    }
+    list() {
+        return Array.from(this.handlers.keys());
+    }
+    clear() {
+        this.handlers.clear();
+        logger.debug(`[${this.scopeName}] Cleared all handlers`);
+    }
+}
+//# sourceMappingURL=handlerRegistry.js.map

package/dist/lib/factories/providerRegistry.d.ts

@@ -1,14 +1,4 @@
 import type { ProviderRegistryOptions } from "../types/index.js";
-import { AIProviderName } from "../constants/enums.js";
-/**
- * Static module -> provider-ID manifest for every provider registered below.
- * Module names (file/dir under src/lib/providers/) intentionally differ from
- * their canonical IDs (e.g. amazonBedrock -> "bedrock", googleVertex ->
- * "vertex"); static scanners that cannot resolve the dynamic import() calls
- * use this mapping to confirm a module is registered. Enforced at runtime so
- * the registry cannot silently drift from this manifest.
- */
-export declare const PROVIDER_MODULE_TO_ID: Readonly<Record<string, AIProviderName>>;
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -43,12 +33,10 @@ export declare class ProviderRegistry {
      * (avoids circular dependencies; see CLAUDE.md).
      *
      * Not registered (by design): index.ts, providerTypeUtils.ts,
-     * openaiChatCompletionsBase.ts, openaiChatCompletionsClient.ts,
-     * anthropicImageBlocks.ts (shared base/helper modules), anthropicBaseProvider.ts
-     * (legacy; anthropic.ts is live), googleNativeGemini3.ts (shared helpers).
-     * Filename != provider ID (e.g. amazonBedrock -> "bedrock"); the
-     * statically-scannable PROVIDER_MODULE_TO_ID manifest maps every registered
-     * module to its provider ID and is enforced below (Pattern Analysis #1178/#1317).
+     * anthropicBaseProvider.ts (legacy; anthropic.ts is live),
+     * googleNativeGemini3.ts (shared helpers). Filename != provider ID
+     * (e.g. amazonBedrock -> "bedrock"); static scanners that miss dynamic
+     * imports may false-positive (Pattern Analysis #1178).
      */
     private static _doRegister;
     /**

package/dist/lib/factories/providerRegistry.js

@@ -3,46 +3,6 @@ import { logger } from "../utils/logger.js";
 import { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, HuggingFaceModels, DeepSeekModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "./providerDescriptors.js";
 import { OPENAI_COMPAT_CATALOG } from "../providers/openaiCompatCatalog.js";
-/**
- * Static module -> provider-ID manifest for every provider registered below.
- * Module names (file/dir under src/lib/providers/) intentionally differ from
- * their canonical IDs (e.g. amazonBedrock -> "bedrock", googleVertex ->
- * "vertex"); static scanners that cannot resolve the dynamic import() calls
- * use this mapping to confirm a module is registered. Enforced at runtime so
- * the registry cannot silently drift from this manifest.
- */
-export const PROVIDER_MODULE_TO_ID = {
-    amazonBedrock: AIProviderName.BEDROCK,
-    amazonSagemaker: AIProviderName.SAGEMAKER,
-    anthropic: AIProviderName.ANTHROPIC,
-    azureOpenai: AIProviderName.AZURE,
-    cloudflare: AIProviderName.CLOUDFLARE,
-    cohere: AIProviderName.COHERE,
-    deepseek: AIProviderName.DEEPSEEK,
-    fireworks: AIProviderName.FIREWORKS,
-    googleAiStudio: AIProviderName.GOOGLE_AI,
-    googleVertex: AIProviderName.VERTEX,
-    groq: AIProviderName.GROQ,
-    huggingFace: AIProviderName.HUGGINGFACE,
-    ideogram: AIProviderName.IDEOGRAM,
-    jina: AIProviderName.JINA,
-    litellm: AIProviderName.LITELLM,
-    llamaCpp: AIProviderName.LLAMACPP,
-    lmStudio: AIProviderName.LM_STUDIO,
-    mistral: AIProviderName.MISTRAL,
-    nvidiaNim: AIProviderName.NVIDIA_NIM,
-    ollama: AIProviderName.OLLAMA,
-    openAI: AIProviderName.OPENAI,
-    openaiCompatible: AIProviderName.OPENAI_COMPATIBLE,
-    openRouter: AIProviderName.OPENROUTER,
-    perplexity: AIProviderName.PERPLEXITY,
-    recraft: AIProviderName.RECRAFT,
-    replicate: AIProviderName.REPLICATE,
-    stability: AIProviderName.STABILITY,
-    togetherAi: AIProviderName.TOGETHER_AI,
-    voyage: AIProviderName.VOYAGE,
-    xai: AIProviderName.XAI,
-};
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -94,12 +54,10 @@ export class ProviderRegistry {
      * (avoids circular dependencies; see CLAUDE.md).
      *
      * Not registered (by design): index.ts, providerTypeUtils.ts,
-     * openaiChatCompletionsBase.ts, openaiChatCompletionsClient.ts,
-     * anthropicImageBlocks.ts (shared base/helper modules), anthropicBaseProvider.ts
-     * (legacy; anthropic.ts is live), googleNativeGemini3.ts (shared helpers).
-     * Filename != provider ID (e.g. amazonBedrock -> "bedrock"); the
-     * statically-scannable PROVIDER_MODULE_TO_ID manifest maps every registered
-     * module to its provider ID and is enforced below (Pattern Analysis #1178/#1317).
+     * anthropicBaseProvider.ts (legacy; anthropic.ts is live),
+     * googleNativeGemini3.ts (shared helpers). Filename != provider ID
+     * (e.g. amazonBedrock -> "bedrock"); static scanners that miss dynamic
+     * imports may false-positive (Pattern Analysis #1178).
      */
     // eslint-disable-next-line max-lines-per-function
     static async _doRegister() {
@@ -270,16 +228,6 @@ export class ProviderRegistry {
                 const { RecraftProvider } = await import("../providers/recraft.js");
                 return new RecraftProvider(modelName, sdk, undefined, recraftCreds);
             }, process.env.RECRAFT_MODEL || RecraftModels.RECRAFT_V3, ["recraft"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.RECRAFT));
-            const unregistered = Object.entries(PROVIDER_MODULE_TO_ID).filter(([module, id]) => {
-                if (!ProviderFactory.hasProvider(id)) {
-                    logger.error(`[ProviderRegistry] drift: module "${module}" not registered as "${id}"`);
-                    return true;
-                }
-                return false;
-            });
-            if (unregistered.length > 0) {
-                throw new Error(`ProviderRegistry drift: ${unregistered.length} module(s) in PROVIDER_MODULE_TO_ID are not registered`);
-            }
             logger.debug("All AI providers registered successfully");
             // ===== TTS HANDLER REGISTRATION =====
             try {

package/dist/lib/utils/avatarProcessor.d.ts

@@ -43,7 +43,7 @@ export declare class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export declare class AvatarProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register an avatar handler for a specific provider.
      */
@@ -63,6 +63,10 @@ export declare class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): AvatarHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate an avatar video via the registered handler.

package/dist/lib/utils/avatarProcessor.js

@@ -13,6 +13,7 @@ import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { NeuroLinkError } from "./errorHandling.js";
 import { logger } from "./logger.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Avatar-specific error codes.
  */
@@ -47,38 +48,26 @@ export class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export class AvatarProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("AvatarProcessor");
     /**
      * Register an avatar handler for a specific provider.
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const key = providerName.toLowerCase();
-        if (this.handlers.has(key)) {
-            logger.warn(`[AvatarProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[AvatarProcessor] Registered avatar handler: ${key}`);
     }
     /**
      * Check if a provider has a registered avatar handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered avatar handler by provider name.
@@ -87,7 +76,13 @@ export class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

package/dist/lib/utils/musicProcessor.d.ts

@@ -42,7 +42,7 @@ export declare class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export declare class MusicProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register a music handler for a specific provider.
      */
@@ -62,6 +62,10 @@ export declare class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): MusicHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate a music track via the registered handler.

package/dist/lib/utils/musicProcessor.js

@@ -13,6 +13,7 @@ import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { NeuroLinkError } from "./errorHandling.js";
 import { logger } from "./logger.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Music-specific error codes.
  */
@@ -46,38 +47,26 @@ export class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export class MusicProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("MusicProcessor");
     /**
      * Register a music handler for a specific provider.
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const key = providerName.toLowerCase();
-        if (this.handlers.has(key)) {
-            logger.warn(`[MusicProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[MusicProcessor] Registered music handler: ${key}`);
     }
     /**
      * Check if a provider has a registered music handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered music handler by provider name.
@@ -86,7 +75,13 @@ export class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

package/dist/lib/utils/sttProcessor.d.ts

@@ -27,11 +27,10 @@ import type { STTOptions, STTResult, STTHandler } from "../types/index.js";
 export declare class STTProcessor {
     /**
      * Handler registry mapping provider names to STT handlers
-     * Uses Map for O(1) lookups and better type safety
      *
      * @private
      */
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Default maximum audio duration for STT transcription (in seconds)
      *
@@ -72,6 +71,15 @@ export declare class STTProcessor {
      * @returns Handler instance or undefined if not registered
      */
     static getHandler(providerName: string): STTHandler | undefined;
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders(): string[];
+    /**
+     * Removes every registered STT handler. Primarily for test isolation —
+     * production code should not need to call this.
+     */
+    static clearHandlers(): void;
     /**
      * Check if a provider is supported (has a registered STT handler)
      *