pi-telegram-notifier 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oreste Acacia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# pi-telegram-notifier
+
+Send the **final** response of each Pi agent run to a paired private Telegram chat. Each notification contains a UTC timestamp, provider, full response text, and the **actual** remaining provider balance when it can be queried. Telegram metadata (provider and quota) is in English; the agent's response is forwarded verbatim in its original language. Intermediate tool calls do not trigger messages.
+
+## Install and configure
+
+Requires Node.js 22.19+ and [Pi](https://pi.dev). Create a Telegram bot using [@BotFather](https://t.me/BotFather), then set its token **outside the repository** before starting Pi:
+
+```sh
+export PI_TELEGRAM_BOT_TOKEN='your-bot-token'
+pi -e .                       # test this checkout as a Pi package
+# Later, after public release: pi install npm:pi-telegram-notifier
+# Or: pi install git:github.com/Gybra/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.
+
+**Privacy:** final agent responses are sent in full to Telegram. They 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.
+
+## Quota coverage
+
+The **quota/credit** field supports these Pi provider IDs (using the credential Pi resolves for the active model):
+
+| Pi provider ID | Mode | Required credential | What is shown |
+| --- | --- | --- | --- |
+| `openai-codex` | Subscription | ChatGPT OAuth | Remaining 5h / 7d usage-window percentages; [official Codex client endpoint](https://github.com/openai/codex/blob/main/codex-rs/backend-client/src/client/rate_limit_resets.rs). |
+| `anthropic` | Subscription | Claude OAuth | Remaining 5h / 7d usage-window percentages; [private OAuth endpoint](https://github.com/openclaw/openclaw/blob/main/src/infra/provider-usage.fetch.claude.ts). |
+| `xai` | Subscription | Grok OAuth | Remaining weekly shared Grok credits percentage, **not** prepaid API credit; [official Grok client endpoint](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/src/extensions/billing.rs). |
+| `zai` | Subscription (Coding Plan) | Z.ai Coding Plan key | Remaining 5h **model** quota percentage; [Z.ai usage plugin endpoint](https://github.com/zai-org/zai-coding-plugins/blob/main/plugins/glm-plan-usage/skills/usage-query-skill/scripts/query-usage.mjs). Not the separate MCP tool quota. |
+| `zai-coding-cn` | Subscription (Coding Plan) | China Coding Plan key | Same model quota on `open.bigmodel.cn`. |
+| `openrouter` | API credit | **Management key** | Remaining account credits in USD; ordinary inference keys cannot access the credits endpoint (HTTP 403). Per-key spending limits are not account credit. |
+| `deepseek` | API credit | API key | Available CNY/USD balance via `/user/balance`. |
+| `moonshotai` | API credit | API key | Available USD balance via `/v1/users/me/balance`. |
+| `moonshotai-cn` | API credit | API key | Available CNY balance via `/v1/users/me/balance`. |
+
+**Not supported as API credit:** an `openai` API key does not expose a verified remaining-balance endpoint; an `anthropic` API key does not expose its subscription quota **or** a verified remaining API credit; an `xai` API key does not expose Grok subscription quota or the prepaid API balance (the latter requires a separate management key and team ID); Z.ai pay-as-you-go keys may have no Coding Plan quota. None of the listed providers currently supports both subscription quota **and** API credit through this extension. Usage/cost reports and spending caps are **not** remaining credit.
+
+Pi resolves and refreshes provider credentials, including those saved in its `auth.json`; this extension does **not** read that file. The Codex, Claude, Grok and Z.ai quota endpoints above are not guaranteed stable public APIs. All other providers, custom/proxied endpoints, inaccessible credentials, and failed or malformed lookups show `Quota unavailable` **without blocking the notification**. Quota percentage is not inferred from context-window usage, token usage, or request rate limits. See [the 41-provider inventory](docs/providers.md) for sources and limitations.
+
+Telegram has a message-length limit; long responses are delivered in consecutive plain-text chunks. If delivery fails, Pi reports a generic failure without leaking message or credentials. Network requests have timeouts; Pi remains usable.
+
+## Develop and release
+
+```sh
+npm test
+npm pack --dry-run --json
+pi -e . --help
+```
+
+Read [AGENTS.md](AGENTS.md) before editing. Open contributions with tests for behavior changes and official provider documentation for balance integrations. MIT licensed; see [LICENSE](LICENSE). CI runs tests and packaging checks. Publishing is deliberately manual: create the public GitHub repository, then publish the npm package with the `pi-package` keyword to make it eligible for the [Pi package gallery](https://pi.dev/packages). No action here pushes, publishes, or handles real credentials.

package/docs/providers.md

@@ -0,0 +1,22 @@
+# Provider balance coverage
+
+Inventory of the 41 built-in provider IDs in the installed Pi model catalog (`@earendil-works/pi-ai`), checked against provider API documentation. This is **account balance / subscription quota**, not the model's context window, request rate limit, past spending, or an API-key spending cap. Pi supplies the active model's credential, whether configured in `auth.json`, environment, or through OAuth. Third-party/custom providers are unknown and display `Quota unavailable`.
+
+| Pi provider ID | Status | Official reference |
+| --- | --- | --- |
+| `openrouter` | Account credit = `total_credits - total_usage` (USD), **only if Pi's credential is an OpenRouter management key**; normal inference keys receive HTTP 403 and show unavailable. | [Get remaining credits](https://openrouter.ai/docs/api/api-reference/credits/get-remaining-credits), `GET https://openrouter.ai/api/v1/credits` |
+| `openai-codex` | Remaining subscription quota for the primary and secondary usage windows (typically 5h / 7d), from `100 - used_percent`; Pi's OAuth token and ChatGPT account ID are required. This backend route is used by the official Codex client but is **not a stable public API**. | [Official Codex client usage request](https://github.com/openai/codex/blob/main/codex-rs/backend-client/src/client/rate_limit_resets.rs), [response fields](https://github.com/openai/codex/blob/main/codex-rs/codex-backend-openapi-models/src/models/rate_limit_status_details.rs), `GET https://chatgpt.com/backend-api/wham/usage` |
+| `deepseek` | Available balance per currency (CNY and/or USD); no currency conversion. | [Get User Balance](https://api-docs.deepseek.com/api/get-user-balance), `GET https://api.deepseek.com/user/balance` |
+| `moonshotai` | Available balance, USD. | [Balance](https://platform.moonshot.ai/docs/api/balance), `GET https://api.moonshot.ai/v1/users/me/balance` |
+| `moonshotai-cn` | Available balance, CNY. | [Balance](https://platform.moonshot.cn/docs/api/balance), `GET https://api.moonshot.cn/v1/users/me/balance` |
+| `zai` | Remaining 5-hour Coding Plan model quota from `100 - percentage` for `TOKENS_LIMIT` only; pay-as-you-go keys or unknown plan data show unavailable. | [Official Z.ai usage query script](https://github.com/zai-org/zai-coding-plugins/blob/main/plugins/glm-plan-usage/skills/usage-query-skill/scripts/query-usage.mjs), `GET https://api.z.ai/api/monitor/usage/quota/limit` (not a stable public API) |
+| `zai-coding-cn` | Same Coding Plan model quota for the China host; not the MCP tool quota. | [Official Z.ai usage query script](https://github.com/zai-org/zai-coding-plugins/blob/main/plugins/glm-plan-usage/skills/usage-query-skill/scripts/query-usage.mjs), `GET https://open.bigmodel.cn/api/monitor/usage/quota/limit` (not a stable public API) |
+| `anthropic` | Remaining 5h and/or 7d Claude **subscription** allowance with Pi OAuth only; regular API keys show unavailable. | [OAuth usage client](https://github.com/openclaw/openclaw/blob/main/src/infra/provider-usage.fetch.claude.ts), `GET https://api.anthropic.com/api/oauth/usage` (private endpoint) |
+| `xai` | Remaining **weekly Grok subscription** credits with Pi OAuth only. The per-product percentages are not the shared pool; xAI API prepaid credit is a different quantity requiring a management key. | [Official Grok billing client](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/src/extensions/billing.rs), `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` (private endpoint); [API management billing](https://docs.x.ai/developers/rest-api-reference/management/billing) |
+| `amazon-bedrock`, `azure-openai-responses`, `cloudflare-ai-gateway`, `cloudflare-workers-ai`, `google-vertex`, `radius`, `vercel-ai-gateway` | Cloud/gateway billing belongs to separate accounts/credentials; no verified remaining plan balance endpoint with Pi's inference credential. | Provider-specific cloud billing tools, not Pi model API keys. |
+| `openai`, `github-copilot` | Subscription balance not exposed through a verified quota endpoint accessible with Pi's resolved inference credential. Admin usage/spending APIs are **not** plan remainder. | [OpenAI organization costs](https://platform.openai.com/docs/api-reference/organization/costs) |
+| `fireworks`, `together` | Documented billing usage / quotas are past spend or request limits, not an available credit balance verified for inference keys. | [Fireworks billing summary](https://docs.fireworks.ai/api-reference/get-billing-summary), [Together billing usage](https://docs.together.ai/reference/billing-usage) |
+| `ant-ling`, `baseten`, `cerebras`, `google`, `groq`, `huggingface`, `kimi-coding`, `meta`, `minimax`, `minimax-cn`, `mistral` | No verified official endpoint returning remaining allowance with Pi's inference credential. | Check provider billing documentation before adding integrations. |
+| `nvidia`, `opencode`, `opencode-go`, `qwen-token-plan`, `qwen-token-plan-cn`, `qwen-token-plan-individual`, `xiaomi`, `xiaomi-token-plan-ams`, `xiaomi-token-plan-cn`, `xiaomi-token-plan-sgp` | No verified official endpoint returning remaining allowance with Pi's inference credential; management/billing credentials, if available, are distinct. | Check provider billing documentation before adding integrations. |
+
+An HTTP 401/403, invalid response or missing credential always yields `Quota unavailable` without suppressing the notification. OpenRouter's `/api/v1/key` reports a **per-key** limit, not remaining account credit: deliberately not used. This inventory is for the Pi catalog present at implementation time; new providers require fresh verification.

package/extensions/index.ts

@@ -0,0 +1,30 @@
+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';
+
+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-pair', {
+    description: 'Pair a private Telegram chat with this Pi installation',
+    handler: async (_args, ctx) => {
+      const token = process.env.PI_TELEGRAM_BOT_TOKEN;
+      if (!token) {
+        ctx.ui.notify('Set PI_TELEGRAM_BOT_TOKEN before starting Pi', 'error');
+        return;
+      }
+      const code = randomBytes(16).toString('hex');
+      ctx.ui.notify(`Send /start ${code} to your Telegram bot within 5 minutes`, 'info');
+      try {
+        saveChatId(agentDir(), await pairChat(token, code));
+        ctx.ui.notify('Private Telegram chat paired', 'info');
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : 'Telegram pairing failed', 'error');
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "pi-telegram-notifier",
+  "version": "0.1.0",
+  "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" },
+  "pi": { "extensions": ["./extensions/index.ts"] },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*" },
+  "repository": { "type": "git", "url": "git+https://github.com/Gybra/pi-telegram-notifier.git" }
+}

package/src/notification.js

@@ -0,0 +1,39 @@
+import { loadChatId, sendTelegram } from './telegram.js';
+import { getQuota } from './quota.js';
+
+export function finalResponse(branch, startLeafId) {
+  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;
+  if (latest?.role !== 'assistant' || !['stop', 'length'].includes(latest.stopReason)) return undefined;
+  const text = latest.content.filter((item) => item.type === 'text').map((item) => item.text).join('');
+  if (!text) return undefined;
+  return { text, provider: latest.provider, modelId: latest.model };
+}
+
+export function formatNotification(timestamp, response, quota) {
+  return `${timestamp}\nProvider: ${response.provider}\n${quota}\n\n${response.text}`;
+}
+
+export function registerNotifications(pi, agentDir, token, fetchImpl = fetch) {
+  let startLeafId;
+  pi.on('agent_start', (_event, ctx) => {
+    startLeafId = ctx.sessionManager.getLeafId();
+  });
+  pi.on('agent_settled', async (_event, ctx) => {
+    if (!token || startLeafId === undefined) return;
+    const response = finalResponse(ctx.sessionManager.getBranch(), startLeafId);
+    startLeafId = undefined;
+    const chatId = loadChatId(agentDir);
+    if (!chatId || !response) return;
+    try {
+      const model = ctx.modelRegistry?.find(response.provider, response.modelId);
+      const quota = await getQuota(model, ctx.modelRegistry, fetchImpl);
+      await sendTelegram(token, chatId,
+        formatNotification(new Date().toISOString(), response, quota), fetchImpl);
+    } catch {
+      if (ctx.hasUI) ctx.ui.notify('Telegram delivery failed; check the bot connection', 'error');
+      else console.error('Telegram delivery failed; check the bot connection');
+    }
+  });
+}

package/src/quota.js

@@ -0,0 +1,101 @@
+const UNAVAILABLE = 'Quota unavailable';
+
+const providers = {
+  openrouter: ['https://openrouter.ai', 'https://openrouter.ai/api/v1/credits'],
+  'openai-codex': ['https://chatgpt.com', 'https://chatgpt.com/backend-api/wham/usage'],
+  deepseek: ['https://api.deepseek.com', 'https://api.deepseek.com/user/balance'],
+  moonshotai: ['https://api.moonshot.ai', 'https://api.moonshot.ai/v1/users/me/balance'],
+  'moonshotai-cn': ['https://api.moonshot.cn', 'https://api.moonshot.cn/v1/users/me/balance'],
+  zai: ['https://api.z.ai', 'https://api.z.ai/api/monitor/usage/quota/limit'],
+  'zai-coding-cn': ['https://open.bigmodel.cn', 'https://open.bigmodel.cn/api/monitor/usage/quota/limit'],
+  anthropic: ['https://api.anthropic.com', 'https://api.anthropic.com/api/oauth/usage'],
+  xai: ['https://api.x.ai', 'https://cli-chat-proxy.grok.com/v1/billing?format=credits'],
+};
+
+function remainingPercent(used) {
+  return typeof used === 'number' && Number.isFinite(used) && used >= 0 && used <= 100 ? 100 - used : undefined;
+}
+
+export async function getQuota(model, modelRegistry, fetchImpl = fetch) {
+  const provider = model && providers[model.provider];
+  if (!provider) return UNAVAILABLE;
+  try {
+    if (new URL(model.baseUrl).origin !== provider[0]) 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[0])) return UNAVAILABLE;
+    const headers = { 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';
+    }
+    if (model.provider === 'openai-codex') {
+      const payload = JSON.parse(Buffer.from(auth.apiKey.split('.')[1], 'base64url').toString('utf8'));
+      const accountId = payload['https://api.openai.com/auth']?.chatgpt_account_id;
+      if (typeof accountId !== 'string' || !accountId) return UNAVAILABLE;
+      headers['ChatGPT-Account-Id'] = accountId;
+    }
+    const response = await fetchImpl(provider[1], {
+      headers,
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return UNAVAILABLE;
+    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 remaining = remainingPercent(used);
+      return remaining === undefined ? UNAVAILABLE : `Remaining quota: 5h ${remaining}%`;
+    }
+    if (model.provider === 'anthropic') {
+      const windows = [['five_hour', '5h'], ['seven_day', '7d']]
+        .map(([key, label]) => {
+          const remaining = remainingPercent(data[key]?.utilization);
+          return remaining === undefined ? undefined : `${label} ${remaining}%`;
+        }).filter(Boolean);
+      return windows.length ? `Remaining quota: ${windows.join(', ')}` : UNAVAILABLE;
+    }
+    if (model.provider === 'xai') {
+      const config = data.config;
+      if (config?.currentPeriod?.type !== 'USAGE_PERIOD_TYPE_WEEKLY') return UNAVAILABLE;
+      let remaining = remainingPercent(config.creditUsagePercent);
+      if (remaining === undefined && config.creditUsagePercent === undefined) {
+        const { currentPeriod, productUsage } = config;
+        if (Date.parse(currentPeriod.start) < Date.parse(currentPeriod.end) &&
+            (productUsage === undefined || (Array.isArray(productUsage) && productUsage.every((item) => item?.usagePercent === 0)))) remaining = 100;
+      }
+      return remaining === undefined ? UNAVAILABLE : `Remaining quota: 7d ${remaining}%`;
+    }
+    if (model.provider === 'openai-codex') {
+      const windows = [data.rate_limit?.primary_window, data.rate_limit?.secondary_window].filter(Boolean);
+      if (!windows.length) return UNAVAILABLE;
+      const remaining = windows.map(({ used_percent: used, limit_window_seconds: seconds }) => {
+        if (!Number.isFinite(used) || used < 0 || used > 100 || !Number.isSafeInteger(seconds) || seconds <= 0) return undefined;
+        const period = seconds % 86400 === 0 ? `${seconds / 86400}d` : seconds % 3600 === 0 ? `${seconds / 3600}h` : `${seconds / 60}m`;
+        return `${period} ${100 - used}%`;
+      });
+      return remaining.every(Boolean) ? `Remaining quota: ${remaining.join(', ')}` : UNAVAILABLE;
+    }
+    if (model.provider === 'openrouter') {
+      const total = data.data?.total_credits;
+      const used = data.data?.total_usage;
+      if (typeof total !== 'number' || typeof used !== 'number' ||
+          !Number.isFinite(total) || !Number.isFinite(used) || total < 0 || used < 0 || used > total) return UNAVAILABLE;
+      return `Remaining credits: ${(total - used).toFixed(6).replace(/\.?0+$/, '')} USD`;
+    }
+    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 }) => {
+        if (!['CNY', 'USD'].includes(currency) || typeof total_balance !== 'string' ||
+            !/^\d+(?:\.\d+)?$/.test(total_balance)) return undefined;
+        return `${total_balance} ${currency}`;
+      });
+      return balances.every(Boolean) ? `Remaining balance: ${balances.join(', ')}` : UNAVAILABLE;
+    }
+    const amount = data.data?.available_balance;
+    if (data.status !== true || data.code !== 0 || typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0) return UNAVAILABLE;
+    return `Remaining balance: ${amount} ${model.provider === 'moonshotai-cn' ? 'CNY' : 'USD'}`;
+  } catch {
+    return UNAVAILABLE;
+  }
+}

package/src/telegram.js

@@ -0,0 +1,82 @@
+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');
+
+export function loadChatId(agentDir) {
+  try {
+    const id = JSON.parse(readFileSync(stateFile(agentDir), 'utf8')).chatId;
+    return Number.isSafeInteger(id) && id > 0 ? id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveChatId(agentDir, chatId) {
+  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')}`;
+  writeFileSync(temporary, JSON.stringify({ chatId }), { mode: 0o600, flag: 'wx' });
+  renameSync(temporary, stateFile(agentDir));
+}
+
+export async function pairChat(token, code, fetchImpl = fetch, now = Date.now) {
+  const expires = now() + 300_000;
+  let offset = 0;
+  while (now() < expires) {
+    let response;
+    try {
+      const url = new URL(`https://api.telegram.org/bot${token}/getUpdates`);
+      url.searchParams.set('timeout', '20');
+      url.searchParams.set('offset', String(offset));
+      response = await fetchImpl(url, { signal: AbortSignal.timeout(25_000) });
+    } catch {
+      throw new Error('Telegram pairing request failed');
+    }
+    if (response.status === 409) throw new Error('Telegram webhook or another getUpdates consumer is active');
+    if (!response.ok) throw new Error(`Telegram pairing failed (HTTP ${response.status})`);
+    let data;
+    try { data = await response.json(); } catch { throw new Error('Invalid Telegram pairing response'); }
+    if (!data.ok || !Array.isArray(data.result)) throw new Error('Invalid Telegram pairing response');
+    for (const update of data.result) {
+      offset = Math.max(offset, update.update_id + 1);
+      if (now() < expires && update.message?.chat?.type === 'private' &&
+          update.message.text === `/start ${code}` &&
+          Number.isSafeInteger(update.message.chat.id) && update.message.chat.id > 0) {
+        return update.message.chat.id;
+      }
+    }
+  }
+  throw new Error('Telegram pairing code expired');
+}
+
+export async function sendTelegram(token, chatId, text, fetchImpl = fetch) {
+  let part = '';
+  const chunks = [];
+  for (const character of text) {
+    if (part.length + character.length > 4096) {
+      chunks.push(part);
+      part = '';
+    }
+    part += character;
+  }
+  if (part) chunks.push(part);
+  for (const chunk of chunks) {
+    let response;
+    try {
+      response = await fetchImpl(`https://api.telegram.org/bot${token}/sendMessage`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ chat_id: chatId, text: chunk }),
+        signal: AbortSignal.timeout(10_000),
+      });
+    } catch {
+      throw new Error('Telegram delivery request failed');
+    }
+    if (!response.ok) throw new Error(`Telegram delivery failed (HTTP ${response.status})`);
+    let data;
+    try { data = await response.json(); } catch { throw new Error('Invalid Telegram delivery response'); }
+    if (!data.ok) throw new Error('Telegram delivery failed');
+  }
+}