Skip to content

The open-source app everyone uses to manage agents at work

5.1 KB
Raw Blame
import { createTelegramMaintenance } from "./maintenance.js";
import type { EndpointRow, RuntimeContext } from "../runtime-types.js";

import { type CredentialMutationLeaseGuard } from "../../chat-credential-mutation-lease.js";

import type { Db } from "@paperclipai/db";

import type {
  ConfigureChatEndpointInput,
} from "@paperclipai/shared";

import {
  unprocessable,
} from "../../../errors.js";

import type { EndpointRecord } from "../runtime-types.js";

type TelegramSetupOptions = {
  fetchImpl: typeof globalThis.fetch;
  getWebhookPublicBaseUrl: () => string | null;
  PROVIDER_CREDENTIAL_CHECK_TIMEOUT_MS: number;
  runtimeContextForRecord: (record: EndpointRecord) => RuntimeContext;
  recordTelegramStopSubscription: ReturnType<typeof createTelegramMaintenance>["recordTelegramStopSubscription"];
  stageTelegramMaintenance: ReturnType<typeof createTelegramMaintenance>["stageTelegramMaintenance"];
  processTelegramMaintenance: ReturnType<typeof createTelegramMaintenance>["processTelegramMaintenance"];
};
export function createTelegramSetup(db: Db, options: TelegramSetupOptions) {
  const { fetchImpl, getWebhookPublicBaseUrl, PROVIDER_CREDENTIAL_CHECK_TIMEOUT_MS, runtimeContextForRecord, recordTelegramStopSubscription, stageTelegramMaintenance, processTelegramMaintenance } = options;

  async function registerTelegramWebhook(endpoint: EndpointRow, input: ConfigureChatEndpointInput, credentials: Record<string, string>, credentialLease: CredentialMutationLeaseGuard, next: EndpointRecord) {
        const webhookUrl = `${getWebhookPublicBaseUrl()}/api/chat-webhooks/${endpoint.publicId}/telegram`;
        const infoResponse = await fetchImpl(
          `https://api.telegram.org/bot${encodeURIComponent(credentials.botToken)}/getWebhookInfo`,
          { signal: AbortSignal.timeout(PROVIDER_CREDENTIAL_CHECK_TIMEOUT_MS) },
        );
        const infoResult = (await infoResponse.json()) as {
          ok?: boolean;
          description?: string;
          result?: { url?: string };
        };
        if (!infoResponse.ok || !infoResult.ok) {
          throw unprocessable(
            `Telegram could not inspect the existing webhook: ${infoResult.description ?? infoResponse.status}`,
          );
        }
        await credentialLease.assertOwned();
        const response = await fetchImpl(
          `https://api.telegram.org/bot${encodeURIComponent(credentials.botToken)}/setWebhook`,
          {
            method: "POST",
            signal: AbortSignal.timeout(PROVIDER_CREDENTIAL_CHECK_TIMEOUT_MS),
            headers: { "content-type": "application/json" },
            body: JSON.stringify({
              url: webhookUrl,
              secret_token: credentials.webhookSecret,
              allowed_updates: [
                "message",
                "edited_message",
                "callback_query",
                "stopped_message_generation",
                "message_reaction",
                "my_chat_member",
              ],
              // A first-time connection may inherit stale updates from a bot
              // that was used before Paperclip owned it. Reconnect is
              // different: Telegram may be holding legitimate updates while
              // the old callback URL is unavailable. Preserve that backlog
              // even when an operator is rotating the public origin.
              drop_pending_updates: input.action === "configure",
            }),
          },
        );
        const result = (await response.json()) as {
          ok?: boolean;
          description?: string;
          result?: unknown;
        };
        if (!response.ok || !result.ok)
          throw unprocessable(
            `Telegram could not register the webhook: ${result.description ?? response.status}`,
          );
        await credentialLease.assertOwned();
        if (result.ok === true && result.result === true) {
          // Telegram's successful boolean receipt acknowledges the exact URL,
          // secret and allowed_updates request above. GET alone cannot prove
          // secret_token, which Telegram deliberately does not return.
          await recordTelegramStopSubscription(
            next.endpoint,
            runtimeContextForRecord(next),
            credentialLease,
          );
        }
        // Command discovery is optional for ingress, but its provider mutation
        // is still a durable, auditable action. A transient or rate-limited
        // failure is retried by the maintenance worker without blocking the
        // otherwise-valid webhook connection.
        const commandAction = await stageTelegramMaintenance(
          endpoint,
          "register_commands",
        );
        if (commandAction)
          await processTelegramMaintenance(
            commandAction.id,
            false,
            credentialLease,
          );
      }

  return { registerTelegramWebhook };
}

const TELEGRAM_WEBHOOK_PORTS = new Set(["", "80", "88", "443", "8443"]);

export function isSupportedTelegramWebhookBaseUrl(value: string | null): boolean {
  if (!value) return false;
  try {
    const url = new URL(value);
    return url.protocol === "https:" && TELEGRAM_WEBHOOK_PORTS.has(url.port);
  } catch {
    return false;
  }
}