@vellumai/vellum-gateway 0.1.7

package/src/telegram/api.ts

@@ -0,0 +1,153 @@
+import type { GatewayConfig } from "../config.js";
+import { getLogger } from "../logger.js";
+
+const log = getLogger("telegram-api");
+
+interface TelegramApiResponse<T> {
+  ok: boolean;
+  result?: T;
+  description?: string;
+  parameters?: { retry_after?: number };
+}
+
+function isRetryable(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+function computeDelay(
+  attempt: number,
+  initialBackoffMs: number,
+  retryAfterHeader: string | null,
+): number {
+  if (retryAfterHeader) {
+    // Try parsing as numeric seconds first (e.g., "120")
+    const seconds = Number(retryAfterHeader);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      // Clamp to max 32-bit signed int to prevent setTimeout overflow
+      return Math.min(seconds * 1000, 2_147_483_647);
+    }
+
+    // Fall back to HTTP-date format (e.g., "Fri, 31 Dec 1999 23:59:59 GMT")
+    const targetTime = new Date(retryAfterHeader).getTime();
+    if (Number.isFinite(targetTime)) {
+      const delayMs = targetTime - Date.now();
+      if (delayMs > 0) {
+        // Clamp to max 32-bit signed int to prevent setTimeout overflow
+        return Math.min(delayMs, 2_147_483_647);
+      }
+    }
+  }
+
+  const exponential = initialBackoffMs * Math.pow(2, attempt - 1);
+  // Add jitter: 0–50% of the computed delay
+  const jitter = Math.random() * exponential * 0.5;
+  return exponential + jitter;
+}
+
+async function retryableFetch<T>(
+  config: GatewayConfig,
+  method: string,
+  doFetch: () => Promise<Response>,
+): Promise<T> {
+  let lastError: Error | null = null;
+  let lastRetryAfter: string | null = null;
+
+  for (let attempt = 0; attempt <= config.telegramMaxRetries; attempt++) {
+    if (attempt > 0) {
+      const delay = computeDelay(
+        attempt,
+        config.telegramInitialBackoffMs,
+        lastRetryAfter,
+      );
+      log.debug({ attempt, delay, method }, "Retrying Telegram API call");
+      await new Promise((r) => setTimeout(r, delay));
+    }
+
+    lastRetryAfter = null;
+
+    let response: Response;
+    try {
+      response = await doFetch();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      log.warn({ err: lastError, attempt, method }, "Telegram API fetch failed");
+      continue;
+    }
+
+    if (!isRetryable(response.status) && !response.ok) {
+      const data = (await response.json().catch(() => ({}))) as TelegramApiResponse<T>;
+      throw new Error(
+        data.description
+          ? `Telegram ${method} failed: ${data.description}`
+          : `Telegram ${method} failed with status ${response.status}`,
+      );
+    }
+
+    if (isRetryable(response.status)) {
+      const data = (await response.json().catch(() => ({}))) as TelegramApiResponse<T>;
+      lastRetryAfter =
+        response.headers.get("retry-after") ??
+        (data.parameters?.retry_after != null
+          ? String(data.parameters.retry_after)
+          : null);
+      lastError = new Error(
+        data.description
+          ? `Telegram ${method} failed: ${data.description}`
+          : `Telegram ${method} failed with status ${response.status}`,
+      );
+      log.warn(
+        { status: response.status, attempt, method, retryAfter: lastRetryAfter },
+        "Telegram API returned retryable error",
+      );
+      continue;
+    }
+
+    const data = (await response.json().catch(() => ({}))) as TelegramApiResponse<T>;
+    if (!data.ok || data.result === undefined) {
+      throw new Error(
+        data.description
+          ? `Telegram ${method} failed: ${data.description}`
+          : `Telegram ${method} failed with status ${response.status}`,
+      );
+    }
+
+    return data.result;
+  }
+
+  throw lastError ?? new Error(`Telegram ${method} failed after retries`);
+}
+
+export async function callTelegramApi<T>(
+  config: GatewayConfig,
+  method: string,
+  body: Record<string, unknown>,
+): Promise<T> {
+  return retryableFetch<T>(config, method, () =>
+    fetch(
+      `${config.telegramApiBaseUrl}/bot${config.telegramBotToken}/${method}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(config.telegramTimeoutMs),
+      },
+    ),
+  );
+}
+
+export async function callTelegramApiMultipart<T>(
+  config: GatewayConfig,
+  method: string,
+  form: FormData,
+): Promise<T> {
+  return retryableFetch<T>(config, method, () =>
+    fetch(
+      `${config.telegramApiBaseUrl}/bot${config.telegramBotToken}/${method}`,
+      {
+        method: "POST",
+        body: form,
+        signal: AbortSignal.timeout(config.telegramTimeoutMs),
+      },
+    ),
+  );
+}

package/src/telegram/download.ts

@@ -0,0 +1,63 @@
+import { fileTypeFromBuffer } from "file-type";
+import type { GatewayConfig } from "../config.js";
+import { callTelegramApi } from "./api.js";
+
+interface TelegramFile {
+  file_id: string;
+  file_unique_id: string;
+  file_size?: number;
+  file_path?: string;
+}
+
+export interface DownloadedFile {
+  filename: string;
+  mimeType: string;
+  data: string; // base64-encoded
+}
+
+/**
+ * Download a file from Telegram by its file_id.
+ * Calls the getFile API to resolve the file path, then fetches the binary.
+ */
+export async function downloadTelegramFile(
+  config: GatewayConfig,
+  fileId: string,
+  hint?: { fileName?: string; mimeType?: string },
+): Promise<DownloadedFile> {
+  const file = await callTelegramApi<TelegramFile>(config, "getFile", {
+    file_id: fileId,
+  });
+
+  if (!file.file_path) {
+    throw new Error(`Telegram getFile returned no file_path for ${fileId}`);
+  }
+
+  const downloadUrl = `${config.telegramApiBaseUrl}/file/bot${config.telegramBotToken}/${file.file_path}`;
+  const response = await fetch(downloadUrl, {
+    signal: AbortSignal.timeout(config.telegramTimeoutMs),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download Telegram file: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const filename =
+    hint?.fileName ||
+    file.file_path.split("/").pop() ||
+    `file_${fileId}`;
+
+  const buffer = await response.arrayBuffer();
+  const detected = await fileTypeFromBuffer(new Uint8Array(buffer));
+
+  const mimeType =
+    hint?.mimeType ||
+    detected?.mime ||
+    response.headers.get("Content-Type")?.split(";")[0].trim() ||
+    "application/octet-stream";
+
+  const data = Buffer.from(buffer).toString("base64");
+
+  return { filename, mimeType, data };
+}

package/src/telegram/normalize.ts

@@ -0,0 +1,118 @@
+import type { GatewayInboundEventV1 } from "../types.js";
+
+interface TelegramPhotoSize {
+  file_id: string;
+  file_unique_id: string;
+  width: number;
+  height: number;
+  file_size?: number;
+}
+
+interface TelegramDocument {
+  file_id: string;
+  file_unique_id: string;
+  file_name?: string;
+  mime_type?: string;
+  file_size?: number;
+}
+
+interface TelegramMessage {
+  message_id?: number;
+  text?: string;
+  caption?: string;
+  chat?: { id?: number; type?: string };
+  from?: {
+    id?: number;
+    is_bot?: boolean;
+    username?: string;
+    first_name?: string;
+    last_name?: string;
+    language_code?: string;
+  };
+  photo?: TelegramPhotoSize[];
+  document?: TelegramDocument;
+}
+
+interface TelegramUpdate {
+  update_id?: number;
+  message?: TelegramMessage;
+  edited_message?: TelegramMessage;
+}
+
+/**
+ * Normalize a Telegram webhook payload into a GatewayInboundEventV1.
+ * Returns null if the payload is unsupported (non-text, non-private, etc.).
+ */
+export function normalizeTelegramUpdate(
+  payload: Record<string, unknown>,
+): Omit<GatewayInboundEventV1, "routing"> | null {
+  const update = payload as TelegramUpdate;
+  const isEdit = !update.message && !!update.edited_message;
+  const message = update.message ?? update.edited_message;
+  const updateId = update.update_id;
+
+  const hasContent = !!(message?.text || message?.photo || message?.document);
+  if (!hasContent || !message?.chat?.id || updateId == null) {
+    return null;
+  }
+
+  // v1 is DM-only
+  if (message.chat.type !== "private") {
+    return null;
+  }
+
+  const externalUserId = message.from?.id
+    ? String(message.from.id)
+    : String(message.chat.id);
+
+  const displayName = [message.from?.first_name, message.from?.last_name]
+    .filter(Boolean)
+    .join(" ")
+    .trim();
+
+  const content = message.text || message.caption || "";
+
+  const attachments: { type: "photo" | "document"; fileId: string; fileName?: string; mimeType?: string; fileSize?: number }[] = [];
+  if (message.photo && message.photo.length > 0) {
+    // Telegram sends multiple sizes; pick the largest (last in array)
+    const largest = message.photo[message.photo.length - 1];
+    attachments.push({ type: "photo", fileId: largest.file_id, fileSize: largest.file_size });
+  }
+  if (message.document) {
+    attachments.push({
+      type: "document",
+      fileId: message.document.file_id,
+      fileName: message.document.file_name,
+      mimeType: message.document.mime_type,
+      fileSize: message.document.file_size,
+    });
+  }
+
+  return {
+    version: "v1",
+    sourceChannel: "telegram",
+    receivedAt: new Date().toISOString(),
+    message: {
+      content,
+      externalChatId: String(message.chat.id),
+      externalMessageId: String(updateId),
+      ...(attachments.length > 0 ? { attachments } : {}),
+      ...(isEdit ? { isEdit: true } : {}),
+    },
+    sender: {
+      externalUserId,
+      username: message.from?.username,
+      displayName: displayName || undefined,
+      firstName: message.from?.first_name,
+      lastName: message.from?.last_name,
+      languageCode: message.from?.language_code,
+      isBot: message.from?.is_bot,
+    },
+    source: {
+      updateId: String(updateId),
+      messageId: message.message_id != null ? String(message.message_id) : undefined,
+      chatType: message.chat.type,
+    },
+    raw: payload,
+  };
+}

package/src/telegram/send.ts

@@ -0,0 +1,107 @@
+import type { GatewayConfig } from "../config.js";
+import { getLogger } from "../logger.js";
+import { downloadAttachment, type RuntimeAttachmentMeta } from "../runtime/client.js";
+import { callTelegramApi, callTelegramApiMultipart } from "./api.js";
+
+const log = getLogger("telegram-send");
+
+const TELEGRAM_MAX_MESSAGE_LEN = 4000;
+
+const IMAGE_MIME_PREFIXES = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+
+function splitText(text: string): string[] {
+  if (text.length <= TELEGRAM_MAX_MESSAGE_LEN) {
+    return [text];
+  }
+
+  const chunks: string[] = [];
+  let cursor = 0;
+  while (cursor < text.length) {
+    let end = Math.min(cursor + TELEGRAM_MAX_MESSAGE_LEN, text.length);
+    // Avoid splitting a surrogate pair
+    if (end < text.length && text.charCodeAt(end - 1) >= 0xd800 && text.charCodeAt(end - 1) <= 0xdbff) {
+      end--;
+    }
+    chunks.push(text.slice(cursor, end));
+    cursor = end;
+  }
+  return chunks;
+}
+
+export async function sendTelegramReply(
+  config: GatewayConfig,
+  chatId: string,
+  text: string,
+): Promise<void> {
+  const chunks = splitText(text);
+
+  for (const chunk of chunks) {
+    await callTelegramApi(config, "sendMessage", {
+      chat_id: chatId,
+      text: chunk,
+    });
+  }
+
+  log.debug({ chatId, chunks: chunks.length }, "Telegram reply sent");
+}
+
+export async function sendTelegramAttachments(
+  config: GatewayConfig,
+  chatId: string,
+  assistantId: string,
+  attachments: RuntimeAttachmentMeta[],
+): Promise<void> {
+  const failures: string[] = [];
+
+  for (const meta of attachments) {
+    if (meta.sizeBytes > config.maxAttachmentBytes) {
+      log.warn({ attachmentId: meta.id, sizeBytes: meta.sizeBytes }, "Skipping oversized outbound attachment");
+      failures.push(meta.filename);
+      continue;
+    }
+
+    try {
+      const payload = await downloadAttachment(config, assistantId, meta.id);
+      const buffer = Buffer.from(payload.data, "base64");
+      const blob = new Blob([buffer], { type: meta.mimeType });
+
+      const form = new FormData();
+      form.set("chat_id", chatId);
+
+      const isImage = IMAGE_MIME_PREFIXES.some((p) => meta.mimeType.startsWith(p));
+      if (isImage) {
+        form.set("photo", blob, meta.filename);
+        await callTelegramApiMultipart(config, "sendPhoto", form);
+      } else {
+        form.set("document", blob, meta.filename);
+        await callTelegramApiMultipart(config, "sendDocument", form);
+      }
+
+      log.debug({ chatId, attachmentId: meta.id, filename: meta.filename }, "Attachment sent to Telegram");
+    } catch (err) {
+      log.error({ err, attachmentId: meta.id, filename: meta.filename }, "Failed to send attachment to Telegram");
+      failures.push(meta.filename);
+    }
+  }
+
+  if (failures.length > 0) {
+    const notice = `⚠️ ${failures.length} attachment(s) could not be delivered: ${failures.join(", ")}`;
+    try {
+      await sendTelegramReply(config, chatId, notice);
+    } catch (err) {
+      log.error({ err, chatId }, "Failed to send attachment failure notice");
+    }
+  }
+}
+
+export async function sendTypingIndicator(config: GatewayConfig, chatId: string): Promise<boolean> {
+  try {
+    await callTelegramApi(config, "sendChatAction", { chat_id: chatId, action: "typing" });
+    return true;
+  } catch (err) {
+    log.debug({ err, chatId }, "Failed to send typing indicator");
+    return false;
+  }
+}
+
+export { splitText };

package/src/telegram/verify.ts

@@ -0,0 +1,17 @@
+import { timingSafeEqual } from "crypto";
+
+export function verifyWebhookSecret(
+  headers: Headers,
+  expectedSecret: string,
+): boolean {
+  const provided = headers.get("x-telegram-bot-api-secret-token");
+  if (!provided || !expectedSecret) {
+    return false;
+  }
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expectedSecret);
+  if (a.length !== b.length) {
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}

package/src/types.ts

@@ -0,0 +1,37 @@
+export type GatewayInboundEventV1 = {
+  version: "v1";
+  sourceChannel: "telegram";
+  receivedAt: string;
+  routing: {
+    assistantId: string;
+    routeSource: "chat_id" | "user_id" | "default";
+  };
+  message: {
+    content: string;
+    externalChatId: string;
+    externalMessageId: string;
+    isEdit?: boolean;
+    attachments?: {
+      type: "photo" | "document";
+      fileId: string;
+      fileName?: string;
+      mimeType?: string;
+      fileSize?: number;
+    }[];
+  };
+  sender: {
+    externalUserId: string;
+    username?: string;
+    displayName?: string;
+    firstName?: string;
+    lastName?: string;
+    languageCode?: string;
+    isBot?: boolean;
+  };
+  source: {
+    updateId: string;
+    messageId?: string;
+    chatType?: string;
+  };
+  raw: Record<string, unknown>;
+};

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}