@tormentalabs/opencode-telegram-plugin 0.2.0

package/src/utils/safeSend.ts

@@ -0,0 +1,99 @@
+import { GrammyError, HttpError } from "grammy";
+
+export type SendResult =
+  | { ok: true; messageId?: number }
+  | { ok: false; retry: boolean; reason: string; retryAfterMs?: number };
+
+/**
+ * Returns true when the error is a Telegram "message is not modified" error.
+ * This is treated as a successful no-op by `safeSend`.
+ */
+export function isNotModifiedError(err: unknown): boolean {
+  return (
+    err instanceof GrammyError &&
+    err.description.includes("message is not modified")
+  );
+}
+
+/**
+ * Returns true when Telegram rejected the request due to malformed entities.
+ */
+export function isParseError(err: unknown): boolean {
+  return (
+    err instanceof GrammyError &&
+    err.description.includes("can't parse entities")
+  );
+}
+
+/**
+ * Returns true when the bot has been blocked by the user (HTTP 403).
+ */
+export function isBotBlockedError(err: unknown): boolean {
+  return err instanceof GrammyError && err.error_code === 403;
+}
+
+/**
+ * Wrap any Telegram Bot API call with standardised error classification.
+ *
+ * | Condition                          | Result                                         |
+ * |------------------------------------|------------------------------------------------|
+ * | Success                            | `{ ok: true, messageId? }`                     |
+ * | "message is not modified"          | `{ ok: true }` — silent no-op                  |
+ * | HTTP 429 (rate limit)              | `{ ok: false, retry: true,  reason: "rate limited" }`  |
+ * | "can't parse entities"             | `{ ok: false, retry: true,  reason: "parse error" }`   |
+ * | HTTP 403 (bot blocked)             | `{ ok: false, retry: false, reason: "bot blocked" }`   |
+ * | "message to edit not found"        | `{ ok: false, retry: false, reason: "message deleted" }` |
+ * | Other GrammyError / HttpError      | `{ ok: false, retry: false, reason: <message> }` |
+ */
+export async function safeSend(
+  fn: () => Promise<unknown>,
+): Promise<SendResult> {
+  try {
+    const result = await fn();
+
+    // Extract message_id when the API returns a Message object.
+    let messageId: number | undefined;
+    if (result !== null && typeof result === "object") {
+      const obj = result as Record<string, unknown>;
+      if ("message_id" in obj && typeof obj.message_id === "number") {
+        messageId = obj.message_id;
+      }
+    }
+
+    return { ok: true, messageId };
+  } catch (err: unknown) {
+    // "message is not modified" is not a real error — content was already
+    // up to date. Treat as success.
+    if (isNotModifiedError(err)) {
+      return { ok: true };
+    }
+
+    if (err instanceof GrammyError) {
+      if (err.error_code === 429) {
+        const retryAfter = err.parameters.retry_after;
+        const retryAfterMs = typeof retryAfter === "number" ? retryAfter * 1000 : undefined;
+        return { ok: false, retry: true, reason: "rate limited", retryAfterMs };
+      }
+      if (isParseError(err)) {
+        return { ok: false, retry: true, reason: "parse error" };
+      }
+      if (isBotBlockedError(err)) {
+        return { ok: false, retry: false, reason: "bot blocked" };
+      }
+      if (err.description.includes("message to edit not found")) {
+        return { ok: false, retry: false, reason: "message deleted" };
+      }
+      return { ok: false, retry: false, reason: err.description };
+    }
+
+    if (err instanceof HttpError) {
+      return { ok: false, retry: true, reason: err.message };
+    }
+
+    if (err instanceof Error) {
+      return { ok: false, retry: false, reason: err.message };
+    }
+
+    return { ok: false, retry: false, reason: String(err) };
+  }
+}

package/src/utils/throttle.ts

