@inkeep/agents-sdk 0.38.2 → 0.39.0

package/dist/index.d.cts

@@ -1283,6 +1283,180 @@ declare function agentMcp(config: AgentMcpConfig): AgentMcpConfig;
  */
 declare function functionTool(config: FunctionToolConfig): FunctionTool;
 
+/**
+ * InkeepCredentialProvider - Abstraction for Credential Management
+ *
+ * This module provides a clean abstraction over credential provider implementations.
+ * Cloud customers can use this without needing to know about or install internal
+ * dependencies like Nango.
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with environment variables (default)
+ * import { InkeepCredentialProvider } from '@inkeep/agents-sdk'
+ *
+ * const credentials = new InkeepCredentialProvider()
+ *
+ * // With custom configuration
+ * const credentials = new InkeepCredentialProvider({
+ *   type: 'memory',
+ *   id: 'my-store'
+ * })
+ * ```
+ */
+/**
+ * Base interface for all credential stores
+ * This is a simplified version for SDK customers
+ */
+interface CredentialStore {
+    /** Unique identifier for this credential store */
+    readonly id: string;
+    /** Type of credential store */
+    readonly type: CredentialProviderType;
+    /** Get a credential by key */
+    get(key: string): Promise<string | null>;
+    /** Set a credential */
+    set(key: string, value: string, metadata?: Record<string, string>): Promise<void>;
+    /** Check if a credential exists */
+    has(key: string): Promise<boolean>;
+    /** Delete a credential */
+    delete(key: string): Promise<boolean>;
+    /** Check if the credential store is available */
+    checkAvailability(): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * Supported credential provider types
+ */
+type CredentialProviderType = 'memory' | 'keychain' | 'nango' | 'custom';
+/**
+ * Configuration for memory-based credential storage
+ */
+interface MemoryCredentialConfig {
+    type: 'memory';
+    /** Optional store ID (defaults to 'memory-default') */
+    id?: string;
+}
+/**
+ * Configuration for keychain-based credential storage
+ */
+interface KeychainCredentialConfig {
+    type: 'keychain';
+    /** Optional store ID (defaults to 'keychain-default') */
+    id?: string;
+    /** Optional service name for keychain entries */
+    serviceName?: string;
+}
+/**
+ * Configuration for Nango-based credential storage (OAuth management)
+ * Note: Using Nango requires the @nangohq/node package to be installed
+ */
+interface NangoCredentialConfig {
+    type: 'nango';
+    /** Optional store ID (defaults to 'nango-default') */
+    id?: string;
+    /** Nango secret key (defaults to NANGO_SECRET_KEY env var) */
+    secretKey?: string;
+    /** Nango API URL (defaults to https://api.nango.dev) */
+    apiUrl?: string;
+}
+/**
+ * Configuration for custom credential provider
+ */
+interface CustomCredentialConfig {
+    type: 'custom';
+    /** Custom credential store implementation */
+    store: CredentialStore;
+}
+/**
+ * Union type for all credential provider configurations
+ */
+type CredentialProviderConfig = MemoryCredentialConfig | KeychainCredentialConfig | NangoCredentialConfig | CustomCredentialConfig;
+/**
+ * InkeepCredentialProvider - Unified credential management for Inkeep SDK
+ *
+ * Provides a clean abstraction over various credential storage backends.
+ * Cloud customers can use simple memory-based storage, while advanced
+ * users can integrate with OAuth providers like Nango.
+ *
+ * @example
+ * ```typescript
+ * // Default memory-based storage
+ * const provider = new InkeepCredentialProvider()
+ *
+ * // Store and retrieve credentials
+ * await provider.set('my-api-key', 'secret-value')
+ * const key = await provider.get('my-api-key')
+ *
+ * // Use environment variables automatically
+ * process.env.MY_TOKEN = 'env-token'
+ * const token = await provider.get('MY_TOKEN') // Returns 'env-token'
+ * ```
+ */
+declare class InkeepCredentialProvider implements CredentialStore {
+    private store;
+    constructor(config?: CredentialProviderConfig);
+    /**
+     * Create the appropriate store based on configuration
+     */
+    private createStore;
+    /**
+     * Create keychain store with dynamic import
+     */
+    private createKeychainStore;
+    /**
+     * Create Nango store with dynamic import
+     */
+    private createNangoStore;
+    get id(): string;
+    get type(): CredentialProviderType;
+    /**
+     * Get a credential by key
+     * @param key - The credential key
+     * @returns The credential value or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a credential
+     * @param key - The credential key
+     * @param value - The credential value
+     * @param metadata - Optional metadata
+     */
+    set(key: string, value: string, metadata?: Record<string, string>): Promise<void>;
+    /**
+     * Check if a credential exists
+     * @param key - The credential key
+     * @returns True if the credential exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a credential
+     * @param key - The credential key
+     * @returns True if the credential was deleted
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if the credential store is available and functional
+     * @returns Availability status
+     */
+    checkAvailability(): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Get the underlying store (for advanced use cases)
+     */
+    getStore(): CredentialStore;
+}
+/**
+ * Factory function to create an InkeepCredentialProvider
+ * @param config - Configuration options
+ * @returns A new InkeepCredentialProvider instance
+ */
+declare function createCredentialProvider(config?: CredentialProviderConfig): InkeepCredentialProvider;
+
 /**
  * Credential Reference System
  *
@@ -1425,4 +1599,220 @@ declare const run: typeof Runner.run;
 declare const stream: typeof Runner.stream;
 declare const raceAgents: typeof Runner.raceAgents;
 
-export { type AgentConfig, AgentError, type AgentInterface, type AgentResponse, type AgentTool, type AllDelegateInputInterface, type AllDelegateOutputInterface, ArtifactComponent, type ArtifactComponentInterface, type ArtifactComponentWithZodProps, type AssistantMessage, type BuilderAgentConfig, type BuilderRelationConfig, type BuilderToolConfig, type CredentialReference, DataComponent, type DataComponentInterface, type DataComponentWithZodProps, ExternalAgent, type ExternalAgentInterface, type ExtractCredentialIds, type FetchDefinitionConfig, FunctionTool, type GenerateOptions, type MCPToolConfig, MaxTurnsExceededError, type Message, type MessageInput, Project, type RequestSchemaConfig, type RequestSchemaDefinition, type RunResult, Runner, type ServerConfig, StatusComponent, type StatusComponentInterface, type StreamEvent, type StreamResponse, SubAgent, type SubAgentCanUseType, type SubAgentConfig, type SubAgentInterface, type SystemMessage, Tool, type ToolCall, type ToolConfig, ToolExecutionError, type ToolMessage, type ToolResult, type TransferConfig, TransferError, type UnionCredentialIds, type UserMessage, agent, agentMcp, artifactComponent, createEnvironmentSettings, createFullProjectViaAPI, credential, credentialRef, dataComponent, deleteFullProjectViaAPI, externalAgent, externalAgents, functionTool, getFullProjectViaAPI, isCredentialReference, mcpServer, mcpTool, project, raceAgents, registerEnvironmentSettings, run, statusComponent, stream, subAgent, type subAgentExternalAgentInterface, type subAgentTeamAgentInterface, transfer, updateFullProjectViaAPI };
+/**
+ * TelemetryProvider - Abstraction for Telemetry/Observability
+ *
+ * This module provides a clean abstraction over telemetry implementations.
+ * Cloud customers can use this without needing to install or configure
+ * OpenTelemetry or Signoz directly.
+ *
+ * Telemetry is OPT-IN - if not configured, a no-op provider is used.
+ *
+ * @example
+ * ```typescript
+ * // Opt-in to telemetry with default console logger
+ * import { InkeepTelemetryProvider, createConsoleTelemetryProvider } from '@inkeep/agents-sdk'
+ *
+ * const telemetry = createConsoleTelemetryProvider()
+ *
+ * // Or with OpenTelemetry (requires @opentelemetry packages)
+ * const telemetry = createOpenTelemetryProvider({
+ *   serviceName: 'my-agent',
+ *   endpoint: 'http://localhost:4318'
+ * })
+ * ```
+ */
+/**
+ * Span status codes
+ */
+declare const SpanStatus: {
+    readonly OK: "ok";
+    readonly ERROR: "error";
+    readonly UNSET: "unset";
+};
+type SpanStatusType = (typeof SpanStatus)[keyof typeof SpanStatus];
+/**
+ * Span interface for tracing
+ */
+interface TelemetrySpan {
+    /** Set span attributes */
+    setAttributes(attributes: Record<string, unknown>): TelemetrySpan;
+    /** Set a single attribute */
+    setAttribute(key: string, value: unknown): TelemetrySpan;
+    /** Record an exception */
+    recordException(error: Error): TelemetrySpan;
+    /** Set span status */
+    setStatus(status: SpanStatusType, message?: string): TelemetrySpan;
+    /** Add an event to the span */
+    addEvent(name: string, attributes?: Record<string, unknown>): TelemetrySpan;
+    /** End the span */
+    end(): void;
+    /** Check if span is recording */
+    isRecording(): boolean;
+    /** Update span name */
+    updateName(name: string): TelemetrySpan;
+}
+/**
+ * Span options
+ */
+interface SpanOptions {
+    /** Span attributes */
+    attributes?: Record<string, unknown>;
+    /** Parent span (for context propagation) */
+    parent?: TelemetrySpan;
+}
+/**
+ * Tracer interface for creating spans
+ */
+interface TelemetryTracer {
+    /** Start a new active span and execute callback */
+    startActiveSpan<T>(name: string, fn: (span: TelemetrySpan) => T): T;
+    startActiveSpan<T>(name: string, options: SpanOptions, fn: (span: TelemetrySpan) => T): T;
+    /** Start a new span without making it active */
+    startSpan(name: string, options?: SpanOptions): TelemetrySpan;
+}
+/**
+ * Logger interface for structured logging
+ */
+interface TelemetryLogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Metrics interface for recording measurements
+ */
+interface TelemetryMetrics {
+    /** Increment a counter */
+    increment(name: string, value?: number, attributes?: Record<string, unknown>): void;
+    /** Record a gauge value */
+    gauge(name: string, value: number, attributes?: Record<string, unknown>): void;
+    /** Record a histogram value */
+    histogram(name: string, value: number, attributes?: Record<string, unknown>): void;
+}
+/**
+ * Main telemetry provider interface
+ */
+interface TelemetryProvider {
+    /** Get a tracer for creating spans */
+    getTracer(name: string, version?: string): TelemetryTracer;
+    /** Get a logger for structured logging */
+    getLogger(name: string): TelemetryLogger;
+    /** Get metrics for recording measurements */
+    getMetrics(name: string): TelemetryMetrics;
+    /** Shutdown the telemetry provider */
+    shutdown(): Promise<void>;
+    /** Check if telemetry is enabled */
+    isEnabled(): boolean;
+}
+/**
+ * Configuration for telemetry provider
+ */
+interface TelemetryConfig {
+    /** Whether telemetry is enabled (default: false) */
+    enabled?: boolean;
+    /** Service name for identifying the source */
+    serviceName?: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Custom provider implementation */
+    provider?: TelemetryProvider;
+}
+/**
+ * No-op telemetry provider (default)
+ */
+declare class NoOpTelemetryProvider implements TelemetryProvider {
+    getTracer(_name: string, _version?: string): TelemetryTracer;
+    getLogger(_name: string): TelemetryLogger;
+    getMetrics(_name: string): TelemetryMetrics;
+    shutdown(): Promise<void>;
+    isEnabled(): boolean;
+}
+/**
+ * Console-based telemetry provider for development/debugging
+ */
+declare class ConsoleTelemetryProvider implements TelemetryProvider {
+    private serviceName;
+    constructor(serviceName?: string);
+    getTracer(name: string, _version?: string): TelemetryTracer;
+    getLogger(name: string): TelemetryLogger;
+    getMetrics(name: string): TelemetryMetrics;
+    shutdown(): Promise<void>;
+    isEnabled(): boolean;
+}
+/**
+ * InkeepTelemetryProvider - Main telemetry management class
+ *
+ * Provides a unified interface for telemetry across the SDK.
+ * Telemetry is OPT-IN - by default, a no-op provider is used.
+ */
+declare class InkeepTelemetryProvider {
+    private provider;
+    constructor(config?: TelemetryConfig);
+    /**
+     * Get a tracer for creating spans
+     */
+    getTracer(name: string, version?: string): TelemetryTracer;
+    /**
+     * Get a logger for structured logging
+     */
+    getLogger(name: string): TelemetryLogger;
+    /**
+     * Get metrics recorder
+     */
+    getMetrics(name: string): TelemetryMetrics;
+    /**
+     * Check if telemetry is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Shutdown the provider
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the underlying provider
+     */
+    getProvider(): TelemetryProvider;
+    /**
+     * Set as the global telemetry provider
+     */
+    setAsGlobal(): void;
+}
+/**
+ * Get the global telemetry provider
+ */
+declare function getGlobalTelemetryProvider(): TelemetryProvider;
+/**
+ * Set the global telemetry provider
+ */
+declare function setGlobalTelemetryProvider(provider: TelemetryProvider): void;
+/**
+ * Create a no-op telemetry provider (default, does nothing)
+ */
+declare function createNoOpTelemetryProvider(): InkeepTelemetryProvider;
+/**
+ * Create a console-based telemetry provider for development
+ */
+declare function createConsoleTelemetryProvider(serviceName?: string): InkeepTelemetryProvider;
+/**
+ * Configuration for OpenTelemetry provider
+ */
+interface OpenTelemetryConfig {
+    /** Service name */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** OTLP endpoint URL */
+    endpoint?: string;
+    /** Additional resource attributes */
+    resourceAttributes?: Record<string, string>;
+}
+/**
+ * Create an OpenTelemetry-based provider
+ *
+ * Note: Requires @opentelemetry packages to be installed
+ */
+declare function createOpenTelemetryProvider(config: OpenTelemetryConfig): Promise<InkeepTelemetryProvider>;
+
+export { type AgentConfig, AgentError, type AgentInterface, type AgentResponse, type AgentTool, type AllDelegateInputInterface, type AllDelegateOutputInterface, ArtifactComponent, type ArtifactComponentInterface, type ArtifactComponentWithZodProps, type AssistantMessage, type BuilderAgentConfig, type BuilderRelationConfig, type BuilderToolConfig, ConsoleTelemetryProvider, type CredentialProviderConfig, type CredentialProviderType, type CredentialReference, type CredentialStore, type CustomCredentialConfig, DataComponent, type DataComponentInterface, type DataComponentWithZodProps, ExternalAgent, type ExternalAgentInterface, type ExtractCredentialIds, type FetchDefinitionConfig, FunctionTool, type GenerateOptions, InkeepCredentialProvider, InkeepTelemetryProvider, type KeychainCredentialConfig, type MCPToolConfig, MaxTurnsExceededError, type MemoryCredentialConfig, type Message, type MessageInput, type NangoCredentialConfig, NoOpTelemetryProvider, type OpenTelemetryConfig, Project, type RequestSchemaConfig, type RequestSchemaDefinition, type RunResult, Runner, type ServerConfig, type SpanOptions, SpanStatus, type SpanStatusType, StatusComponent, type StatusComponentInterface, type StreamEvent, type StreamResponse, SubAgent, type SubAgentCanUseType, type SubAgentConfig, type SubAgentInterface, type SystemMessage, type TelemetryConfig, type TelemetryLogger, type TelemetryMetrics, type TelemetryProvider, type TelemetrySpan, type TelemetryTracer, Tool, type ToolCall, type ToolConfig, ToolExecutionError, type ToolMessage, type ToolResult, type TransferConfig, TransferError, type UnionCredentialIds, type UserMessage, agent, agentMcp, artifactComponent, createConsoleTelemetryProvider, createCredentialProvider, createEnvironmentSettings, createFullProjectViaAPI, createNoOpTelemetryProvider, createOpenTelemetryProvider, credential, credentialRef, dataComponent, deleteFullProjectViaAPI, externalAgent, externalAgents, functionTool, getFullProjectViaAPI, getGlobalTelemetryProvider, isCredentialReference, mcpServer, mcpTool, project, raceAgents, registerEnvironmentSettings, run, setGlobalTelemetryProvider, statusComponent, stream, subAgent, type subAgentExternalAgentInterface, type subAgentTeamAgentInterface, transfer, updateFullProjectViaAPI };