@juspay/neurolink 11.27.0 → 11.29.0

package/dist/types/index.js

@@ -85,6 +85,7 @@ export * from "./video.js";
 export * from "./avatar.js";
 export * from "./music.js";
 export * from "./replicate.js";
+export * from "./mediaCatalog.js";
 // Safe-fetch helper types (SSRF-hardened download)
 export * from "./safeFetch.js";
 // ModelPool — multi-provider failover with per-member cooldown (M9.x+)
@@ -96,3 +97,5 @@ export * from "./classifierRouter.js";
 // Multi-Agent orchestration types
 export * from "./agentNetwork.js";
 export * from "./localUsage.js";
+// resolveRequestKind() dispatch-decision types
+export * from "./dispatch.js";

package/dist/types/mediaCatalog.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Types backing the static media-handler catalog
+ * (src/lib/factories/mediaHandlerCatalog.ts) — the single source of truth
+ * for provider names/aliases across the six media-generation ecosystems
+ * (TTS, STT, Realtime, Video, Avatar, Music).
+ */
+export type MediaHandlerKind = "tts" | "stt" | "realtime" | "video" | "avatar" | "music";
+export type MediaHandlerDescriptor = {
+    readonly kind: MediaHandlerKind;
+    readonly name: string;
+    readonly aliases?: readonly string[];
+};

package/dist/types/mediaCatalog.js

@@ -0,0 +1,7 @@
+/**
+ * Types backing the static media-handler catalog
+ * (src/lib/factories/mediaHandlerCatalog.ts) — the single source of truth
+ * for provider names/aliases across the six media-generation ecosystems
+ * (TTS, STT, Realtime, Video, Avatar, Music).
+ */
+export {};

package/dist/types/video.d.ts

@@ -13,6 +13,19 @@
  */
 import type { VideoGenerationResult, VideoOutputOptions } from "./multimodal.js";
 export type { VideoGenerationResult, VideoOutputOptions, } from "./multimodal.js";
+/**
+ * Bag-form input to `VideoProcessor.generate()` — the primary data (image,
+ * prompt, region) alongside the video-specific output options, collapsed
+ * into a single object matching Music/Avatar's existing `generate(provider,
+ * options)` shape. `VideoHandler.generate()`'s own 4-positional-argument
+ * signature is unchanged; `VideoProcessor.generate()` translates between the
+ * two internally.
+ */
+export type VideoGenerateOptions = VideoOutputOptions & {
+    image: Buffer;
+    prompt: string;
+    region?: string;
+};
 /**
  * Director-mode transition options.
  *

package/dist/utils/videoProcessor.d.ts

@@ -11,7 +11,7 @@
  * @module utils/videoProcessor
  */
 import { VIDEO_ERROR_CODES } from "../constants/videoErrors.js";
-import type { VideoGenerationResult, VideoHandler, VideoOutputOptions, VideoTransitionOptions } from "../types/index.js";
+import type { VideoGenerateOptions, VideoGenerationResult, VideoHandler, VideoOutputOptions, VideoTransitionOptions } from "../types/index.js";
 import { VideoError } from "../adapters/video/vertexVideoHandler.js";
 export { VideoError, VIDEO_ERROR_CODES };
 /**
@@ -45,13 +45,19 @@ export declare class VideoProcessor {
      * Generate a single video clip via the registered handler.
      *
      * @param provider - Registered provider name (e.g. "vertex", "kling")
-     * @param image - Source image buffer
-     * @param prompt - Text prompt describing the desired motion / content
-     * @param options - Resolution / length / aspect-ratio / audio options
-     * @param region - Optional region override (Vertex location, etc.)
+     * @param options - Bag of the source image, prompt, optional region
+     *   override, and resolution / length / aspect-ratio / audio options.
+     *   Translated internally into the handler-level 4-positional-argument
+     *   call — `VideoHandler.generate()`'s own signature is unchanged.
      * @throws VideoError on registry miss, handler-not-configured, or
      *         generation failure
      */
