@quecue/dev-notify 0.2.4 → 0.2.5

package/CHANGELOG.en.md

@@ -2,6 +2,13 @@
 
 English | [简体中文](CHANGELOG.md)
 
+## 0.2.5 — 2026-11-07
+
+- Distinguish Telegram `getMe` failures during reply-button preparation, bridge unreadiness, and notification-delivery failures. Retain bounded API error codes and report safe delivery categories and API-acknowledged part counts, without exposing underlying exceptions or server bodies. Do not infer exact send error codes discarded by the communication library.
+- Add isolated regressions for Telegram failure with successful buttonless Feishu delivery, bridge unreadiness with ordinary delivery on both channels, and recovery with buttons on both channels. No new retries, replays, or authorization.
+- Cover explicit channel rejection, unknown exceptions, and successful API delivery followed by local message-mapping failure without incorrectly claiming non-delivery or resending. Windows x64 / Node 24 totals 247 tests: 246 passed, 0 failed, and 1 opt-in native credential test skipped; not macOS real-machine acceptance.
+- This release improves diagnostics; it does not establish or fix the specific cause of historical missing notifications on any particular device.
+
 ## 0.2.4 — 2026-11-07
 
 - Recover valid bot locks belonging to confirmed exited processes so a crashed reply bridge does not permanently remove Reply to Claude buttons. Live processes, reused PIDs, unknown permissions, and damaged locks are not preempted; concurrent recovery is serialized.

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 简体中文 | [English](CHANGELOG.en.md)
 
+## 0.2.5 — 2026-11-07
+
+- 区分回复按钮的 Telegram `getMe` 身份查询失败、桥接未就绪与通知投递失败；保留有界 API 错误码，投递失败显示安全分类及 API 确认分段数，不输出底层异常或服务端正文。通讯库未保留的具体发送错误码不会猜测。
+- 补充 Telegram 失败而飞书成功且无按钮、桥接未就绪仍发送双渠道普通通知、恢复后双渠道带按钮的隔离回归；不新增重试、补发或授权。
+- 补充渠道明确拒绝、未知异常和 API 成功但本地消息映射失败的回归，避免误报未送达或重复发送。Windows x64／Node 24 共 247 项测试：246 通过、0 失败、1 项显式原生凭据测试跳过；不代表 macOS 实机验收。
+- 本版改进故障诊断，不代表已确认或修复某台设备历史漏发的具体根因。
+
 ## 0.2.4 — 2026-11-07
 
 - 修复回复桥接异常退出后残留 Bot 锁导致通知不再出现“回复 Claude”按钮：仅回收格式有效且已确认进程退出的锁；活进程、PID 复用、权限未知或损坏锁均不抢占，并串行化并发恢复。

package/dist/claude-hook.js

@@ -6,6 +6,7 @@ import { t } from './i18n.js';
 import { shouldNotify } from './notifications.js';
 import { transcriptEndTime } from './hook-time.js';
 import { findSessionName } from './reply-platform.js';
