pi-telegram-notifier 0.1.2 → 0.1.4

package/README.md

@@ -12,7 +12,7 @@ export PI_TELEGRAM_BOT_TOKEN='your-bot-token'
 pi
 ```
 
-If Pi is already running, run `/reload` after installing the package (restart Pi if you just set the token). If you previously installed a local checkout, run `pi list`, then `pi remove /absolute/path/to/pi-telegram-notifier` to avoid loading both copies. To get future releases, run `pi update npm:pi-telegram-notifier`. In Pi run `/telegram-pair`. Within five minutes send **`/start <code>`** to your bot in a private Telegram chat using the displayed one-time code. The extension stores only the numeric chat ID in `~/.pi/agent/pi-telegram-notifier.json` (or `$PI_CODING_AGENT_DIR/pi-telegram-notifier.json`), with mode 0600. To switch chats, run `/telegram-pair` again; the existing chat stays paired if pairing fails. The bot needs to receive messages via `getUpdates` during pairing: a webhook or another updates consumer must be disconnected first. There is no always-on polling after pairing.
+If Pi is already running, run `/reload` after installing the package (restart Pi if you just set the token). If you previously installed a local checkout, run `pi list`, then `pi remove /absolute/path/to/pi-telegram-notifier` to avoid loading both copies. To get future releases, run `pi update npm:pi-telegram-notifier`. In Pi run `/telegram-pair`. Use `/telegram-status` to see whether the bot token is configured and a private chat is paired; it reports local state and does not verify live Telegram connectivity. Within five minutes send **`/start <code>`** to your bot in a private Telegram chat using the displayed one-time code. The extension stores only the numeric chat ID in `~/.pi/agent/pi-telegram-notifier.json` (or `$PI_CODING_AGENT_DIR/pi-telegram-notifier.json`), with mode 0600. To switch chats, run `/telegram-pair` again; the existing chat stays paired if pairing fails. The bot needs to receive messages via `getUpdates` during pairing: a webhook or another updates consumer must be disconnected first. There is no always-on polling after pairing.
 
 **Privacy:** final agent responses and the device hostname are sent to Telegram. Responses can contain sensitive text; only use this package if that is acceptable for your projects and Telegram chat. Bot and provider tokens are not stored in the package or sent as message text. Telegram Bot API uses the bot token in the request URL; do not log outgoing URLs. Keep your shell environment and Pi credentials private. A lost or compromised Telegram bot token must be revoked with BotFather.
 
@@ -41,6 +41,8 @@ Telegram has a message-length limit; long responses are delivered in consecutive
 ## Develop and release
 
 ```sh
+npm ci
+npm run typecheck
 npm test
 npm pack --dry-run --json
 pi --no-extensions -e . --help

package/extensions/index.ts

