@inkeep/agents-sdk 0.39.4 → 0.40.0

package/dist/credential-provider.d.ts

@@ -0,0 +1,176 @@
+//#region src/credential-provider.d.ts
+/**
+ * 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;
+//#endregion
+export { CredentialProviderConfig, CredentialProviderType, CredentialStore, CustomCredentialConfig, InkeepCredentialProvider, KeychainCredentialConfig, MemoryCredentialConfig, NangoCredentialConfig, createCredentialProvider };

package/dist/credential-provider.js

@@ -0,0 +1,237 @@
+//#region src/credential-provider.ts
+/**
+* Default configuration using memory store
+*/
+const DEFAULT_CONFIG = {
+	type: "memory",
+	id: "memory-default"
+};
+/**
+* Simple in-memory credential store implementation
+* Automatically loads from environment variables as fallback
+*/
+var InMemoryStore = class {
+	id;
+	type = "memory";
+	credentials = /* @__PURE__ */ new Map();
+	constructor(id = "memory-default") {
+		this.id = id;
+	}
+	async get(key) {
+		const credential = this.credentials.get(key);
+		if (!credential) {
+			const envValue = process.env[key];
+			if (envValue) {
+				this.credentials.set(key, envValue);
+				return envValue;
+			}
+			return null;
+		}
+		return credential;
+	}
+	async set(key, value, _metadata) {
+		this.credentials.set(key, value);
+	}
+	async has(key) {
+		return this.credentials.has(key) || !!process.env[key];
+	}
+	async delete(key) {
+		return this.credentials.delete(key);
+	}
+	async checkAvailability() {
+		return { available: true };
+	}
+};
+/**
+* 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'
+* ```
+*/
+var InkeepCredentialProvider = class {
+	store;
+	constructor(config = DEFAULT_CONFIG) {
+		this.store = this.createStore(config);
+	}
+	/**
+	* Create the appropriate store based on configuration
+	*/
+	createStore(config) {
+		switch (config.type) {
+			case "memory": return new InMemoryStore(config.id);
+			case "keychain": return this.createKeychainStore(config);
+			case "nango": return this.createNangoStore(config);
+			case "custom": return config.store;
+			default: throw new Error(`Unknown credential provider type: ${config.type}`);
+		}
+	}
+	/**
+	* Create keychain store with dynamic import
+	*/
+	createKeychainStore(config) {
+		const storeId = config.id || "keychain-default";
+		return {
+			id: storeId,
+			type: "keychain",
+			get: async (key) => {
+				const { createKeyChainStore } = await import("@inkeep/agents-core/credential-stores");
+				return createKeyChainStore(storeId).get(key);
+			},
+			set: async (key, value, metadata) => {
+				const { createKeyChainStore } = await import("@inkeep/agents-core/credential-stores");
+				return createKeyChainStore(storeId).set(key, value, metadata);
+			},
+			has: async (key) => {
+				const { createKeyChainStore } = await import("@inkeep/agents-core/credential-stores");
+				return createKeyChainStore(storeId).has(key);
+			},
+			delete: async (key) => {
+				const { createKeyChainStore } = await import("@inkeep/agents-core/credential-stores");
+				return createKeyChainStore(storeId).delete(key);
+			},
+			checkAvailability: async () => {
+				try {
+					const { createKeyChainStore } = await import("@inkeep/agents-core/credential-stores");
+					return createKeyChainStore(storeId).checkAvailability();
+				} catch {
+					return {
+						available: false,
+						reason: "Keychain store requires keytar package to be installed"
+					};
+				}
+			}
+		};
+	}
+	/**
+	* Create Nango store with dynamic import
+	*/
+	createNangoStore(config) {
+		const storeId = config.id || "nango-default";
+		const secretKey = config.secretKey;
+		const apiUrl = config.apiUrl;
+		return {
+			id: storeId,
+			type: "nango",
+			get: async (key) => {
+				const { createNangoCredentialStore } = await import("@inkeep/agents-core/credential-stores");
+				return createNangoCredentialStore(storeId, {
+					secretKey,
+					apiUrl
+				}).get(key);
+			},
+			set: async (key, value, metadata) => {
+				const { createNangoCredentialStore } = await import("@inkeep/agents-core/credential-stores");
+				return createNangoCredentialStore(storeId, {
+					secretKey,
+					apiUrl
+				}).set(key, value, metadata);
+			},
+			has: async (key) => {
+				const { createNangoCredentialStore } = await import("@inkeep/agents-core/credential-stores");
+				return createNangoCredentialStore(storeId, {
+					secretKey,
+					apiUrl
+				}).has(key);
+			},
+			delete: async (key) => {
+				const { createNangoCredentialStore } = await import("@inkeep/agents-core/credential-stores");
+				return createNangoCredentialStore(storeId, {
+					secretKey,
+					apiUrl
+				}).delete(key);
+			},
+			checkAvailability: async () => {
+				try {
+					const { createNangoCredentialStore } = await import("@inkeep/agents-core/credential-stores");
+					return createNangoCredentialStore(storeId, {
+						secretKey,
+						apiUrl
+					}).checkAvailability();
+				} catch (error) {
+					return {
+						available: false,
+						reason: error instanceof Error ? error.message : "Nango store requires @nangohq/node package and NANGO_SECRET_KEY"
+					};
+				}
+			}
+		};
+	}
+	get id() {
+		return this.store.id;
+	}
+	get type() {
+		return this.store.type;
+	}
+	/**
+	* Get a credential by key
+	* @param key - The credential key
+	* @returns The credential value or null if not found
+	*/
+	async get(key) {
+		return this.store.get(key);
+	}
+	/**
+	* Set a credential
+	* @param key - The credential key
+	* @param value - The credential value
+	* @param metadata - Optional metadata
+	*/
+	async set(key, value, metadata) {
+		return this.store.set(key, value, metadata);
+	}
+	/**
+	* Check if a credential exists
+	* @param key - The credential key
+	* @returns True if the credential exists
+	*/
+	async has(key) {
+		return this.store.has(key);
+	}
+	/**
+	* Delete a credential
+	* @param key - The credential key
+	* @returns True if the credential was deleted
+	*/
+	async delete(key) {
+		return this.store.delete(key);
+	}
+	/**
+	* Check if the credential store is available and functional
+	* @returns Availability status
+	*/
+	async checkAvailability() {
+		return this.store.checkAvailability();
+	}
+	/**
+	* Get the underlying store (for advanced use cases)
+	*/
+	getStore() {
+		return this.store;
+	}
+};
+/**
+* Factory function to create an InkeepCredentialProvider
+* @param config - Configuration options
+* @returns A new InkeepCredentialProvider instance
+*/
+function createCredentialProvider(config = DEFAULT_CONFIG) {
+	return new InkeepCredentialProvider(config);
+}
+
+//#endregion
+export { InkeepCredentialProvider, createCredentialProvider };

