@juspay/neurolink 9.56.1 → 9.57.0

package/dist/files/fileReferenceRegistry.js

@@ -17,6 +17,7 @@ import { tmpdir } from "node:os";
 import { basename, extname, join } from "node:path";
 import { estimatePostProcessingTokens } from "../context/fileTokenBudget.js";
 import { logger } from "../utils/logger.js";
+import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "../utils/mimeTypeHints.js";
 import { StreamingReader } from "./streamingReader.js";
 import { SIZE_TIER_THRESHOLDS } from "../types/index.js";
 /** Default maximum files in registry before LRU eviction */
@@ -89,19 +90,33 @@ export class FileReferenceRegistry {
             const sizeMB = (sizeBytes / (1024 * 1024)).toFixed(1);
             throw new Error(`File too large (${sizeMB} MB). Maximum accepted size is 2 GB.`);
         }
+        // Normalize the caller-provided mimetype hint — shared helper drops
+        // `application/octet-stream` because that opaque sentinel would
+        // otherwise be trusted verbatim for the output mimeType and mask a
+        // better magic-byte-derived classification (e.g. PNG bytes hinted as
+        // octet-stream would record mimeType=octet-stream, not image/png).
+        const hintMime = normalizeMimeHint(options.mimetype);
+        const hintExt = hintMime ? mimeHintToExtension(hintMime) : "";
         // Detect file type from magic bytes and extension.
-        // If the provided filename has no extension, append one guessed from magic bytes
-        // so downstream processors (e.g., VideoProcessor) can validate by extension.
-        let filename = options.filename || `file-${Date.now()}${this.guessExtension(buffer)}`;
-        if (!extname(filename)) {
-            const guessedExt = this.guessExtension(buffer);
-            if (guessedExt) {
-                filename = `${filename}${guessedExt}`;
-            }
+        // If the provided filename has no extension, append one guessed from the
+        // mimetype hint first (more reliable for text formats than magic bytes),
+        // then fall back to magic bytes — so downstream processors (e.g.,
+        // VideoProcessor) can validate by extension. Compute once, reuse.
+        const synthDefaultExt = hintExt
+            ? `.${hintExt}`
+            : this.guessExtension(buffer);
+        let filename = options.filename || `file-${Date.now()}${synthDefaultExt}`;
+        if (!extname(filename) && synthDefaultExt) {
+            filename = `${filename}${synthDefaultExt}`;
         }
         const ext = extname(filename).toLowerCase().replace(".", "");
-        const detectedType = options.fileType || this.detectType(buffer, ext);
-        const mimeType = this.guessMimeType(detectedType, ext);
+        const detectedType = options.fileType ||
+            (hintMime && mimeHintToFileType(hintMime)) ||
+            this.detectType(buffer, ext);
+        // Prefer the caller's hint verbatim for the output mimeType, but only
+        // when normalizeMimeHint accepted it (i.e. it is not the opaque
+        // octet-stream sentinel). Otherwise derive from the detected type.
+        const mimeType = hintMime || this.guessMimeType(detectedType, ext);
         const sizeTier = FileReferenceRegistry.classifySizeTier(sizeBytes);
         // Generate preview (fast — only reads first N chars)
         const preview = this.extractPreview(buffer, detectedType, options.maxPreviewChars ?? this.defaultPreviewChars);

package/dist/index.js

@@ -37,7 +37,7 @@ export { AIProviderFactory };
 export { GoogleTTSHandler } from "./adapters/tts/googleTTSHandler.js";
 // Config Manager export
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
-// Core Infrastructure exports (Mastra-inspired patterns)
+// Core Infrastructure exports (factory + registry patterns)
 export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, withRetry, TypedEventEmitter, } from "./core/infrastructure/index.js";
 // ============================================================================
 // CLIENT SDK EXPORTS - Type-safe API access for browser and Node.js
@@ -107,6 +107,23 @@ export { SpanSerializer } from "./observability/utils/spanSerializer.js";
 // Middleware exports
 // Version
 export const VERSION = "1.0.0";