+import { ReplyPreparationError, safeDeliveryReason, safeFailureReason } from './notification-diagnostics.js';
 import { lifecycleHook, interactionHook, attachReply, mapReplies, notificationCoverage } from './reply-hooks.js';
 export const MAX_HOOK_BYTES = 8 * 1024 * 1024;
 export async function readHookInput(input = process.stdin, limit = MAX_HOOK_BYTES) {
@@ -139,8 +140,8 @@ export async function dispatchClaudeHook(bytes, configFile, context) {
     try {
         binding = await attachReply(notification, data, configFile, options);
     }
-    catch {
-        context.err(t('hook.replyNotReady'));
+    catch (error) {
+        context.err(error instanceof ReplyPreparationError ? error.message : t('hook.replyNotReady'));
     }
     let covered = { telegram: [], feishu: false };
     try {
@@ -168,10 +169,12 @@ export async function dispatchClaudeHook(bytes, configFile, context) {
                 mapReplies(plan, binding);
             const result = await context.send(plan, config);
             if (!result.ok)
-                context.err(t('hook.sendIncomplete', { channel }));
+                context.err(t('hook.sendIncompleteDetail', {
+                    channel, sent: result.sent, planned: result.planned, reason: safeDeliveryReason(result.error),
+                }));
         }
-        catch {
-            context.err(t('hook.sendFailed', { channel }));
+        catch (error) {
+            context.err(t('hook.sendFailedDetail', { channel, reason: safeFailureReason(error) }));
         }
     }
     if (!channels)

package/dist/cli.js

@@ -16,7 +16,7 @@ import { startBridge, stopBridge, bridgeStatus, runBridge } from './reply-bridge
 import { updatePackage } from './update.js';
 import { postUpdate } from './maintenance.js';
 import { localeName, parseLocale, resolveLocale, setLocale, t } from './i18n.js';
-export const VERSION = '0.2.4';
+export const VERSION = '0.2.5';
 const helpText = () => t('cli.help', { version: VERSION });
 function rawLang(argv) {
     for (let i = 0; i < argv.length; i++) {

package/dist/i18n.js

@@ -305,7 +305,16 @@ const zh = {
     'hook.notificationFallback': 'Claude Code 正在等待你的确认或输入，请回到终端处理。',
     'hook.interactionFailed': 'Claude Code 的回复状态或交互处理失败。没有自动选择答案或批准权限，请在本机处理。',
     'hook.sessionNameFailed': '读取不到 Claude Code 会话名称，通知底部将省略主题。',
-    'hook.replyNotReady': '远程回复还没有就绪，仍会尝试发送普通通知。',
+    'hook.replyNotReady': '回复按钮准备失败（会话、授权、本地状态或桥接检查）；仍会尝试向各渠道发送普通通知，不代表 Telegram 已送达。',
+    'hook.replyIdentityFailed': '回复按钮准备失败：Telegram getMe 身份查询失败（{reason}）；仍会尝试发送不带按钮的普通通知。',
+    'hook.sendIncompleteDetail': '{channel}：通知投递或发送后处理未全部完成（API 确认 {sent}/{planned} 段；{reason}）。整条消息不会自动重发。',
+    'hook.sendFailedDetail': '{channel}：通知发送流程失败（{reason}）。整条消息不会自动重发。',
+    'diagnostic.network': '网络请求失败或响应无效（可能为超时或连接异常，无法进一步区分）',
+    'diagnostic.rejected': '渠道明确拒绝请求（当前接口未保留具体错误码）',
+    'diagnostic.unknown': '原因未分类；为避免泄密，不显示底层错误',
+    'diagnostic.telegramCode': 'Telegram API 错误码 {code}',
+    'diagnostic.telegramUnknown': 'Telegram API 返回失败，错误码未知',
+    'diagnostic.httpCode': 'HTTP 状态码 {code}',
     'hook.coverageFailed': '没有核验到选择题通知的覆盖情况，将保留普通权限提醒。',
     'hook.sendIncomplete': '{channel}：Claude Code 通知没有完整发送。整条消息不会自动重发。',
     'hook.sendFailed': '{channel}：Claude Code 通知发送失败。请检查配置、系统凭据和网络；整条消息不会自动重发。',
@@ -803,7 +812,16 @@ secrets are never written in plaintext.`,
     'hook.notificationFallback': 'Claude Code is waiting for your confirmation or input. Return to the terminal to handle it.',
     'hook.interactionFailed': 'Claude Code reply state or interaction handling failed. No answer or permission was selected automatically; handle it locally.',
     'hook.sessionNameFailed': 'Could not read the Claude Code session name; the topic will be omitted from the notification footer.',
-    'hook.replyNotReady': 'Remote replies are not ready yet; a normal notification will still be attempted.',
+    'hook.replyNotReady': 'Reply button preparation failed during session, authorization, local-state, or bridge checks; normal notifications will still be attempted on each channel. This does not mean Telegram delivery succeeded.',
+    'hook.replyIdentityFailed': 'Reply button preparation failed: Telegram getMe identity lookup failed ({reason}); normal notifications without buttons will still be attempted.',
+    'hook.sendIncompleteDetail': '{channel}: delivery or post-send processing did not fully complete (API acknowledged {sent}/{planned} parts; {reason}). The message will not be resent automatically.',
+    'hook.sendFailedDetail': '{channel}: notification sending failed ({reason}). The message will not be resent automatically.',
+    'diagnostic.network': 'Network request failed or response was invalid (possibly a timeout or connection failure; cannot distinguish further)',
+    'diagnostic.rejected': 'The channel explicitly rejected the request (the current interface does not retain its exact error code)',
+    'diagnostic.unknown': 'Unclassified reason; underlying error withheld to protect secrets',
+    'diagnostic.telegramCode': 'Telegram API error code {code}',
+    'diagnostic.telegramUnknown': 'Telegram API failed with an unknown error code',
+    'diagnostic.httpCode': 'HTTP status {code}',
     'hook.coverageFailed': 'Could not verify question-notification coverage; the general permission reminder will be kept.',
     'hook.sendIncomplete': '{channel}: the Claude Code notification was not fully sent. The message will not be resent automatically.',
     'hook.sendFailed': '{channel}: the Claude Code notification failed to send. Check configuration, system credentials, and network; the message will not be resent automatically.',

package/dist/notification-diagnostics.js

@@ -0,0 +1,41 @@
+import { HttpError, TelegramApiError, TransportError } from '@quecue/notify-core';
+import { ConfigError } from './config.js';
+import { t } from './i18n.js';
+// 仅保留类型和有界状态码；不输出底层异常、URL、Token 或服务端正文。
+export class TelegramRequestError extends ConfigError {
+    code;
+    constructor(code) {
+        super(t(code === 409 ? 'reply.telegramConflict' : 'reply.telegramRequestFailed'));
+        this.code = code;
+    }
+}
+export function safeFailureReason(error) {
+    if (error instanceof TelegramRequestError || error instanceof TelegramApiError) {
+        const code = error.code;
+        return Number.isSafeInteger(code) && code >= 100 && code <= 599
+            ? t('diagnostic.telegramCode', { code }) : t('diagnostic.telegramUnknown');
+    }
+    if (error instanceof HttpError) {
+        const code = error.status;
+        return Number.isSafeInteger(code) && code >= 100 && code <= 599
+            ? t('diagnostic.httpCode', { code }) : t('diagnostic.network');
+    }
+    if (error instanceof TransportError)
+        return t('diagnostic.network');
+    return t('diagnostic.unknown');
+}
+export class ReplyPreparationError extends ConfigError {
+    constructor(error) {
+        super(t('hook.replyIdentityFailed', { reason: safeFailureReason(error) }));
+    }
+}
+// 公共库目前只返回安全文本而非错误类型。仅匹配本地已知值，不转发任意字符串。
+export function safeDeliveryReason(error) {
+    for (const key of ['channels.network', 'channels.noResponse', 'channels.responseTooLarge', 'channels.notJsonObject']) {
+        if (error === t(key))
+            return t('diagnostic.network');
+    }
+    if (error === t('channels.rejected'))
+        return t('diagnostic.rejected');
+    return t('diagnostic.unknown');
+}

package/dist/reply-hooks.js

@@ -6,6 +6,7 @@ import { findSession } from './reply-platform.js';
 import { textHash } from './reply-engine.js';
 import { telegramApi, replyHint } from './reply-telegram.js';
 import { bridgeStatus, startBridge } from './reply-bridge.js';
+import { ReplyPreparationError } from './notification-diagnostics.js';
 import { createInteraction, questionsContent, showInteraction, waitInteraction } from './reply-interactions.js';
 import { makePlan, deliver } from './channels.js';
 import { completeToolCall, endSessionInteractions, finishInteraction, matchingCall, registerToolCall } from './reply-outcomes.js';
@@ -115,7 +116,14 @@ export async function attachReply(message, data, file, options = {}) {
         options.err?.(t('reply.bridgeNotReadyButton'));
         return null;
     }
-    const api = apiFor(access, options), bot = await api('getMe', {});
+    const api = apiFor(access, options);
+    let bot;
+    try {
+        bot = await api('getMe', {});
+    }
+    catch (error) {
+        throw new ReplyPreparationError(error);
+    }
     if (typeof bot?.username !== 'string' || !/^[A-Za-z0-9_]{5,64}$/.test(bot.username))
         throw new ConfigError(t('reply.botUsernameInvalid'));
     const token = randomBytes(16).toString('hex');

package/dist/reply-telegram.js

@@ -2,6 +2,7 @@ import { createTelegramApi, TelegramApiError } from '@quecue/notify-core';
 import { requestJson } from './channels.js';
 import { ConfigError } from './config.js';
 import { t } from './i18n.js';
+import { TelegramRequestError } from './notification-diagnostics.js';
 export function telegramApi(token, request = requestJson) {
     const call = createTelegramApi(token, { request });
     return async (method, payload) => {
@@ -12,9 +13,7 @@ export function telegramApi(token, request = requestJson) {
         }
         catch (error) {
             if (error instanceof TelegramApiError) {
-                if (error.code === 409)
-                    throw new ConfigError(t('reply.telegramConflict'));
-                throw new ConfigError(t('reply.telegramRequestFailed'));
+                throw new TelegramRequestError(error.code);
             }
             throw error;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quecue/dev-notify",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "跨平台开发任务通知工具，支持 Telegram 与飞书",
   "license": "MIT",
   "repository": {