@andreprado/agentkit 0.1.0-alpha.23 → 0.1.0-alpha.24

package/src/index.ts

@@ -9,6 +9,7 @@ export type DiscordChannelMode = "interactions" | "bot";
 export type TelegramAllowedUpdate = "message";
 export type ChannelAudioMode = "off" | "reject" | "transcribe";
 export type TranscriptionProviderName = "test" | "openai" | "groq";
+export type GenericWebhookDirection = "inbound" | "outbound";
 
 export type AgentProvider = {
   name: AgentProviderName;
@@ -66,6 +67,37 @@ export type ChannelAudioConfig =
       maxBytes?: number;
     };
 
+export type ChannelReplyRouteInput = {
+  channel: string;
+  recipientFrom?: string;
+};
+
+export type ChannelReplyRouteConfig = {
+  channel: string;
+  recipientFrom?: string;
+};
+
+export type GenericWebhookOutputAuthInput =
+  | {
+      type: "none";
+    }
+  | {
+      type: "bearer";
+      tokenSecret: string;
+    }
+  | {
+      type: "header";
+      headerName: string;
+      valueSecret: string;
+    }
+  | {
+      type: "hmac";
+      secret: string;
+      headerName?: string;
+    };
+
+export type GenericWebhookOutputAuthConfig = GenericWebhookOutputAuthInput;
+
 export type AgentTranscriptionLimits = {
   maxDurationSeconds?: number;
   maxBytes?: number;
@@ -92,6 +124,7 @@ export type WebsiteChannelInput = {
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
   audio?: ChannelAudioInput;
+  replyTo?: ChannelReplyRouteInput;
 };
 
 export type WebsiteChannelConfig = {
@@ -103,6 +136,7 @@ export type WebsiteChannelConfig = {
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
   audio?: ChannelAudioConfig;
+  replyTo?: ChannelReplyRouteConfig;
 };
 
 export type TelegramChannelInput = {
@@ -112,6 +146,7 @@ export type TelegramChannelInput = {
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
   audio?: ChannelAudioInput;
+  replyTo?: ChannelReplyRouteInput;
 };
 
 export type TelegramChannelConfig = {
@@ -123,6 +158,7 @@ export type TelegramChannelConfig = {
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
   audio?: ChannelAudioConfig;
+  replyTo?: ChannelReplyRouteConfig;
 };
 
 export type WhatsappChannelInput = {
@@ -132,6 +168,7 @@ export type WhatsappChannelInput = {
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
   audio?: ChannelAudioInput;
+  replyTo?: ChannelReplyRouteInput;
 };
 
 export type WhatsappChannelConfig = {
@@ -142,6 +179,7 @@ export type WhatsappChannelConfig = {
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
   audio?: ChannelAudioConfig;
+  replyTo?: ChannelReplyRouteConfig;
 };
 
 export type DiscordChannelInput = {
@@ -150,6 +188,7 @@ export type DiscordChannelInput = {
   secrets?: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  replyTo?: ChannelReplyRouteInput;
 };
 
 export type DiscordChannelConfig = {
@@ -160,6 +199,7 @@ export type DiscordChannelConfig = {
   secrets: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  replyTo?: ChannelReplyRouteConfig;
   audio?: never;
 };
 
@@ -168,6 +208,7 @@ export type SlackChannelInput = {
   secrets?: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  replyTo?: ChannelReplyRouteInput;
 };
 
 export type SlackChannelConfig = {
@@ -177,6 +218,7 @@ export type SlackChannelConfig = {
   secrets: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  replyTo?: ChannelReplyRouteConfig;
   audio?: never;
 };
 
@@ -185,15 +227,42 @@ export type GenericWebhookChannelInput = {
   secrets?: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferInput;
+  replyTo?: ChannelReplyRouteInput;
 };
 
 export type GenericWebhookChannelConfig = {
   type: "webhook";
   provider: "generic";
+  direction: "inbound";
   name: string;
   secrets: string[];
   limits?: ChannelLimits;
   buffer?: ChannelBufferConfig;
+  replyTo?: ChannelReplyRouteConfig;
+  urlSecret?: never;
+  auth?: never;
+  audio?: never;
+};
+
+export type GenericWebhookOutputChannelInput = {
+  name: string;
+  urlSecret: string;
+  auth?: GenericWebhookOutputAuthInput;
+  secrets?: string[];
+  limits?: ChannelLimits;
+};
+
+export type GenericWebhookOutputChannelConfig = {
+  type: "webhook";
+  provider: "generic";
+  direction: "outbound";
+  name: string;
+  urlSecret: string;
+  auth: GenericWebhookOutputAuthConfig;
+  secrets: string[];
+  limits?: ChannelLimits;
+  buffer?: never;
+  replyTo?: never;
   audio?: never;
 };
 
@@ -203,7 +272,8 @@ export type AgentChannel =
   | WhatsappChannelConfig
   | DiscordChannelConfig
   | SlackChannelConfig
-  | GenericWebhookChannelConfig;
+  | GenericWebhookChannelConfig
+  | GenericWebhookOutputChannelConfig;
 
 export type IntegrationTagsConfig = {
   enable?: string[];
@@ -454,6 +524,7 @@ export function websiteChannel(input: WebsiteChannelInput): WebsiteChannelConfig
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "website channel") } : {}),
     ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "website channel") } : {}),
+    ...(input.replyTo ? { replyTo: normalizeChannelReplyRoute(input.replyTo, "website channel") } : {}),
   };
 }
 
@@ -470,6 +541,7 @@ export function telegramChannel(input: TelegramChannelInput): TelegramChannelCon
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "telegram channel") } : {}),
     ...(input.audio ? { audio: normalizeChannelAudio(input.audio, "telegram channel") } : {}),