+// ============================================================================
+// Dynamic Arguments
+// ============================================================================
+//
+// Dynamic arguments let you pass functions instead of static values to
+// generate() and stream(). Resolution happens automatically before
+// provider dispatch. Pass dynamicContext inline for per-request
+// user/tenant/session context that dynamic functions can read.
+//
+// Example:
+//   await neurolink.generate({
+//     input: { text: "Hello" },
+//     model: (ctx) => ctx.requestContext.tenant?.plan === "enterprise"
+//       ? "gpt-4o" : "gpt-4o-mini",
+//     dynamicContext: { tenant: { id: "t1", plan: "enterprise" } },
+//   });
+// ============================================================================
 /**
  * Quick start factory function for creating AI provider instances.
  *
@@ -348,7 +365,7 @@ export async function getTelemetryStatus() {
 export { 
 // Main Evaluator
 Evaluator, 
-// Factory and Registry (Mastra-inspired patterns)
+// Factory and Registry
 EvaluationAggregator, EvaluatorFactory, getEvaluatorFactory, getEvaluatorRegistry, 
 // Error utilities
 evaluationErrors, isRetryableEvaluationError, isEvaluationError, createEvaluationFailedError, createParseError, createStrategyNotFoundError, createProviderError, createMaxRetriesExceededError, createBatchEvaluationError, createConfigurationError, contextToErrorContext, 

package/dist/lib/auth/AuthProviderFactory.d.ts

@@ -5,7 +5,7 @@
  * extension, no singleton instance. Providers are registered by
  * AuthProviderRegistry using dynamic imports to avoid circular dependencies.
  */
-import type { AuthProviderConfig, AuthProviderConstructor, AuthProviderMetadata, MastraAuthProvider } from "../types/index.js";
+import type { AuthProviderConfig, AuthProviderConstructor, AuthProviderMetadata, AuthProvider } from "../types/index.js";
 /**
  * AuthProviderFactory - Creates authentication provider instances
  *
@@ -33,7 +33,7 @@ export declare class AuthProviderFactory {
     /**
      * Create a provider instance
      */
-    static createProvider(typeOrAlias: string, config: AuthProviderConfig): Promise<MastraAuthProvider>;
+    static createProvider(typeOrAlias: string, config: AuthProviderConfig): Promise<AuthProvider>;
     /**
      * Check if a provider is registered
      */