+    static generate(provider: string, options: VideoGenerateOptions): Promise<VideoGenerationResult>;
+    /**
+     * @deprecated Positional form kept for backward compatibility with
+     * pre-bag callers (VideoProcessor is a public export). Use the
+     * options-bag overload.
+     */
     static generate(provider: string, image: Buffer, prompt: string, options: VideoOutputOptions, region?: string): Promise<VideoGenerationResult>;
     /**
      * Generate a transition clip via the registered handler (Director Mode).

package/dist/utils/videoProcessor.js

@@ -14,6 +14,11 @@ import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { VIDEO_ERROR_CODES } from "../constants/videoErrors.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { logger } from "./logger.js";
+import { withTimeout } from "./async/withTimeout.js";
+// Video generation is legitimately minutes-long (Kling/Runway render queues),
+// so the bound is generous — its job is to convert a wedged handler into an
+// error rather than an eternal hang, not to police normal latency.
+const VIDEO_GENERATION_TIMEOUT_MS = 600_000;
 // VideoError is canonical in vertexVideoHandler.ts (existing). Re-export
 // here so consumers of `VideoProcessor` can import the typed error from
 // the same module. Both throws and instanceof checks resolve to the same
@@ -69,19 +74,17 @@ export class VideoProcessor {
             "video.audio": options.audio,
         };
     }
-    /**
-     * Generate a single video clip via the registered handler.
-     *
-     * @param provider - Registered provider name (e.g. "vertex", "kling")
-     * @param image - Source image buffer
-     * @param prompt - Text prompt describing the desired motion / content
-     * @param options - Resolution / length / aspect-ratio / audio options
-     * @param region - Optional region override (Vertex location, etc.)
-     * @throws VideoError on registry miss, handler-not-configured, or
-     *         generation failure
-     */
-    static async generate(provider, image, prompt, options, region) {
-        const span = SpanSerializer.createSpan(SpanType.MEDIA_GENERATION, "video.generate", this.buildSpanAttributes(provider, options));
+    static async generate(provider, optionsOrImage, legacyPrompt, legacyOptions, legacyRegion) {
+        const bag = Buffer.isBuffer(optionsOrImage)
+            ? {
+                image: optionsOrImage,
+                prompt: legacyPrompt ?? "",
+                ...(legacyRegion !== undefined ? { region: legacyRegion } : {}),
+                ...(legacyOptions ?? {}),
+            }
+            : optionsOrImage;
+        const { image, prompt, region, ...videoOptions } = bag;
+        const span = SpanSerializer.createSpan(SpanType.MEDIA_GENERATION, "video.generate", this.buildSpanAttributes(provider, videoOptions));
         try {
             const handler = this.getHandler(provider);
             if (!handler) {
@@ -105,7 +108,10 @@ export class VideoProcessor {
                 });
             }
             logger.debug(`[VideoProcessor] Starting video generation with provider: ${provider}`);
-            const result = await handler.generate(image, prompt, options, region);
+            // Bounded per repo guideline (async provider calls wrap withTimeout):
+            // video generation is legitimately slow, so the deadline is generous —
+            // but a wedged handler must error, never hang the caller forever.
+            const result = await withTimeout(handler.generate(image, prompt, videoOptions, region), VIDEO_GENERATION_TIMEOUT_MS, `Video generation via "${provider}" timed out after ${VIDEO_GENERATION_TIMEOUT_MS}ms`);
             const ended = SpanSerializer.endSpan(span, SpanStatus.OK);
             getMetricsAggregator().recordSpan(ended);
             logger.info(`[VideoProcessor] Generated ${result.data.length} bytes (${provider})`);
@@ -124,7 +130,7 @@ export class VideoProcessor {
                 category: ErrorCategory.EXECUTION,
                 severity: ErrorSeverity.HIGH,
                 retriable: true,
-                context: { provider, options, region },
+                context: { provider, options: videoOptions, region },
                 originalError: err instanceof Error ? err : undefined,
             });
         }
