@inkeep/agents-sdk 0.41.2 → 0.43.0

package/dist/builderFunctions.js

@@ -7,7 +7,9 @@ import { Project } from "./project.js";
 import { StatusComponent as StatusComponent$1 } from "./status-component.js";
 import { Tool } from "./tool.js";
 import { SubAgent } from "./subAgent.js";
-import { CredentialReferenceApiInsertSchema, MCPToolConfigSchema } from "@inkeep/agents-core";
+import { Trigger } from "./trigger.js";
+import { CredentialReferenceApiInsertSchema, MCPToolConfigSchema, SignatureVerificationConfigSchema } from "@inkeep/agents-core";
+import { validateJMESPath, validateRegex } from "@inkeep/agents-core/utils/signature-validation";
 
 //#region src/builderFunctions.ts
 /**
@@ -322,6 +324,133 @@ function agentMcp(config) {
 function functionTool(config) {
 	return new FunctionTool(config);
 }
+/**
+* Creates a webhook trigger for external service integration.
+*
+* Triggers allow external services to invoke agents via webhooks.
+* They support authentication via arbitrary header key-value pairs,
+* payload transformation, input validation, and signature verification.
+*
+* @param config - Trigger configuration
+* @returns A Trigger instance
+* @throws {Error} If signatureVerification config validation fails
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+*
+* // GitHub webhook trigger with signature verification
+* const githubWebhookSecret = credential({
+*   id: 'github-webhook-secret',
+*   name: 'GitHub Webhook Secret',
+*   type: 'bearer',
+*   value: process.env.GITHUB_WEBHOOK_SECRET
+* });
+*
+* const githubTrigger = trigger({
+*   name: 'GitHub Events',
+*   description: 'Handle GitHub webhook events',
+*   enabled: true,
+*   inputSchema: z.object({
+*     action: z.string(),
+*     repository: z.object({
+*       name: z.string(),
+*       url: z.string()
+*     })
+*   }),
+*   outputTransform: {
+*     jmespath: '{action: action, repo: repository.name, url: repository.url}'
+*   },
+*   messageTemplate: 'GitHub {{action}} on repository {{repo}}: {{url}}',
+*   authentication: {
+*     headers: [
+*       { name: 'X-GitHub-Token', value: process.env.GITHUB_TOKEN }
+*     ]
+*   },
+*   signingSecretCredentialReference: githubWebhookSecret,
+*   signatureVerification: {
+*     algorithm: 'sha256',
+*     encoding: 'hex',
+*     signature: {
+*       source: 'header',
+*       key: 'x-hub-signature-256',
+*       prefix: 'sha256='
+*     },
+*     signedComponents: [
+*       { source: 'body', required: true }
+*     ],
+*     componentJoin: {
+*       strategy: 'concatenate',
+*       separator: ''
+*     }
+*   }
+* });
+*
+* // Slack webhook trigger with complex signature
+* const slackTrigger = trigger({
+*   name: 'Slack Events',
+*   description: 'Handle Slack webhook events',
+*   messageTemplate: 'Slack event: {{type}}',
+*   signingSecretCredentialReference: slackSecret,
+*   signatureVerification: {
+*     algorithm: 'sha256',
+*     encoding: 'hex',
+*     signature: {
+*       source: 'header',
+*       key: 'x-slack-signature',
+*       prefix: 'v0='
+*     },
+*     signedComponents: [
+*       { source: 'literal', value: 'v0', required: true },
+*       { source: 'header', key: 'x-slack-request-timestamp', required: true },
+*       { source: 'body', required: true }
+*     ],
+*     componentJoin: {
+*       strategy: 'concatenate',
+*       separator: ':'
+*     }
+*   }
+* });
+*
+* // Simple webhook trigger with no signature verification
+* const simpleTrigger = trigger({
+*   name: 'Internal Webhook',
+*   description: 'Internal webhook with no signature',
+*   messageTemplate: 'New message: {{text}}'
+* });
+* ```
+*/
+function trigger(config) {
+	if (config.signatureVerification !== void 0 && config.signatureVerification !== null) {
+		const triggerName = config.name || "unknown";
+		try {
+			SignatureVerificationConfigSchema.parse(config.signatureVerification);
+		} catch (error) {
+			if (error instanceof Error) throw new Error(`Invalid signatureVerification config in trigger '${triggerName}': ${error.message}`);
+			throw error;
+		}
+		const sigConfig = config.signatureVerification;
+		if (sigConfig.signature.regex) {
+			const result = validateRegex(sigConfig.signature.regex);
+			if (!result.valid) throw new Error(`Invalid signatureVerification config in trigger '${triggerName}': ${result.error}`);
+		}
+		if (sigConfig.signature.source === "body" && sigConfig.signature.key) {
+			const result = validateJMESPath(sigConfig.signature.key);
+			if (!result.valid) throw new Error(`Invalid signatureVerification config in trigger '${triggerName}': ${result.error}`);
+		}
+		for (const component of sigConfig.signedComponents) {
+			if (component.regex) {
+				const result = validateRegex(component.regex);
+				if (!result.valid) throw new Error(`Invalid signatureVerification config in trigger '${triggerName}': ${result.error}`);
+			}
+			if (component.source === "body" && component.key) {
+				const result = validateJMESPath(component.key);
+				if (!result.valid) throw new Error(`Invalid signatureVerification config in trigger '${triggerName}': ${result.error}`);
+			}
+		}
+	}
+	return new Trigger(config);
+}
 
 //#endregion
