byok-llm 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+/** Supported built-in provider IDs */
+type BuiltinProviderId = "anthropic" | "openai" | "openrouter" | "google" | "groq" | "xai" | "mistral" | "deepseek";
+/** Any provider ID (builtins + custom) */
+type ProviderId = BuiltinProviderId | (string & {});
+/** How a provider authenticates requests */
+type AuthStyle = "x-api-key" | "bearer" | "query-param";
+/** Definition of a provider */
+interface ProviderDefinition {
+    /** Unique identifier, e.g. 'anthropic' */
+    id: ProviderId;
+    /** Human-readable name, e.g. 'Anthropic' */
+    name: string;
+    /** Environment variable names to check, in order */
+    envKeys: string[];
+    /** Expected key prefix for format validation (e.g. 'sk-ant-') */
+    keyPrefix?: string | string[];
+    /** Base URL for API requests */
+    baseUrl: string;
+    /** URL where users can get an API key */
+    docsUrl: string;
+    /** How this provider authenticates */
+    authStyle: AuthStyle;
+    /** Custom auth header name (default depends on authStyle) */
+    authHeader?: string;
+    /** Extra default headers to include */
+    defaultHeaders?: Record<string, string>;
+    /** Lightweight endpoint to validate a key (GET request) */
+    validateEndpoint?: string;
+    /** Whether this provider is OpenAI-SDK-compatible */
+    openaiCompatible?: boolean;
+}
+/** Where a resolved key came from */
+type KeySource = "runtime" | "env" | "project-config" | "user-config";
+/** A resolved API key with metadata */
+interface ResolvedKey {
+    key: string;
+    source: KeySource;
+    providerId: ProviderId;
+    envVar?: string;
+}
+/** Result of key validation */
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    /** Extra metadata from the provider (e.g. org name, remaining credits) */
+    meta?: Record<string, unknown>;
+}
+/** Result of fallback resolution */
+interface ResolvedProvider {
+    providerId: ProviderId;
+    key: string;
+    source: KeySource;
+    baseUrl: string;
+    headers: Record<string, string>;
+}
+/** Per-provider config in config files */
+interface ProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    disabled?: boolean;
+    headers?: Record<string, string>;
+}
+/** Full byok-ai config file shape */
+interface ByokConfig {
+    providers?: Record<string, ProviderConfig>;
+    defaultProvider?: ProviderId;
+    fallbackOrder?: ProviderId[];
+}
+/** Status of a single provider */
+interface ProviderStatus {
+    id: ProviderId;
+    name: string;
+    configured: boolean;
+    source?: KeySource;
+    keyPreview?: string;
+    valid?: boolean;
+    error?: string;
+}
+/** Overall status report */
+interface StatusReport {
+    providers: ProviderStatus[];
+    defaultProvider?: ProviderId;
+}
+/** Options for the setup wizard */
+interface WizardOptions {
+    /** Which providers to offer for configuration */
+    providers?: ProviderId[];
+    /** At least one of these must be configured */
+    required?: ProviderId[];
+    /** App name shown in prompts */
+    appName?: string;
+    /** Skip providers that already have keys configured */
+    skipConfigured?: boolean;
+}
+/** OpenAI-SDK-compatible configuration */
+interface OpenAICompatibleConfig {
+    apiKey: string;
+    baseURL: string;
+    defaultHeaders?: Record<string, string>;
+}
+/** Options passed to the top-level init */
+interface ByokOptions {
+    /** Provider overrides (runtime keys) */
+    providers?: Record<string, ProviderConfig>;
+    /** Path to project config file */
+    configPath?: string;
+    /** Disable user config loading */
+    noUserConfig?: boolean;
+}
+
+/**
+ * Register a custom provider (or override a built-in one).
+ */
+declare function registerProvider(definition: ProviderDefinition): void;
+/**
+ * Get a provider definition by ID.
+ */
+declare function getProvider(id: ProviderId): ProviderDefinition | undefined;
+/**
+ * List all registered providers.
+ */
+declare function listProviders(): ProviderDefinition[];
+/**
+ * Check if a provider is registered.
+ */
+declare function hasProvider(id: ProviderId): boolean;
+/**
+ * Default fallback order (most common providers first).
+ */
+declare const DEFAULT_FALLBACK_ORDER: ProviderId[];
+
+/**
+ * Initialize / reset the config cache. Call this if you change options at runtime.
+ */
+declare function initConfig(options?: ByokOptions): ByokConfig;
+/**
+ * Get the current config (loads if needed).
+ */
+declare function getConfig(): ByokConfig;
+/**
+ * Resolve an API key for a provider, checking all layers.
+ *
+ * Resolution order:
+ * 1. Runtime options (passed via init or resolveKey options)
+ * 2. Environment variables
+ * 3. Project config file
+ * 4. User config file
+ * 5. Stored keys (~/.config/byok-ai/keys.json)
+ */
+declare function resolveKey(providerId: ProviderId, runtimeKey?: string): Promise<ResolvedKey | null>;
+/**
+ * Try to resolve a working provider from a list, in order.
+ * Returns the first provider that has a configured key.
+ */
+declare function resolveWithFallback(providerIds?: ProviderId[]): Promise<ResolvedProvider | null>;
+/**
+ * Get all providers that currently have keys configured.
+ */
+declare function getConfiguredProviders(): Promise<ResolvedKey[]>;
+
+/**
+ * Get auth headers for a provider (resolves key automatically).
+ */
+declare function getProviderHeaders(providerId: ProviderId): Promise<Record<string, string>>;
+/**
+ * Get the base URL for a provider.
+ */
+declare function getProviderBaseUrl(providerId: ProviderId): string;
+/**
+ * Get a config object compatible with the OpenAI SDK.
+ * Works for: openai, openrouter, groq, xai, mistral, deepseek, and any
+ * other provider marked as openaiCompatible.
+ */
+declare function getOpenAICompatibleConfig(providerId: ProviderId): Promise<OpenAICompatibleConfig>;
+
+/**
+ * Get the user-level config path.
+ */
+declare function getUserConfigPath(): string;
+/**
+ * Get the user-level keys storage path.
+ */
+declare function getKeysStorePath(): string;
+
+/**
+ * Validate a key's format (prefix check).
+ */
+declare function validateKeyFormat(providerId: ProviderId, key: string): ValidationResult;
+/**
+ * Validate a key by making a lightweight API call.
+ * This hits a read-only endpoint (like listing models) to verify the key works.
+ */
+declare function validateKey(providerId: ProviderId, key: string): Promise<ValidationResult>;
+/**
+ * Validate all currently configured keys.
+ */
+declare function validateAllKeys(): Promise<Record<string, ValidationResult>>;
+
+/**
+ * Store an API key for a provider.
+ */
+declare function storeKey(providerId: ProviderId, key: string): Promise<void>;
+/**
+ * Get a stored API key for a provider.
+ */
+declare function getKey(providerId: ProviderId): Promise<string | null>;
+/**
+ * Remove a stored API key for a provider.
+ */
+declare function removeKey(providerId: ProviderId): Promise<void>;
+/**
+ * List all stored provider IDs.
+ */
+declare function listStoredKeys(): Promise<ProviderId[]>;
+/**
+ * Clear all stored keys.
+ */
+declare function clearAllKeys(): Promise<void>;
+
+/**
+ * Check if a provider has its API key set via environment variable.
+ */
+declare function hasEnvKey(providerId: ProviderId): boolean;
+/**
+ * Get the env var value for a provider (checks all registered env var names).
+ */
+declare function getEnvKey(providerId: ProviderId): string | null;
+/**
+ * Get the primary env var name for a provider (for display/docs).
+ */
+declare function getEnvVarName(providerId: ProviderId): string | null;
+/**
+ * Generate a .env template string with all providers.
+ */
+declare function generateEnvTemplate(providerIds?: ProviderId[]): string;
+
+/**
+ * Run the interactive setup wizard.
+ *
+ * Walks the user through configuring API keys for the specified providers.
+ * Keys are stored in ~/.config/byok-ai/keys.json with 0600 permissions.
+ */
+declare function setupWizard(options?: WizardOptions): Promise<void>;
+
+/**
+ * Get the status of all registered providers.
+ */
+declare function getStatus(providerIds?: ProviderId[]): Promise<StatusReport>;
+/**
+ * Print a formatted status report to stdout.
+ */
+declare function printStatus(providerIds?: ProviderId[]): Promise<void>;
+
+/**
+ * All-in-one initialization: loads config, checks for keys,
+ * and optionally runs the setup wizard if no keys are found.
+ *
+ * @example
+ * ```typescript
+ * import { init } from 'byok-ai';
+ *
+ * const provider = await init({
+ *   providers: ['anthropic', 'openai', 'openrouter'],
+ *   appName: 'my-cli-tool',
+ * });
+ *
+ * // provider.key, provider.baseUrl, provider.headers are ready to use
+ * ```
+ */
+declare function init(options?: ByokOptions & {
+    /** Providers to check (in fallback order) */
+    providers?: ProviderId[];
+    /** App name for wizard prompts */
+    appName?: string;
+    /** Run wizard if no keys found (default: true) */
+    interactive?: boolean;
+}): Promise<ResolvedProvider | null>;
+
+export { type AuthStyle, type BuiltinProviderId, type ByokConfig, type ByokOptions, DEFAULT_FALLBACK_ORDER, type KeySource, type OpenAICompatibleConfig, type ProviderConfig, type ProviderDefinition, type ProviderId, type ProviderStatus, type ResolvedKey, type ResolvedProvider, type StatusReport, type ValidationResult, type WizardOptions, clearAllKeys, generateEnvTemplate, getConfig, getConfiguredProviders, getEnvKey, getEnvVarName, getKey, getKeysStorePath, getOpenAICompatibleConfig, getProvider, getProviderBaseUrl, getProviderHeaders, getStatus, getUserConfigPath, hasEnvKey, hasProvider, init, initConfig, listProviders, listStoredKeys, printStatus, registerProvider, removeKey, resolveKey, resolveWithFallback, setupWizard, storeKey, validateAllKeys, validateKey, validateKeyFormat };