+    ...(input.replyTo ? { replyTo: normalizeChannelReplyRoute(input.replyTo, "telegram channel") } : {}),
   };
 }
 
@@ -485,6 +557,7 @@ export function whatsappChannel(input: WhatsappChannelInput): WhatsappChannelCon
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, `${input.provider} whatsapp channel`) } : {}),
     ...(input.audio ? { audio: normalizeChannelAudio(input.audio, `${input.provider} whatsapp channel`) } : {}),
+    ...(input.replyTo ? { replyTo: normalizeChannelReplyRoute(input.replyTo, `${input.provider} whatsapp channel`) } : {}),
   };
 }
 
@@ -499,6 +572,7 @@ export function discordChannel(input: DiscordChannelInput): DiscordChannelConfig
     secrets: normalizeChannelSecrets(input.secrets ?? defaultDiscordChannelSecrets(mode), "discord channel"),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "discord channel") } : {}),
+    ...(input.replyTo ? { replyTo: normalizeChannelReplyRoute(input.replyTo, "discord channel") } : {}),
   };
 }
 
@@ -510,6 +584,7 @@ export function slackChannel(input: SlackChannelInput): SlackChannelConfig {
     secrets: normalizeChannelSecrets(input.secrets ?? ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"], "slack channel"),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "slack channel") } : {}),
+    ...(input.replyTo ? { replyTo: normalizeChannelReplyRoute(input.replyTo, "slack channel") } : {}),
   };
 }
 
@@ -517,10 +592,32 @@ export function webhookChannel(input: GenericWebhookChannelInput): GenericWebhoo
   return {
     type: "webhook",
     provider: "generic",
+    direction: "inbound",
     name: input.name,
     secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBHOOK_SECRET"], "generic webhook channel"),
     ...(input.limits ? { limits: input.limits } : {}),
     ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "generic webhook channel") } : {}),