@@ -0,0 +1,128 @@
+export interface ThrottleOptions {
+  /** Minimum milliseconds between executions. */
+  intervalMs: number;
+}
+
+/**
+ * A callable throttle handle with `flush` and `cancel` control methods.
+ *
+ * Calling it schedules `fn` for execution according to the throttle rules.
+ * `flush()` runs any pending call immediately and returns its promise.
+ * `cancel()` silently drops the pending call.
+ */
+export interface Throttle {
+  (fn: () => Promise<void>): Promise<void>;
+  flush(): Promise<void>;
+  cancel(): void;
+}
+
+/**
+ * Create a trailing-edge throttle:
+ *
+ * - The **first** call in an idle period executes immediately.
+ * - **Subsequent** calls within `intervalMs` replace the pending call;
+ *   only the **latest** one runs (trailing edge).
+ * - The replaced call's promise is resolved as a silent no-op.
+ * - `flush()` executes any pending call immediately.
+ * - `cancel()` drops the pending call (resolved silently).
+ */
+export function createThrottle(opts: ThrottleOptions): Throttle {
+  let lastExecutionTime = 0;
+  let pending: (() => Promise<void>) | null = null;
+  let pendingResolve: (() => void) | null = null;
+  let pendingReject: ((err: unknown) => void) | null = null;
+  let timerId: ReturnType<typeof setTimeout> | null = null;
+  let isRunning = false;
+
+  function clearTimer(): void {
+    if (timerId !== null) {
+      clearTimeout(timerId);
+      timerId = null;
+    }
+  }
+
+  /** Silently resolve and drop the pending call without executing it. */
+  function dropPending(): void {
+    pendingResolve?.();
+    pending = null;
+    pendingResolve = null;
+    pendingReject = null;
+  }
+
+  /**
+   * Execute the pending function immediately (if any), resolving or rejecting
+   * the promise that was returned to the original caller.
+   */
+  async function runPending(): Promise<void> {
+    // If a previous execution is still in progress, defer until it finishes.
+    if (isRunning) {
+      timerId = setTimeout(() => void runPending(), opts.intervalMs);
+      return;
+    }
+
+    const fn = pending;
+    const resolve = pendingResolve;
+    const reject = pendingReject;
+
+    pending = null;
+    pendingResolve = null;
+    pendingReject = null;
+    timerId = null;
+
+    if (fn === null) return;
+
+    isRunning = true;
+    try {
+      await fn();
+      resolve?.();
+    } catch (err: unknown) {
+      reject?.(err);
+    } finally {
+      isRunning = false;
+      lastExecutionTime = Date.now();
+    }
+  }
+
+  const throttleFn = (fn: () => Promise<void>): Promise<void> => {
+    const now = Date.now();
+    const elapsed = now - lastExecutionTime;
+
+    // First call ever, or the interval has already elapsed → run immediately.
+    if (!isRunning && (lastExecutionTime === 0 || elapsed >= opts.intervalMs)) {
+      lastExecutionTime = now;
+      isRunning = true;
+      return fn().finally(() => {
+        isRunning = false;
+        lastExecutionTime = Date.now();
+      });
+    }
+
+    // Drop any existing pending call (resolve it as a silent no-op) and
+    // schedule the new one to fire at the trailing edge of the interval.
+    clearTimer();
+    dropPending();
+
+    return new Promise<void>((resolve, reject) => {
+      pending = fn;
+      pendingResolve = resolve;
+      pendingReject = reject;
+
+      const delay = opts.intervalMs - elapsed;
+      timerId = setTimeout(() => {
+        void runPending();
+      }, delay);
+    });
+  };
+
+  throttleFn.flush = (): Promise<void> => {
+    clearTimer();
+    return runPending();
+  };
+
+  throttleFn.cancel = (): void => {
+    clearTimer();
+    dropPending();
+  };
+
+  return throttleFn as Throttle;
+}

package/src/utils/typing.ts

@@ -0,0 +1,30 @@
+import type { Api, RawApi } from "grammy";
+
+/**
+ * Send a "typing" chat action immediately, then repeat every 4 500 ms to keep
+ * the indicator alive while the bot is streaming a response.
+ *
+ * @param api    The grammY `Api` instance.
+ * @param chatId The target chat ID.
+ * @returns A stop function — call it to clear the interval.
+ *
+ * All errors are silently swallowed so a transient Telegram hiccup never
+ * interrupts the main response flow.
+ */
+export function startTyping(api: Api<RawApi>, chatId: number): () => void {
+  // Fire immediately so the indicator appears without delay.
+  void api.sendChatAction(chatId, "typing").catch(() => undefined);
+
+  const intervalId = setInterval(() => {
+    void api.sendChatAction(chatId, "typing").catch(() => undefined);
+  }, 4500);
+
+  // Ensure the timer doesn't prevent Node.js from exiting gracefully.
+  if (typeof intervalId === "object" && "unref" in intervalId) {
+    intervalId.unref();
+  }
+
+  return () => {
+    clearInterval(intervalId);
+  };
+}