openllmprovider 0.1.0

package/src/types/errors.ts

@@ -0,0 +1,87 @@
+export type ErrorCode =
+  | 'AUTH_ERROR'
+  | 'VALIDATION_ERROR'
+  | 'MODEL_NOT_FOUND'
+  | 'CREDENTIAL_NOT_FOUND'
+  | 'PROVIDER_NOT_REGISTERED'
+  | 'CATALOG_SYNC_FAILED'
+
+interface ErrorOptions {
+  providerID?: string
+  modelId?: string
+}
+
+interface ErrorJSON {
+  code: ErrorCode
+  message: string
+  providerID?: string
+  modelId?: string
+}
+
+export class OpenLLMProviderError extends Error {
+  readonly code: ErrorCode
+  readonly providerID?: string
+  readonly modelId?: string
+
+  constructor(message: string, code: ErrorCode, options?: ErrorOptions) {
+    super(message)
+    this.name = this.constructor.name
+    this.code = code
+    this.providerID = options?.providerID
+    this.modelId = options?.modelId
+    const captureStackTrace = (
+      Error as unknown as {
+        captureStackTrace?: (target: Error, ctor: typeof Error) => void
+      }
+    ).captureStackTrace
+    if (typeof captureStackTrace === 'function') {
+      captureStackTrace(this, this.constructor as typeof Error)
+    }
+  }
+
+  toJSON(): ErrorJSON {
+    const result: ErrorJSON = {
+      code: this.code,
+      message: this.message,
+    }
+    if (this.providerID !== undefined) result.providerID = this.providerID
+    if (this.modelId !== undefined) result.modelId = this.modelId
+    return result
+  }
+}
+
+export class AuthError extends OpenLLMProviderError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, 'AUTH_ERROR', options)
+  }
+}
+
+export class ValidationError extends OpenLLMProviderError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, 'VALIDATION_ERROR', options)
+  }
+}
+
+export class ModelNotFoundError extends OpenLLMProviderError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, 'MODEL_NOT_FOUND', options)
+  }
+}
+
+export class CredentialNotFoundError extends OpenLLMProviderError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, 'CREDENTIAL_NOT_FOUND', options)
+  }
+}
+
+export class ProviderNotRegisteredError extends OpenLLMProviderError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, 'PROVIDER_NOT_REGISTERED', options)
+  }
+}
+
+export class CatalogSyncFailedError extends OpenLLMProviderError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, 'CATALOG_SYNC_FAILED', options)
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,26 @@
+import type { LanguageModelV3 } from '@ai-sdk/provider'
+
+export type LanguageModel = LanguageModelV3
+export type { LanguageModelV3 }
+
+export type { ProviderDefinition, ProviderUserConfig } from './provider.js'
+export { ProviderDefinitionSchema, ProviderUserConfigSchema } from './provider.js'
+
+export type { ModelDefinition, ModelAlias } from './model.js'
+export { ModelDefinitionSchema, ModelAliasSchema } from './model.js'
+
+export type { SecretRef, SecretResolver } from './auth.js'
+export { SecretRefSchema } from './auth.js'
+
+export type { AuthHook, AuthMethod, AuthCredential, ProviderInfo } from './plugin.js'
+
+export {
+  OpenLLMProviderError,
+  AuthError,
+  ValidationError,
+  ModelNotFoundError,
+  CredentialNotFoundError,
+  ProviderNotRegisteredError,
+  CatalogSyncFailedError,
+} from './errors.js'
+export type { ErrorCode } from './errors.js'