@@ -2,13 +2,28 @@ import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { pairChat, saveChatId } from '../src/telegram.js';
-import { registerNotifications } from '../src/notification.js';
+import { loadChatId, pairChat, saveChatId } from '#src/telegram';
+import { registerNotifications } from '#src/notification';
 
 const agentDir = () => process.env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
 
 export default function (pi: ExtensionAPI) {
   registerNotifications(pi, agentDir(), process.env.PI_TELEGRAM_BOT_TOKEN);
+  pi.registerCommand('telegram-status', {
+    description: 'Show the Telegram bot configuration and pairing status',
+    handler: async (_args, ctx) => {
+      const tokenConfigured = !!process.env.PI_TELEGRAM_BOT_TOKEN;
+      const paired = loadChatId(agentDir()) !== undefined;
+      ctx.ui.notify([
+        'Telegram status',
+        `Bot token: ${tokenConfigured ? 'configured' : 'not configured'}`,
+        `Private chat: ${paired ? 'paired' : 'not paired'}`,
+        'Live connectivity: not checked',
+        !tokenConfigured ? 'Set PI_TELEGRAM_BOT_TOKEN and restart Pi.' : '',
+        !paired ? 'Run /telegram-pair to pair a private chat.' : '',
+      ].filter(Boolean).join('\n'), 'info');
+    },
+  });
   pi.registerCommand('telegram-pair', {
     description: 'Pair a private Telegram chat with this Pi installation',
     handler: async (_args, ctx) => {

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "pi-telegram-notifier",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Telegram notifications for final Pi agent responses and provider balances",
   "type": "module",
   "license": "MIT",
   "engines": { "node": ">=22.19.0" },
   "keywords": ["pi-package", "pi", "telegram", "notifications"],
   "files": ["extensions", "src", "README.md", "LICENSE", "docs/providers.md"],
-  "scripts": { "test": "node --test" },
+  "imports": { "#src/*": "./src/*.ts" },
+  "scripts": { "test": "node --test", "typecheck": "tsc --noEmit" },
   "pi": { "extensions": ["./extensions/index.ts"] },
   "peerDependencies": { "@earendil-works/pi-coding-agent": "*" },
+  "devDependencies": { "@types/node": "22.20.4", "typescript": "5.9.3" },
   "repository": { "type": "git", "url": "git+https://github.com/Gybra/pi-telegram-notifier.git" }
 }

package/src/{notification.js → notification.ts}

@@ -1,8 +1,11 @@
 import { hostname } from 'node:os';
-import { loadChatId, sendTelegram } from './telegram.js';
-import { getQuota } from './quota.js';
+import type { ExtensionAPI, SessionEntry } from '@earendil-works/pi-coding-agent';
+import { loadChatId, sendTelegram } from '#src/telegram';
+import { getQuota } from '#src/quota';
 
-export function finalResponse(branch, startLeafId) {
+type FinalResponse = { text: string; provider: string; modelId: string };
+
+export function finalResponse(branch: SessionEntry[], startLeafId: string | null): FinalResponse | undefined {
   const index = startLeafId === null ? -1 : branch.findIndex((entry) => entry.id === startLeafId);
   if (index < 0 && startLeafId !== null) return undefined;
   const latest = branch.slice(index + 1).filter((entry) => entry.type === 'message').at(-1)?.message;
@@ -12,12 +15,12 @@ export function finalResponse(branch, startLeafId) {
   return { text, provider: latest.provider, modelId: latest.model };
 }
 
-export function formatNotification(timestamp, response, quota) {
+export function formatNotification(timestamp: string, response: FinalResponse, quota: string): string {
   return `${timestamp}\nDevice: ${hostname()}\nProvider: ${response.provider}\n${quota}\n\n${response.text}`;
 }
 
-export function registerNotifications(pi, agentDir, token, fetchImpl = fetch) {
-  let startLeafId;
+export function registerNotifications(pi: ExtensionAPI, agentDir: string, token: string | undefined, fetchImpl: typeof fetch = fetch): void {
+  let startLeafId: string | null | undefined;
   pi.on('agent_start', (_event, ctx) => {
     startLeafId = ctx.sessionManager.getLeafId();
   });
@@ -27,7 +30,7 @@ export function registerNotifications(pi, agentDir, token, fetchImpl = fetch) {
     startLeafId = undefined;
     const chatId = loadChatId(agentDir);
     if (!chatId || !response) return;
-    let quota;
+    let quota: string;
     try {
       const model = ctx.modelRegistry?.find(response.provider, response.modelId);
       quota = await getQuota(model, ctx.modelRegistry, fetchImpl);

package/src/{quota.js → quota.ts}

@@ -1,6 +1,10 @@
+import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
+
 const UNAVAILABLE = 'Quota unavailable';
 
-const providers = {
+type Model = NonNullable<ReturnType<ModelRegistry['find']>>;
+
+const providers: Record<string, { origin: string; url: string }> = {
   openrouter: { origin: 'https://openrouter.ai', url: 'https://openrouter.ai/api/v1/credits' },
   'openai-codex': { origin: 'https://chatgpt.com', url: 'https://chatgpt.com/backend-api/wham/usage' },
   deepseek: { origin: 'https://api.deepseek.com', url: 'https://api.deepseek.com/user/balance' },
@@ -12,19 +16,19 @@ const providers = {
   xai: { origin: 'https://api.x.ai', url: 'https://cli-chat-proxy.grok.com/v1/billing?format=credits' },
 };
 
-function remainingPercent(used) {
+function remainingPercent(used: unknown): number | undefined {
   return typeof used === 'number' && Number.isFinite(used) && used >= 0 && used <= 100 ? 100 - used : undefined;
 }
 
-export async function getQuota(model, modelRegistry, fetchImpl = fetch) {
+export async function getQuota(model: Model | undefined, modelRegistry: Pick<ModelRegistry, 'getApiKeyAndHeaders' | 'isUsingOAuth'> | undefined, fetchImpl: typeof fetch = fetch): Promise<string> {
   const provider = model && providers[model.provider];
   if (!provider) return UNAVAILABLE;
   try {
     if (new URL(model.baseUrl).origin !== provider.origin) return UNAVAILABLE;
-    if (['anthropic', 'xai'].includes(model.provider) && !modelRegistry.isUsingOAuth(model)) return UNAVAILABLE;
-    const auth = await modelRegistry.getApiKeyAndHeaders(model);
-    if (!auth.ok || !auth.apiKey || (auth.baseUrl && new URL(auth.baseUrl).origin !== provider.origin)) return UNAVAILABLE;
-    const headers = { Authorization: ['zai', 'zai-coding-cn'].includes(model.provider) ? auth.apiKey : `Bearer ${auth.apiKey}` };
+    if (['anthropic', 'xai'].includes(model.provider) && !modelRegistry?.isUsingOAuth(model)) return UNAVAILABLE;
+    const auth = await modelRegistry?.getApiKeyAndHeaders(model);
+    if (!auth?.ok || !auth.apiKey || (auth.baseUrl && new URL(auth.baseUrl).origin !== provider.origin)) return UNAVAILABLE;
+    const headers: Record<string, string> = { Authorization: ['zai', 'zai-coding-cn'].includes(model.provider) ? auth.apiKey : `Bearer ${auth.apiKey}` };
     if (model.provider === 'anthropic') {
       headers['anthropic-beta'] = 'oauth-2025-04-20';
       headers['anthropic-version'] = '2023-06-01';
@@ -43,7 +47,7 @@ export async function getQuota(model, modelRegistry, fetchImpl = fetch) {
     const data = await response.json();
     if (['zai', 'zai-coding-cn'].includes(model.provider)) {
       if (data.success === false || ![undefined, 0, 200].includes(data.code)) return UNAVAILABLE;
-      const used = data.data?.limits?.find((limit) => limit.type === 'TOKENS_LIMIT')?.percentage;
+      const used = data.data?.limits?.find((limit: { type: string; percentage: number }) => limit.type === 'TOKENS_LIMIT')?.percentage;
       const remaining = remainingPercent(used);
       return remaining === undefined ? UNAVAILABLE : `Remaining quota: 5h ${remaining}%`;
     }
@@ -85,7 +89,7 @@ export async function getQuota(model, modelRegistry, fetchImpl = fetch) {
     }
     if (model.provider === 'deepseek') {
       if (!Array.isArray(data.balance_infos) || !data.balance_infos.length) return UNAVAILABLE;
-      const balances = data.balance_infos.map(({ currency, total_balance }) => {
+      const balances = data.balance_infos.map(({ currency, total_balance }: { currency: string; total_balance: string }) => {
         if (!['CNY', 'USD'].includes(currency) || typeof total_balance !== 'string' ||
             !/^\d+(?:\.\d+)?$/.test(total_balance)) return undefined;
         return `${total_balance} ${currency}`;

package/src/{telegram.js → telegram.ts}

@@ -2,18 +2,18 @@ import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
-const stateFile = (agentDir) => join(agentDir, 'pi-telegram-notifier.json');
+const stateFile = (agentDir: string) => join(agentDir, 'pi-telegram-notifier.json');
 
-export function loadChatId(agentDir) {
+export function loadChatId(agentDir: string): number | undefined {
   try {
-    const id = JSON.parse(readFileSync(stateFile(agentDir), 'utf8')).chatId;
-    return Number.isSafeInteger(id) && id > 0 ? id : undefined;
+    const id: unknown = JSON.parse(readFileSync(stateFile(agentDir), 'utf8')).chatId;
+    return typeof id === 'number' && Number.isSafeInteger(id) && id > 0 ? id : undefined;
   } catch {
     return undefined;
   }
 }
 
-export function saveChatId(agentDir, chatId) {
+export function saveChatId(agentDir: string, chatId: number): void {
   if (!Number.isSafeInteger(chatId) || chatId <= 0) throw new Error('Invalid private chat ID');
   mkdirSync(agentDir, { recursive: true, mode: 0o700 });
   const temporary = `${stateFile(agentDir)}.${randomBytes(8).toString('hex')}`;
@@ -21,7 +21,7 @@ export function saveChatId(agentDir, chatId) {
   renameSync(temporary, stateFile(agentDir));
 }
 
-export async function pairChat(token, code, fetchImpl = fetch, now = Date.now) {
+export async function pairChat(token: string, code: string, fetchImpl: typeof fetch = fetch, now: () => number = Date.now): Promise<number> {
   const expires = now() + 300_000;
   let offset = 0;
   while (now() < expires) {
@@ -51,9 +51,9 @@ export async function pairChat(token, code, fetchImpl = fetch, now = Date.now) {
   throw new Error('Telegram pairing code expired');
 }
 
-export async function sendTelegram(token, chatId, text, fetchImpl = fetch) {
+export async function sendTelegram(token: string, chatId: number, text: string, fetchImpl: typeof fetch = fetch): Promise<void> {
   let part = '';
-  const chunks = [];
+  const chunks: string[] = [];
   for (const character of text) {
     if (part.length + character.length > 4096) {
       chunks.push(part);