@pwshub/aisdk 0.0.5 → 0.0.6

package/src/logger.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Configurable logger for @pwshub/aisdk
+ *
+ * Provides a default console logger with the ability to set custom
+ * or no-op loggers for production environments.
+ */
+
+/**
+ * @typedef {Object} Logger
+ * @property {(message: string) => void} warn
+ * @property {(message: string) => void} error
+ * @property {(message: string) => void} debug
+ */
+
+const defaultLogger = {
+  warn: (message) => console.warn(message),
+  error: (message) => console.error(message),
+  debug: (message) => console.debug(message),
+}
+
+let currentLogger = defaultLogger
+
+/**
+ * Sets a custom logger instance
+ * @param {Logger} logger
+ * @throws {Error} When logger doesn't implement required methods
+ */
+export const setLogger = (logger) => {
+  if (!logger || typeof logger.warn !== 'function' || typeof logger.error !== 'function') {
+    throw new Error('Logger must implement warn() and error() methods')
+  }
+  currentLogger = logger
+}
+
+/**
+ * Returns the current logger instance
+ * @returns {Logger}
+ */
+export const getLogger = () => currentLogger
+
+/**
+ * No-op logger for silencing all output
+ */
+export const noopLogger = {
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+}

package/src/models.js

@@ -198,6 +198,11 @@ export const DEFAULT_MODELS = [
     max_in: 400000,
     max_out: 128000,
     enable: true,
+    // gpt-5-nano only supports default values for temperature and top_p
+    paramOverrides: {
+      temperature: { fixedValue: 1 },
+      topP: { fixedValue: 1 },
+    },
   },
   {
     id: 'gpt-5.1',

package/src/providers.js

@@ -42,7 +42,7 @@ const openai = {
     Authorization: `Bearer ${apikey}`,
     'Content-Type': 'application/json',
   }),