@@ -66,4 +66,4 @@ export declare class AuthProviderFactory {
 /**
  * Create an auth provider using the factory
  */
-export declare function createAuthProvider(type: string, config: AuthProviderConfig): Promise<MastraAuthProvider>;
+export declare function createAuthProvider(type: string, config: AuthProviderConfig): Promise<AuthProvider>;

package/dist/lib/auth/providers/BaseAuthProvider.d.ts

@@ -10,7 +10,7 @@
  * - Error handling via unified AuthError factory
  */
 import { EventEmitter } from "events";
-import type { AuthenticatedContext, AuthHealthCheck, AuthorizationResult, AuthProviderConfig, AuthProviderType, AuthRequestContext, AuthSession, AuthUser, MastraAuthProvider, RBACConfig, SessionConfig, SessionStorage, SessionValidationResult, TokenClaims, TokenValidationResult } from "../../types/index.js";
+import type { AuthenticatedContext, AuthHealthCheck, AuthorizationResult, AuthProviderConfig, AuthProviderType, AuthRequestContext, AuthSession, AuthUser, AuthProvider, RBACConfig, SessionConfig, SessionStorage, SessionValidationResult, TokenClaims, TokenValidationResult } from "../../types/index.js";
 /**
  * @deprecated Use `AuthError` from `../errors.js` instead.
  * Kept for backward compatibility with CognitoProvider / KeycloakProvider.
@@ -81,7 +81,7 @@ export declare class InMemorySessionStorage implements SessionStorage {
  * - updateUserPermissions() - Update user permissions in provider
  * - dispose() - Clean up resources
  */
-export declare abstract class BaseAuthProvider implements MastraAuthProvider {
+export declare abstract class BaseAuthProvider implements AuthProvider {
     abstract readonly type: AuthProviderType;
     readonly config: AuthProviderConfig;
     protected sessionStorage: SessionStorage;

package/dist/lib/auth/providers/BaseAuthProvider.js

@@ -607,7 +607,7 @@ export class BaseAuthProvider {
         logger.debug(`[BaseAuthProvider] Disposed ${this.type} provider`);
     }
     // ===========================================================================
-    // METHODS FROM MastraAuthProvider INTERFACE
+    // METHODS FROM AuthProvider INTERFACE
     // ===========================================================================
     /**
      * Check if a user is authorized to perform an action

package/dist/lib/auth/serverBridge.d.ts

@@ -3,11 +3,11 @@
  * Converts an auth provider's authenticateToken() into the validate
  * callback expected by the existing createAuthMiddleware.
  */
-import type { MastraAuthProvider } from "../types/index.js";
+import type { AuthProvider } from "../types/index.js";
 /**
  * Create a validate function for server auth middleware from an auth provider.
  */
-export declare function createAuthValidatorFromProvider(provider: MastraAuthProvider): (token: string, ctx: unknown) => Promise<{
+export declare function createAuthValidatorFromProvider(provider: AuthProvider): (token: string, ctx: unknown) => Promise<{
     id: string;
     email?: string;
     roles?: string[];

package/dist/lib/dynamic/dynamicResolver.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Dynamic Argument Resolution Utilities
+ *
+ * Provides utilities for resolving dynamic arguments to their actual values,
+ * with support for caching, memoization, fallbacks, and conditional resolution.
+ *
+ * @module dynamic/dynamicResolver
+ */
+import type { DynamicArgument, DynamicResolutionContext, ResolutionOptions, ResolutionResult, DynamicConfig, ResolvedConfig } from "../types/index.js";
+/**
+ * Resolution cache for dynamic arguments
+ */
+declare class ResolutionCache {
+    private cache;
+    private cleanupInterval;
+    constructor(cleanupIntervalMs?: number);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+    private startCleanup;
+    destroy(): void;
+}
+declare const globalCache: ResolutionCache;
+/**
+ * Resolve a dynamic argument to its actual value
+ *
+ * @template T - The expected resolved type
+ * @param argument - The dynamic argument to resolve
+ * @param context - Resolution context (optional for static values)
+ * @param options - Resolution options
+ * @returns Resolution result with value and metadata
+ *
+ * @example Resolve static value
+ * ```typescript
+ * const result = await resolveDynamicArgument("gpt-4o");
+ * console.log(result.value); // "gpt-4o"
+ * console.log(result.resolutionType); // "static"
+ * ```
+ *
+ * @example Resolve context-aware function
+ * ```typescript
+ * const modelSelector = ({ requestContext }) =>
+ *   requestContext.tenant?.plan === "enterprise" ? "claude-3-opus" : "claude-3-sonnet";
+ *
+ * const result = await resolveDynamicArgument(modelSelector, {
+ *   requestContext: { requestId: "123", tenant: { id: "t1", plan: "enterprise" } }
+ * });
+ * console.log(result.value); // "claude-3-opus"
+ * ```
+ */
+export declare function resolveDynamicArgument<T>(argument: DynamicArgument<T>, context?: DynamicResolutionContext, options?: ResolutionOptions): Promise<ResolutionResult<T>>;
+/**
+ * Resolve multiple dynamic arguments in parallel
+ *
+ * @example
+ * ```typescript
+ * const [model, temperature] = await resolveDynamicArguments(
+ *   [
+ *     ({ requestContext }) => requestContext.user?.preferences?.preferredModel || "gpt-4o",
+ *     0.7,
+ *   ],
+ *   context
+ * );
+ * ```
+ */
+export declare function resolveDynamicArguments<T extends readonly unknown[]>(arguments_: {
+    [K in keyof T]: DynamicArgument<T[K]>;
+}, context?: DynamicResolutionContext, options?: ResolutionOptions): Promise<{
+    [K in keyof T]: T[K];
+}>;
+/**
+ * Resolve all properties of a dynamic configuration object
+ *
+ * @example
+ * ```typescript
+ * const dynamicConfig = {
+ *   model: ({ requestContext }) => requestContext.tenant?.settings?.defaultModel || "gpt-4o",
+ *   temperature: 0.7,
+ *   maxTokens: async () => (await fetchConfig()).maxTokens,
+ * };
+ *
+ * const resolved = await resolveDynamicConfig(dynamicConfig, context);
+ * // resolved.model, resolved.temperature, resolved.maxTokens are all resolved values
+ * ```
+ */
+export declare function resolveDynamicConfig<T extends Record<string, unknown>>(config: DynamicConfig<T>, context?: DynamicResolutionContext, options?: ResolutionOptions): Promise<ResolvedConfig<T>>;
+/**
+ * Create a memoized dynamic argument that caches its result
+ *
+ * @example
+ * ```typescript
+ * const expensiveModelSelector = memoizeDynamicArgument(
+ *   async ({ requestContext }) => {
+ *     const config = await fetchTenantConfig(requestContext.tenant?.id);
+ *     return config.preferredModel;
+ *   },
+ *   { cacheTtl: 300000 } // Cache for 5 minutes
+ * );
+ * ```
+ */
+export declare function memoizeDynamicArgument<T>(argument: DynamicArgument<T>, options?: {
+    cacheTtl?: number;
+    cacheKey?: string;
+}): DynamicArgument<T>;
+/**
+ * Create a dynamic argument with fallback chain
+ *
+ * @example
+ * ```typescript
+ * const modelWithFallback = withFallback(
+ *   ({ requestContext }) => requestContext.user?.preferences?.preferredModel,
+ *   ({ requestContext }) => requestContext.tenant?.settings?.defaultModel,
+ *   "gpt-4o" // Final static fallback
+ * );
+ * ```
+ */
+export declare function withFallback<T>(...arguments_: DynamicArgument<T | undefined | null>[]): DynamicArgument<T>;
+/**
+ * Create a conditional dynamic argument
+ *
+ * @example
+ * ```typescript
+ * const conditionalModel = conditional(
+ *   ({ requestContext }) => requestContext.tenant?.plan === "enterprise",
+ *   "claude-3-opus",   // If true
+ *   "claude-3-sonnet"  // If false
+ * );
+ * ```
+ */
+export declare function conditional<T>(condition: DynamicArgument<boolean>, ifTrue: DynamicArgument<T>, ifFalse: DynamicArgument<T>): DynamicArgument<T>;
+/**
+ * Create a mapped dynamic argument that transforms the result
+ *
+ * @example
+ * ```typescript
+ * const upperCaseModel = mapDynamicArgument(
+ *   ({ requestContext }) => requestContext.user?.preferences?.preferredModel,
+ *   (model) => model?.toUpperCase()
+ * );
+ * ```
+ */
+export declare function mapDynamicArgument<T, U>(argument: DynamicArgument<T>, transform: (value: T) => U | Promise<U>): DynamicArgument<U>;
+/**
+ * Create a dynamic argument that combines multiple arguments
+ *
+ * @example
+ * ```typescript
+ * const combinedConfig = combineDynamicArguments(
+ *   [
+ *     ({ requestContext }) => requestContext.user?.preferences?.preferredModel,
+ *     ({ requestContext }) => requestContext.tenant?.settings?.defaultTemperature,
+ *   ],
+ *   ([model, temperature]) => ({ model: model || "gpt-4o", temperature: temperature || 0.7 })
+ * );
+ * ```
+ */
+export declare function combineDynamicArguments<T extends readonly unknown[], U>(arguments_: {
+    [K in keyof T]: DynamicArgument<T[K]>;
+}, combiner: (values: T) => U | Promise<U>): DynamicArgument<U>;
+/**
+ * Check if a value contains any dynamic arguments (is a function)
+ */
+export declare function hasDynamicArgument<T>(value: DynamicArgument<T>): boolean;
+/**
+ * Check if an object has any dynamic properties
+ */
+export declare function hasDynamicProperties<T extends Record<string, unknown>>(config: DynamicConfig<T>): boolean;
+/**
+ * Clear the global resolution cache
+ */
+export declare function clearResolutionCache(): void;
+/**
+ * Get resolution cache statistics
+ */
+export declare function getResolutionCacheStats(): {
+    size: number;
+};
+/**
+ * Destroy the resolver (cleanup intervals, etc.)
+ */
+export declare function destroyResolver(): void;
+/**
+ * Interpolate environment variables in a string
+ *
+ * Supports syntax:
+ * - ${VAR} - Simple substitution
+ * - ${VAR:-default} - Use default if VAR is unset or empty
+ * - ${VAR:+replacement} - Use replacement if VAR is set and non-empty
+ *
+ * @example
+ * ```typescript
+ * interpolateEnvVars("Model: ${DEFAULT_MODEL:-gpt-4o}");
+ * // Returns "Model: gpt-4o" if DEFAULT_MODEL is not set
+ *
+ * interpolateEnvVars("API Key: ${OPENAI_API_KEY}");
+ * // Returns "API Key: sk-xxx..." if OPENAI_API_KEY is set
+ *
+ * interpolateEnvVars("Debug: ${DEBUG:+enabled}");
+ * // Returns "Debug: enabled" if DEBUG is set, "Debug: " otherwise
+ * ```
+ */
+export declare function interpolateEnvVars(input: string, customEnv?: Record<string, string | undefined>): string;
+/**
+ * Create a dynamic argument that interpolates environment variables
+ *
+ * @example
+ * ```typescript
+ * const model = fromEnv("${PREFERRED_MODEL:-gpt-4o}");
+ * // Resolves to value of PREFERRED_MODEL or "gpt-4o" as fallback
+ * ```
+ */
+export declare function fromEnv(template: string): DynamicArgument<string>;
+/**
+ * Create a dynamic argument from a single environment variable
+ *
+ * @example
+ * ```typescript
+ * const apiKey = envVar("OPENAI_API_KEY");
+ * // Resolves to value of OPENAI_API_KEY or undefined
+ *
+ * const model = envVar("DEFAULT_MODEL", "gpt-4o");
+ * // Resolves to DEFAULT_MODEL value or "gpt-4o" as default
+ * ```
+ */
+export declare function envVar<T extends string = string>(name: string, defaultValue?: T): DynamicArgument<T | undefined>;
+/**
+ * Create a dynamic argument that selects from environment-based configurations
+ *
+ * @example
+ * ```typescript
+ * const model = envSwitch("NODE_ENV", {
+ *   development: "gpt-4o-mini",
+ *   production: "gpt-4o",
+ *   test: "gpt-3.5-turbo",
+ * }, "gpt-4o-mini");
+ * ```
+ */
+export declare function envSwitch<T>(envVarName: string, options: Record<string, T>, defaultValue: T): DynamicArgument<T>;
+/**
+ * Create a dynamic argument that parses a JSON value from an environment variable
+ *
+ * @example
+ * ```typescript
+ * // If RATE_LIMITS='{"requestsPerMinute": 100, "tokensPerDay": 50000}'
+ * const rateLimits = envJson<RateLimits>("RATE_LIMITS", { requestsPerMinute: 10 });
+ * ```
+ */
+export declare function envJson<T>(name: string, defaultValue?: T): DynamicArgument<T | undefined>;
+/**
+ * Create a dynamic argument that reads a number from an environment variable
+ *
+ * @example
+ * ```typescript
+ * const maxTokens = envNumber("MAX_TOKENS", 1000);
+ * const temperature = envNumber("TEMPERATURE", 0.7);
+ * ```
+ */
+export declare function envNumber(name: string, defaultValue?: number): DynamicArgument<number | undefined>;
+/**
+ * Create a dynamic argument that reads a boolean from an environment variable
+ *
+ * @example
+ * ```typescript
+ * const enableDebug = envBoolean("DEBUG", false);
+ * const enableTools = envBoolean("ENABLE_TOOLS", true);
+ * ```
+ */
+export declare function envBoolean(name: string, defaultValue?: boolean): DynamicArgument<boolean | undefined>;
+/**
+ * Create a dynamic argument that reads a comma-separated list from an environment variable
+ *
+ * @example
+ * ```typescript
+ * // If ALLOWED_PROVIDERS='openai,anthropic,vertex'
+ * const providers = envList("ALLOWED_PROVIDERS", ["openai"]);
+ * // Returns ["openai", "anthropic", "vertex"]
+ * ```
+ */
+export declare function envList(name: string, defaultValue?: string[], separator?: string): DynamicArgument<string[] | undefined>;
+export { globalCache as resolutionCache };