+    ...(input.replyTo ? { replyTo: normalizeChannelReplyRoute(input.replyTo, "generic webhook channel") } : {}),
+  };
+}
+
+export function webhookOutputChannel(input: GenericWebhookOutputChannelInput): GenericWebhookOutputChannelConfig {
+  const auth = normalizeGenericWebhookOutputAuth(input.auth ?? { type: "none" }, "generic webhook output channel");
+  const requiredSecrets = [
+    input.urlSecret,
+    ...genericWebhookOutputAuthSecrets(auth),
+    ...(input.secrets ?? []),
+  ];
+
+  return {
+    type: "webhook",
+    provider: "generic",
+    direction: "outbound",
+    name: input.name,
+    urlSecret: normalizeSecretName(input.urlSecret, "generic webhook output channel urlSecret"),
+    auth,
+    secrets: normalizeChannelSecrets(requiredSecrets, "generic webhook output channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
   };
 }
 
@@ -548,14 +645,22 @@ function normalizeChannelSecrets(secrets: string[], context: string): string[] {
   const uniqueSecrets = new Set<string>();
 
   for (const secret of secrets) {
-    if (!/^[A-Z_][A-Z0-9_]*$/.test(secret)) {
-      throw new Error(`${context} secrets must be environment variable names, not secret values.`);
+    uniqueSecrets.add(normalizeSecretName(secret, `${context} secrets`));
+  }
+
+  return Array.from(uniqueSecrets).sort();
+}
+
+function normalizeSecretName(secret: string, context: string): string {
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(secret)) {
+    if (context.endsWith("secrets")) {
+      throw new Error(`${context} must be environment variable names, not secret values.`);
     }
 
-    uniqueSecrets.add(secret);
+    throw new Error(`${context} must be an environment variable name, not a secret value.`);
   }
 
-  return Array.from(uniqueSecrets).sort();
+  return secret;
 }
 
 function normalizeIntegrationName(value: string, context: string): string {
@@ -717,6 +822,87 @@ function normalizeChannelAudio(input: ChannelAudioInput, context: string): Chann
   };
 }
 
+function normalizeChannelReplyRoute(input: ChannelReplyRouteInput, context: string): ChannelReplyRouteConfig {
+  const channel = input.channel.trim();
+
+  if (!/^[a-z][a-z0-9-]*$/.test(channel)) {
+    throw new Error(`${context} replyTo.channel must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.`);
+  }
+
+  return {
+    channel,
+    ...(input.recipientFrom ? { recipientFrom: normalizeJsonPath(input.recipientFrom, `${context} replyTo.recipientFrom`) } : {}),
+  };
+}
+
+function normalizeJsonPath(value: string, context: string): string {
+  const path = value.trim().replace(/^payload\./, "");
+
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(path)) {
+    throw new Error(`${context} must be a dotted JSON field path such as "phone" or "customer.phone".`);
+  }
+
+  return path;
+}
+
+function normalizeGenericWebhookOutputAuth(
+  auth: GenericWebhookOutputAuthInput,
+  context: string,
+): GenericWebhookOutputAuthConfig {
+  if (auth.type === "none") {
+    return { type: "none" };
+  }
+
+  if (auth.type === "bearer") {
+    return {
+      type: "bearer",
+      tokenSecret: normalizeSecretName(auth.tokenSecret, `${context} auth.tokenSecret`),
+    };
+  }
+
+  if (auth.type === "header") {
+    if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(auth.headerName)) {
+      throw new Error(`${context} auth.headerName must be an HTTP header name.`);
+    }
+
+    return {
+      type: "header",
+      headerName: auth.headerName,
+      valueSecret: normalizeSecretName(auth.valueSecret, `${context} auth.valueSecret`),
+    };
+  }
+
+  if (auth.type === "hmac") {
+    if (auth.headerName !== undefined && !/^[A-Za-z][A-Za-z0-9-]*$/.test(auth.headerName)) {
+      throw new Error(`${context} auth.headerName must be an HTTP header name.`);
+    }
+
+    return {
+      type: "hmac",
+      secret: normalizeSecretName(auth.secret, `${context} auth.secret`),
+      ...(auth.headerName ? { headerName: auth.headerName } : {}),
+    };
+  }
+
+  throw new Error(`${context} auth.type must be "none", "bearer", "header", or "hmac".`);
+}
+
+function genericWebhookOutputAuthSecrets(auth: GenericWebhookOutputAuthConfig): string[] {
+  if (auth.type === "bearer") {
+    return [auth.tokenSecret];
+  }
+
+  if (auth.type === "header") {
+    return [auth.valueSecret];
+  }
+
+  if (auth.type === "hmac") {
+    return [auth.secret];
+  }
+
+  return [];
+}
+
 function validatePositiveInteger(value: number, field: string): void {
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`${field} must be a positive integer.`);