package/dist/credential-ref.d.ts

@@ -0,0 +1,60 @@
+//#region src/credential-ref.d.ts
+/**
+ * Credential Reference System
+ *
+ * This module provides a way to reference credentials by ID without including
+ * the full credential definition in the code. Credentials are resolved from
+ * environment files at runtime during the push operation.
+ */
+/**
+ * Represents a reference to a credential by its ID.
+ * The actual credential will be resolved from the environment file at push time.
+ */
+interface CredentialReference {
+  __type: 'credential-ref';
+  id: string;
+}
+/**
+ * Create a reference to a credential by its ID.
+ * The credential must be defined in the environment files.
+ *
+ * @param id - The ID of the credential to reference
+ * @returns A credential reference that will be resolved at push time
+ *
+ * @example
+ * ```typescript
+ * const apiKeyRef = credentialRef('api-key');
+ *
+ * const fetchDef = fetchDefinition({
+ *   credential: apiKeyRef,
+ *   // ...
+ * });
+ * ```
+ */
+declare function credentialRef<T extends string = string>(id: T): CredentialReference;
+/**
+ * Type guard to check if a value is a credential reference
+ */
+declare function isCredentialReference(value: any): value is CredentialReference;
+/**
+ * Type helper to extract credential IDs from environment configuration
+ */
+type ExtractCredentialIds<T> = T extends {
+  credentials?: infer C;
+} ? C extends Record<string, any> ? keyof C : never : never;
+/**
+ * Type helper to create a union of all available credential IDs from multiple environments
+ */
+type UnionCredentialIds<T extends Record<string, any>> = { [K in keyof T]: ExtractCredentialIds<T[K]> }[keyof T];
+/**
+ * Type helper to extract tool IDs from environment configuration
+ */
+type ExtractMcpServerIds<T> = T extends {
+  mcpServers?: infer T;
+} ? T extends Record<string, any> ? keyof T : never : never;
+/**
+ * Type helper to create a union of all available tool IDs from multiple environments
+ */
+type UnionMcpServerIds<T extends Record<string, any>> = { [K in keyof T]: ExtractMcpServerIds<T[K]> }[keyof T];
+//#endregion
+export { CredentialReference, ExtractCredentialIds, ExtractMcpServerIds, UnionCredentialIds, UnionMcpServerIds, credentialRef, isCredentialReference };

