@inkdropapp/ai 0.1.3 → 0.1.4

package/README.md

@@ -370,6 +370,51 @@ const settings: AISettings = {
 `openrouter` looks up `OPENROUTER_API_KEY`; `ollama_local` looks up
 `OLLAMA_LOCAL_API_KEY`. Each gets its own keyring entry under its `baseURL`.
 
+### Adding an OpenAI-compatible provider at runtime
+
+Two-step flow: persist the new entry into `AISettings` and rebuild the
+registry, then set the API key on the resulting provider instance.
+
+```ts
+// 1. Add the entry to settings and persist (host owns the config layer).
+const next: AISettings = {
+  ...settings,
+  providers: {
+    ...settings.providers,
+    openaiCompatible: [
+      ...(settings.providers.openaiCompatible ?? []),
+      {
+        id: 'groq',
+        baseURL: 'https://api.groq.com/openai/v1',
+        models: [{ id: 'llama-3.3-70b-versatile' }]
+      }
+    ]
+  }
+}
+writeConfigFile(next) // your persistence layer
+registry.updateSettings(next)
+
+// 2. The provider now exists in the registry — set its API key.
+const provider = registry.getProvider('groq')!
+await provider.setApiKey('gsk-...')
+```
+
+`updateSettings` rebuilds the provider list but preserves the shared
+`KeyStore`, so any keys already in the keyring stay resolved.
+
+If your UX needs to **validate the key before persisting the entry**, you can
+write directly to the `KeyStore` first — keys are stored against the
+normalised `baseURL`, not the provider id, so this works without the entry
+being registered yet:
+
+```ts
+await registry.keyStore.setKey('https://api.groq.com/openai/v1', 'gsk-...')
+// later, once validated: persist the AISettings entry and updateSettings.
+```
+
+Once you add the entry and rebuild, `provider.isAuthenticated()` returns
+`true` because the key already lives under that `baseURL`.
+
 ### Mixing slots across providers
 
 ```ts

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@inkdropapp/ai",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "AI integration common module",
   "type": "module",
   "main": "src/index.ts",
   "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./constants": {
+      "types": "./types/provider-constants.d.ts",
+      "default": "./src/provider-constants.ts"
+    }
+  },
   "scripts": {
     "lint": "eslint src __tests__",
     "test": "node --experimental-vm-modules --no-warnings=ExperimentalWarning node_modules/jest/bin/jest.js --config jest.config.cjs --runInBand",

package/src/index.ts

@@ -36,11 +36,17 @@ export {
 } from './errors.js'
 export { KeyStore, type KeyStoreOptions } from './key-store.js'
 export { normalizeBaseURL } from './url.js'
-export { AnthropicProvider } from './providers/anthropic.js'
 export {
-  OpenAICompatibleProvider,
+  ANTHROPIC_PROVIDER_ID,
+  ANTHROPIC_PROVIDER_NAME,
+  ANTHROPIC_ENV_VAR,
+  ANTHROPIC_DEFAULT_BASE_URL,
+  OPENAI_COMPATIBLE_PROVIDER_ID,
+  OPENAI_COMPATIBLE_PROVIDER_NAME,
   deriveEnvVarName
-} from './providers/openai-compatible.js'
+} from './provider-constants.js'
+export { AnthropicProvider } from './providers/anthropic.js'
+export { OpenAICompatibleProvider } from './providers/openai-compatible.js'
 export {
   AIRegistry,
   type AIRegistryOptions,

package/src/provider-constants.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure-data provider metadata for settings UIs.
+ *
+ * This module has no class or native-module imports, so it's safe to load in
+ * an Electron renderer process — unlike the main package entrypoint, which
+ * transitively pulls in `@napi-rs/keyring`.
+ *
+ * Consume via the `@inkdropapp/ai/constants` subpath:
+ *
+ *   import {
+ *     ANTHROPIC_PROVIDER_ID,
+ *     ANTHROPIC_PROVIDER_NAME,
+ *     ANTHROPIC_ENV_VAR,
+ *     ANTHROPIC_DEFAULT_BASE_URL,
+ *     OPENAI_COMPATIBLE_PROVIDER_ID,
+ *     OPENAI_COMPATIBLE_PROVIDER_NAME,
+ *     deriveEnvVarName
+ *   } from '@inkdropapp/ai/constants'
+ */
+
+export const ANTHROPIC_PROVIDER_ID = 'anthropic'
+export const ANTHROPIC_PROVIDER_NAME = 'Anthropic'
+export const ANTHROPIC_ENV_VAR = 'ANTHROPIC_API_KEY'
+export const ANTHROPIC_DEFAULT_BASE_URL = 'https://api.anthropic.com'
+
+/**
+ * The `AISettings.providers` key for OpenAI-compatible entries. Use this to
+ * tag a settings-UI row as "an OpenAI-compatible provider" (vs. the built-in
+ * Anthropic row).
+ *
+ * Runtime provider ids for OpenAI-compatible entries are user-chosen
+ * (`AISettings.providers.openaiCompatible[].id`); this constant is the
+ * *type/kind*, not an instance id.
+ */
+export const OPENAI_COMPATIBLE_PROVIDER_ID = 'openaiCompatible'
+export const OPENAI_COMPATIBLE_PROVIDER_NAME = 'OpenAI-Compatible'
+
+/**
+ * Derives the env-var name for an OpenAI-compatible provider entry from its
+ * user-chosen `id`.
+ *
+ * Rules: replace any non-alphanumeric character with `_`, collapse runs of `_`,
+ * uppercase, append `_API_KEY`.
+ *
+ * Examples:
+ *   `openrouter`     → `OPENROUTER_API_KEY`
+ *   `together_ai`    → `TOGETHER_AI_API_KEY`
+ *   `ollama-local`   → `OLLAMA_LOCAL_API_KEY`
+ *   `my.proxy`       → `MY_PROXY_API_KEY`
+ */
+export const deriveEnvVarName = (id: string): string => {
+  const sanitized = id
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toUpperCase()
+  return `${sanitized}_API_KEY`
+}

package/src/providers/anthropic.ts

@@ -18,6 +18,12 @@ import { NoApiKey } from '../errors.js'
 import type { KeyStore } from '../key-store.js'
 import { mapAiSdkError } from '../internal/map-ai-sdk-error.js'
 import { mapAiSdkStream } from '../internal/map-ai-sdk-stream.js'
+import {
+  ANTHROPIC_DEFAULT_BASE_URL,
+  ANTHROPIC_ENV_VAR,
+  ANTHROPIC_PROVIDER_ID,
+  ANTHROPIC_PROVIDER_NAME
+} from '../provider-constants.js'
 import type { AIModel, AIProvider, CompletionRequest } from '../provider.js'
 import type {
   AnthropicModelConfig,
@@ -25,11 +31,6 @@ import type {
 } from '../settings.js'
 import type { StreamEvent } from '../stream-events.js'
 
-const PROVIDER_ID = 'anthropic'
-const PROVIDER_NAME = 'Anthropic'
-const ENV_VAR = 'ANTHROPIC_API_KEY'
-const DEFAULT_BASE_URL = 'https://api.anthropic.com'
-
 /**
  * The Anthropic (Claude) provider.
  *
@@ -45,9 +46,9 @@ const DEFAULT_BASE_URL = 'https://api.anthropic.com'
  * `clearApiKey` is called or the resolved API key changes.
  */
 export class AnthropicProvider implements AIProvider {
-  readonly id = PROVIDER_ID
-  readonly name = PROVIDER_NAME
-  readonly envVarName = ENV_VAR
+  readonly id = ANTHROPIC_PROVIDER_ID
+  readonly name = ANTHROPIC_PROVIDER_NAME
+  readonly envVarName = ANTHROPIC_ENV_VAR
   readonly baseURL: string
 
   private readonly keyStore: KeyStore
@@ -64,7 +65,7 @@ export class AnthropicProvider implements AIProvider {
     catalog?: AnthropicCatalog
   ) {
     this.keyStore = keyStore
-    this.baseURL = config.baseURL ?? DEFAULT_BASE_URL
+    this.baseURL = config.baseURL ?? ANTHROPIC_DEFAULT_BASE_URL
 
     const baseModels = catalog?.models ?? ANTHROPIC_MODELS
     this.defaultId = catalog?.defaultModelId ?? ANTHROPIC_DEFAULT_MODEL_ID

package/src/providers/openai-compatible.ts

@@ -11,6 +11,7 @@ import { NoApiKey } from '../errors.js'
 import type { KeyStore } from '../key-store.js'
 import { mapAiSdkError } from '../internal/map-ai-sdk-error.js'
 import { mapAiSdkStream } from '../internal/map-ai-sdk-stream.js'
+import { deriveEnvVarName } from '../provider-constants.js'
 import type { AIModel, AIProvider, CompletionRequest } from '../provider.js'
 import type {
   OpenAICompatibleModelConfig,
@@ -26,26 +27,6 @@ const DEFAULT_CAPABILITIES: ModelCapabilities = {
   maxTokens: 32_000
 }
 
-/**
- * Derives the env-var name for a user-named provider entry.
- *
- * Rules: replace any non-alphanumeric character with `_`, collapse runs of `_`,
- * uppercase, append `_API_KEY`.
- *
- * Examples:
- *   `openrouter`     → `OPENROUTER_API_KEY`
- *   `together_ai`    → `TOGETHER_AI_API_KEY`
- *   `ollama-local`   → `OLLAMA_LOCAL_API_KEY`
- *   `my.proxy`       → `MY_PROXY_API_KEY`
- */
-export const deriveEnvVarName = (id: string): string => {
-  const sanitized = id
-    .replace(/[^a-zA-Z0-9]+/g, '_')
-    .replace(/^_+|_+$/g, '')
-    .toUpperCase()
-  return `${sanitized}_API_KEY`
-}
-
 const mergeCapabilities = (
   override: Partial<ModelCapabilities> | undefined
 ): ModelCapabilities => ({

package/types/index.d.ts

@@ -5,6 +5,7 @@ export { ANTHROPIC_MODELS, ANTHROPIC_DEFAULT_MODEL_ID, ANTHROPIC_DEFAULT_FAST_MO
 export { AIError, NoApiKey, AuthenticationError, RateLimitExceeded, ServerOverloaded, PromptTooLarge, UpstreamError, isAIError, type AIErrorKind } from './errors.js';
 export { KeyStore, type KeyStoreOptions } from './key-store.js';
 export { normalizeBaseURL } from './url.js';
+export { ANTHROPIC_PROVIDER_ID, ANTHROPIC_PROVIDER_NAME, ANTHROPIC_ENV_VAR, ANTHROPIC_DEFAULT_BASE_URL, OPENAI_COMPATIBLE_PROVIDER_ID, OPENAI_COMPATIBLE_PROVIDER_NAME, deriveEnvVarName } from './provider-constants.js';
 export { AnthropicProvider } from './providers/anthropic.js';
-export { OpenAICompatibleProvider, deriveEnvVarName } from './providers/openai-compatible.js';
+export { OpenAICompatibleProvider } from './providers/openai-compatible.js';
 export { AIRegistry, type AIRegistryOptions, type ResolvedSlot } from './registry.js';

package/types/provider-constants.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure-data provider metadata for settings UIs.
+ *
+ * This module has no class or native-module imports, so it's safe to load in
+ * an Electron renderer process — unlike the main package entrypoint, which
+ * transitively pulls in `@napi-rs/keyring`.
+ *
+ * Consume via the `@inkdropapp/ai/constants` subpath:
+ *
+ *   import {
+ *     ANTHROPIC_PROVIDER_ID,
+ *     ANTHROPIC_PROVIDER_NAME,
+ *     ANTHROPIC_ENV_VAR,
+ *     ANTHROPIC_DEFAULT_BASE_URL,
+ *     OPENAI_COMPATIBLE_PROVIDER_ID,
+ *     OPENAI_COMPATIBLE_PROVIDER_NAME,
+ *     deriveEnvVarName
+ *   } from '@inkdropapp/ai/constants'
+ */
+export declare const ANTHROPIC_PROVIDER_ID = "anthropic";
+export declare const ANTHROPIC_PROVIDER_NAME = "Anthropic";
+export declare const ANTHROPIC_ENV_VAR = "ANTHROPIC_API_KEY";
+export declare const ANTHROPIC_DEFAULT_BASE_URL = "https://api.anthropic.com";
+/**
+ * The `AISettings.providers` key for OpenAI-compatible entries. Use this to
+ * tag a settings-UI row as "an OpenAI-compatible provider" (vs. the built-in
+ * Anthropic row).
+ *
+ * Runtime provider ids for OpenAI-compatible entries are user-chosen
+ * (`AISettings.providers.openaiCompatible[].id`); this constant is the
+ * *type/kind*, not an instance id.
+ */
+export declare const OPENAI_COMPATIBLE_PROVIDER_ID = "openaiCompatible";
+export declare const OPENAI_COMPATIBLE_PROVIDER_NAME = "OpenAI-Compatible";
+/**
+ * Derives the env-var name for an OpenAI-compatible provider entry from its
+ * user-chosen `id`.
+ *
+ * Rules: replace any non-alphanumeric character with `_`, collapse runs of `_`,
+ * uppercase, append `_API_KEY`.
+ *
+ * Examples:
+ *   `openrouter`     → `OPENROUTER_API_KEY`
+ *   `together_ai`    → `TOGETHER_AI_API_KEY`
+ *   `ollama-local`   → `OLLAMA_LOCAL_API_KEY`
+ *   `my.proxy`       → `MY_PROXY_API_KEY`
+ */
+export declare const deriveEnvVarName: (id: string) => string;

package/types/providers/openai-compatible.d.ts

@@ -2,19 +2,6 @@ import { type OpenAICompatibleProvider as SdkOpenAICompatibleProvider } from '@a
 import type { KeyStore } from '../key-store.js';
 import type { AIModel, AIProvider } from '../provider.js';
 import type { OpenAICompatibleProviderConfig } from '../settings.js';
-/**
- * Derives the env-var name for a user-named provider entry.
- *
- * Rules: replace any non-alphanumeric character with `_`, collapse runs of `_`,
- * uppercase, append `_API_KEY`.
- *
- * Examples:
- *   `openrouter`     → `OPENROUTER_API_KEY`
- *   `together_ai`    → `TOGETHER_AI_API_KEY`
- *   `ollama-local`   → `OLLAMA_LOCAL_API_KEY`
- *   `my.proxy`       → `MY_PROXY_API_KEY`
- */
-export declare const deriveEnvVarName: (id: string) => string;
 /**
  * Provider for any OpenAI-compatible chat-completions endpoint
  * (OpenRouter, Together, Fireworks, Groq, vLLM, Ollama via `/v1`, LiteLLM, …).