-  url: () => 'https://api.openai.com/v1/chat/completions',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.openai.com/v1/chat/completions',
   buildBody: (modelName, messages, config, providerOptions) => ({
     model: modelName,
     messages,
@@ -96,7 +96,7 @@ const anthropic = {
     'anthropic-version': '2023-06-01',
     'Content-Type': 'application/json',
   }),
-  url: () => 'https://api.anthropic.com/v1/messages',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.anthropic.com/v1/messages',
   buildBody: (modelName, messages, config, providerOptions) => {
     const system = messages.find((m) => m.role === 'system')?.content
     const filtered = messages.filter((m) => m.role !== 'system')
@@ -129,8 +129,12 @@ const anthropic = {
 /** @type {ProviderAdapter} */
 const google = {
   headers: () => ({ 'Content-Type': 'application/json' }),
-  url: (modelName, apikey) =>
-    `https://generativelanguage.googleapis.com/v1/models/${modelName}:generateContent?key=${apikey}`,
+  url: (modelName, apikey, gatewayUrl) => {
+    if (gatewayUrl) {
+      return gatewayUrl
+    }
+    return `https://generativelanguage.googleapis.com/v1/models/${modelName}:generateContent?key=${apikey}`
+  },
   buildBody: (modelName, messages, config, providerOptions) => {
     const system = messages.find((m) => m.role === 'system')?.content
     const contents = messages
@@ -243,7 +247,7 @@ const dashscope = {
   }),
   // International users should use dashscope-intl.aliyuncs.com
   // China users can use dashscope.aliyuncs.com
-  url: () => 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions',
   buildBody: (modelName, messages, config, providerOptions) => ({
     model: modelName,
     messages,
@@ -276,7 +280,7 @@ const deepseek = {
     Authorization: `Bearer ${apikey}`,
     'Content-Type': 'application/json',
   }),
-  url: () => 'https://api.deepseek.com/chat/completions',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.deepseek.com/chat/completions',
   buildBody: (modelName, messages, config, providerOptions) => ({
     model: modelName,
     messages,
@@ -305,7 +309,7 @@ const mistral = {
     'Content-Type': 'application/json',
     Accept: 'application/json',
   }),
-  url: () => 'https://api.mistral.ai/v1/chat/completions',
+  url: (modelName, apikey, gatewayUrl) => gatewayUrl || 'https://api.mistral.ai/v1/chat/completions',
   buildBody: (modelName, messages, config, providerOptions) => ({
     model: modelName,
     messages,
@@ -333,8 +337,14 @@ const ollama = {
     'Content-Type': 'application/json',
     ...(apikey && { Authorization: `Bearer ${apikey}` }),
   }),
-  // Default to localhost, but can be overridden via gatewayUrl
-  url: () => 'http://localhost:11434/api/chat',
+  url: (modelName, apikey, gatewayUrl) => {
+    if (gatewayUrl) {
+      return gatewayUrl
+    }
+    // Warn about localhost default in development
+    console.warn('[ai-client] Ollama using default localhost URL (http://localhost:11434). Set gatewayUrl in createAi() for production.')
+    return 'http://localhost:11434/api/chat'
+  },
   buildBody: (modelName, messages, config, providerOptions) => {
     // Ollama uses snake_case options
     const options = {}

package/src/registry.js

@@ -30,6 +30,7 @@ import { DEFAULT_MODELS } from './models.js'
  * @property {number} max_out               - Max output tokens
  * @property {boolean} enable
  * @property {string[]} [supportedParams]   - Canonical param names; falls back to provider default
+ * @property {Record<string, import('./coerce.js').ParamOverride>} [paramOverrides] - Model-specific param overrides
  */
 
 /**
@@ -51,11 +52,116 @@ export const PROVIDER_DEFAULT_PARAMS = {
 /** @type {ProviderId[]} */
 const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'dashscope', 'deepseek', 'mistral', 'ollama']
 
+/**
+ * Creates a new registry instance with the given models
+ * @param {import('./models.js').ModelRecord[]} [initialModels] - Initial models to load (defaults to DEFAULT_MODELS)
+ * @returns {{
+ *   getModel: (modelId: string) => { record: ModelRecord, supportedParams: string[], paramOverrides: Record<string, import('./coerce.js').ParamOverride> },
+ *   listModels: () => ModelRecord[],
+ *   addModels: (models: ModelRecord[]) => void,
+ *   setModels: (models: ModelRecord[]) => void
+ * }}
+ */
+export const createRegistry = (initialModels = DEFAULT_MODELS) => {
+  /** @type {Map<string, ModelRecord>} */
+  let REGISTRY = new Map(initialModels.map((model) => {
+    const normalized = normalizeModelRecord(model)
+    return [normalized.id, normalized]
+  }))
+
+  /**
+   * Looks up a model by provider/name format.
+   * @param {string} modelId - Model in 'provider/name' format
+   * @returns {{ record: ModelRecord, supportedParams: string[], paramOverrides: Record<string, import('./coerce.js').ParamOverride> }}
+   */
+  const getModel = (modelId) => {
+    if (!modelId.includes('/')) {
+      const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+      throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
+    }
+
+    const parts = modelId.split('/')
+    if (parts.length !== 2) {
+      const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+      throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
+    }
+
+    const [provider, name] = parts
+
+    for (const m of REGISTRY.values()) {
+      if (m.name === name && m.provider === provider) {
+        const record = m
+
+        if (!record.enable) {
+          throw new Error(`Model "${record.provider}/${record.name}" is currently disabled.`)
+        }
+
+        const supportedParams = record.supportedParams ?? PROVIDER_DEFAULT_PARAMS[record.provider]
+        const paramOverrides = record.paramOverrides ?? {}
+
+        return {
+          record, supportedParams, paramOverrides,
+        }
+      }
+    }
+
+    const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
+    throw new Error(`Unknown model "${modelId}". Available: ${available}`)
+  }
+
+  /**
+   * Returns all enabled model records.
+   * @returns {ModelRecord[]}
+   */
+  const listModels = () =>
+    [...REGISTRY.values()].filter((m) => m.enable)
+
+  /**
+   * Adds one or more models to the registry.
+   * @param {ModelRecord[]} models - Array of model records to add
+   */
+  const addModels = (models) => {
+    if (!Array.isArray(models)) {
+      throw new Error(`addModels expects an array. Got: ${typeof models}`)
+    }
+
+    models.forEach((model, index) => {
+      validateModelRecord(model, index)
+    })
+
+    models.forEach((model) => {
+      const normalized = normalizeModelRecord(model)
+      REGISTRY.set(normalized.id, normalized)
+    })
+  }
+
+  /**
+   * Replaces the entire registry with a new list of models.
+   * @param {ModelRecord[]} models - Array of model records
+   */
+  const setModels = (models) => {
+    if (!Array.isArray(models)) {
+      throw new Error(`setModels expects an array. Got: ${typeof models}`)
+    }
+
+    models.forEach((model, index) => {
+      validateModelRecord(model, index)
+    })
+
+    REGISTRY = new Map(models.map((model) => {
+      const normalized = normalizeModelRecord(model)
+      return [normalized.id, normalized]
+    }))
+  }
+
+  return { getModel, listModels, addModels, setModels }
+}
+
 /** @type {Map<string, ModelRecord>} */
 let REGISTRY = new Map()
 
 /**
- * Initializes the registry with default models.
+ * Initializes the global registry with default models.
  * Called automatically at module import.
  */
 const initRegistry = () => {
@@ -114,6 +220,50 @@ const validateModelRecord = (model, index) => {
     }
   }
 
+  // Check optional paramOverrides if present
+  if (model.paramOverrides !== undefined) {
+    if (typeof model.paramOverrides !== 'object' || model.paramOverrides === null || Array.isArray(model.paramOverrides)) {
+      errors.push('"paramOverrides" must be an object')
+    } else {
+      for (const [param, override] of Object.entries(model.paramOverrides)) {
+        if (typeof override !== 'object' || override === null) {
+          errors.push(`"paramOverrides.${param}" must be an object`)
+        } else {
+          // Check that override has at least one valid property
+          const validKeys = ['fixedValue', 'supportedValues', 'range']
+          const hasValidKey = Object.keys(override).some((k) => validKeys.includes(k))
+          if (!hasValidKey) {
+            errors.push(`"paramOverrides.${param}" must have at least one of: ${validKeys.join(', ')}`)
+          }
+          // Validate fixedValue type
+          if (override.fixedValue !== undefined && typeof override.fixedValue !== 'number') {
+            errors.push(`"paramOverrides.${param}.fixedValue" must be a number`)
+          }
+          // Validate supportedValues type
+          if (override.supportedValues !== undefined) {
+            if (!Array.isArray(override.supportedValues)) {
+              errors.push(`"paramOverrides.${param}.supportedValues" must be an array`)
+            } else {
+              override.supportedValues.forEach((v, i) => {
+                if (typeof v !== 'number') {
+                  errors.push(`"paramOverrides.${param}.supportedValues[${i}]" must be a number`)
+                }
+              })
+            }
+          }
+          // Validate range type
+          if (override.range !== undefined) {
+            if (typeof override.range !== 'object' || override.range === null) {
+              errors.push(`"paramOverrides.${param}.range" must be an object`)
+            } else if (typeof override.range.min !== 'number' || typeof override.range.max !== 'number') {
+              errors.push(`"paramOverrides.${param}.range" must have numeric min and max`)
+            }
+          }
+        }
+      }
+    }
+  }
+
   if (errors.length > 0) {
     throw new Error(`Invalid model record at index ${index}: ${errors.join('; ')}`)
   }
@@ -138,55 +288,55 @@ const normalizeModelRecord = (model) => {
     max_out: model.max_out ?? 8000,
     enable: model.enable ?? true,
     ...(model.supportedParams !== undefined && { supportedParams: model.supportedParams }),
+    ...(model.paramOverrides !== undefined && { paramOverrides: model.paramOverrides }),
   }
 }
 
 /**
- * Looks up a model by provider/name format.
- * Validates it is enabled, and resolves its effective supported params.
+ * Gets a model from the global registry (for backward compatibility).
+ * For isolated registries, use the getModel from createRegistry() instead.
  *
- * @param {string} modelId - Model in 'provider/name' format (e.g., 'openai/gpt-4o', 'ollama/llama3.2')
- * @returns {{ record: ModelRecord, supportedParams: string[] }}
- * @throws {Error} When the model is not found or is disabled
+ * @param {string} modelId - Model in 'provider/name' format
+ * @returns {{ record: ModelRecord, supportedParams: string[], paramOverrides: Record<string, import('./coerce.js').ParamOverride> }}
  */
 export const getModel = (modelId) => {
-  // Require provider/name format
   if (!modelId.includes('/')) {
     const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
     throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
   }
-  
+
   const parts = modelId.split('/')
   if (parts.length !== 2) {
     const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
     throw new Error(`Model must be in 'provider/name' format. Got: "${modelId}". Available: ${available}`)
   }
-  
+
   const [provider, name] = parts
-  
-  // Search for model by name and provider
+
   for (const m of REGISTRY.values()) {
     if (m.name === name && m.provider === provider) {
       const record = m
-      
+
       if (!record.enable) {
         throw new Error(`Model "${record.provider}/${record.name}" is currently disabled.`)
       }
 
       const supportedParams = record.supportedParams ?? PROVIDER_DEFAULT_PARAMS[record.provider]
+      const paramOverrides = record.paramOverrides ?? {}
 
       return {
-        record, supportedParams,
+        record, supportedParams, paramOverrides,
       }
     }
   }
-  
+
   const available = [...REGISTRY.values()].map(m => `${m.provider}/${m.name}`).join(', ')
   throw new Error(`Unknown model "${modelId}". Available: ${available}`)
 }
 
 /**
- * Returns all enabled model records.
+ * Returns all enabled model records from the global registry.
+ * For isolated registries, use the listModels from createRegistry() instead.
  *
  * @returns {ModelRecord[]}
  */
@@ -194,23 +344,20 @@ export const listModels = () =>
   [...REGISTRY.values()].filter((m) => m.enable)
 
 /**
- * Adds one or more models to the registry.
- * Existing models with the same ID are overwritten.
+ * Adds one or more models to the global registry.
+ * For isolated registries, use the addModels from createRegistry() instead.
  *
  * @param {ModelRecord[]} models - Array of model records to add
- * @throws {Error} When models is not an array or contains invalid records
  */
 export const addModels = (models) => {
   if (!Array.isArray(models)) {
     throw new Error(`addModels expects an array. Got: ${typeof models}`)
   }
 
-  // Validate and normalize each model record
   models.forEach((model, index) => {
     validateModelRecord(model, index)
   })
 
-  // Add normalized models to the registry
   models.forEach((model) => {
     const normalized = normalizeModelRecord(model)
     REGISTRY.set(normalized.id, normalized)
@@ -218,18 +365,16 @@ export const addModels = (models) => {
 }
 
 /**
- * Replaces the entire model registry with a new list of models.
- * Use this to load models from a CMS or other external source.
+ * Replaces the entire global registry with a new list of models.
+ * For isolated registries, use the setModels from createRegistry() instead.
  *
  * @param {ModelRecord[]} models - Array of model records
- * @throws {Error} When models is not an array or contains invalid records
  */
 export const setModels = (models) => {
   if (!Array.isArray(models)) {
     throw new Error(`setModels expects an array. Got: ${typeof models}`)
   }
 
-  // Validate and normalize each model record
   models.forEach((model, index) => {
     validateModelRecord(model, index)
   })

package/src/security.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Security utilities for @pwshub/aisdk
+ *
+ * Provides API key validation, sanitization for logging,
+ * and other security-related functions.
+ */
+
+import { InputError } from './errors.js'
+
+/**
+ * Sensitive field patterns to redact from logs
+ * @type {string[]}
+ */
+const SENSITIVE_KEYS = [
+  'apikey',
+  'api_key',
+  'apiKey',
+  'authorization',
+  'key',
+  'token',
+  'secret',
+  'password',
+  'credential',
+]
+
+/**
+ * Sanitizes an object for safe logging by removing/masking sensitive fields
+ * @param {unknown} obj - The object to sanitize
+ * @returns {unknown} Sanitized object safe for logging
+ */
+export const sanitizeForLogging = (obj) => {
+  if (typeof obj !== 'object' || obj === null) {
+    return obj
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(sanitizeForLogging)
+  }
+
+  const sanitized = {}
+
+  for (const [key, value] of Object.entries(obj)) {
+    const lowerKey = key.toLowerCase()
+    if (SENSITIVE_KEYS.some((s) => lowerKey.includes(s))) {
+      sanitized[key] = '[REDACTED]'
+    } else if (typeof value === 'object' && value !== null) {
+      sanitized[key] = sanitizeForLogging(value)
+    } else {
+      sanitized[key] = value
+    }
+  }
+
+  return sanitized
+}
+
+/**
+ * Provider-specific API key format patterns for validation warnings
+ * @type {Record<string, {pattern: RegExp, message: string}>}
+ */
+const API_KEY_PATTERNS = {
+  openai: {
+    pattern: /^sk-[a-zA-Z0-9]{20,}/,
+    message: 'OpenAI API key format looks incorrect (should start with sk-)',
+  },
+  anthropic: {
+    pattern: /^sk-ant-[a-zA-Z0-9_-]{20,}/i,
+    message: 'Anthropic API key format looks incorrect (should start with sk-ant-)',
+  },
+  google: {
+    pattern: /^AIza[0-9A-Za-z_-]{35}/,
+    message: 'Google API key format looks incorrect (should start with AIza)',
+  },
+  deepseek: {
+    pattern: /^sk-[a-zA-Z0-9]{20,}/,
+    message: 'DeepSeek API key format looks incorrect (should start with sk-)',
+  },
+  mistral: {
+    pattern: /^[a-zA-Z0-9]{32,}/,
+    message: 'Mistral API key format looks incorrect',
+  },
+  dashscope: {
+    pattern: /^sk-[a-zA-Z0-9]{20,}/,
+    message: 'DashScope API key format looks incorrect (should start with sk-)',
+  },
+  ollama: {
+    // Ollama doesn't require API keys, so no validation
+    pattern: /.*/,
+    message: '',
+  },
+}
+
+/**
+ * Validates API key format per provider
+ * @param {string} apikey - The API key to validate
+ * @param {string} provider - The provider ID
+ * @param {import('./logger.js').Logger} logger - Logger instance for warnings
+ * @throws {InputError} When API key is missing or empty
+ */
+export const validateApiKey = (apikey, provider, logger) => {
+  // Check if API key is provided and not empty
+  if (!apikey || typeof apikey !== 'string' || apikey.trim() === '') {
+    throw new InputError('API key is required', {
+      status: 401,
+      provider,
+      model: 'unknown',
+    })
+  }
+
+  // Provider-specific format warnings (not throwing, just warning)
+  const providerWarning = API_KEY_PATTERNS[provider]
+  if (providerWarning && providerWarning.message && !providerWarning.pattern.test(apikey)) {
+    logger.warn(`[ai-client] ${providerWarning.message}`)
+  }
+}

package/src/validation.js

@@ -48,8 +48,8 @@ export const validateAskOptions = (params) => {
   }
 
   // When using messages, system can still be provided (will be prepended)
-  if (params.prompt !== undefined && typeof params.prompt !== 'string') {
-    errors.push('"prompt" must be a string')
+  if (params.prompt !== undefined && (typeof params.prompt !== 'string' || params.prompt.trim() === '')) {
+    errors.push('"prompt" must be a non-empty string')
   }
 
   // Optional string fields
@@ -75,8 +75,8 @@ export const validateAskOptions = (params) => {
           errors.push(`messages[${i}] must be an object`)
         } else if (!['user', 'assistant', 'system'].includes(msg.role)) {
           errors.push(`messages[${i}].role must be 'user', 'assistant', or 'system'`)
-        } else if (typeof msg.content !== 'string') {
-          errors.push(`messages[${i}].content must be a string`)
+        } else if (typeof msg.content !== 'string' || msg.content.trim() === '') {
+          errors.push(`messages[${i}].content must be a non-empty string`)
         }
       })
     }

package/src/validation.test.js

@@ -81,11 +81,12 @@ describe('validateAskOptions', () => {
       )
     })
 
-    it('should pass with empty string prompt', () => {
-      assert.doesNotThrow(
+    it('should throw when prompt is empty string', () => {
+      assert.throws(
         () => validateAskOptions({
           model: 'gpt-4o', apikey: 'test-key', prompt: '',
-        })
+        }),
+        /"prompt" must be a non-empty string/
       )
     })
 
@@ -94,7 +95,7 @@ describe('validateAskOptions', () => {
         () => validateAskOptions({
           model: 'gpt-4o', apikey: 'test-key', prompt: 123,
         }),
-        /"prompt" must be a string/
+        /"prompt" must be a non-empty string/
       )
     })
 
@@ -138,7 +139,7 @@ describe('validateAskOptions', () => {
           apikey: 'test-key',
           messages: [{ role: 'user' }],
         }),
-        /messages\[0\]\.content must be a string/
+        /messages\[0\]\.content must be a non-empty string/
       )
     })
   })
@@ -280,7 +281,7 @@ describe('validateAskOptions', () => {
             role: 'user', content: 123,
           }],
         }),
-        /messages\[0\].content must be a string/
+        /messages\[0\].content must be a non-empty string/
       )
     })
   })