@@ -169,7 +175,8 @@ export class VideoProcessor {
             });
         }
         try {
-            return await handler.generateTransition(firstFrame, lastFrame, prompt, options, region);
+            // Same bound as generate(): a wedged transition must error, not hang.
+            return await withTimeout(handler.generateTransition(firstFrame, lastFrame, prompt, options, region), VIDEO_GENERATION_TIMEOUT_MS, `Video transition via "${provider}" timed out after ${VIDEO_GENERATION_TIMEOUT_MS}ms`);
         }
         catch (err) {
             if (err instanceof VideoError) {

package/dist/voice/index.d.ts

@@ -8,9 +8,13 @@
  * Use STTProcessor (src/lib/utils/sttProcessor.ts) for STT.
  * Use RealtimeProcessor for realtime voice sessions.
  *
- * Importing this module also auto-registers every shipped TTS / STT /
- * Realtime handler whose backing API key is present in `process.env`.
- * Registration is idempotent and silently skipped on failure.
+ * Importing this module does NOT register any handlers as a side effect.
+ * Call `registerDefaultTTSHandlers()` / `registerDefaultSTTHandlers()` /
+ * `registerDefaultRealtimeHandlers()` explicitly (or go through
+ * `ProviderRegistry.registerAllProviders()`, which every documented
+ * `NeuroLink` entry point already calls) to register every shipped handler
+ * whose backing API key is present in `process.env`. Registration is
+ * idempotent and silently skipped on failure.
  *
  * @module voice
  */

package/dist/voice/index.js

@@ -8,12 +8,17 @@
  * Use STTProcessor (src/lib/utils/sttProcessor.ts) for STT.
  * Use RealtimeProcessor for realtime voice sessions.
  *
- * Importing this module also auto-registers every shipped TTS / STT /
- * Realtime handler whose backing API key is present in `process.env`.
- * Registration is idempotent and silently skipped on failure.
+ * Importing this module does NOT register any handlers as a side effect.
+ * Call `registerDefaultTTSHandlers()` / `registerDefaultSTTHandlers()` /
+ * `registerDefaultRealtimeHandlers()` explicitly (or go through
+ * `ProviderRegistry.registerAllProviders()`, which every documented
+ * `NeuroLink` entry point already calls) to register every shipped handler
+ * whose backing API key is present in `process.env`. Registration is
+ * idempotent and silently skipped on failure.
  *
  * @module voice
  */
+import { MEDIA_HANDLER_CATALOG } from "../factories/mediaHandlerCatalog.js";
 import { logger } from "../utils/logger.js";
 import { STTProcessor } from "../utils/sttProcessor.js";
 import { TTSProcessor } from "../utils/ttsProcessor.js";
@@ -76,37 +81,48 @@ import { GoogleSTT } from "./providers/GoogleSTT.js";
 import { OpenAISTT } from "./providers/OpenAISTT.js";
 import { GeminiLive } from "./providers/GeminiLive.js";
 import { OpenAIRealtime } from "./providers/OpenAIRealtime.js";
-const TTS_HANDLER_CANDIDATES = [
-    {
-        // Google TTS doubles as both the AI Studio and Vertex TTS handler.
-        name: "google-ai",
-        aliases: ["vertex"],
-        factory: () => new GoogleTTSHandler(),
-    },
-    { name: "openai-tts", factory: () => new OpenAITTS() },
-    {
-        name: "elevenlabs",
-        aliases: ["elevenlabs-tts"],
-        factory: () => new ElevenLabsTTS(),
-    },
-    { name: "azure-tts", factory: () => new AzureTTS() },
-    { name: "fish-audio", factory: () => new FishAudioTTS() },
-    { name: "cartesia", factory: () => new CartesiaTTS() },
-];
-const STT_HANDLER_CANDIDATES = [
-    {
-        name: "whisper",
-        aliases: ["openai-stt"],
-        factory: () => new OpenAISTT(),
-    },
-    { name: "deepgram", factory: () => new DeepgramSTT() },
-    { name: "google-stt", factory: () => new GoogleSTT() },
-    { name: "azure-stt", factory: () => new AzureSTT() },
-];
-const REALTIME_HANDLER_CANDIDATES = [
-    { name: "openai-realtime", factory: () => new OpenAIRealtime() },
-    { name: "gemini-live", factory: () => new GeminiLive() },
-];
+// Provider names + aliases are the Task-8 catalog's job — only the factory
+// (which needs the imported handler class) stays local to this module.
+const TTS_HANDLER_FACTORIES = {
+    // Google TTS doubles as both the AI Studio and Vertex TTS handler.
+    "google-ai": () => new GoogleTTSHandler(),
+    "openai-tts": () => new OpenAITTS(),
+    elevenlabs: () => new ElevenLabsTTS(),
+    "azure-tts": () => new AzureTTS(),
+    "fish-audio": () => new FishAudioTTS(),
+    cartesia: () => new CartesiaTTS(),
+};
+const TTS_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kind === "tts").map((entry) => {
+    const factory = TTS_HANDLER_FACTORIES[entry.name];
+    if (!factory) {
+        throw new Error(`[voice/tts] no handler factory for catalog entry "${entry.name}"`);
+    }
+    return { name: entry.name, aliases: entry.aliases, factory };
+});
+const STT_HANDLER_FACTORIES = {
+    whisper: () => new OpenAISTT(),
+    deepgram: () => new DeepgramSTT(),
+    "google-stt": () => new GoogleSTT(),
+    "azure-stt": () => new AzureSTT(),
+};
+const STT_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kind === "stt").map((entry) => {
+    const factory = STT_HANDLER_FACTORIES[entry.name];
+    if (!factory) {
+        throw new Error(`[voice/stt] no handler factory for catalog entry "${entry.name}"`);
+    }
+    return { name: entry.name, aliases: entry.aliases, factory };
+});
+const REALTIME_HANDLER_FACTORIES = {
+    "openai-realtime": () => new OpenAIRealtime(),
+    "gemini-live": () => new GeminiLive(),
+};
+const REALTIME_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kind === "realtime").map((entry) => {
+    const factory = REALTIME_HANDLER_FACTORIES[entry.name];
+    if (!factory) {
+        throw new Error(`[voice/realtime] no handler factory for catalog entry "${entry.name}"`);
+    }
+    return { name: entry.name, aliases: entry.aliases, factory };
+});
 function registerCandidates(candidates, supports, getRegistered, register, scope, requireConfigured) {
     for (const { name, aliases, factory } of candidates) {
         // Compute missingName / missingAliases separately so a manually-
@@ -168,9 +184,3 @@ export function registerDefaultSTTHandlers() {
 export function registerDefaultRealtimeHandlers() {
     registerCandidates(REALTIME_HANDLER_CANDIDATES, (name) => RealtimeProcessor.supports(name), (name) => RealtimeProcessor.getHandler(name), (name, handler) => RealtimeProcessor.registerHandler(name, handler), "voice/realtime", false);
 }
-// Run once at module import so consumers who follow the documented
-// `nl.generate(...)` flow get every configured handler without manually
-// calling `registerHandler`.
-registerDefaultTTSHandlers();
-registerDefaultSTTHandlers();
-registerDefaultRealtimeHandlers();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.27.0",
+  "version": "11.29.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -73,6 +73,7 @@
     "test:context": "pnpm exec tsx test/continuous-test-suite-context.ts",
     "test:evaluation": "pnpm exec tsx test/continuous-test-suite-evaluation.ts",
     "test:handler-registry": "pnpm exec tsx test/continuous-test-suite-handler-registry.ts",
+    "test:resolve-request-kind": "pnpm exec tsx test/continuous-test-suite-resolve-request-kind.ts",
     "test:mcp": "pnpm exec tsx test/continuous-test-suite-mcp-infra.ts",
     "test:tool-resolution": "pnpm exec tsx test/continuous-test-suite-tool-resolution.ts",
     "test:mcp:http": "pnpm exec tsx test/continuous-test-suite-mcp-http.ts",
@@ -80,6 +81,7 @@
     "test:mcp:cli": "pnpm exec tsx test/continuous-test-suite-mcp-cli.ts",
     "test:mcp:full": "pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:mcp:sdk && pnpm run test:mcp:cli && pnpm run test:mcp:http",
     "test:media": "pnpm exec tsx test/continuous-test-suite-media-gen.ts",
+    "test:media-registry-collisions": "pnpm exec tsx test/continuous-test-suite-media-registry-collisions.ts",
     "test:memory": "pnpm exec tsx test/continuous-test-suite-memory.ts",
     "test:openai-compat-streaming-retry": "pnpm exec tsx test/continuous-test-suite-openai-compat-streaming-retry.ts",
     "test:anthropic-streaming-retry": "pnpm exec tsx test/continuous-test-suite-anthropic-streaming-retry.ts",