@andreprado/agentkit 0.1.0-alpha.10

package/src/runtime/channels/telegram.ts

@@ -0,0 +1,360 @@
+import type {
+  ChannelAdapter,
+  ChannelSendInput,
+  ChannelStatusResult,
+  RawWebhookEvent,
+  WebhookVerificationResult,
+} from "../channels";
+import { AgentKitError } from "../errors";
+
+export const telegramChannelAdapter: ChannelAdapter = {
+  type: "telegram",
+  provider: "telegram",
+  requiredSecrets: ["TELEGRAM_BOT_TOKEN", "TELEGRAM_WEBHOOK_SECRET"],
+  verifyWebhook(input): WebhookVerificationResult {
+    const expected = input.secrets.TELEGRAM_WEBHOOK_SECRET;
+
+    if (!expected) {
+      return {
+        ok: false,
+        code: "channel_secret_missing",
+        message: "Secret TELEGRAM_WEBHOOK_SECRET is not set for this channel.",
+      };
+    }
+
+    const actual = input.headers.get("x-telegram-bot-api-secret-token");
+
+    if (actual !== expected) {
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Telegram webhook secret token did not match.",
+      };
+    }
+
+    return { ok: true };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const updateId = readNumber(body, "update_id");
+
+    if (updateId === undefined) {
+      throw new AgentKitError("channel_payload_invalid", "Telegram payload is missing update_id.");
+    }
+
+    const base = {
+      type: "telegram" as const,
+      provider: "telegram" as const,
+      providerEventId: String(updateId),
+      dedupeKey: `telegram:${input.channelId}:${updateId}`,
+      receivedAt: input.receivedAt,
+    };
+    const message = readRecord(body, "message");
+    const chat = readRecord(message, "chat");
+    const from = readRecord(message, "from");
+    const chatId = readNumberishString(chat, "id") ?? "unknown";
+    const userId = readNumberishString(from, "id") ?? "unknown";
+    const identity = {
+      key: `telegram:user:${userId}:chat:${chatId}`,
+      display: readString(from, "first_name"),
+      redactedDisplay: `telegram:user:${redactId(userId)}:chat:${chatId}`,
+    };
+
+    if (!Object.keys(message).length) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          externalIdentity: identity,
+          unsupportedReason: "unsupported_update_type:non_message",
+        },
+      ];
+    }
+
+    const chatType = readString(chat, "type");
+
+    if (chatType !== "private") {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          externalIdentity: identity,
+          unsupportedReason: `unsupported_chat_type:${chatType ?? "unknown"}`,
+        },
+      ];
+    }
+
+    const text = readString(message, "text");
+
+    if (!text) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          externalIdentity: identity,
+          unsupportedReason: "unsupported_message_type:non_text",
+        },
+      ];
+    }
+
+    return [
+      {
+        ...base,
+        kind: "message",
+        externalIdentity: identity,
+        message: {
+          role: "user",
+          contentType: "text",
+          content: text,
+          providerMessageId: readNumberishString(message, "message_id"),
+        },
+      },
+    ];
+  },
+  async sendMessage(input) {
+    return sendTelegramMessage(input);
+  },
+  getStatus(input) {
+    if (!input.secrets.TELEGRAM_BOT_TOKEN) {
+      return {
+        status: "needs_setup",
+        checkedAt: new Date().toISOString(),
+        message: "Secret TELEGRAM_BOT_TOKEN is missing.",
+      };
+    }
+
+    return {
+      status: "needs_setup",
+      checkedAt: new Date().toISOString(),
+      message: "Run agentkit channels setup to call Telegram setWebhook.",
+    };
+  },
+};
+
+export type TelegramSendMessageRequest = {
+  method: "POST";
+  url: string;
+  body: {
+    chat_id: string;
+    text: string;
+  };
+  idempotencyKey: string;
+};
+
+type TelegramFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export function buildTelegramSendMessageRequest(input: ChannelSendInput): TelegramSendMessageRequest {
+  return buildTelegramSendMessageRequestInternal(input, "<redacted>");
+}
+
+export async function sendTelegramMessage(
+  input: ChannelSendInput,
+  fetcher: TelegramFetch = fetch,
+): Promise<Awaited<ReturnType<ChannelAdapter["sendMessage"]>>> {
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildTelegramSendMessageRequest(input);
+
+    return {
+      ok: true,
+      status: "sent",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const token = input.secrets.TELEGRAM_BOT_TOKEN;
+
+  if (!token) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret TELEGRAM_BOT_TOKEN is not set for this channel.",
+    };
+  }
+
+  let request: TelegramSendMessageRequest;
+  let actualRequest: TelegramSendMessageRequest;
+
+  try {
+    request = buildTelegramSendMessageRequest(input);
+    actualRequest = buildTelegramSendMessageRequestInternal(input, token);
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(actualRequest.url, {
+      method: actualRequest.method,
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    const errorMessage = (error instanceof Error ? error.message : String(error)).replace(token, "<redacted>");
+
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Telegram sendMessage request failed before a response: ${errorMessage}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok || !isRecord(payload) || payload.ok !== true) {
+    const description =
+      isRecord(payload) && typeof payload.description === "string"
+        ? payload.description
+        : `Telegram sendMessage returned HTTP ${response.status}.`;
+    const syntheticExpectedFailure = isSyntheticTelegramChatId(request.body.chat_id) && /chat not found/i.test(description);
+
+    return {
+      ok: false,
+      retryable: syntheticExpectedFailure ? false : response.status === 429 || response.status >= 500,
+      code: syntheticExpectedFailure ? "synthetic_expected_failure" : "channel_send_failed",
+      message: syntheticExpectedFailure
+        ? "Synthetic Telegram smoke reached AgentKit. Telegram correctly rejected the fake chat ID."
+        : description,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const result = isRecord(payload.result) ? payload.result : undefined;
+  const messageId = readNumberishString(result ?? {}, "message_id");
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: request.idempotencyKey,
+    ...(messageId ? { providerMessageId: messageId } : {}),
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      body: request.body,
+    },
+  };
+}
+
+function isSyntheticTelegramChatId(chatId: string): boolean {
+  return chatId === "456" || chatId.startsWith("agentkit-synthetic-");
+}
+
+function buildTelegramSendMessageRequestInternal(input: ChannelSendInput, token: string): TelegramSendMessageRequest {
+  const chatId = input.externalIdentity.key.match(/:chat:([^:]+)$/)?.[1];
+
+  if (!chatId) {
+    throw new AgentKitError("channel_payload_invalid", "Telegram external identity is missing chat ID.");
+  }
+
+  return {
+    method: "POST",
+    url: `https://api.telegram.org/bot${token}/sendMessage`,
+    body: {
+      chat_id: chatId,
+      text: input.message.content,
+    },
+    idempotencyKey: `telegram:${input.channelId}:${input.conversationId}:${chatId}`,
+  };
+}
+
+export function parseTelegramWebhookInfo(input: unknown, checkedAt: string): ChannelStatusResult {
+  if (!isRecord(input) || input.ok !== true || !isRecord(input.result)) {
+    return {
+      status: "failed",
+      checkedAt,
+      message: "Telegram getWebhookInfo response was not ok.",
+    };
+  }
+
+  const url = readString(input.result, "url");
+  const pendingUpdateCount = readNumber(input.result, "pending_update_count") ?? 0;
+
+  return {
+    status: url ? "connected" : "needs_setup",
+    checkedAt,
+    providerMetadata: {
+      hasWebhookUrl: Boolean(url),
+      pendingUpdateCount,
+    },
+  };
+}
+
+function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(input.rawBody) as unknown;
+
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    throw new AgentKitError("channel_payload_invalid", "Telegram payload must be valid JSON.", { cause: error });
+  }
+
+  throw new AgentKitError("channel_payload_invalid", "Telegram payload must be a JSON object.");
+}
+
+function readRecord(value: Record<string, unknown>, key: string): Record<string, unknown> {
+  const record = value[key];
+  return isRecord(record) ? record : {};
+}
+
+function readString(value: Record<string, unknown>, key: string): string | undefined {
+  const field = value[key];
+  return typeof field === "string" && field.length > 0 ? field : undefined;
+}
+
+function readNumber(value: Record<string, unknown>, key: string): number | undefined {
+  const field = value[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+
+function readNumberishString(value: Record<string, unknown>, key: string): string | undefined {
+  const field = value[key];
+
+  if (typeof field === "string" && field.length > 0) {
+    return field;
+  }
+
+  if (typeof field === "number" && Number.isFinite(field)) {
+    return String(field);
+  }
+
+  return undefined;
+}
+
+function redactId(value: string): string {
+  if (value.length <= 2) {
+    return "*".repeat(value.length);
+  }
+
+  return `${value.slice(0, 1)}***${value.slice(-1)}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/channels/website.ts

@@ -0,0 +1,132 @@
+import type { ChannelAdapter, ChannelSendInput, NormalizedChannelEvent, RawWebhookEvent } from "../channels";
+import { AgentKitError } from "../errors";
+
+export const websiteChannelAdapter: ChannelAdapter = {
+  type: "website",
+  provider: "agentkit",
+  requiredSecrets: ["AGENTKIT_WEBSITE_CHANNEL_TOKEN"],
+  verifyWebhook(input) {
+    const expected = input.secrets.AGENTKIT_WEBSITE_CHANNEL_TOKEN;
+
+    if (!expected) {
+      return {
+        ok: false,
+        code: "channel_secret_missing",
+        message: "Secret AGENTKIT_WEBSITE_CHANNEL_TOKEN is not set for this channel.",
+      };
+    }
+
+    const bearer = input.headers.get("authorization");
+    const headerToken = input.headers.get("x-agentkit-channel-token");
+
+    if (bearer !== `Bearer ${expected}` && headerToken !== expected) {
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Website channel token did not match.",
+      };
+    }
+
+    return { ok: true };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const message = readRecord(body, "message");
+    const text = readString(message, "text");
+    const eventId = readString(body, "event_id") ?? readString(message, "id");
+    const clientId = readString(body, "client_id");
+    const visitorId = readString(body, "visitor_id") ?? clientId;
+
+    if (!eventId) {
+      throw new AgentKitError("channel_payload_invalid", "Website channel payload is missing event_id.");
+    }
+
+    if (!visitorId) {
+      throw new AgentKitError("channel_payload_invalid", "Website channel payload is missing visitor_id or client_id.");
+    }
+
+    const base = {
+      type: "website" as const,
+      provider: "agentkit" as const,
+      providerEventId: eventId,
+      dedupeKey: `website:${input.channelId}:${eventId}`,
+      externalIdentity: {
+        key: `website:visitor:${visitorId}`,
+        redactedDisplay: `website:visitor:${visitorId}`,
+      },
+      receivedAt: input.receivedAt,
+    };
+
+    if (!text) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: "unsupported_message_type:non_text",
+        },
+      ];
+    }
+
+    return [
+      {
+        ...base,
+        kind: "message",
+        message: {
+          role: "user",
+          contentType: "text",
+          content: text,
+          providerMessageId: readString(message, "id"),
+        },
+      },
+    ];
+  },
+  async sendMessage(input) {
+    return {
+      ok: true,
+      status: "sent",
+      providerMessageId: buildWebsiteProviderMessageId(input),
+    };
+  },
+  getStatus() {
+    return {
+      status: "connected",
+      checkedAt: new Date().toISOString(),
+    };
+  },
+};
+
+function buildWebsiteProviderMessageId(input: ChannelSendInput): string {
+  return `website:${input.channelId}:${input.conversationId}`;
+}
+
+function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(input.rawBody) as unknown;
+
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    throw new AgentKitError("channel_payload_invalid", "Website channel payload must be valid JSON.", {
+      cause: error,
+    });
+  }
+
+  throw new AgentKitError("channel_payload_invalid", "Website channel payload must be a JSON object.");
+}
+
+function readRecord(value: Record<string, unknown>, key: string): Record<string, unknown> {
+  const record = value[key];
+  return isRecord(record) ? record : {};
+}
+
+function readString(value: Record<string, unknown>, key: string): string | undefined {
+  const field = value[key];
+  return typeof field === "string" && field.length > 0 ? field : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export type { NormalizedChannelEvent };

package/src/runtime/channels/whatsapp-meta.ts

@@ -0,0 +1,71 @@
+import type { ChannelAdapter, WebhookVerificationResult } from "../channels";
+
+export const metaWhatsappChannelAdapter: ChannelAdapter = {
+  type: "whatsapp",
+  provider: "meta",
+  requiredSecrets: ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"],
+  verifyWebhook(input): WebhookVerificationResult {
+    if (input.method === "GET") {
+      const url = new URL(input.url);
+      const mode = url.searchParams.get("hub.mode");
+      const verifyToken = url.searchParams.get("hub.verify_token");
+      const expected = input.secrets.META_WHATSAPP_VERIFY_TOKEN;
+
+      if (!expected) {
+        return {
+          ok: false,
+          code: "channel_secret_missing",
+          message: "Secret META_WHATSAPP_VERIFY_TOKEN is not set for this channel.",
+        };
+      }
+
+      if (mode === "subscribe" && verifyToken === expected) {
+        return { ok: true };
+      }
+
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Meta webhook verification token did not match.",
+      };
+    }
+
+    return {
+      ok: false,
+      code: "channel_payload_invalid",
+      message: "Meta Cloud API POST signature verification is planned but not implemented yet.",
+    };
+  },
+  normalizeInbound(input) {
+    return [
+      {
+        type: "whatsapp",
+        provider: "meta",
+        kind: "unsupported",
+        providerEventId: `meta:${input.channelId}:planned`,
+        dedupeKey: `whatsapp:meta:${input.channelId}:planned`,
+        externalIdentity: {
+          key: "whatsapp:meta:planned",
+          redactedDisplay: "whatsapp:meta:planned",
+        },
+        receivedAt: input.receivedAt,
+        unsupportedReason: "adapter_planned:meta_cloud_api",
+      },
+    ];
+  },
+  async sendMessage() {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Meta Cloud API sendMessage is planned but not implemented yet.",
+    };
+  },
+  getStatus() {
+    return {
+      status: "needs_setup",
+      checkedAt: new Date().toISOString(),
+      message: "Meta Cloud API adapter is planned for a later Channels milestone.",
+    };
+  },
+};