package/src/types/model.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod'
+
+export interface ModelDefinition {
+  modelId: string
+  name?: string
+  family?: string
+  type?: 'chat' | 'embedding' | 'image'
+  reasoning?: boolean
+  tool_call?: boolean
+  structured_output?: boolean
+  temperature?: boolean
+  attachment?: boolean
+  streaming?: boolean
+  system_message?: boolean
+  modalities: {
+    input: Array<'text' | 'image' | 'audio' | 'video' | 'pdf'>
+    output: Array<'text' | 'image' | 'audio'>
+  }
+  limit: {
+    context: number
+    output: number
+    input_images?: number
+  }
+  cost?: {
+    input: number
+    output: number
+    cache_read?: number
+    cache_write?: number
+  }
+  status?: 'stable' | 'beta' | 'deprecated'
+  knowledgeCutoff?: string
+  provenance?: 'snapshot' | 'remote' | 'user-override'
+}
+
+export const ModelDefinitionSchema = z
+  .object({
+    modelId: z.string(),
+    name: z.string().optional(),
+    family: z.string().optional(),
+    type: z.enum(['chat', 'embedding', 'image']).optional(),
+    reasoning: z.boolean().optional(),
+    tool_call: z.boolean().optional(),
+    structured_output: z.boolean().optional(),
+    temperature: z.boolean().optional(),
+    attachment: z.boolean().optional(),
+    streaming: z.boolean().optional(),
+    system_message: z.boolean().optional(),
+    modalities: z
+      .object({
+        input: z.array(z.enum(['text', 'image', 'audio', 'video', 'pdf'])),
+        output: z.array(z.enum(['text', 'image', 'audio'])),
+      })
+      .passthrough(),
+    limit: z
+      .object({
+        context: z.number(),
+        output: z.number(),
+        input_images: z.number().optional(),
+      })
+      .passthrough(),
+    cost: z
+      .object({
+        input: z.number(),
+        output: z.number(),
+        cache_read: z.number().optional(),
+        cache_write: z.number().optional(),
+      })
+      .passthrough()
+      .optional(),
+    status: z.enum(['stable', 'beta', 'deprecated']).optional(),
+    knowledgeCutoff: z.string().optional(),
+    provenance: z.enum(['snapshot', 'remote', 'user-override']).optional(),
+  })
+  .passthrough()
+
+export interface ModelAlias {
+  alias: string
+  provider: string
+  model: string
+}
+
+export const ModelAliasSchema = z
+  .object({
+    alias: z.string(),
+    provider: z.string(),
+    model: z.string(),
+  })
+  .passthrough()

package/src/types/plugin.ts

@@ -0,0 +1,49 @@
+export interface ProviderInfo {
+  id: string
+  name?: string
+}
+
+/**
+ * Unified credential for all auth types.
+ *
+ * API key auth (type: 'api'):
+ *   - key: the API key string (e.g. sk-ant-xxx for Anthropic, sk-xxx for OpenAI)
+ *
+ * OAuth auth (type: 'oauth'):
+ *   - key:     short-lived access_token for API calls
+ *   - refresh: long-lived refresh_token used to obtain a new access_token when expired
+ *   - expires: absolute timestamp (ms) when the access_token expires
+ *
+ * Well-known auth (type: 'wellknown'):
+ *   - key: credential discovered from well-known config file locations
+ */
+export interface AuthCredential {
+  type: 'api' | 'oauth' | 'wellknown'
+  /** API key (type 'api') or OAuth access_token (type 'oauth') */
+  key?: string
+  /** OAuth refresh_token — only present when type is 'oauth' */
+  refresh?: string
+  /** Absolute timestamp (ms) when the access_token expires — only present when type is 'oauth' */
+  expires?: number
+  baseURL?: string
+  apiHost?: string
+  host?: string
+  location?: string
+  [key: string]: unknown
+}
+
+export interface AuthMethod {
+  type: string
+  label: string
+  handler(): Promise<AuthCredential>
+}
+
+export interface AuthHook {
+  provider: string
+  loader(
+    getAuth: () => Promise<AuthCredential>,
+    provider: ProviderInfo,
+    setAuth: (credential: AuthCredential) => Promise<void>,
+  ): Promise<Record<string, unknown>>
+  methods: AuthMethod[]
+}

package/src/types/provider.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod'
+import type { SecretRef } from './auth.js'
+import { SecretRefSchema } from './auth.js'
+import type { ModelDefinition } from './model.js'
+import { ModelDefinitionSchema } from './model.js'
+
+export interface ProviderDefinition {
+  id: string
+  name: string
+  bundledProvider?: string
+  defaultSettings?: {
+    baseURL?: string
+    headers?: Record<string, string>
+    options?: Record<string, unknown>
+  }
+  models?: ModelDefinition[]
+}
+
+export const ProviderDefinitionSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    bundledProvider: z.string().optional(),
+    defaultSettings: z
+      .object({
+        baseURL: z.string().optional(),
+        headers: z.record(z.string()).optional(),
+        options: z.record(z.unknown()).optional(),
+      })
+      .passthrough()
+      .optional(),
+    models: z.array(ModelDefinitionSchema).optional(),
+  })
+  .passthrough()
+
+export interface ProviderUserConfig {
+  apiKey?: SecretRef
+  baseURL?: string
+  headers?: Record<string, string>
+  options?: Record<string, unknown>
+}
+
+export const ProviderUserConfigSchema = z.object({
+  apiKey: SecretRefSchema.optional(),
+  baseURL: z.string().optional(),
+  headers: z.record(z.string()).optional(),
+  options: z.record(z.unknown()).optional(),
+})