package/dist/credential-ref.js

@@ -0,0 +1,33 @@
+//#region src/credential-ref.ts
+/**
+* Create a reference to a credential by its ID.
+* The credential must be defined in the environment files.
+*
+* @param id - The ID of the credential to reference
+* @returns A credential reference that will be resolved at push time
+*
+* @example
+* ```typescript
+* const apiKeyRef = credentialRef('api-key');
+*
+* const fetchDef = fetchDefinition({
+*   credential: apiKeyRef,
+*   // ...
+* });
+* ```
+*/
+function credentialRef(id) {
+	return {
+		__type: "credential-ref",
+		id
+	};
+}
+/**
+* Type guard to check if a value is a credential reference
+*/
+function isCredentialReference(value) {
+	return value && typeof value === "object" && value.__type === "credential-ref";
+}
+
+//#endregion
+export { credentialRef, isCredentialReference };

package/dist/data-component.d.ts

@@ -0,0 +1,39 @@
+import { DataComponentInsert } from "@inkeep/agents-core";
+import { z } from "zod";
+
+//#region src/data-component.d.ts
+type DataComponentConfigWithZod = Omit<DataComponentInsert, 'tenantId' | 'projectId' | 'props' | 'render'> & {
+  props?: Record<string, unknown> | z.ZodObject<any> | null;
+  render?: {
+    component: string;
+    mockData: Record<string, unknown>;
+  } | null;
+};
+interface DataComponentInterface {
+  config: Omit<DataComponentInsert, 'tenantId' | 'projectId'>;
+  init(): Promise<void>;
+  getId(): DataComponentInsert['id'];
+  getName(): DataComponentInsert['name'];
+  getDescription(): DataComponentInsert['description'];
+  getProps(): DataComponentInsert['props'];
+  setContext(tenantId: string, projectId: string, baseURL?: string): void;
+}
+declare class DataComponent implements DataComponentInterface {
+  config: Omit<DataComponentInsert, 'tenantId' | 'projectId'>;
+  private baseURL;
+  private tenantId;
+  private projectId;
+  private initialized;
+  private id;
+  constructor(config: DataComponentConfigWithZod);
+  setContext(tenantId: string, projectId: string, baseURL?: string): void;
+  getId(): string;
+  getName(): string;
+  getDescription(): string;
+  getProps(): DataComponentInsert['props'];
+  getRender(): DataComponentInsert['render'];
+  init(): Promise<void>;
+  private upsertDataComponent;
+}
+//#endregion
+export { DataComponent, DataComponentInterface };

package/dist/data-component.js

