feat: Telegram provider (direct Bot API)

.gitignore

@@ -35,3 +35,6 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+
+# test results
+test/

examples/basic/index.ts

@@ -1,13 +1,15 @@
 import { Spectrum } from "spectrum-ts";
 import { imessage } from "spectrum-ts/providers/imessage";
 
+// import { telegram } from "spectrum-ts/providers/telegram";
 // import { terminal } from "spectrum-ts/providers/terminal";
 
 const app = await Spectrum({
   projectId: "",
   projectSecret: "",
   providers: [
     imessage.config(),
+    // telegram.config({ token: "YOUR_BOT_TOKEN" }),
     // terminal.config({}),
   ],
 });

packages/spectrum-ts/package.json

@@ -38,10 +38,11 @@
   },
   "dependencies": {
     "@photon-ai/advanced-imessage": "^0.4.3",
-    "@photon-ai/whatsapp-business": "^0.1.1",
     "@photon-ai/imessage-kit": "^3.0.0-rc.2",
+    "@photon-ai/whatsapp-business": "^0.1.1",
     "@repeaterjs/repeater": "^3.0.6",
     "better-grpc": "^0.3.2",
+    "grammy": "^1.42.0",
     "mime-types": "^3.0.1",
     "type-fest": "^5.4.1",
     "zod": "^4.2.1"

packages/spectrum-ts/src/platform/define.ts

@@ -123,6 +123,69 @@ function createPlatformInstance<
         stopTyping: async () => {
           await def.actions.stopTyping?.(typingCtx);
         },
+        editMessage: async (
+          messageId: string,
+          ...content: [ContentInput, ...ContentInput[]]
+        ) => {
+          if (!def.actions.editMessage) {
+            return;
+          }
+          const built = await resolveContents(content);
+          for (const item of built) {
+            await def.actions.editMessage({
+              ...typingCtx,
+              messageId,
+              content: item,
+            });
+          }
+        },
+        deleteMessage: async (messageId: string) => {
+          if (!def.actions.deleteMessage) {
+            return;
+          }
+          await def.actions.deleteMessage({
+            ...typingCtx,
+            messageId,
+          });
+        },
+        forwardMessage: async (messageId: string, toSpaceId: string) => {
+          if (!def.actions.forwardMessage) {
+            return;
+          }
+          await def.actions.forwardMessage({
+            ...typingCtx,
+            messageId,
+            toSpaceId,
+          });
+        },
+        copyMessage: async (messageId: string, toSpaceId: string) => {
+          if (!def.actions.copyMessage) {
+            return;
+          }
+          await def.actions.copyMessage({
+            ...typingCtx,
+            messageId,
+            toSpaceId,
+          });
+        },
+        pinMessage: async (messageId: string) => {
+          if (!def.actions.pinMessage) {
+            return;
+          }
+          await def.actions.pinMessage({
+            ...typingCtx,
+            messageId,
+          });
+        },
+        unpinMessage: async (messageId: string) => {
+          if (!def.actions.unpinMessage) {
+            return;
+          }
+          await def.actions.unpinMessage({
+            ...typingCtx,
+            messageId,
+          });
+        },
         responding: async <T>(fn: () => T | Promise<T>): Promise<T> => {
           await def.actions.startTyping?.(typingCtx);
           try {

packages/spectrum-ts/src/platform/types.ts

@@ -131,6 +131,45 @@ export interface PlatformDef<
       client: _Client;
       config: z.infer<_ConfigSchema>;
     }) => Promise<void>;
+    editMessage?: (_: {
+      space: _ResolvedSpace & SpaceRef;
+      messageId: string;
+      content: Content;
+      client: _Client;
+      config: z.infer<_ConfigSchema>;
+    }) => Promise<void>;
+    deleteMessage?: (_: {
+      space: _ResolvedSpace & SpaceRef;
+      messageId: string;
+      client: _Client;
+      config: z.infer<_ConfigSchema>;
+    }) => Promise<void>;
+    forwardMessage?: (_: {
+      space: _ResolvedSpace & SpaceRef;
+      messageId: string;
+      toSpaceId: string;
+      client: _Client;
+      config: z.infer<_ConfigSchema>;
+    }) => Promise<void>;
+    copyMessage?: (_: {
+      space: _ResolvedSpace & SpaceRef;
+      messageId: string;
+      toSpaceId: string;
+      client: _Client;
+      config: z.infer<_ConfigSchema>;
+    }) => Promise<void>;
+    pinMessage?: (_: {
+      space: _ResolvedSpace & SpaceRef;
+      messageId: string;
+      client: _Client;
+      config: z.infer<_ConfigSchema>;
+    }) => Promise<void>;
+    unpinMessage?: (_: {
+      space: _ResolvedSpace & SpaceRef;
+      messageId: string;
+      client: _Client;
+      config: z.infer<_ConfigSchema>;
+    }) => Promise<void>;
   };
 
   config: _ConfigSchema;
