zardbot-telegram 1.0.0

package/dist/tts/client.js

@@ -0,0 +1,130 @@
+import { config } from "../config.js";
+import { logger } from "../utils/logger.js";
+const TTS_REQUEST_TIMEOUT_MS = 2_400_000; // 40 minutes for long responses
+/**
+ * Returns true if TTS is configured (API URL is set).
+ */
+export function isTtsConfigured() {
+    return Boolean(config.tts?.apiUrl);
+}
+/**
+ * Fetches available voices from the TTS server.
+ *
+ * GETs from `{TTS_API_URL}/v1/audio/voices` (Pocket TTS API).
+ *
+ * @returns Array of available voices
+ */
+export async function getAvailableVoices() {
+    if (!isTtsConfigured()) {
+        logger.warn("[TTS] Cannot fetch voices: TTS API URL not configured");
+        return [];
+    }
+    try {
+        const voicesUrl = `${config.tts.apiUrl}/v1/audio/voices`;
+        const response = await fetch(voicesUrl, {
+            method: "GET",
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (response.ok) {
+            const rawData = await response.text();
+            logger.debug("[TTS] Raw voices response:", rawData.substring(0, 200));
+            const parsed = JSON.parse(rawData);
+            // Pocket TTS returns {voices: [{voice_id, name}, ...]} or an array
+            const voices = Array.isArray(parsed)
+                ? parsed
+                : parsed.voices ||
+                    parsed.data ||
+                    [];
+            logger.info(`[TTS] Parsed voices count: ${voices.length}`);
+            if (Array.isArray(voices) && voices.length > 0) {
+                return voices.map((v) => {
+                    const voice = v;
+                    const id = voice.voice_id || voice.id || voice.name || String(v);
+                    const name = voice.name ||
+                        id
+                            .split("-")
+                            .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+                            .join(" ");
+                    return {
+                        id,
+                        name,
+                        description: voice.name ? undefined : "Pocket TTS voice",
+                    };
+                });
+            }
+        }
+        else {
+            logger.warn(`[TTS] Voices endpoint returned HTTP ${response.status}`);
+        }
+    }
+    catch (err) {
+        logger.warn("[TTS] Failed to fetch voices from server", err);
+    }
+    // Fallback: return just the configured default voice
+    const defaultVoices = [
+        {
+            id: config.tts.voice || "david-attenborough-original",
+            name: config.tts.voice || "David Attenborough",
+            description: "Default voice",
+        },
+    ];
+    logger.debug(`[TTS] Using ${defaultVoices.length} default voice(s)`);
+    return defaultVoices;
+}
+/**
+ * Synthesizes speech from text using the TTS API.
+ *
+ * Sends a JSON POST to `{TTS_API_URL}/v1/audio/speech`.
+ *
+ * @param text - Text to synthesize
+ * @param voice - Voice ID to use (defaults to configured default voice)
+ * @returns Audio buffer and content type
+ */
+export async function synthesizeSpeech(text, voice) {
+    if (!isTtsConfigured()) {
+        throw new Error("TTS is not configured: TTS_API_URL is required");
+    }
+    const url = `${config.tts.apiUrl}/v1/audio/speech`;
+    let selectedVoice = voice || config.tts.voice || "david-attenborough-original";
+    if (!selectedVoice.match(/\.\w+$/)) {
+        selectedVoice += ".wav";
+    }
+    const body = {
+        model: config.tts.model || "tts-1",
+        input: text,
+        voice: selectedVoice,
+        response_format: "wav",
+        speed: config.tts.speed || 1.0,
+    };
+    logger.debug(`[TTS] Sending speech synthesis request: url=${url}, voice=${selectedVoice}, text=${text.length} chars`);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TTS_REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            throw new Error(`TTS API returned HTTP ${response.status}: ${errorBody || response.statusText}`);
+        }
+        const contentType = response.headers.get("content-type") || "audio/wav";
+        const arrayBuffer = await response.arrayBuffer();
+        const audioBuffer = Buffer.from(arrayBuffer);
+        logger.debug(`[TTS] Synthesized audio: ${audioBuffer.length} bytes, type=${contentType}`);
+        return { audio: audioBuffer, contentType };
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new Error(`TTS request timed out after ${TTS_REQUEST_TIMEOUT_MS}ms`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/utils/error-format.js

@@ -0,0 +1,29 @@
+const DEFAULT_MAX_ERROR_DETAILS_LENGTH = 1500;
+function clipText(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+export function formatErrorDetails(error, maxLength = DEFAULT_MAX_ERROR_DETAILS_LENGTH) {
+    let details = "";
+    if (error instanceof Error) {
+        details = error.stack ?? `${error.name}: ${error.message}`;
+    }
+    else if (typeof error === "string") {
+        details = error;
+    }
+    else {
+        try {
+            details = JSON.stringify(error, null, 2);
+        }
+        catch {
+            details = String(error);
+        }
+    }
+    const normalized = details.trim();
+    if (!normalized || normalized === "{}" || normalized === "[object Object]") {
+        return "unknown error";
+    }
+    return clipText(normalized, maxLength);
+}

package/dist/utils/logger.js

@@ -0,0 +1,127 @@
+import { config } from "../config.js";
+/**
+ * Mapping of log levels to numeric values for comparison
+ * Used to determine if a message should be logged based on configured level
+ */
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Normalizes a string value to a valid LogLevel
+ * Falls back to 'info' if the value is invalid
+ *
+ * @param value - The log level string to normalize
+ * @returns A valid LogLevel
+ */
+function normalizeLogLevel(value) {
+    if (value in LOG_LEVELS) {
+        return value;
+    }
+    return "info";
+}
+/**
+ * Formats the log message prefix with timestamp and level
+ *
+ * @param level - The log level for the message
+ * @returns Formatted prefix string
+ */
+function formatPrefix(level) {
+    return `[${new Date().toISOString()}] [${level.toUpperCase()}]`;
+}
+/**
+ * Formats individual arguments for logging
+ * Special handling for Error objects to extract stack trace
+ *
+ * @param arg - The argument to format
+ * @returns Formatted argument
+ */
+function formatArg(arg) {
+    if (arg instanceof Error) {
+        return arg.stack ?? `${arg.name}: ${arg.message}`;
+    }
+    return arg;
+}
+/**
+ * Prepends formatted prefix to log arguments
+ * Handles different argument formats (string vs non-string first argument)
+ *
+ * @param level - The log level for prefix formatting
+ * @param args - The arguments to log
+ * @returns Array with prefix prepended
+ */
+function withPrefix(level, args) {
+    const formattedArgs = args.map((arg) => formatArg(arg));
+    const prefix = formatPrefix(level);
+    if (formattedArgs.length === 0) {
+        return [prefix];
+    }
+    if (typeof formattedArgs[0] === "string") {
+        return [`${prefix} ${formattedArgs[0]}`, ...formattedArgs.slice(1)];
+    }
+    return [prefix, ...formattedArgs];
+}
+/**
+ * Determines if a message should be logged based on configured log level
+ * Messages with level >= configured level will be logged
+ *
+ * @param level - The level of the message to check
+ * @returns True if the message should be logged
+ */
+function shouldLog(level) {
+    const configLevel = normalizeLogLevel(config.server.logLevel);
+    return LOG_LEVELS[level] >= LOG_LEVELS[configLevel];
+}
+/**
+ * Logger interface with methods for different log levels
+ * Each method checks if the message should be logged based on configured level
+ * and formats the output with timestamp and level prefix
+ */
+export const logger = {
+    /**
+     * Logs debug-level messages (most verbose)
+     * Used for detailed diagnostics and internal operations
+     *
+     * @param args - Arguments to log
+     */
+    debug: (...args) => {
+        if (shouldLog("debug")) {
+            console.log(...withPrefix("debug", args));
+        }
+    },
+    /**
+     * Logs info-level messages
+     * Used for important events and general information
+     *
+     * @param args - Arguments to log
+     */
+    info: (...args) => {
+        if (shouldLog("info")) {
+            console.log(...withPrefix("info", args));
+        }
+    },
+    /**
+     * Logs warning-level messages
+     * Used for recoverable errors and potential issues
+     *
+     * @param args - Arguments to log
+     */
+    warn: (...args) => {
+        if (shouldLog("warn")) {
+            console.warn(...withPrefix("warn", args));
+        }
+    },
+    /**
+     * Logs error-level messages
+     * Used for critical failures and exceptions
+     *
+     * @param args - Arguments to log
+     */
+    error: (...args) => {
+        if (shouldLog("error")) {
+            console.error(...withPrefix("error", args));
+        }
+    },
+};

package/dist/utils/safe-background-task.js

@@ -0,0 +1,33 @@
+import { logger } from "./logger.js";
+function runHookSafely(taskName, hookName, hook, value) {
+    if (!hook) {
+        return;
+    }
+    try {
+        void Promise.resolve(hook(value)).catch((hookError) => {
+            logger.error(`[safeBackgroundTask] ${taskName}: ${hookName} failed:`, hookError);
+        });
+    }
+    catch (hookError) {
+        logger.error(`[safeBackgroundTask] ${taskName}: ${hookName} failed:`, hookError);
+    }
+}
+export function safeBackgroundTask({ taskName, task, onSuccess, onError, }) {
+    const handleError = (error) => {
+        logger.error(`[safeBackgroundTask] ${taskName} failed:`, error);
+        runHookSafely(taskName, "onError", onError, error);
+    };
+    try {
+        const taskPromise = task();
+        void taskPromise
+            .then((result) => {
+            runHookSafely(taskName, "onSuccess", onSuccess, result);
+        })
+            .catch((error) => {
+            handleError(error);
+        });
+    }
+    catch (error) {
+        handleError(error);
+    }
+}

package/dist/utils/telegram-rate-limit-retry.js

@@ -0,0 +1,93 @@
+function getErrorMessage(error) {
+    const parts = [];
+    if (error instanceof Error) {
+        parts.push(error.message);
+    }
+    if (typeof error === "object" && error !== null) {
+        const description = Reflect.get(error, "description");
+        if (typeof description === "string") {
+            parts.push(description);
+        }
+        const message = Reflect.get(error, "message");
+        if (typeof message === "string") {
+            parts.push(message);
+        }
+    }
+    if (typeof error === "string") {
+        parts.push(error);
+    }
+    return parts.join("\n");
+}
+function getRetryAfterSecondsFromError(error) {
+    if (typeof error === "object" && error !== null) {
+        const parameters = Reflect.get(error, "parameters");
+        if (typeof parameters === "object" && parameters !== null) {
+            const retryAfter = Reflect.get(parameters, "retry_after");
+            if (typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter > 0) {
+                return retryAfter;
+            }
+        }
+    }
+    const message = getErrorMessage(error);
+    const retryMatch = message.match(/retry after\s+(\d+)/i);
+    if (!retryMatch) {
+        return null;
+    }
+    const parsedSeconds = Number.parseInt(retryMatch[1], 10);
+    if (!Number.isFinite(parsedSeconds) || parsedSeconds <= 0) {
+        return null;
+    }
+    return parsedSeconds;
+}
+function isTelegramRateLimitError(error) {
+    if (typeof error === "object" && error !== null) {
+        const status = Reflect.get(error, "status");
+        if (typeof status === "number" && status === 429) {
+            return true;
+        }
+        const errorCode = Reflect.get(error, "error_code");
+        if (typeof errorCode === "number" && errorCode === 429) {
+            return true;
+        }
+    }
+    const message = getErrorMessage(error).toLowerCase();
+    return /\b429\b/.test(message) || message.includes("too many requests");
+}
+function wait(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function getTelegramRetryAfterMs(error, fallbackDelayMs = 1000) {
+    if (!isTelegramRateLimitError(error)) {
+        return null;
+    }
+    const retryAfterSeconds = getRetryAfterSecondsFromError(error);
+    if (retryAfterSeconds !== null) {
+        return retryAfterSeconds * 1000;
+    }
+    return Math.max(1, Math.floor(fallbackDelayMs));
+}
+export async function withTelegramRateLimitRetry(operation, options) {
+    const maxRetries = Math.max(0, Math.floor(options?.maxRetries ?? 3));
+    const fallbackDelayMs = options?.fallbackDelayMs ?? 1000;
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const retryAfterMs = getTelegramRetryAfterMs(error, fallbackDelayMs);
+            if (retryAfterMs === null || attempt >= maxRetries) {
+                throw error;
+            }
+            attempt += 1;
+            options?.onRetry?.({
+                attempt,
+                retryAfterMs,
+                error,
+            });
+            await wait(retryAfterMs);
+        }
+    }
+}

package/dist/variant/manager.js

@@ -0,0 +1,103 @@
+/**
+ * Variant Manager - manages model variants (reasoning modes)
+ */
+import { opencodeClient } from "../opencode/client.js";
+import { getCurrentModel, setCurrentModel } from "../settings/manager.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Get available variants for a model from OpenCode API
+ * @param providerID Provider ID
+ * @param modelID Model ID
+ * @returns Array of available variants
+ */
+export async function getAvailableVariants(providerID, modelID) {
+    try {
+        const { data, error } = await opencodeClient.config.providers();
+        if (error || !data) {
+            logger.warn("[VariantManager] Failed to fetch providers:", error);
+            return [{ id: "default" }];
+        }
+        const provider = data.providers.find((p) => p.id === providerID);
+        if (!provider) {
+            logger.warn(`[VariantManager] Provider ${providerID} not found`);
+            return [{ id: "default" }];
+        }
+        const model = provider.models[modelID];
+        if (!model) {
+            logger.warn(`[VariantManager] Model ${modelID} not found in provider ${providerID}`);
+            return [{ id: "default" }];
+        }
+        // Start with default variant (always present)
+        const variants = [{ id: "default" }];
+        if (model.variants) {
+            // Add other variants from API (excluding default if it's already there)
+            const apiVariants = Object.entries(model.variants)
+                .filter(([id]) => id !== "default")
+                .map(([id, info]) => ({
+                id,
+                disabled: info.disabled,
+            }));
+            variants.push(...apiVariants);
+            logger.debug(`[VariantManager] Found ${variants.length} variants for ${providerID}/${modelID} (including default)`);
+        }
+        else {
+            logger.debug(`[VariantManager] No variants found for ${providerID}/${modelID}, using default only`);
+        }
+        return variants;
+    }
+    catch (err) {
+        logger.error("[VariantManager] Error fetching variants:", err);
+        return [{ id: "default" }];
+    }
+}
+/**
+ * Get current variant from settings
+ * @returns Current variant ID (defaults to "default")
+ */
+export function getCurrentVariant() {
+    const currentModel = getCurrentModel();
+    return currentModel?.variant || "default";
+}
+/**
+ * Set current variant in settings
+ * @param variantId Variant ID to set
+ */
+export function setCurrentVariant(variantId) {
+    const currentModel = getCurrentModel();
+    if (!currentModel) {
+        logger.warn("[VariantManager] Cannot set variant: no current model");
+        return;
+    }
+    currentModel.variant = variantId;
+    setCurrentModel(currentModel);
+    logger.info(`[VariantManager] Variant set to: ${variantId}`);
+}
+/**
+ * Format variant for button display
+ * @param variantId Variant ID (e.g., "default", "low", "high")
+ * @returns Formatted string "💭 Default", "💭 Low", etc.
+ */
+export function formatVariantForButton(variantId) {
+    const capitalized = variantId.charAt(0).toUpperCase() + variantId.slice(1);
+    return `💡 ${capitalized}`;
+}
+/**
+ * Format variant for display in messages
+ * @param variantId Variant ID
+ * @returns Formatted string with capitalized first letter
+ */
+export function formatVariantForDisplay(variantId) {
+    return variantId.charAt(0).toUpperCase() + variantId.slice(1);
+}
+/**
+ * Validate if a model supports a specific variant
+ * @param providerID Provider ID
+ * @param modelID Model ID
+ * @param variantId Variant ID to validate
+ * @returns true if variant is supported, false otherwise
+ */
+export async function validateVariantForModel(providerID, modelID, variantId) {
+    const variants = await getAvailableVariants(providerID, modelID);
+    const found = variants.find((v) => v.id === variantId && !v.disabled);
+    return found !== undefined;
+}

package/dist/variant/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "zardbot-telegram",
+  "version": "1.0.0",
+  "description": "ZardBot Telegram Bot - A Telegram client for OpenCode with TTS and STT support.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "zardbot-telegram": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "npm run build && npm start",
+    "release:prepare": "node scripts/release-prepare.mjs",
+    "release:rc": "node scripts/release-prepare.mjs rc",
+    "release:notes:preview": "node scripts/release-notes-preview.mjs",
+    "lint": "eslint src --ext .ts --max-warnings=0",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-joe-git/zardbot-telegram.git"
+  },
+  "keywords": [
+    "zardbot",
+    "opencode",
+    "telegram",
+    "telegram-bot",
+    "grammy",
+    "tts",
+    "stt",
+    "developer-tools",
+    "cli"
+  ],
+  "author": "ZardBot Team",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ai-joe-git/zardbot-telegram/issues"
+  },
+  "homepage": "https://github.com/ai-joe-git/zardbot-telegram#readme",
+  "dependencies": {
+    "@grammyjs/menu": "^1.3.1",
+    "@opencode-ai/sdk": "^1.1.21",
+    "better-sqlite3": "^12.6.2",
+    "dotenv": "^17.2.3",
+    "grammy": "^1.39.2",
+    "https-proxy-agent": "^7.0.6",
+    "socks-proxy-agent": "^8.0.5",
+    "telegram-markdown-v2": "^0.0.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.8",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}