@@ -0,0 +1,109 @@
+import { generateIdFromName } from "./utils/generateIdFromName.js";
+import { getLogger } from "@inkeep/agents-core";
+import { convertZodToJsonSchema, isZodSchema } from "@inkeep/agents-core/utils/schema-conversion";
+
+//#region src/data-component.ts
+const logger = getLogger("dataComponent");
+var DataComponent = class {
+	config;
+	baseURL;
+	tenantId;
+	projectId;
+	initialized = false;
+	id;
+	constructor(config) {
+		this.id = config.id || generateIdFromName(config.name);
+		let processedProps;
+		if (config.props && isZodSchema(config.props)) processedProps = convertZodToJsonSchema(config.props);
+		else processedProps = config.props;
+		this.config = {
+			...config,
+			id: this.id,
+			props: processedProps,
+			render: config.render || null
+		};
+		this.baseURL = process.env.INKEEP_API_URL || "http://localhost:3002";
+		this.tenantId = "default";
+		this.projectId = "default";
+		logger.info({
+			dataComponentId: this.getId(),
+			dataComponentName: config.name
+		}, "DataComponent constructor initialized");
+	}
+	setContext(tenantId, projectId, baseURL) {
+		this.tenantId = tenantId;
+		this.projectId = projectId;
+		if (baseURL) this.baseURL = baseURL;
+	}
+	getId() {
+		return this.id;
+	}
+	getName() {
+		return this.config.name;
+	}
+	getDescription() {
+		return this.config.description || "";
+	}
+	getProps() {
+		return this.config.props;
+	}
+	getRender() {
+		return this.config.render;
+	}
+	async init() {
+		if (this.initialized) return;
+		try {
+			await this.upsertDataComponent();
+			logger.info({ dataComponentId: this.getId() }, "DataComponent initialized successfully");
+			this.initialized = true;
+		} catch (error) {
+			logger.error({
+				dataComponentId: this.getId(),
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to initialize data component");
+			throw error;
+		}
+	}
+	async upsertDataComponent() {
+		const dataComponentData = {
+			id: this.getId(),
+			name: this.config.name,
+			description: this.config.description,
+			props: this.config.props,
+			render: this.config.render
+		};
+		logger.info({ dataComponentData }, "dataComponentData for create/update");
+		const updateResponse = await fetch(`${this.baseURL}/tenants/${this.tenantId}/projects/${this.projectId}/data-components/${this.getId()}`, {
+			method: "PUT",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(dataComponentData)
+		});
+		logger.info({
+			status: updateResponse.status,
+			dataComponentId: this.getId()
+		}, "data component updateResponse");
+		if (updateResponse.ok) {
+			logger.info({ dataComponentId: this.getId() }, "DataComponent updated successfully");
+			return;
+		}
+		if (updateResponse.status === 404) {
+			logger.info({ dataComponentId: this.getId() }, "DataComponent not found, creating new data component");
+			const createResponse = await fetch(`${this.baseURL}/tenants/${this.tenantId}/projects/${this.projectId}/data-components`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(dataComponentData)
+			});
+			if (!createResponse.ok) {
+				const errorText$1 = await createResponse.text().catch(() => "Unknown error");
+				throw new Error(`Failed to create data component: ${createResponse.status} ${createResponse.statusText} - ${errorText$1}`);
+			}
+			logger.info({ dataComponentId: this.getId() }, "DataComponent created successfully");
+			return;
+		}
+		const errorText = await updateResponse.text().catch(() => "Unknown error");
+		throw new Error(`Failed to update data component: ${updateResponse.status} ${updateResponse.statusText} - ${errorText}`);
+	}
+};
+
+//#endregion
+export { DataComponent };

package/dist/environment-settings.d.ts

@@ -0,0 +1,27 @@
+import { Tool } from "./tool.js";
+import { ExtractCredentialIds, ExtractMcpServerIds, UnionCredentialIds, UnionMcpServerIds } from "./credential-ref.js";
+import { CredentialReferenceApiInsert } from "@inkeep/agents-core";
+
+//#region src/environment-settings.d.ts
+interface EnvironmentSettingsConfig {
+  credentials?: {
+    [settingId: string]: CredentialReferenceApiInsert;
+  };
+  mcpServers?: {
+    [mcpServerId: string]: Tool;
+  };
+}
+/**
+ * Create a setting helper with TypeScript autocomplete
+ */
+declare function createEnvironmentSettings<T extends Record<string, EnvironmentSettingsConfig>>(environments: T): {
+  getEnvironmentCredential: (key: UnionCredentialIds<T>) => CredentialReferenceApiInsert;
+  getEnvironmentMcp: (key: UnionMcpServerIds<T>) => Tool;
+  getEnvironmentSetting: (key: UnionCredentialIds<T>) => CredentialReferenceApiInsert;
+};
+/**
+ * Create type-safe environment configurations
+ */
+declare function registerEnvironmentSettings<T extends EnvironmentSettingsConfig>(config: T): T;
+//#endregion
+export { type ExtractCredentialIds, type ExtractMcpServerIds, type UnionCredentialIds, type UnionMcpServerIds, createEnvironmentSettings, registerEnvironmentSettings };