dsh-notify-me 1.18.0 → 1.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +66 -0
- package/README.en.md +124 -39
- package/README.md +114 -38
- package/cordis.patch.yml +13 -0
- package/lib/client.js +317 -22
- package/lib/host-fallback.js +20 -4
- package/lib/index.js +29 -8
- package/lib/mac-notify.js +178 -0
- package/lib/page-bridge.js +52 -8
- package/lib/relay.js +149 -14
- package/lib/win-toast.js +315 -0
- package/lib/win-toast.ps1 +66 -0
- package/macos/DSHNotify.swift +117 -0
- package/macos/build.sh +32 -0
- package/package.json +10 -3
- package/smoke/mac-notify-test.mjs +174 -0
- package/smoke/win-toast-test.mjs +203 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,72 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to **dsh-notify-me** are documented here.
|
|
4
4
|
|
|
5
|
+
## [1.20.0] — 2026-11-12
|
|
6
|
+
|
|
7
|
+
同源中继可以按网关自己的字段形状发请求体了:`relay.bodyTemplate` 写一段 JSON 模板,宿主渲染后转发;模板配错在宿主启动时就拦下,不会让每条提醒都回 500。
|
|
8
|
+
|
|
9
|
+
### 新增
|
|
10
|
+
|
|
11
|
+
- **同源中继支持自定义 JSON 请求体模板**(配置键 `relay.bodyTemplate`,[#34](https://github.com/chromoany/dsh-notify-me/pull/34),原提案 sakurakugu):网关不接受 Apprise 的 `{title, body, type}` 形状时(自有推送服务、MagicPush 风格的 REST API 等),写一段 JSON 模板,宿主用事件字段渲染后转发。占位符为 `{{title}}` `{{body}}` `{{text}}` `{{event}}` `{{time}}` `{{session}}` `{{source}}` `{{version}}`,其中 `{{session}}` 取载荷的 `sessionId`,占位符要写在 JSON 字符串里;代入值先按 JSON 字符串转义,所以标题里的引号、换行不会把模板弄坏。不配置这个键时行为与 1.19.0 完全一致。
|
|
12
|
+
- **模板在宿主启动时校验**:渲染结果不是 JSON 对象、或模板超过 16 KiB(UTF-8 字节),中继整条不挂载,日志留一行 warning 写明原因,状态回包与设置页也显示中继未启用——配错一次就能发现,而不是每条提醒都回 500。
|
|
13
|
+
- **渲染后的请求体另有 256 KiB 上限**:模板可以重复占位符把 64 KiB 的载荷放大,所以渲染结果超过上限时回 `500 {reason:'rendered-body-too-large'}` 且不发送;运行期的 `invalid-body-template` / `template-too-large` 作为配置漂移的兜底保留。
|
|
14
|
+
|
|
15
|
+
### 测试
|
|
16
|
+
|
|
17
|
+
- `smoke/relay-route-test.mjs` 新增:模板字段渲染、标题引号与换行的 JSON 转义、凭据仍由宿主提供、模板请求体不添加 Apprise 的 `type`、坏模板启动即不注册(warning 写明原因)、超大模板同样拦下、重复占位符放大超过上限时回 500 且不发送。
|
|
18
|
+
|
|
19
|
+
### 文档
|
|
20
|
+
|
|
21
|
+
- README 中英补 `relay.bodyTemplate` 的配置示例、占位符与转义规则、启动校验与两级体积上限;POST 契约与回包口径同步。
|
|
22
|
+
- `cordis.patch.yml` 的 relay 段补 `bodyTemplate` 行;致谢补 [#34](https://github.com/chromoany/dsh-notify-me/pull/34)(sakurakugu);版本升到 1.20.0。
|
|
23
|
+
|
|
24
|
+
## [1.19.0] — 2026-11-09
|
|
25
|
+
|
|
26
|
+
「回到页面也保留提醒」把 1.17.0 的收起动作交还给你;Windows 桌面端的审批通知终于带上真的「同意 / 拒绝」按钮,macOS 桌面端的系统通知改由宿主助手发出。同时收编 [#27](https://github.com/chromoany/dsh-notify-me/issues/27) / [#28](https://github.com/chromoany/dsh-notify-me/pull/28) / [#29](https://github.com/chromoany/dsh-notify-me/issues/29) / [#30](https://github.com/chromoany/dsh-notify-me/pull/30) / [#31](https://github.com/chromoany/dsh-notify-me/issues/31) / [#32](https://github.com/chromoany/dsh-notify-me/pull/32) / [#33](https://github.com/chromoany/dsh-notify-me/issues/33):把「转发外部通知」总开关接到宿主兜底上,并修掉 macOS 原生通道的几个边界。
|
|
27
|
+
|
|
28
|
+
### 新增
|
|
29
|
+
|
|
30
|
+
- **回到页面也保留提醒**(配置键 `keepOnReturn`,默认关;[#27](https://github.com/chromoany/dsh-notify-me/issues/27) / [#28](https://github.com/chromoany/dsh-notify-me/pull/28)):1.17.0 起只要回到 DSH 页面,残留通知一律收起。系统通知样式设成「持续」时,这正好把你要留着的提醒收走——现在打开这个开关,离开时收到的通知在你回到页面后不再被收起,留到你点掉或点「关闭」。它只管「回到页面收起残留通知」这一条;三种「自动消失」仍只管定时关闭。
|
|
31
|
+
- **一键「前台也提醒」**([#27](https://github.com/chromoany/dsh-notify-me/issues/27) 第 2 点):设置页「什么时候提醒」卡片顶部新增这一行,一次把「窗口在前台时也提醒『需要你』」打开、「当前对话不弹通知」关掉、「回复完成」设为「总是提醒」——等价于下面三项都调成前台可见。关掉它恢复默认的「只在后台提醒」。它不新增存储键,只是那三项的派生视图,三者任一被单独改动,这一行会跟着变。
|
|
32
|
+
- **Windows 桌面端审批通知带「同意 / 拒绝」按钮**([#33](https://github.com/chromoany/dsh-notify-me/issues/33)):Electron 的渲染进程把 `Notification` 的 `actions` 数组整个丢掉(`platform_notification_service.cc` 只抄 title/body/tag/icon/silent/has_reply/timeout_type),桌面端 `dsh-app://` 又注册不了 Service Worker——按钮因此从来没在 Windows 桌面出现过。现在审批提醒改由宿主发原生 Toast:`lib/index.js` 起 `lib/win-toast.ps1`(WinRT `ToastNotificationManager`,AUMID `electron.app.DeepSeek Harness`),按钮用 `activationType="protocol"` 指向 `dsh-notify-me://approve?token=…` / reject,点击后宿主把动作交回页面,仍走页面里同一个 `decidePending()`——「同意」就是「允许一次」,不多放行任何东西。首次使用时在 `HKCU\Software\Classes\dsh-notify-me` 注册协议处理器(一个把动作写入文件再打开 `dsh://open` 的 VBS);token 单次、3 分钟有效,动作文件取走即删。不需要编译、不需要管理员权限;关掉它:profile patch 层 `winToast: { enabled: false }`。
|
|
33
|
+
- **macOS 桌面端系统通知**([#31](https://github.com/chromoany/dsh-notify-me/issues/31) / [#32](https://github.com/chromoany/dsh-notify-me/pull/32),原提案 xty13114150041):页面里的 `new Notification()` 在 `dsh-app://app` 上进不了通知中心。新增 `lib/mac-notify.js` + `macos/DSHNotify.swift`(`macos/build.sh` 编译),宿主用 `UNUserNotificationCenter` 发通知;点通知把会话 id 写回临时文件并打开 `dsh://open`,页面重新获得焦点时取走并切到对应对话,`autoFocus` 关掉时只抬窗。`macNotify: { enabled, appPath }`,路由与助手都就绪时才生效;提示音仍由页面合成,「系统通知音」模式交给 macOS。
|
|
34
|
+
|
|
35
|
+
### 修复
|
|
36
|
+
|
|
37
|
+
- **总开关现在也管页面关闭后的宿主兜底**:宿主侧兜底(`hostFallback`)推送时只问了「有没有页面持有租约」,从不知道页面里那个总开关,心跳也刻意没带它。于是把「转发外部通知」关掉、再关掉标签页,宿主照样把「回复完成 / 审批请求」推到你的网关——正是刚被关掉的那条外部通知。现在心跳与 pagehide 释放都会带上 `external: {enabled, attention, done}`,宿主侧兜底照它决定推不推:总开关关了就两条都不推,「转发「需要你」」关了只留回复完成,「转发「回复完成」」关了只留审批。被开关压下的审批不占去重 id,开关再打开时同一审批仍会补上;被压下的 `turn/end` 也不吃掉那 15 秒节流窗口。
|
|
38
|
+
- **开关一改就立刻告诉宿主**:与静音列表同一条路径——改完马上补一次心跳,而不是等下一次间隔(最长 20 秒)。关掉开关、紧接着关标签页,不会再有那一段「宿主还按旧答案推送」的窗口。
|
|
39
|
+
- **半截的开关汇报按「没说过」处理**:`external` 只有三个字段全是布尔才被采纳;缺字段、写错类型都保留上一次的答案,绝不会因为读到 `enabled` 缺失就当成关闭,把运维明确打开的兜底悄悄静音。页面从没报过开关时(宿主刚起来、页面还没打开)兜底照旧按 `hostFallback.enabled` 推,不会被静音。
|
|
40
|
+
- **macOS 原生通道不再漏掉启动时的等待**:探测是异步的,而宿主起来时积压的等待可能在探测回包前就被绑定并计为「已提醒」——那一条用页面通知发不出去(macOS 桌面端本来就收不到),此后再也不会补发。现在探测完成前到达的提醒先排队,探测回包后统一重放;期间已被答掉的审批直接丢弃,不再补一条幽灵通知。探测同时加了「页面必须真的在桌面壳里」这一道门(`isDesktopShell()`),浏览器经隧道连到 macOS 宿主时不会再把提醒送进宿主机器。
|
|
41
|
+
- **原生通知也参与收起与自动消失**:macOS 通知中心里的那条原来不归 `trackToast()` 记账,回到页面收不掉,「总是关闭 / 从不关闭」也管不到它。助手新增 `--id` / `--remove` 两个参数(按请求 identifier 撤回),页面侧把原生通知按 tag 记账并交给同一套定时器与 `withdrawToasts()`——回到页面(或打开 `keepOnReturn` 时保留)、到点关闭,与构造器通知一致。Windows 原生 Toast 走同一条记账路径,`remove` 用 `ToastNotificationManager.History.Remove(tag, group, aumid)`。
|
|
42
|
+
- **助手可以按 id 撤回**:`lib/mac-notify.js` 的 `POST /__dsh-notify-me/mac-notify` 新增 `{remove: id}` 分支;`macos/DSHNotify.swift` 收到 `--remove <id>` 时调用 `removeDeliveredNotifications(withIdentifiers:)` 后退出。`--id` 为空时仍回落 UUID,旧助手没有这两个参数也不会被打坏(撤回失败只是留在通知中心,不影响提醒)。
|
|
43
|
+
- **macOS 路由测试不再依赖 POSIX shell**:原测试用 `#!/bin/sh` 桩当助手可执行文件,Windows CI 上 `spawn` 不认 shebang,恰是 Codex 在 #32 上标出的 P1。`mountMacNotify` 现在接受可注入的 `deps`(`spawn` / `execFile` / `clickFile`),测试用假 `spawn` + 普通空文件当助手,任何平台都跑;`smoke/win-toast-test.mjs` 同样用假 `spawn` 驱动 `reg.exe` / `powershell.exe`。
|
|
44
|
+
|
|
45
|
+
### 变更
|
|
46
|
+
|
|
47
|
+
- **设置页总开关的说明补上兜底**:中文「关闭后不向任何外部端点发送,页面关闭后的宿主兜底也一样。」、英文同样加一句,原先那句只描述页面自己。
|
|
48
|
+
- **健康探针新增 `pageExternal`**:报出页面最近一次汇报的开关(没报过是 `null`)。「兜底怎么不推了」这类问题,答案就在这里。
|
|
49
|
+
- **macOS 桌面端不再依赖页面通知权限**:路由可用时提示音仍由页面合成,只有「系统通知音」模式交给 macOS。
|
|
50
|
+
- **未注册原生路由的平台行为不变**:Linux、Web、助手未编译、`winToast` 关掉时都退回原来的页面通知;macOS 审批通知仍不带快捷裁决按钮,Windows 桌面端改由宿主 Toast 提供按钮。
|
|
51
|
+
- **设置页文案按通道分流**:「审批通知上直接裁决」的说明、「试一试」的反馈、「回到页面就收起」的边界都写明 Web 有按钮、Windows 桌面端有按钮、macOS 桌面端没有;`bridgeOffDesktop` 同样按通道说清。
|
|
52
|
+
- **原生通知与页面通知共用同一套开关**:`keepOnReturn` / 三种「自动消失」对宿主发出的通知同样生效;`debug()` 新增 `winNative` / `winNativeLast`。
|
|
53
|
+
|
|
54
|
+
### 测试
|
|
55
|
+
|
|
56
|
+
- `smoke/host-fallback-test.mjs` 新增两节:总开关关闭后两种提醒都不推出、打开后恢复、「需要你 / 回复完成」各自只静音自己那一类、被压下的审批不烧 id、页面从没报过开关时仍然推送。
|
|
57
|
+
- `smoke/page-bridge-test.mjs` 新增:`createPresence` 的 `externalAllowed()` 语义(未报告 → 放行、总开关 → 全静音、分项 → 只静音自己、半截报告 → 保留上一次、释放后仍记得),以及心跳里 `external` 字段的容错。
|
|
58
|
+
- `smoke/smoke-test.cjs`:心跳体改为 `{alive, external, language, muted}`,释放体为 `{alive, external, language}`;新增「改开关立即补一次心跳」;webhook 计数视图改为屏蔽整条 host-bridge 路由(探测、心跳、释放都算宿主协调,不算投递);`keepOnReturn` 打开后回到页面不再收起残留通知。
|
|
59
|
+
- `smoke/mac-notify-test.mjs` 重写:`mountMacNotify` 注入假 `spawn` / `execFile` 与临时 `clickFile`,助手只是普通文件、无需可执行位;覆盖未在 macOS 桌面宿主时不注册、缺助手时 `enabled:false` 与 `501`、探针、`405` / `403` / `400`、传入参数含 `--id` / `--sound`、`{remove:id}` 走撤回、点击回传只被取走一次。
|
|
60
|
+
- 新增 `smoke/win-toast-test.mjs`:Windows 桌面门控、探针与 `enabled`、`405` / `403` / `501` / `400`、审批 payload(AUMID / tag / 标题 / 按钮 token / 文案)与 base64 传递、`HKCU\Software\Classes\dsh-notify-me` 的三条注册命令、协议动作单次绑定审批 key、`open` 动作带会话、token 过期、`{remove}` 走 `-RemoveTag`。用假 `spawn` 驱动 `reg.exe` / `powershell.exe`,不需要真宿主。
|
|
61
|
+
- `npm test` 现在跑八套:上面这些加上原有的 host-route / page-bridge / host-fallback / relay / cordis-host,`smoke/smoke-test.cjs` 末尾断言 `api.version` 与 `package.json` 一致(1.19.0)。
|
|
62
|
+
|
|
63
|
+
### 文档
|
|
64
|
+
|
|
65
|
+
- README 中英的心跳契约更新为 `{alive, language, muted, external}`,并重写「心跳不带页面的推送开关」那段立场:可见性 / 闲置那类启发式仍然不带(宿主看不见,只照做一半会得到谁也说不清的规则),但用户亲手写进配置的开关与静音列表一样,宿主照它执行就是页面自己的意思。
|
|
66
|
+
- README 中英新增「Windows 桌面端怎么发带按钮的通知」一节;「macOS 桌面端怎么发系统通知」补上原生通知参与收起 / 自动消失、启动时排队的等待会重放、助手 `--id` / `--remove`;顶部导读、提醒渠道表、已知限制与开发自检的测试清单同步。
|
|
67
|
+
- `docs/console-config.md` / `.en.md` 补 `winToast`(profile patch 层配置,`{enabled:false}` 关掉宿主原生审批 Toast)与 `debug().winNative` / `winNativeLast`。
|
|
68
|
+
- `cordis.patch.yml` 补 `winToast` 配置行与注释;`docs/listing.md` 的 `latest` 更新到 1.19.0。
|
|
69
|
+
- 设置页截图按 1.19.0 重拍:中文 592×1170、英文 592×1188(比 1.18.0 多「前台也提醒(一键)」与「回到页面也保留提醒」两行,页脚版本号已是 `dsh-notify-me v1.19.0`),`docs/README.md` 的尺寸表与版本标注同步更新。
|
|
70
|
+
|
|
5
71
|
## [1.18.0] — 2026-11-08
|
|
6
72
|
|
|
7
73
|
回应 [#26](https://github.com/chromoany/dsh-notify-me/issues/26):会话行悬停时那两个图标已经挤到标题了——铃铛可以关掉,右键菜单里也放一个同样能用的。
|
package/README.en.md
CHANGED
|
@@ -18,17 +18,15 @@
|
|
|
18
18
|
|
|
19
19
|
</div>
|
|
20
20
|
|
|
21
|
-
[
|
|
21
|
+
[Preview](#ui-preview) · [Install](#installation) · [Settings](#configure-it-from-dsh-settings) · [Compatibility](#compatibility) · [Known limitations](#known-limitations) · [Changelog](CHANGELOG.md)
|
|
22
22
|
|
|
23
23
|
A notification plugin for DSH Web / Desktop, so you can afford to keep full access off without watching the page all day.
|
|
24
24
|
|
|
25
25
|
- **When input is needed:** approval, plan review, and questions get a notification, a sound, and a title marker.
|
|
26
26
|
- **When a background reply finishes:** come back for the result; clicking the notification returns to that conversation. Pick "background only", "quiet for the open one", or "always".
|
|
27
|
-
- **When you walk off but the window stays in front:** over 3 minutes without input counts as away, and the alert still fires as usual; the toast that arrived does not clear itself before you come back, and is withdrawn the moment you are back at the page (taskbar, Alt-Tab or the toast itself).
|
|
27
|
+
- **When you walk off but the window stays in front:** over 3 minutes without input counts as away, and the alert still fires as usual; the toast that arrived does not clear itself before you come back, and is withdrawn the moment you are back at the page (taskbar, Alt-Tab or the toast itself) — turn on "keep alerts when you come back" to let it wait there instead.
|
|
28
28
|
- **When you leave your computer:** optionally forward alerts to Discord, Bark, Gotify, Feishu group bots, ServerChan, WxPusher, or your own webhook.
|
|
29
|
-
- **When you close the page entirely:** optional host-side fallback — with no page open the host process keeps pushing "needs you" / "reply finished" to your gateway; or turn on just the same-origin relay so the page can reach an authenticated gateway. Both are off by default and configured in the profile's patch layer (see
|
|
30
|
-
|
|
31
|
-
> The page or desktop app has to stay running (background / minimized is fine); system notifications need notification permission. Approval buttons rely on a Service Worker, so only Web has them — Desktop notifications carry no buttons, and clicking one takes you back to the conversation to decide. With host-side fallback enabled you still get external push once the page is closed — local toasts and the approval buttons still need the page.
|
|
29
|
+
- **When you close the page entirely:** optional host-side fallback — with no page open the host process keeps pushing "needs you" / "reply finished" to your gateway; or turn on just the same-origin relay so the page can reach an authenticated gateway. Both are off by default and configured in the profile's patch layer (see [After the page closes: host-side fallback and the same-origin relay](#after-the-page-closes-host-side-fallback-and-the-same-origin-relay)).
|
|
32
30
|
|
|
33
31
|
## UI Preview
|
|
34
32
|
|
|
@@ -45,6 +43,10 @@ Just the plugin's own panel (the real component, on the same dark theme as the h
|
|
|
45
43
|
|
|
46
44
|
</details>
|
|
47
45
|
|
|
46
|
+
> **macOS Desktop (DSH Desktop)** raises its system notifications through a small host-spawned helper, `DSH Notify.app`: build it once with `bash macos/build.sh` and allow it in System Settings (see [How macOS Desktop raises system notifications](#how-macos-desktop-raises-system-notifications)).
|
|
47
|
+
|
|
48
|
+
> The page or desktop app has to stay running (background / minimized is fine); system notifications need notification permission. Approval buttons work on Web and Windows Desktop; macOS Desktop and pages without a Service Worker get a plain notification — click it and decide in the conversation (see [Alert channels](#alert-channels)). With host-side fallback enabled you still get external push once the page is closed — local toasts and the approval buttons still need the page.
|
|
49
|
+
|
|
48
50
|
## Installation
|
|
49
51
|
|
|
50
52
|
### DSH Web
|
|
@@ -72,17 +74,22 @@ The Electron application manages the `desktop` profile. Do not change the Web co
|
|
|
72
74
|
2. Open **Settings → Notify me**. Confirm that the section and the plugin version at its foot appear, and leave "Enable reminders" and "Sound" on.
|
|
73
75
|
3. Click **Test "reply finished"** on the settings page. A test notification should appear and play a sound according to your current sound settings. This local test is not forwarded to any external endpoint, and the "also alert while the window is in front" switch does not apply to it.
|
|
74
76
|
|
|
75
|
-
Web users can also test the approval buttons, which then appear on the notification. Desktop
|
|
77
|
+
Web users can also test the approval buttons, which then appear on the notification. Windows Desktop posts a native toast through the host and carries the same buttons; macOS Desktop sends a plain notification (the differences are in [Alert channels](#alert-channels)).
|
|
78
|
+
|
|
79
|
+
<details>
|
|
80
|
+
<summary>Optional console check</summary>
|
|
76
81
|
|
|
77
|
-
|
|
82
|
+
In environments with DevTools, you can also run:
|
|
78
83
|
|
|
79
84
|
```js
|
|
80
85
|
window.__dshNotifyMe.test("done") // "reply finished" sample
|
|
81
86
|
window.__dshNotifyMe.test("attention") // "needs you" sample
|
|
82
|
-
window.__dshNotifyMe.test("approval") // Approve / Reject when the bridge is available; a plain notification otherwise (
|
|
83
|
-
window.__dshNotifyMe.debug() // bridge ("active" = buttons work), raiseChannel, the last raise attempt in raiseLast, a refused toast's platform message in lastToastReject, configStored for whether the settings really persisted,
|
|
87
|
+
window.__dshNotifyMe.test("approval") // Approve / Reject when the bridge is available (Web) or through the Windows desktop host's native toast; a plain notification otherwise (macOS Desktop, or no Service Worker)
|
|
88
|
+
window.__dshNotifyMe.debug() // bridge ("active" = buttons work), raiseChannel, the last raise attempt in raiseLast, a refused toast's platform message in lastToastReject, configStored for whether the settings really persisted, hostBridge for host coordination, and the native channels in macNative / macNativeLast and winNative / winNativeLast; after coming back to the page, toastsLive / toastsWithdrawn / lastToastWithdrawAt show what is still tracked, how many were withdrawn, and when that last happened
|
|
84
89
|
```
|
|
85
90
|
|
|
91
|
+
</details>
|
|
92
|
+
|
|
86
93
|
If no test notification appears, check in this order: whether the notification permission was declined (click once on the page and choose **Allow**; or address-bar lock → Site settings → Notifications → Allow → reload), whether DSH was restarted after installing, and whether the browser's notifications are switched off in the OS settings.
|
|
87
94
|
|
|
88
95
|
## Why you need it
|
|
@@ -99,7 +106,7 @@ dsh-notify-me decouples **supervision** from **sitting in front of the screen**:
|
|
|
99
106
|
| 🔔 Input needed | Alerts even in the foreground; the conversation on screen keeps only a title marker |
|
|
100
107
|
| ✅ Reply finished | Alerts while the page is hidden / backgrounded (or "quiet for the open one" / "always") |
|
|
101
108
|
|
|
102
|
-
**Input needed** covers approval requests, plan review, and questions (`ask_user_question`). The approve / reject quick decision
|
|
109
|
+
**Input needed** covers approval requests, plan review, and questions (`ask_user_question`). The approve / reject quick decision works where a notification can carry buttons: Web through the Service Worker bridge, Windows Desktop through the host-posted native toast. macOS Desktop and pages without a Service Worker get a plain notification — click it and decide in the conversation (see [Known limitations](#known-limitations)).
|
|
103
110
|
|
|
104
111
|
**Reply finished** also covers background sessions. A finished but unread session keeps the `✅ Reply finished ·` title marker until opened. Title markers are independent of the alert policy.
|
|
105
112
|
|
|
@@ -115,16 +122,18 @@ Open **Settings → Notify me**. The page lays out three blocks — how you get
|
|
|
115
122
|
|
|
116
123
|
- **Enable reminders** — master switch: off means no toasts, no sound, and the tab title is left alone;
|
|
117
124
|
- **Sound / Volume** — the switch toggles directly; the volume slider is folded into that row and revealed by clicking the title (▸ becomes ▾). What it actually plays is decided by Advanced → Alert sound source;
|
|
118
|
-
- **Decide approvals from the toast** (on by default) — approvals carry Approve / Reject, one click settles the request without switching back. Web gets a system notification with buttons; Desktop `dsh-app://` cannot register a Service Worker
|
|
125
|
+
- **Decide approvals from the toast** (on by default) — approvals carry Approve / Reject, one click settles the request without switching back. Web gets a system notification with buttons; Windows Desktop gets a native toast posted by the host, with the same two buttons; macOS Desktop `dsh-app://` cannot register a Service Worker and its native helper carries no buttons, so there you click the notification and decide in the conversation. The line under "Try it" states truthfully whether the current environment can provide buttons.
|
|
119
126
|
|
|
120
127
|
### When to alert
|
|
121
128
|
|
|
122
129
|
- **Also alert "needs you" while the window is in front** (on by default): off means you only hear it once the window goes to the background;
|
|
130
|
+
- **Alert in the foreground too (one switch)** (off by default): turns on "also alert 'needs you' in the foreground", turns off "stay quiet for the conversation on screen", and sets "reply finished" to "always" in one click — it is not its own stored key, just a derived view of those three, and the row follows if you change one of them individually; turn it off to restore the default background-only behaviour;
|
|
123
131
|
- **Stay quiet for the conversation on screen** (on by default): a wait in the conversation you are looking at keeps only the tab marker, and is delivered once you leave;
|
|
124
132
|
- **When "reply finished" alerts** (default "background only"): background only / quiet for the open one / always — pick one;
|
|
125
133
|
- **Dismiss the toast automatically** (default "keep while away"): keep while away / always close / never close — pick one; the choice only covers the closing on the timer, and leftover toasts are withdrawn once you are back at the page;
|
|
134
|
+
- **Keep alerts when you come back** (off by default): when on, alerts that arrived while you were away are not withdrawn after you return to the DSH page — they stay until you dismiss them or click Close. Meant for an OS notification style that keeps alerts on screen, when the reminder itself should wait there;
|
|
126
135
|
- **Ignore subagent sessions** (on by default): skips background subagent sessions, while the one you have open still alerts;
|
|
127
|
-
- **Click a toast to open that conversation** (on by default): switches to that conversation and brings the window forward — on Windows through the host route, on macOS / Linux through the `dsh://open` deep link — and with several tabs only one is raised.
|
|
136
|
+
- **Click a toast to open that conversation** (on by default): switches to that conversation and brings the window forward — on Windows through the host route, on macOS / Linux through the `dsh://open` deep link — and with several tabs only one is raised. Host-posted native notifications (Windows native toast, macOS Notification Centre) use the same click handling.
|
|
128
137
|
|
|
129
138
|
<details>
|
|
130
139
|
<summary>Edge cases behind the switches</summary>
|
|
@@ -132,7 +141,7 @@ Open **Settings → Notify me**. The page lays out three blocks — how you get
|
|
|
132
141
|
- **What counts as background**: switching to another app, being covered by another window, or minimizing all count; a window left in front with 3 minutes of no keyboard or mouse input counts too, and `idleMinutes: 0` falls back to looking only at the window.
|
|
133
142
|
- **When "stay quiet for the conversation on screen" is replayed**: as usual once the window goes to the background or the idle timer fires; if you already handled it, it is dropped.
|
|
134
143
|
- **The three "reply finished" choices**: "background only" = alert when you are not watching the page; "quiet for the open one" = the one on screen stays silent while other conversations still alert, useful with several open; "always" = never suppress. An old profile's "also alert 'reply finished' while in front" switch migrates to this setting automatically.
|
|
135
|
-
- **"Keep while away"**: while you are at the page a plain toast closes itself after a few seconds; one that arrived while you were away stays in the notification centre until you come back. It is withdrawn the moment you are back (taskbar, Alt-Tab, the toast itself, or restoring a minimized window), and none of the three options affect that — so a toast you never opened in the notification centre is not left in your way. A toast with Approve / Reject carries no auto-dismiss timer — it stays until you click a button, answer the request in the page, or a newer request replaces it; a desktop approval toast, which cannot render buttons,
|
|
144
|
+
- **"Keep while away"**: while you are at the page a plain toast closes itself after a few seconds; one that arrived while you were away stays in the notification centre until you come back. It is withdrawn the moment you are back (taskbar, Alt-Tab, the toast itself, or restoring a minimized window), and none of the three options affect that — so a toast you never opened in the notification centre is not left in your way. **With "keep alerts when you come back" on, the return no longer withdraws them either** — they wait until you dismiss them or click Close, and stay on screen under a persistent OS notification style. A Web toast with Approve / Reject carries no auto-dismiss timer — it stays until you click a button, answer the request in the page, or a newer request replaces it; a macOS desktop approval toast, which cannot render buttons, and a Windows desktop native approval toast both close after 12 s and are likewise not withdrawn while you are away. Host-posted native notifications (the Windows native toast, macOS Notification Centre) are tracked by the same ledger: not withdrawn while you are away, withdrawn when you return unless that switch is on, and covered by the auto-dismiss choice as well.
|
|
136
145
|
- **Fallback for a toast click**: on Desktop a window that will not raise leaves only the conversation switch, with the reason in `debug().raiseLast`; turn this switch off and a click does nothing.
|
|
137
146
|
|
|
138
147
|
</details>
|
|
@@ -182,7 +191,7 @@ Off by default. Supports Discord Webhook / Bark / Gotify / Feishu group bots / S
|
|
|
182
191
|
<details>
|
|
183
192
|
<summary>Target URLs, forwarding switches, test messages, and the failure log</summary>
|
|
184
193
|
|
|
185
|
-
- **External notifications** (default off): forward each alert to your own push endpoints as well, so it reaches you away from the machine; any number of targets, each of which can be enabled or disabled on its own. "Forward 'needs you'" and "Forward 'reply finished'" switch independently; **Send test notification** sends one test message to every target (not limited by those two switches, and never pretending to be a real alert). Forwarding follows exactly the same trigger rules as local alerts ("stay quiet for the conversation on screen" and friends apply to it too); the alert text is sent as-is to the addresses you fill in, so **only use endpoints you trust**;
|
|
194
|
+
- **External notifications** (default off): forward each alert to your own push endpoints as well, so it reaches you away from the machine; any number of targets, each of which can be enabled or disabled on its own. "Forward 'needs you'" and "Forward 'reply finished'" switch independently; **Send test notification** sends one test message to every target (not limited by those two switches, and never pretending to be a real alert). Forwarding follows exactly the same trigger rules as local alerts ("stay quiet for the conversation on screen" and friends apply to it too); with the master switch off the **host-side fallback after a closed page stops too** (the switches ride the heartbeat — see "after the page closes"), so there is no "the page is gone but it still pushes"; the alert text is sent as-is to the addresses you fill in, so **only use endpoints you trust**;
|
|
186
195
|
- **What each target takes**: Discord — the webhook URL; Bark — `https://api.day.app/<device key>`; Gotify — `https://<server>/message?token=<app token>`; Feishu — the group-bot webhook plus an optional verification secret; ServerChan — the full `…/send/<SendKey>.send` URL; WxPusher — the appToken and the receiver UID; a custom endpoint receives one POST of JSON: `{source, event, title, body, text, sessionId, time}`;
|
|
187
196
|
- **Reliable delivery**: failures that look transient (network error, 5xx, 429) are retried after 2 s and 6 s; anything else stops at once. Switching forwarding off or deleting a target cancels a retry that is already on a timer — it is not counted as a failure and never reaches the failure log. A delivery that still fails is recorded in the failure log (10 entries at most — title and body snippet plus host only, never the full endpoint), which the settings page shows and can clear;
|
|
188
197
|
- **Service codes and "unverified"**: a 2xx from Feishu / ServerChan / WxPusher also carries a service code (`0` for Feishu and ServerChan, `1000` for WxPusher); a wrong code is recorded as a failure with the service's own message, and a 2xx whose body is not that service's JSON (empty, or a proxy/WAF HTML page) is "sent but unverified" rather than a success;
|
|
@@ -193,14 +202,27 @@ Off by default. Supports Discord Webhook / Bark / Gotify / Feishu group bots / S
|
|
|
193
202
|
|
|
194
203
|
</details>
|
|
195
204
|
|
|
196
|
-
####
|
|
205
|
+
#### Runtime & diagnostics
|
|
206
|
+
|
|
207
|
+
The last block inside Advanced. The page protocol is detected automatically to tell Web from Desktop (DSH Desktop, `dsh-app://`); override it by hand if detection is wrong — on Windows a toast click goes through the host route for native raising, on macOS / Linux through the `dsh://open` deep link (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised)), and the raise path itself carries no quick-decision buttons — those come from the Service Worker bridge on Web and from the host-posted native toast on Windows Desktop. When the manual override disagrees with detection the page says so.
|
|
208
|
+
|
|
209
|
+
<details>
|
|
210
|
+
<summary>Alert language, Desktop window raising, and reset</summary>
|
|
211
|
+
|
|
212
|
+
- **Alert language**: follow the UI / Simplified Chinese / English — governs the alert copy and the `🔔 …` title marker;
|
|
213
|
+
- **Desktop window raising**: on Windows the host route does the native activation, on macOS / Linux the `dsh://open` deep link does; raising back a minimized or covered window is measured to work on Windows and Linux (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised));
|
|
214
|
+
- **Reset settings**: restores every switch and sound setting to the factory defaults (external push targets and chosen custom audio files are kept).
|
|
215
|
+
|
|
216
|
+
</details>
|
|
217
|
+
|
|
218
|
+
## After the page closes: host-side fallback and the same-origin relay
|
|
197
219
|
|
|
198
220
|
Both live in the host process (`lib/host-fallback.js`, `lib/relay.js`, optional modules inside the package) and both are off by default: with no config the host registers the raise-window route and nothing else, so behaviour is identical before and after the upgrade. They are configured in the profile's patch layer, not on the Settings page — they make the host act on the page's behalf, they are not browser preferences; the Settings page only reports the state it probed.
|
|
199
221
|
|
|
200
222
|
<details>
|
|
201
223
|
<summary>Host-side fallback: the host keeps pushing after the page closes</summary>
|
|
202
224
|
|
|
203
|
-
With no page open the browser half does not run, and that is where alerts stop. The host-side fallback subscribes to the host's session event feed (`session/event`) and pushes the same two alerts to your gateway on its own once the page is closed.
|
|
225
|
+
With no page open the browser half does not run, and that is where alerts stop. The host-side fallback subscribes to the host's session event feed (`session/event`) and pushes the same two alerts to your gateway on its own once the page is closed. It shares the page's switches: the heartbeat reports `external: {enabled, attention, done}`, so turning off the 「Forward to external targets」 master switch (or just 「needs you」 / 「reply finished」) silences the fallback the same way — otherwise switching the master switch off and closing the tab would still deliver that last external alert.
|
|
204
226
|
|
|
205
227
|
An override example for the profile (`~/.dsh/profiles/<profile>/cordis.patch.yml`). **`config` is replaced wholesale, not deep-merged**: a patch row naming the same `id` assigns the whole `config`, which is why the example spells out all three blocks — an omitted key falls back to the plugin's own defaults (the same values as the bundled YAML), but a `gateway.target` wiped along with it does not come back on its own.
|
|
206
228
|
|
|
@@ -228,6 +250,7 @@ An override example for the profile (`~/.dsh/profiles/<profile>/cordis.patch.yml
|
|
|
228
250
|
path: ''
|
|
229
251
|
target: ''
|
|
230
252
|
credentialsFile: ''
|
|
253
|
+
bodyTemplate: '' # optional JSON template, see "Same-origin relay"
|
|
231
254
|
```
|
|
232
255
|
|
|
233
256
|
Key by key (defaults in parentheses):
|
|
@@ -245,7 +268,7 @@ Key by key (defaults in parentheses):
|
|
|
245
268
|
|
|
246
269
|
**The credentials file** is a mode-0600 JSON file readable by the host user, holding `{"user": "...", "password": "..."}` (sent as HTTP Basic) or `{"authorization": "Bearer ..."}` (sent verbatim; a bare token gets `Bearer ` prepended). It must not go into the patch layer — that layer is world-readable and lands in the profile directory. Leaving the key empty sends the request without an authentication header: plenty of webhook endpoints never ask for one, and treating a missing credentials file as an error would make every alert fail; only a path that is configured and unreadable counts as credentials-unavailable. When the gateway answers 401 / 403 the host drops the cached credential, re-reads the file and retries exactly once, so a rotated password needs no host restart.
|
|
247
270
|
|
|
248
|
-
**Deduplication rides on one page online lease**: on load the page probes `GET /__dsh-notify-me/host-bridge` once (and again every 60 s; no probe while the page is hidden, one catch-up probe when it becomes visible), and it only starts heartbeating when the reply says `hostFallback.enabled === true` — the body is `{alive, language, muted}` (`muted` being the ids of the sessions the user silenced), the interval is `leaseMs/3` clamped to 5–20 s, and `pagehide` releases immediately with one `{alive:false}` (sent with `keepalive`). A fresh host-side lease means no fallback push (the page is delivering), while an expired lease or an `alive:false` hands over, waiting at most `pageLeaseMs`. The heartbeat carries the language
|
|
271
|
+
**Deduplication rides on one page online lease**: on load the page probes `GET /__dsh-notify-me/host-bridge` once (and again every 60 s; no probe while the page is hidden, one catch-up probe when it becomes visible), and it only starts heartbeating when the reply says `hostFallback.enabled === true` — the body is `{alive, language, muted, external}` (`muted` being the ids of the sessions the user silenced, `external` the `{enabled, attention, done}` forward switches), the interval is `leaseMs/3` clamped to 5–20 s, a change to the mute list or to any forward switch beats immediately instead of waiting for that interval, and `pagehide` releases immediately with one `{alive:false, language, external}` (sent with `keepalive`). A fresh host-side lease means no fallback push (the page is delivering), while an expired lease or an `alive:false` hands over, waiting at most `pageLeaseMs`. The heartbeat carries the language, the mute list and the forward switches, because all three are settled state the user wrote into the config, so the host following them is the page speaking: the mute list keeps silenced sessions silent, and `external.enabled: false` (the 「Forward to external targets」 master switch off) stops the host fallback as well — otherwise turning the switch off and closing the tab would still deliver the external alert that was just switched off; `attention` / `done` gate 「needs you」 and 「reply finished」 respectively. What still stays out is the page's visibility and idle heuristics: the host cannot see them, and honouring half of them would produce a rule nobody can predict. The language it brings is what keeps an English page from getting Chinese host alerts, and it applies whenever `language: 'auto'`. `external` is only honoured when all three fields are booleans; an incomplete report keeps the previous answer, and a page that has never reported at all leaves the host on `hostFallback.enabled`. The list is trimmed by bytes on the wire (an 8 KiB budget, at most 200 ids): a session past the cut is still silenced locally, it is just no longer covered by the fallback. `pageLeaseMs: 0` turns coordination off so the host always pushes — the page then gets everything twice while it is open, so use it for debugging only.
|
|
249
272
|
|
|
250
273
|
**The two route contracts**: the probe the page calls, `GET /__dsh-notify-me/host-bridge`, answers `{ok, version, features, hostFallback:{enabled, leaseMs}, relay:{enabled, path, upstreamHost, upstreamPath}, language, page:{alive, ageMs}}` (`upstreamHost` / `upstreamPath` name the gateway the host forwards to, present only while the relay is enabled; the credential is never published); it is only registered while `hostFallback.enabled` or `relay.enabled` is true, so on a stock install it is a 404 and the page reads that as "off" rather than as a fault. The heartbeat `POST` requires the intent header `x-dsh-notify-me-page: bridge` (missing header → `403`), answers `400` to bad JSON and `413` to a body over 16 KiB, and `200 {ok, leaseUntil}` on success.
|
|
251
274
|
|
|
@@ -268,6 +291,25 @@ The page is left reporting "sent but unverifiable". The same-origin relay moves
|
|
|
268
291
|
|
|
269
292
|
Enabling it takes `relay.enabled: true`, an absolute `relay.path`, `relay.target` (empty falls back to `gateway.target`) and `relay.credentialsFile` (empty falls back to `gateway.credentialsFile`). The path is itself the capability — knowing it is enough to make the host send a notification for you, so it is worth as much as a password; keep a random token in it: `/__dsh-notify-me/relay/<32 hex token>`.
|
|
270
293
|
|
|
294
|
+
`relay.bodyTemplate` (optional) is for a gateway that does not accept the Apprise `{title, body, type}` shape: write a JSON template and the host renders the request body from it. Placeholders are `{{title}}` `{{body}}` `{{text}}` `{{event}}` `{{time}}` `{{session}}` (which reads the payload's `sessionId`) `{{source}}` `{{version}}`, and they belong inside JSON strings; values are JSON-string-escaped, so a quote or a newline in a title cannot break the template, a field the event does not carry renders as the empty string, and a field the template does not name never appears in the body.
|
|
295
|
+
|
|
296
|
+
The template is checked when the host boots: if it does not render to a JSON object, or the template is over 16 KiB (counted as UTF-8 bytes), the whole relay is not mounted, one warning line in the log names the reason, and both the status reply and the settings page show the relay as off — a misconfiguration shows up once instead of failing every alert with a 500. The rendered body has its own 256 KiB cap (a template may repeat placeholders and blow the body up); over it the route answers `500 {reason:'rendered-body-too-large'}` and sends nothing. Leaving the key empty keeps the original `{title, body, type:'info'}` payload unchanged.
|
|
297
|
+
|
|
298
|
+
Example: push alerts to your own push service (a MagicPush-style API below — it wants `channel_ids` + `title` + `content`, with the Bearer token in the host's mode-0600 credentials file):
|
|
299
|
+
|
|
300
|
+
```yaml
|
|
301
|
+
- id: notify-me
|
|
302
|
+
config:
|
|
303
|
+
relay:
|
|
304
|
+
enabled: true
|
|
305
|
+
path: '/__dsh-notify-me/relay/<32 hex token>'
|
|
306
|
+
target: 'https://push.example.com/api/v1/notifications/send'
|
|
307
|
+
credentialsFile: '/absolute/path/push-credentials.json' # {"authorization":"Bearer fn_push_..."}
|
|
308
|
+
bodyTemplate: '{"channel_ids":["<channel-id>"],"title":"{{title}}","content":"{{text}}"}'
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
The YAML single quotes keep the template as written; in the settings page point a **custom webhook** target at the same `target` and the request folds onto the relay route — the credential stays on the host either way.
|
|
312
|
+
|
|
271
313
|
How to use it: **Settings → Notify me → Advanced → External push** gains two read-only rows, and the "Same-origin relay" one shows `Enabled · address: <origin><relay.path>`; paste that absolute address into the URL of a **custom webhook** target on the same page, and the page never has to know the credentials.
|
|
272
314
|
|
|
273
315
|
You do not have to change the address either: **a "custom webhook" target that names the relay's own upstream gateway is folded onto the relay route when it is sent.** Such an address cannot work from a browser (the three CORS facts above block it, and the `no-cors` fallback is a *cross-site* POST that Apprise answers `403 Cross-site request rejected`), and older builds recorded that as `unverified` — the settings row read "last delivery sent-unverified" and the test button reported "sent-unverified", **while the phone stayed silent**. Folded, the request stays same-origin and the host adds the credential, so the verdict is the gateway's real status. Folding requires all of: the target is of type "custom", its URL's host equals `relay.upstreamHost`, its path equals `relay.upstreamPath`, it carries no signature secret (the signature is computed in the page and the relay cannot carry it), and it is not already same-origin with this page. If either the host or the path differs it is posted exactly as configured — one gateway usually serves several notify keys by path, so comparing the host alone would send key A's alert to key B; the settings page prints a note under any target that will be folded.
|
|
@@ -277,32 +319,20 @@ Behind a tunnel or reverse proxy the relay passes the same `Host` gate as the br
|
|
|
277
319
|
What comes back (which is how the page turns "sent but unverifiable" into something checkable):
|
|
278
320
|
|
|
279
321
|
- `GET` / `HEAD` `<relay.path>` → `200 {ok, route, version, enabled}`: a read-only probe that forwards nothing and carries no credential, but it does go through **the same gate as the other host entry points** — the path itself is the capability, so an ungated probe would tell whoever guessed it that the guess was right; use it to confirm that this process mounted the path you configured;
|
|
280
|
-
- `POST` → reads the body (64 KiB cap), requires a JSON object, maps it onto the gateway's `{title, body, type:'info'}` (the payload's `tag` is deliberately
|
|
322
|
+
- `POST` → reads the body (64 KiB cap), requires a JSON object, maps it onto the gateway's `{title, body, type:'info'}` (or onto a rendered `relay.bodyTemplate` JSON object when one is configured; the payload's `tag` is deliberately never forwarded: Apprise treats a tag as a service filter, and an unmatched one answers 424), and attaches `gateway.headers` plus the credentials; the request must carry the `x-dsh-notify-me-relay: relay` intent header, without it the answer is `403 {reason:'missing-intent'}` — a cross-site form post cannot set a custom header, and setting one costs a preflight the gateway always fails;
|
|
281
323
|
- `200 {ok, upstreamStatus, upstreamBody}` (with `upstreamBody` at most 500 characters) — the forward succeeded; a non-2xx from the gateway answers `502` in the same shape;
|
|
324
|
+
- `500 {reason}`: a template that cannot be used (`invalid-body-template` / `template-too-large` / `rendered-body-too-large`) — the first two are normally caught at boot; this is the runtime backstop, and nothing is sent;
|
|
282
325
|
- `400` (bad or empty JSON body), `413` (body over the cap), `405` (wrong method), `403` (refused by the gate, or a missing intent header), `503` (a credentials file is configured but cannot be read), `502 {reason:'upstream-error'}` (the upstream call itself failed, or the gateway answered 3xx — redirects are not followed, because following one would replay the body and the `Authorization` header somewhere else).
|
|
283
326
|
|
|
284
327
|
Credentials stay in the host: the page cannot read them, and they are never echoed into a response or a log line. The `POST` goes through the same gate as the other host entry points, so a forged caller (a cross-site page, a DNS-rebinding page) is refused even if it learns the path.
|
|
285
328
|
|
|
286
329
|
</details>
|
|
287
330
|
|
|
288
|
-
#### Runtime & diagnostics
|
|
289
|
-
|
|
290
|
-
The last block inside Advanced. The page protocol is detected automatically to tell Web from Desktop (DSH Desktop, `dsh-app://`); override it by hand if detection is wrong — on Windows a toast click goes through the host route for native raising, on macOS / Linux through the `dsh://open` deep link (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised)), and it carries no quick-decision buttons, while Web uses `window.focus()` plus the Service Worker bridge. When the manual override disagrees with detection the page says so.
|
|
291
|
-
|
|
292
|
-
<details>
|
|
293
|
-
<summary>Alert language, Desktop window raising, and reset</summary>
|
|
294
|
-
|
|
295
|
-
- **Alert language**: follow the UI / Simplified Chinese / English — governs the alert copy and the `🔔 …` title marker;
|
|
296
|
-
- **Desktop window raising**: on Windows the host route does the native activation, on macOS / Linux the `dsh://open` deep link does; raising back a minimized or covered window is measured to work on Windows and Linux (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised));
|
|
297
|
-
- **Reset settings**: restores every switch and sound setting to the factory defaults (external push targets and chosen custom audio files are kept).
|
|
298
|
-
|
|
299
|
-
</details>
|
|
300
|
-
|
|
301
331
|
## Alert channels
|
|
302
332
|
|
|
303
333
|
| Channel | What it does |
|
|
304
334
|
| --- | --- |
|
|
305
|
-
| System notification | Through the browser into the Windows / macOS / Linux notification centre; clicking it returns to the conversation it came from. Web can carry Approve / Reject |
|
|
335
|
+
| System notification | Through the browser into the Windows / macOS / Linux notification centre; clicking it returns to the conversation it came from. On macOS Desktop the host spawns `DSH Notify.app` to post it (see [How macOS Desktop raises system notifications](#how-macos-desktop-raises-system-notifications)); on Windows Desktop the host posts a native approval toast that carries Approve / Reject (see [How Windows Desktop raises buttoned notifications](#how-windows-desktop-raises-buttoned-notifications)). Web can carry Approve / Reject too |
|
|
306
336
|
| Sound | WebAudio cue by default, with different patterns for "needs you" and "done"; swap in a custom audio file, or hand the sound over to the system notification sound |
|
|
307
337
|
| Tab title | `🔔 Action needed · …` / `✅ Reply finished · …`, following the alert language; gone once you open that session, and both markers can be up at the same time |
|
|
308
338
|
| External push (optional, default off) | Forwards the same alert to Discord / Bark / Gotify / Feishu / ServerChan / WxPusher / a custom webhook |
|
|
@@ -339,12 +369,12 @@ The reminder core still has zero third-party runtime dependencies and is fully s
|
|
|
339
369
|
|
|
340
370
|
### Quick decisions, and how they reach the agent
|
|
341
371
|
|
|
342
|
-
|
|
372
|
+
On Web, notifications with Approve / Reject buttons can only be raised by a Service Worker (passing `actions` to `new Notification()` throws a `TypeError` outright), so the same bundle file is registered a second time as a worker whose only job is relaying which button was clicked back to the page; on Windows Desktop the host posts a native toast with the same two buttons instead. **The decision still happens in the page** either way, through the same `PendingApproval.answer('allowed-once' | 'rejected')` the approval panel uses for Allow once / Reject — so "Approve" is exactly "Allow once" and releases nothing extra.
|
|
343
373
|
|
|
344
374
|
<details>
|
|
345
375
|
<summary>Button-toast bookkeeping and window raising</summary>
|
|
346
376
|
|
|
347
|
-
Each button toast is booked against its interaction key, and one toast claims only one wait; once the request has been answered in the page, or replaced by a newer request, clicking the leftover buttons decides nothing and just closes it quietly. Button toasts carry no auto-dismiss timer — they stay until you click or answer; plain toasts close after 5 s, and a desktop approval toast without buttons after 12 s. With "never close" selected neither kind closes on the timer; all three options cover that timer only, so anything still up is withdrawn once you are back at the page. If you miss the click, the approval in the conversation is still waiting for you.
|
|
377
|
+
Each button toast is booked against its interaction key, and one toast claims only one wait; once the request has been answered in the page, or replaced by a newer request, clicking the leftover buttons decides nothing and just closes it quietly. Button toasts carry no auto-dismiss timer — they stay until you click or answer; plain toasts close after 5 s, and a desktop approval toast without buttons after 12 s. With "never close" selected neither kind closes on the timer; all three options cover that timer only, so anything still up is withdrawn once you are back at the page (not when "keep alerts when you come back" is on). If you miss the click, the approval in the conversation is still waiting for you.
|
|
348
378
|
|
|
349
379
|
The "raise a window and switch its conversation" part of a body click is scheduled on the worker half as well: `client.focus()` raises exactly one window (a visible one first) and routes the conversation switch to that window alone, so several DSH tabs never fight over focus or all switch at once.
|
|
350
380
|
|
|
@@ -371,6 +401,32 @@ The cases where it will not raise are the same ones listed under [Known limitati
|
|
|
371
401
|
|
|
372
402
|
</details>
|
|
373
403
|
|
|
404
|
+
### How macOS Desktop raises system notifications
|
|
405
|
+
|
|
406
|
+
On macOS Desktop (`dsh-app://app`) the page's own `new Notification()` never reaches the Notification Centre — nothing is shown and nothing throws (`Notification.permission` still reads `granted`). The plugin takes the host path there instead: the page POSTs `/__dsh-notify-me/mac-notify`, the host (`lib/mac-notify.js`) spawns the helper app in `macos/`, and that helper posts a real `UNUserNotificationCenter` notification.
|
|
407
|
+
|
|
408
|
+
- **One-time setup**: `bash macos/build.sh` builds `macos/DSH Notify.app` (needs Xcode Command Line Tools, a few seconds). The bundle is `.gitignore`d, so it is in neither the repository nor the npm package. Allow it under System Settings → Notifications → DSH Notify the first time one arrives.
|
|
409
|
+
- **Which path is used is automatic**: the host registers the route only when all three hold — macOS, the desktop shell (the Electron binary), and a built helper. Otherwise the `GET` probe reports `enabled: false` and the page keeps its own notification, exactly as before this change. `dsh web` in a browser never reaches the route.
|
|
410
|
+
- **Clicking returns to that conversation**: the helper writes the session id to `dsh-notify-me-click.json` in the temp directory and opens `dsh://open` to raise the window; the next time the page regains focus it `GET`s that id once, switches to the conversation and clears it, so nothing jumps twice. With `autoFocus` off the window is raised but the conversation is left alone.
|
|
411
|
+
- **Sound**: the "system notification sound" mode hands the sound to macOS; the synthesized modes stay in the page, so the two never stack.
|
|
412
|
+
- **Still no Approve / Reject buttons**: notification actions require registered categories, and the helper never touches approval state — decisions stay in the conversation.
|
|
413
|
+
- **Turning it off**: add `macNotify: { enabled: false }` to the `notify-me` entry in the profile's patch layer, or delete `macos/DSH Notify.app` and the probe falls back to `enabled: false`.
|
|
414
|
+
|
|
415
|
+
Like the window-raise route, this one registers exactly one exact path and refuses everything else: anything but GET / POST is `405` (including the preflight `OPTIONS`, which never gets a CORS header), a non-loopback peer or an unlisted `Host` / `Origin` is `403`, a POST without the `x-dsh-notify-me-mac: notify` header is `403`, a missing helper is `501`, and a body that is not a notification is `400`. The reply carries no system information, only the helper's exit status.
|
|
416
|
+
|
|
417
|
+
### How Windows Desktop raises buttoned notifications
|
|
418
|
+
|
|
419
|
+
The page's own `new Notification()` is not refused on Windows Desktop, but it cannot carry buttons: Electron's renderer hands the platform only title / body / tag / icon / silent and drops the `actions` array entirely (`DisplayNotification()` in `shell/browser/notifications/platform_notification_service.cc`); and a `dsh-app://` page cannot register a Service Worker, while only a Service Worker can draw button notifications. The plugin therefore posts approval alerts through the host as native toasts.
|
|
420
|
+
|
|
421
|
+
- **Who posts it**: the host half (`lib/index.js`) registers `POST /__dsh-notify-me/win-toast` and runs one `powershell.exe` with `lib/win-toast.ps1`, which sends the toast through the WinRT `ToastNotificationManager` under the "DeepSeek Harness" AUMID — the same notification stack DSH's own notifications use, so it follows the same system notification settings.
|
|
422
|
+
- **How the buttons decide**: the toast's two buttons use `activationType="protocol"` and point at `dsh-notify-me://approve?token=…` / reject. Clicking one invokes the handler registered for that protocol (a VBS that writes the action to a file and opens `dsh://open`); the host hands the action back on the page's next probe, and the page still goes through the same `decidePending()` the approval panel uses — "Approve" is "Allow once" and releases nothing extra.
|
|
423
|
+
- **Registration**: the first buttoned toast registers that handler under `HKCU\Software\Classes\dsh-notify-me` (current-user, no admin rights needed) and books the toast into `ToastNotificationManager.History` by tag. Tokens are single-use and valid for 3 minutes; an action file is deleted once taken.
|
|
424
|
+
- **When it does not post**: outside the Windows desktop host, with `winToast.enabled: false`, or without `powershell.exe`, the route reports `enabled: false` (`501`) and the page keeps its own buttonless notification — the same behaviour as before this change.
|
|
425
|
+
- **Turning it off**: add `winToast: { enabled: false }` to the `notify-me` entry in the profile's patch layer; approval alerts go back to the page's own notification, without buttons.
|
|
426
|
+
- **Auto-dismiss and withdrawal**: native toasts are tracked by `trackToast()`: a plain toast closes after 5 s, a buttoned approval after 12 s ("always close" / "never close" still apply), and they are withdrawn when you come back to the page unless "keep alerts when you come back" is on.
|
|
427
|
+
|
|
428
|
+
Like the other routes, this one registers exactly one exact path and refuses everything else: anything but GET / POST is `405`, a non-loopback peer or an unlisted `Host` / `Origin` is `403`, a POST without the `x-dsh-notify-me-win: toast` header is `403`, and a body that is not a valid notification is `400`. The reply reports the delivery status only, never system information.
|
|
429
|
+
|
|
374
430
|
## Known limitations
|
|
375
431
|
|
|
376
432
|
**Runtime prerequisites**
|
|
@@ -382,11 +438,11 @@ The cases where it will not raise are the same ones listed under [Known limitati
|
|
|
382
438
|
|
|
383
439
|
**Platform differences**
|
|
384
440
|
|
|
385
|
-
- Quick-decision buttons need a Service Worker: `http://127.0.0.1` and `https` work, `http://192.168.x.x`-style LAN addresses do not; **the Desktop (`dsh-app://`) is tested and cannot register a Service Worker** (the host does not grant the `allowServiceWorkers` privilege)
|
|
441
|
+
- Quick-decision buttons need a Service Worker: `http://127.0.0.1` and `https` work, `http://192.168.x.x`-style LAN addresses do not; **the Desktop (`dsh-app://`) is tested and cannot register a Service Worker** (the host does not grant the `allowServiceWorkers` privilege): on Windows Desktop approval alerts are posted by the host as native toasts with real buttons (see [How Windows Desktop raises buttoned notifications](#how-windows-desktop-raises-buttoned-notifications)), while macOS Desktop falls back to a buttonless notification. When the host renders no notification buttons, the `bridge` field of `debug()` explains why, and nothing else is affected.
|
|
386
442
|
- Windows caps a toast tag at 64 characters, and Chromium hands the platform the whole `n#<origin>#<tag>` string — the desktop page's `dsh-app://app` alone takes 16. The plugin sizes each tag against the current `location.origin` and, when it does not fit, keeps a readable prefix and swaps the tail for a short hash, so a tag seen through `debug()` may be shortened; if the platform still refuses one, its message lands in `debug().lastToastReject` and the settings test button reports it instead of claiming the toast was sent.
|
|
387
443
|
- On Desktop (Windows) a toast click can still fail to raise the window: when the target window is owned by a higher integrity level (elevated / UAC), sits on another virtual desktop, has its foreground repeatedly stolen by another process, or is hidden to the tray with `SW_HIDE`, the host script answers `FOCUSED=0` and the route answers `202`, with the conversation switch intact (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised)).
|
|
388
444
|
- Desktop (macOS / Linux) toast clicks rely on the `dsh://open` deep link: when the system has no `x-scheme-handler/dsh` registration, or the shell has no `second-instance` / `open-url` handling, the window will not raise. Measured to work on Linux; macOS is untested.
|
|
389
|
-
- macOS:
|
|
445
|
+
- macOS Desktop: the page's own `new Notification()` never reaches the Notification Centre (`Notification.permission` reads `granted` yet nothing shows), so the plugin posts through a host-spawned helper — build it once with `bash macos/build.sh` (see [How macOS Desktop raises system notifications](#how-macos-desktop-raises-system-notifications)). Without the helper it falls back to the old behaviour, i.e. no system notification on Desktop. Approval buttons still do not render on the macOS desktop host; Windows Desktop posts a native toast with working buttons (see [How Windows Desktop raises buttoned notifications](#how-windows-desktop-raises-buttoned-notifications)).
|
|
390
446
|
|
|
391
447
|
**Alert content and timing**
|
|
392
448
|
|
|
@@ -409,13 +465,20 @@ The cases where it will not raise are the same ones listed under [Known limitati
|
|
|
409
465
|
```sh
|
|
410
466
|
node --check lib/client.js
|
|
411
467
|
node --check lib/index.js
|
|
412
|
-
npm test # smoke-test (state machine) + host-route-test (host half) + page-bridge-test + host-fallback-test + relay-route-test + cordis-host-test
|
|
468
|
+
npm test # smoke-test (state machine) + host-route-test (host half) + page-bridge-test + host-fallback-test + relay-route-test + cordis-host-test + mac-notify-test + win-toast-test
|
|
413
469
|
npm pack --dry-run # preview the published tarball
|
|
414
470
|
```
|
|
415
471
|
|
|
472
|
+
<details>
|
|
473
|
+
<summary>What each suite covers, and the manual raise check</summary>
|
|
474
|
+
|
|
416
475
|
`smoke/smoke-test.cjs` is the offline state-machine suite: three host generations + master switch + zh/en cases + the quick-decision bridge (worker half included) + idle detection and toast self-dismiss + withdrawing leftover toasts on return + toast tag length handling + the page's host-bridge probe / heartbeat / release and the shape of `debug().hostBridge`. `smoke/host-route-test.mjs` needs no local DSH and runs the `lib/index.js` route, its probe and the 403/405/501 gate on every platform.
|
|
417
476
|
|
|
418
|
-
The three new suites also ship their own fake `ctx`, need no local DSH and touch no network: `smoke/page-bridge-test.mjs` runs the page-bridge route — status shape, heartbeat and release, missing intent header `403`, cross-origin `403`, bad JSON `400`, oversized `413`, the `allowedOrigins`-derived `Host` (a simulated tunnel) being let through, and path collisions; `smoke/host-fallback-test.mjs` runs the host fallback — approval dedupe, `turn/end` throttling, subagent skip, no push on a fresh lease, a push after the lease expires, an immediate push after `alive:false`, language following the heartbeat, credentials re-read after a 401, and the health probe; `smoke/relay-route-test.mjs` runs the relay — the `GET` probe, `405`, cross-origin `403`, `413`, `400`, `503`, the `200` / `502` mapping and "retry exactly once on a 401".
|
|
477
|
+
The three new suites also ship their own fake `ctx`, need no local DSH and touch no network: `smoke/page-bridge-test.mjs` runs the page-bridge route — status shape, heartbeat and release, missing intent header `403`, cross-origin `403`, bad JSON `400`, oversized `413`, the `allowedOrigins`-derived `Host` (a simulated tunnel) being let through, and path collisions; `smoke/host-fallback-test.mjs` runs the host fallback — approval dedupe, `turn/end` throttling, subagent skip, no push on a fresh lease, a push after the lease expires, an immediate push after `alive:false`, language following the heartbeat, credentials re-read after a 401, and the health probe; `smoke/relay-route-test.mjs` runs the relay — the `GET` probe, `405`, cross-origin `403`, `413`, `400`, `503`, the `200` / `502` mapping and "retry exactly once on a 401", `relay.bodyTemplate` rendering and JSON escaping, a broken template registering no route at boot, and the rendered-size cap.
|
|
478
|
+
|
|
479
|
+
`smoke/mac-notify-test.mjs` runs the macOS notification route: registered only on the macOS desktop host, the probe, the `405` / `403` / `501` / `400` refusals, the arguments handed to the helper, and the click hand-off being taken exactly once. It fakes the platform and Electron version, needs no real helper, and runs on every platform.
|
|
480
|
+
|
|
481
|
+
`smoke/win-toast-test.mjs` runs the Windows native-toast route: the Windows desktop gate, the `GET` probe, the `405` / `403` / `501` / `400` refusals, the approval payload and its base64 pass-through, the three `HKCU\Software\Classes\dsh-notify-me` registration commands, approve / reject / open actions being claimed once, token expiry, and `{remove}` withdrawal. It drives `reg.exe` / `powershell.exe` through a fake `spawn`, so it needs no real Windows desktop host and runs on every platform.
|
|
419
482
|
|
|
420
483
|
When `lib/focus-window.ps1` changes (Windows only), also run it by hand:
|
|
421
484
|
|
|
@@ -425,6 +488,8 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # the last line
|
|
|
425
488
|
|
|
426
489
|
`cordis-host-test.mjs` borrows `@deepseek-ai/cordis` from a local DSH installation (it probes the global npm directory, `~/.dsh/profiles/web/node_modules` and the flat fallback `~/.dsh/profiles/node_modules` in turn); in a source checkout with no profile dependencies, point it there with `DSH_CORDIS_PATH=<checkout>/vendor/cordis/lib/index.js`.
|
|
427
490
|
|
|
491
|
+
</details>
|
|
492
|
+
|
|
428
493
|
## Credits & how contributions land
|
|
429
494
|
|
|
430
495
|
| Contributor | Contribution |
|
|
@@ -440,11 +505,31 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # the last line
|
|
|
440
505
|
| <a href="https://github.com/Donald-Yip"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/Donald-Yip.png" width="40" height="40" alt="@Donald-Yip"></a> | [#18](https://github.com/chromoany/dsh-notify-me/issues/18): the report that a Windows notification tag over the 64-character cap made the platform silently reject the approval test toast |
|
|
441
506
|
| <a href="https://github.com/dunxuan"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/dunxuan.png" width="40" height="40" alt="@dunxuan"></a> | [#20](https://github.com/chromoany/dsh-notify-me/issues/20): the report that alerts for the open session showed a placeholder instead of the session title |
|
|
442
507
|
| <a href="https://github.com/unnamed42"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/unnamed42.png" width="40" height="40" alt="@unnamed42"></a> | [#21](https://github.com/chromoany/dsh-notify-me/issues/21) / [#22](https://github.com/chromoany/dsh-notify-me/pull/22): the Linux `dsh://open` raise-path report and patch, which brought the deep link back on macOS / Linux in 1.14.4 |
|
|
443
|
-
| <a href="https://github.com/LIEGU0317"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/LIEGU0317.png" width="40" height="40" alt="@LIEGU0317"></a> | [#24](https://github.com/chromoany/dsh-notify-me/issues/24) / [#25](https://github.com/chromoany/dsh-notify-me/pull/25): the host-side fallback push and same-origin relay modules (optional, off by default), with tests and docs |
|
|
508
|
+
| <a href="https://github.com/LIEGU0317"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/LIEGU0317.png" width="40" height="40" alt="@LIEGU0317"></a> | [#24](https://github.com/chromoany/dsh-notify-me/issues/24) / [#25](https://github.com/chromoany/dsh-notify-me/pull/25): the host-side fallback push and same-origin relay modules (optional, off by default), with tests and docs; [#29](https://github.com/chromoany/dsh-notify-me/issues/29) / [#30](https://github.com/chromoany/dsh-notify-me/pull/30): the host fallback ignored the "Forward to external targets" switch (the heartbeat and pagehide now carry `external`), landing in 1.19.0 |
|
|
444
509
|
| <a href="https://github.com/ekexium"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/ekexium.png" width="40" height="40" alt="@ekexium"></a> | [#23](https://github.com/chromoany/dsh-notify-me/issues/23): the per-conversation mute request (an on/off switch per session, persistence across restarts, a mark on the session row), supported since 1.16.0 |
|
|
510
|
+
| <a href="https://github.com/AomiRaku"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/AomiRaku.png" width="40" height="40" alt="@AomiRaku"></a> | [#26](https://github.com/chromoany/dsh-notify-me/issues/26): the report that the row's hover buttons were covering the title, asking for a switchable mute bell and a mute entry in the context menu — shipped in 1.18.0 |
|
|
511
|
+
| <a href="https://github.com/Matthew-Laplace"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/Matthew-Laplace.png" width="40" height="40" alt="@Matthew-Laplace"></a> | [#27](https://github.com/chromoany/dsh-notify-me/issues/27) / [#28](https://github.com/chromoany/dsh-notify-me/pull/28): the `keepOnReturn` proposal and minimal patch (keep alerts after coming back to the page), plus the ask for a single "alert in the foreground too" preset — supported since 1.19.0 |
|
|
512
|
+
| <a href="https://github.com/xty13114150041"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/xty13114150041.png" width="40" height="40" alt="@xty13114150041"></a> | [#31](https://github.com/chromoany/dsh-notify-me/issues/31) / [#32](https://github.com/chromoany/dsh-notify-me/pull/32): the macOS Desktop "notifications never arrive" investigation and the host-helper approach (`lib/mac-notify.js` + `macos/`) — supported since 1.19.0 |
|
|
513
|
+
| <a href="https://github.com/Inh-ui"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/Inh-ui.png" width="40" height="40" alt="@Inh-ui"></a> | [#33](https://github.com/chromoany/dsh-notify-me/issues/33): the report that Windows Desktop approval notifications carry no Approve / Reject buttons, with the source-level finding that Electron drops `actions` and Desktop cannot register a Service Worker — fixed in 1.19.0 |
|
|
514
|
+
| <a href="https://github.com/sakurakugu"><img src="https://raw.githubusercontent.com/chromoany/dsh-notify-me/main/docs/contributors/sakurakugu.png" width="40" height="40" alt="@sakurakugu"></a> | [#34](https://github.com/chromoany/dsh-notify-me/pull/34): the custom JSON body template for the same-origin relay (`relay.bodyTemplate`), with tests and docs — supported since 1.20.0 |
|
|
445
515
|
|
|
446
516
|
Attribution policy: external PRs are landed as maintainer commits — the original commit is not reused and no Co-authored-by trailer is added, so GitHub's contributors graph lists the maintainer only and contributors are credited above.
|
|
447
517
|
|
|
518
|
+
## Star History
|
|
519
|
+
|
|
520
|
+
<details>
|
|
521
|
+
<summary>Show the Star History chart</summary>
|
|
522
|
+
|
|
523
|
+
<a href="https://www.star-history.com/?repos=chromoany%2Fdsh-notify-me&type=timeline&legend=bottom-right">
|
|
524
|
+
<picture>
|
|
525
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=chromoany/dsh-notify-me&type=date&theme=dark&legend=bottom-right" />
|
|
526
|
+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=chromoany/dsh-notify-me&type=date&legend=bottom-right" />
|
|
527
|
+
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=chromoany/dsh-notify-me&type=date&legend=bottom-right" />
|
|
528
|
+
</picture>
|
|
529
|
+
</a>
|
|
530
|
+
|
|
531
|
+
</details>
|
|
532
|
+
|
|
448
533
|
## License
|
|
449
534
|
|
|
450
535
|
MIT — see [LICENSE](LICENSE).
|