@inkeep/agents-sdk 0.41.2 → 0.43.0

package/dist/builderFunctions.d.ts

@@ -1,3 +1,4 @@
+import { Trigger } from "./trigger.js";
 import { ArtifactComponent } from "./artifact-component.js";
 import { Tool } from "./tool.js";
 import { SubAgent } from "./subAgent.js";
@@ -8,276 +9,364 @@ import { AgentConfig, FunctionToolConfig, SubAgentConfig } from "./types.js";
 import { Agent } from "./agent.js";
 import { Project, ProjectConfig } from "./project.js";
 import { StatusComponent as StatusComponent$1 } from "./status-component.js";
-import { CredentialReferenceApiInsert, MCPToolConfig } from "@inkeep/agents-core";
+import { CredentialReferenceApiInsert, MCPToolConfig, TriggerApiInsert } from "@inkeep/agents-core";
 
 //#region src/builderFunctions.d.ts
 
 /**
- * Helper function to create agent - OpenAI style
- */
+* Helper function to create agent - OpenAI style
+*/
 declare function agent(config: AgentConfig): Agent;
 /**
- * Helper function to create projects - OpenAI style
- *
- * Projects are the top-level organizational unit that contains Agents, Sub Agents, and shared configurations.
- * They provide model inheritance and execution limits that cascade down to Agents and Sub Agents.
- *
- * @param config - Project configuration
- * @returns A new Project instance
- *
- * @example
- * ```typescript
- * const customerSupport = project({
- *   id: 'customer-support-project',
- *   name: 'Customer Support System',
- *   description: 'Multi-agent customer support system',
- *   models: {
- *     base: { model: 'gpt-4.1-mini' },
- *     structuredOutput: { model: 'gpt-4.1' }
- *   },
- *   stopWhen: {
- *     transferCountIs: 10,
- *     stepCountIs: 50
- *   },
- *   agent: () => [
- *     agent({
- *       id: 'support-agent',
- *       name: 'Support Agent',
- *       // ... agent config
- *     })
- *   ]
- * });
- * ```
- */
+* Helper function to create projects - OpenAI style
+*
+* Projects are the top-level organizational unit that contains Agents, Sub Agents, and shared configurations.
+* They provide model inheritance and execution limits that cascade down to Agents and Sub Agents.
+*
+* @param config - Project configuration
+* @returns A new Project instance
+*
+* @example
+* ```typescript
+* const customerSupport = project({
+*   id: 'customer-support-project',
+*   name: 'Customer Support System',
+*   description: 'Multi-agent customer support system',
+*   models: {
+*     base: { model: 'gpt-4.1-mini' },
+*     structuredOutput: { model: 'gpt-4.1' }
+*   },
+*   stopWhen: {
+*     transferCountIs: 10,
+*     stepCountIs: 50
+*   },
+*   agent: () => [
+*     agent({
+*       id: 'support-agent',
+*       name: 'Support Agent',
+*       // ... agent config
+*     })
+*   ]
+* });
+* ```
+*/
 declare function project(config: ProjectConfig): Project;
 /**
- * Creates a new agent with stable ID enforcement.
- *
- * Agents require explicit stable IDs to ensure consistency across deployments.
- * This is different from tools which auto-generate IDs from their names.
- *
- * @param config - Agent configuration including required stable ID
- * @returns A new SubAgent instance
- * @throws {Error} If config.id is not provided
- *
- * @example
- * ```typescript
- * const myAgent = agent({
- *   id: 'customer-support-agent',
- *   name: 'Customer Support',
- *   prompt: 'Help customers with their questions'
- * });
- * ```
- */
+* Creates a new agent with stable ID enforcement.
+*
+* Agents require explicit stable IDs to ensure consistency across deployments.
+* This is different from tools which auto-generate IDs from their names.
+*
+* @param config - Agent configuration including required stable ID
+* @returns A new SubAgent instance
+* @throws {Error} If config.id is not provided
+*
+* @example
+* ```typescript
+* const myAgent = agent({
+*   id: 'customer-support-agent',
+*   name: 'Customer Support',
+*   prompt: 'Help customers with their questions'
+* });
+* ```
+*/
 declare function subAgent(config: SubAgentConfig): SubAgent;
 /**
- * Creates a credential reference for authentication.
- *
- * Credentials are used to authenticate with external services.
- * They should be stored securely and referenced by ID.
- *
- * @param config - Credential configuration
- * @returns A validated credential reference
- *
- * @example
- * ```typescript
- * const apiCredential = credential({
- *   id: 'github-token',
- *   name: 'GitHub Token',
- *   type: 'bearer',
- *   value: process.env.GITHUB_TOKEN
- * });
- * ```
- */
-declare function credential(config: CredentialReferenceApiInsert): {
-  id: string;
-  name: string;
-  credentialStoreId: string;
-  type: "memory" | "keychain" | "nango";
-  createdAt?: string | undefined;
-  updatedAt?: string | undefined;
-  retrievalParams?: Record<string, unknown> | null | undefined;
-  userId?: string | null | undefined;
-  toolId?: string | null | undefined;
-  createdBy?: string | null | undefined;
-};
+* Creates a credential reference for authentication.
+*
+* Credentials are used to authenticate with external services.
+* They should be stored securely and referenced by ID.
+*
+* @param config - Credential configuration
+* @returns A validated credential reference
+*
+* @example
+* ```typescript
+* const apiCredential = credential({
+*   id: 'github-token',
+*   name: 'GitHub Token',
+*   type: 'bearer',
+*   value: process.env.GITHUB_TOKEN
+* });
+* ```
+*/
+declare function credential(config: CredentialReferenceApiInsert): CredentialReferenceApiInsert;
 /**
- * Creates an MCP (Model Context Protocol) server for tool functionality.
- *
- * MCP servers provide tool functionality through a standardized protocol.
- * They can be remote services accessed via HTTP/WebSocket.
- *
- * @param config - MCP server configuration
- * @returns A Tool instance configured as an MCP server
- * @throws {Error} If serverUrl is not provided
- *
- * @example
- * ```typescript
- * // Remote MCP server
- * const apiServer = mcpServer({
- *   name: 'external_api',
- *   description: 'External API service',
- *   serverUrl: 'https://api.example.com/mcp'
- * });
- *
- * // With authentication
- * const secureServer = mcpServer({
- *   name: 'secure_api',
- *   description: 'Secure API service',
- *   serverUrl: 'https://secure.example.com/mcp',
- *   credential: credential({
- *     id: 'api-key',
- *     name: 'API Key',
- *     type: 'bearer',
- *     value: process.env.API_KEY
- *   })
- * });
- * ```
- */
+* Creates an MCP (Model Context Protocol) server for tool functionality.
+*
+* MCP servers provide tool functionality through a standardized protocol.
+* They can be remote services accessed via HTTP/WebSocket.
+*
+* @param config - MCP server configuration
+* @returns A Tool instance configured as an MCP server
+* @throws {Error} If serverUrl is not provided
+*
+* @example
+* ```typescript
+* // Remote MCP server
+* const apiServer = mcpServer({
+*   name: 'external_api',
+*   description: 'External API service',
+*   serverUrl: 'https://api.example.com/mcp'
+* });
+*
+* // With authentication
+* const secureServer = mcpServer({
+*   name: 'secure_api',
+*   description: 'Secure API service',
+*   serverUrl: 'https://secure.example.com/mcp',
+*   credential: credential({
+*     id: 'api-key',
+*     name: 'API Key',
+*     type: 'bearer',
+*     value: process.env.API_KEY
+*   })
+* });
+* ```
+*/
 declare function mcpServer(config: MCPServerConfig): Tool;
 /**
- * Creates an MCP tool from a raw configuration object.
- *
- * This is a low-level builder for advanced use cases where you need
- * full control over the MCPToolConfig. For most cases, use `mcpServer()`.
- *
- * @param config - Complete MCP tool configuration
- * @returns A Tool instance
- *
- * @example
- * ```typescript
- * const customTool = mcpTool({
- *   id: 'custom-tool',
- *   name: 'Custom Tool',
- *   serverUrl: 'https://example.com/mcp',
- *   transport: { type: 'stdio' }
- * });
- * ```
- */
+* Creates an MCP tool from a raw configuration object.
+*
+* This is a low-level builder for advanced use cases where you need
+* full control over the MCPToolConfig. For most cases, use `mcpServer()`.
+*
+* @param config - Complete MCP tool configuration
+* @returns A Tool instance
+*
+* @example
+* ```typescript
+* const customTool = mcpTool({
+*   id: 'custom-tool',
+*   name: 'Custom Tool',
+*   serverUrl: 'https://example.com/mcp',
+*   transport: { type: 'stdio' }
+* });
+* ```
+*/
 declare function mcpTool(config: MCPToolConfig): Tool;
 /**
- * Creates an artifact component with automatic ID generation.
- *
- * Artifact components represent structured UI components that can
- * be rendered with different levels of detail (summary vs full).
- *
- * @param config - Artifact component configuration
- * @returns An ArtifactComponent instance
- *
- * @example
- * ```typescript
- * const productCard = artifactComponent({
- *   name: 'Product Card',
- *   description: 'Display product information',
- *   props: {
- *     type: 'object',
- *     properties: {
- *       title: { type: 'string', inPreview: true },
- *       price: { type: 'string', inPreview: true },
- *       description: { type: 'string' },
- *       image: { type: 'string' }
- *     }
- *   }
- * });
- * ```
- */
+* Creates an artifact component with automatic ID generation.
+*
+* Artifact components represent structured UI components that can
+* be rendered with different levels of detail (summary vs full).
+*
+* @param config - Artifact component configuration
+* @returns An ArtifactComponent instance
+*
+* @example
+* ```typescript
+* const productCard = artifactComponent({
+*   name: 'Product Card',
+*   description: 'Display product information',
+*   props: {
+*     type: 'object',
+*     properties: {
+*       title: { type: 'string', inPreview: true },
+*       price: { type: 'string', inPreview: true },
+*       description: { type: 'string' },
+*       image: { type: 'string' }
+*     }
+*   }
+* });
+* ```
+*/
 declare function artifactComponent(config: ArtifactComponentConfig): ArtifactComponent;
 /**
- * Creates a data component with automatic ID generation.
- *
- * Data components represent structured data that can be
- * passed between agents or used in processing.
- *
- * @param config - Data component configuration
- * @returns A DataComponent instance
- *
- * @example
- * ```typescript
- * const userProfile = dataComponent({
- *   name: 'User Profile',
- *   description: 'User profile data',
- *   props: {
- *     userId: '123',
- *     name: 'John Doe',
- *     email: 'john@example.com'
- *   }
- * });
- * ```
- */
+* Creates a data component with automatic ID generation.
+*
+* Data components represent structured data that can be
+* passed between agents or used in processing.
+*
+* @param config - Data component configuration
+* @returns A DataComponent instance
+*
+* @example
+* ```typescript
+* const userProfile = dataComponent({
+*   name: 'User Profile',
+*   description: 'User profile data',
+*   props: {
+*     userId: '123',
+*     name: 'John Doe',
+*     email: 'john@example.com'
+*   }
+* });
+* ```
+*/
 declare function dataComponent(config: DataComponentConfig): DataComponent;
 /**
- * Creates a status component for structured status updates.
- *
- * Status components define the structure of status updates
- * that agents can generate during long-running operations.
- *
- * @param config - Status component configuration
- * @returns A StatusComponent instance
- *
- * @example
- * ```typescript
- * import { z } from 'zod';
- *
- * const toolCallStatus = statusComponent({
- *   type: 'tool_call_summary',
- *   description: 'Summary of a tool execution',
- *   detailsSchema: z.object({
- *     tool_name: z.string(),
- *     summary: z.string(),
- *     status: z.enum(['success', 'error', 'in_progress'])
- *   })
- * });
- * ```
- */
+* Creates a status component for structured status updates.
+*
+* Status components define the structure of status updates
+* that agents can generate during long-running operations.
+*
+* @param config - Status component configuration
+* @returns A StatusComponent instance
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+*
+* const toolCallStatus = statusComponent({
+*   type: 'tool_call_summary',
+*   description: 'Summary of a tool execution',
+*   detailsSchema: z.object({
+*     tool_name: z.string(),
+*     summary: z.string(),
+*     status: z.enum(['success', 'error', 'in_progress'])
+*   })
+* });
+* ```
+*/
 declare function statusComponent(config: StatusComponentConfig): StatusComponent$1;
 /**
- * (deprecated in favor of mcpTool.with()) Creates an agent MCP configuration.
- *
- * Agent MCP configurations are used to configure the MCP server for an agent.
- *
- * @param config - Agent MCP configuration
- * @returns An AgentMcpConfig instance
- */
+* (deprecated in favor of mcpTool.with()) Creates an agent MCP configuration.
+*
+* Agent MCP configurations are used to configure the MCP server for an agent.
+*
+* @param config - Agent MCP configuration
+* @returns An AgentMcpConfig instance
+*/
 declare function agentMcp(config: AgentMcpConfig): AgentMcpConfig;
 /**
- * Creates a function tool that executes user-defined code in a sandboxed environment.
- *
- * Function tools allow users to define custom logic that runs securely in isolated
- * environments. Dependencies are installed automatically in the sandbox.
- *
- * @param config - Function tool configuration
- * @returns A FunctionTool instance
- *
- * @example
- * ```typescript
- * const calculatorTool = functionTool({
- *   name: 'calculator',
- *   description: 'Performs basic math operations',
- *   inputSchema: {
- *     type: 'object',
- *     properties: {
- *       operation: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
- *       a: { type: 'number' },
- *       b: { type: 'number' }
- *     },
- *     required: ['operation', 'a', 'b']
- *   },
- *   dependencies: {
- *     'lodash': '^4.17.21'
- *   },
- *   execute: async (params) => {
- *     const { operation, a, b } = params;
- *     switch (operation) {
- *       case 'add': return { result: a + b };
- *       case 'subtract': return { result: a - b };
- *       case 'multiply': return { result: a * b };
- *       case 'divide': return { result: a / b };
- *       default: throw new Error(`Unknown operation: ${operation}`);
- *     }
- *   }
- * });
- * ```
- */
+* Creates a function tool that executes user-defined code in a sandboxed environment.
+*
+* Function tools allow users to define custom logic that runs securely in isolated
+* environments. Dependencies are installed automatically in the sandbox.
+*
+* @param config - Function tool configuration
+* @returns A FunctionTool instance
+*
+* @example
+* ```typescript
+* const calculatorTool = functionTool({
+*   name: 'calculator',
+*   description: 'Performs basic math operations',
+*   inputSchema: {
+*     type: 'object',
+*     properties: {
+*       operation: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
+*       a: { type: 'number' },
+*       b: { type: 'number' }
+*     },
+*     required: ['operation', 'a', 'b']
+*   },
+*   dependencies: {
+*     'lodash': '^4.17.21'
+*   },
+*   execute: async (params) => {
+*     const { operation, a, b } = params;
+*     switch (operation) {
+*       case 'add': return { result: a + b };
+*       case 'subtract': return { result: a - b };
+*       case 'multiply': return { result: a * b };
+*       case 'divide': return { result: a / b };
+*       default: throw new Error(`Unknown operation: ${operation}`);
+*     }
+*   }
+* });
+* ```
+*/
 declare function functionTool(config: FunctionToolConfig): FunctionTool;
+/**
+* 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}}'
+* });
+* ```
+*/
+declare function trigger(config: Omit<TriggerApiInsert, "id"> & {
+  id?: string;
+}): Trigger;
 //#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 };