@@ -192,6 +231,18 @@ export interface AnyPlatformDef {
     reactToMessage?: (_: any) => Promise<void>;
     // biome-ignore lint/suspicious/noExplicitAny: wildcard action
     replyToMessage?: (_: any) => Promise<void>;
+    // biome-ignore lint/suspicious/noExplicitAny: wildcard action
+    editMessage?: (_: any) => Promise<void>;
+    // biome-ignore lint/suspicious/noExplicitAny: wildcard action
+    deleteMessage?: (_: any) => Promise<void>;
+    // biome-ignore lint/suspicious/noExplicitAny: wildcard action
+    forwardMessage?: (_: any) => Promise<void>;
+    // biome-ignore lint/suspicious/noExplicitAny: wildcard action
+    copyMessage?: (_: any) => Promise<void>;
+    // biome-ignore lint/suspicious/noExplicitAny: wildcard action
+    pinMessage?: (_: any) => Promise<void>;
+    // biome-ignore lint/suspicious/noExplicitAny: wildcard action
+    unpinMessage?: (_: any) => Promise<void>;
   };
   config: z.ZodType<object>;
   events: {

packages/spectrum-ts/src/providers/telegram/errors.ts

@@ -0,0 +1,122 @@
+import { GrammyError, HttpError } from "grammy";
+
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+export interface TelegramLogger {
+  debug(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+}
+
+export const createLogger = (level: LogLevel = "error"): TelegramLogger => {
+  const threshold = LOG_LEVELS[level];
+  const noop = () => {};
+
+  return {
+    debug:
+      threshold >= LOG_LEVELS.debug
+        ? (msg, ...args) => console.debug(`[Telegram] ${msg}`, ...args)
+        : noop,
+    info:
+      threshold >= LOG_LEVELS.info
+        ? (msg, ...args) => console.info(`[Telegram] ${msg}`, ...args)
+        : noop,
+    warn:
+      threshold >= LOG_LEVELS.warn
+        ? (msg, ...args) => console.warn(`[Telegram] ${msg}`, ...args)
+        : noop,
+    error:
+      threshold >= LOG_LEVELS.error
+        ? (msg, ...args) => console.error(`[Telegram] ${msg}`, ...args)
+        : noop,
+  };
+};
+
+export class TelegramError extends Error {
+  readonly errorCode: number;
+  readonly description: string;
+  readonly retryAfter?: number;
+
+  constructor(errorCode: number, description: string, retryAfter?: number) {
+    super(`Telegram API error ${errorCode}: ${description}`);
+    this.name = "TelegramError";
+    this.errorCode = errorCode;
+    this.description = description;
+    this.retryAfter = retryAfter;
+  }
+
+  static fromGrammyError(err: GrammyError): TelegramError {
+    const retryAfter =
+      err.error_code === 429
+        ? (err.parameters?.retry_after ?? undefined)
+        : undefined;
+    return new TelegramError(err.error_code, err.description, retryAfter);
+  }
+
+  static fromUnknown(err: unknown): TelegramError | Error {
+    if (err instanceof TelegramError) {
+      return err;
+    }
+    if (err instanceof GrammyError) {
+      return TelegramError.fromGrammyError(err);
+    }
+    if (err instanceof HttpError) {
+      return new TelegramError(0, `Network error: ${err.message}`);
+    }
+    if (err instanceof Error) {
+      return err;
+    }
+    return new Error(String(err));
+  }
+}
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+export const withRetry = async <T>(
+  fn: () => Promise<T>,
+  logger: TelegramLogger,
+  maxRetries = 3
+): Promise<T> => {
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      const wrapped = TelegramError.fromUnknown(err);
+
+      if (wrapped instanceof TelegramError && wrapped.retryAfter) {
+        const waitMs = wrapped.retryAfter * 1000;
+        logger.warn(
+          `Rate limited, retrying in ${wrapped.retryAfter}s (attempt ${attempt + 1}/${maxRetries + 1})`
+        );
+        await sleep(waitMs);
+        continue;
+      }
+
+      if (wrapped instanceof TelegramError && wrapped.errorCode >= 500) {
+        const backoff = Math.min(1000 * 2 ** attempt, 30_000);
+        logger.warn(
+          `Server error ${wrapped.errorCode}, retrying in ${backoff}ms (attempt ${attempt + 1}/${maxRetries + 1})`
+        );
+        await sleep(backoff);
+        continue;
+      }
+
+      throw wrapped;
+    }
+  }
+
+  throw TelegramError.fromUnknown(lastError);
+};