-export { agent, agentMcp, artifactComponent, credential, dataComponent, functionTool, mcpServer, mcpTool, project, statusComponent, subAgent };
+export { agent, agentMcp, artifactComponent, credential, dataComponent, functionTool, mcpServer, mcpTool, project, statusComponent, subAgent, trigger };

package/dist/builderFunctionsExperimental.d.ts

@@ -1,22 +1,22 @@
 //#region src/builderFunctionsExperimental.d.ts
 /**
- * Creates an agent relation configuration.
- *
- * Relations define how agents can interact with each other.
- * Transfer relations allow transfers, while delegate relations
- * allow temporary task delegation.
- *
- * @param targetAgent - The ID of the target agent
- * @param relationType - The type of relation (transfer or delegate)
- * @returns An agent relation configuration
- *
- * @example
- * ```typescript
- * const transferRelation = agentRelation('support-agent', 'transfer');
- * const delegateRelation = agentRelation('specialist-agent', 'delegate');
- * ```
- */
-declare function agentRelation(targetAgent: string, relationType?: 'transfer' | 'delegate'): {
+* Creates an agent relation configuration.
+*
+* Relations define how agents can interact with each other.
+* Transfer relations allow transfers, while delegate relations
+* allow temporary task delegation.
+*
+* @param targetAgent - The ID of the target agent
+* @param relationType - The type of relation (transfer or delegate)
+* @returns An agent relation configuration
+*
+* @example
+* ```typescript
+* const transferRelation = agentRelation('support-agent', 'transfer');
+* const delegateRelation = agentRelation('specialist-agent', 'delegate');
+* ```
+*/
+declare function agentRelation(targetAgent: string, relationType?: "transfer" | "delegate"): {
   targetAgent: string;
   relationType: "transfer" | "delegate";
 };

package/dist/builders.d.ts

@@ -7,18 +7,18 @@ import { z } from "zod";
 //#region src/builders.d.ts
 
 /**
- * Function signature for tool execution
- * @template TParams - Type of input parameters
- * @template TResult - Type of return value
- */
+* Function signature for tool execution
+* @template TParams - Type of input parameters
+* @template TResult - Type of return value
+*/
 type ToolExecuteFunction<TParams = unknown, TResult = unknown> = (params: TParams) => Promise<TResult>;
 /**
- * Function signature for transfer conditions
- */
+* Function signature for transfer conditions
+*/
 type TransferConditionFunction = (context: unknown) => boolean;
 /**
- * Configuration for MCP server builders
- */
+* Configuration for MCP server builders
+*/
 interface MCPServerConfig {
   name: string;
   description: string;
@@ -26,14 +26,14 @@ interface MCPServerConfig {
   id?: string;
   parameters?: Record<string, z.ZodJSONSchema>;
   credential?: CredentialReferenceApiInsert;
-  transport?: 'streamable_http' | 'sse';
+  transport?: "streamable_http" | "sse";
   activeTools?: string[];
   headers?: Record<string, string>;
   imageUrl?: string;
 }
 /**
- * Configuration for component builders
- */
+* Configuration for component builders
+*/
 interface ComponentConfig {
   id?: string;
   name: string;
@@ -55,12 +55,12 @@ interface StatusComponentConfig {
   detailsSchema?: Record<string, unknown> | z.ZodObject<any>;
 }
 /**
- * Schema for transfer configuration (excluding function properties)
- */
-declare const TransferConfigSchema: z.ZodObject<{
-  agent: z.ZodCustom<SubAgent, SubAgent>;
-  description: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+* Schema for transfer configuration (excluding function properties)
+*/
+declare const TransferConfigSchema: z.ZodType<{
+  agent: SubAgent;
+  description?: string;
+}>;
 type AgentMcpConfig = {
   server: Tool;
   selectedTools?: string[];
@@ -68,44 +68,44 @@ type AgentMcpConfig = {
   toolPolicies?: Record<string, ToolPolicy>;
 };
 /**
- * Input configuration for MCP tool customization
- * Supports flexible tool selection with per-tool policies
- */
+* Input configuration for MCP tool customization
+* Supports flexible tool selection with per-tool policies
+*/
 type AgentMcpConfigInput = {
   /**
-   * Tools to enable from the MCP server - can be strings or objects with policies
-   * - undefined or null: all tools enabled (no filtering)
-   * - []: zero tools enabled (explicit empty selection)
-   * - ['tool1', 'tool2']: specific tools enabled
-   */
+  * Tools to enable from the MCP server - can be strings or objects with policies
+  * - undefined or null: all tools enabled (no filtering)
+  * - []: zero tools enabled (explicit empty selection)
+  * - ['tool1', 'tool2']: specific tools enabled
+  */
   selectedTools?: McpToolSelection[] | null;
   /** Custom headers for MCP server requests */
   headers?: Record<string, string>;
 };
 /**
- * Creates a transfer configuration for agent transfers.
- *
- * Transfers allow one agent to hand off control to another agent
- * based on optional conditions.
- *
- * @param targetAgent - The agent to transfer to
- * @param description - Optional description of when/why to transfer
- * @param condition - Optional function to determine if transfer should occur
- * @returns A validated transfer configuration
- *
- * @example
- * ```typescript
- * // Simple transfer
- * const transfer = transfer(supportAgent, 'Transfer to support');
- *
- * // Conditional transfer
- * const conditionalHandoff = transfer(
- *   specialistAgent,
- *   'Transfer to specialist for complex issues',
- *   (context) => context.complexity > 0.8
- * );
- * ```
- */
+* Creates a transfer configuration for agent transfers.
+*
+* Transfers allow one agent to hand off control to another agent
+* based on optional conditions.
+*
+* @param targetAgent - The agent to transfer to
+* @param description - Optional description of when/why to transfer
+* @param condition - Optional function to determine if transfer should occur
+* @returns A validated transfer configuration
+*
+* @example
+* ```typescript
+* // Simple transfer
+* const transfer = transfer(supportAgent, 'Transfer to support');
+*
+* // Conditional transfer
+* const conditionalHandoff = transfer(
+*   specialistAgent,
+*   'Transfer to specialist for complex issues',
+*   (context) => context.complexity > 0.8
+* );
+* ```
+*/
 declare function transfer(targetAgent: SubAgent, description?: string, condition?: TransferConditionFunction): TransferConfig;
 //#endregion
 export { AgentMcpConfig, AgentMcpConfigInput, ArtifactComponentConfig, ComponentConfig, DataComponentConfig, MCPServerConfig, StatusComponentConfig, ToolExecuteFunction, TransferConditionFunction, TransferConfigSchema, transfer };

package/dist/credential-provider.d.ts

@@ -1,29 +1,29 @@
 //#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'
- * })
- * ```
- */
+* 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
- */
+* 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;
@@ -44,33 +44,33 @@ interface CredentialStore {
   }>;
 }
 /**
- * Supported credential provider types
- */
-type CredentialProviderType = 'memory' | 'keychain' | 'nango' | 'custom';
+* Supported credential provider types
+*/
+type CredentialProviderType = "memory" | "keychain" | "nango" | "custom";
 /**
- * Configuration for memory-based credential storage
- */
+* Configuration for memory-based credential storage
+*/
 interface MemoryCredentialConfig {
-  type: 'memory';
+  type: "memory";
   /** Optional store ID (defaults to 'memory-default') */
   id?: string;
 }
 /**
- * Configuration for keychain-based credential storage
- */
+* Configuration for keychain-based credential storage
+*/
 interface KeychainCredentialConfig {
-  type: 'keychain';
+  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
- */
+* Configuration for Nango-based credential storage (OAuth management)
+* Note: Using Nango requires the @nangohq/node package to be installed
+*/
 interface NangoCredentialConfig {
-  type: 'nango';
+  type: "nango";
   /** Optional store ID (defaults to 'nango-default') */
   id?: string;
   /** Nango secret key (defaults to NANGO_SECRET_KEY env var) */
@@ -79,98 +79,98 @@ interface NangoCredentialConfig {
   apiUrl?: string;
 }
 /**
- * Configuration for custom credential provider
- */
+* Configuration for custom credential provider
+*/
 interface CustomCredentialConfig {
-  type: 'custom';
+  type: "custom";
   /** Custom credential store implementation */
   store: CredentialStore;
 }
 /**
- * Union type for all credential provider configurations
- */
+* 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'
- * ```
- */
+* 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
-   */
+  * Create the appropriate store based on configuration
+  */
   private createStore;
   /**
-   * Create keychain store with dynamic import
-   */
+  * Create keychain store with dynamic import
+  */
   private createKeychainStore;
   /**
-   * Create Nango store with dynamic import
-   */
+  * 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 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 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
-   */
+  * 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 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
-   */
+  * 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)
-   */
+  * 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
- */
+* 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

@@ -111,7 +111,7 @@ var InkeepCredentialProvider = class {
 				} catch {
 					return {
 						available: false,
-						reason: "Keychain store requires keytar package to be installed"
+						reason: "Keychain store requires @napi-rs/keyring package to be installed"
 					};
 				}
 			}