dsh-notify-me 1.19.0 → 1.20.1

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 CHANGED
@@ -2,6 +2,37 @@
2
2
 
3
3
  All notable changes to **dsh-notify-me** are documented here.
4
4
 
5
+ ## [1.20.1] — 2026-11-13
6
+
7
+ Windows 中文用户名下点审批通知的「同意 / 拒绝」不再弹脚本错误:协议处理器改成纯 ASCII + UTF-16LE BOM 落盘。
8
+
9
+ ### 修复
10
+
11
+ - **非 ASCII 用户名下点通知按钮必弹 800A004C**([#36](https://github.com/chromoany/dsh-notify-me/issues/36)):`notify-handler.vbs` 原来按 UTF-8 无 BOM 写入,且把 `C:\Users\<用户名>\AppData\Local\dsh-notify-me\actions` 整个绝对路径烘进脚本。WSH 用系统 ANSI 代码页(中文是 CP936)解码这种文件,中文用户名被按双字节拆开、路径里的反斜杠被吃掉,第 8 行 `FolderExists` 找不到目录,于是每次点按钮都弹 Windows Script Host 错误框,动作写不进 actions 目录,DSH 也不会被唤回。现在脚本里只写 `sh.ExpandEnvironmentStrings("%LOCALAPPDATA%") & "\dsh-notify-me\actions"`,点击时才解析路径,脚本正文保持纯 ASCII;文件本身同时改成 UTF-16LE + BOM 写入,将来真有非 ASCII 进脚本也不会被按 ANSI 解码。
12
+
13
+ ### 测试
14
+
15
+ - `smoke/win-toast-test.mjs` 原来用 UTF-8 回读脚本并断言包含临时目录路径,恰好把编码问题盖住;现在断言脚本带 UTF-16LE BOM、正文纯 ASCII、含 `ExpandEnvironmentStrings` 表达式、不烘入任何 profile 路径。测试把 `LOCALAPPDATA` 指向临时目录,走的是生产分支。
16
+
17
+ ## [1.20.0] — 2026-11-12
18
+
19
+ 同源中继可以按网关自己的字段形状发请求体了:`relay.bodyTemplate` 写一段 JSON 模板,宿主渲染后转发;模板配错在宿主启动时就拦下,不会让每条提醒都回 500。
20
+
21
+ ### 新增
22
+
23
+ - **同源中继支持自定义 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 完全一致。
24
+ - **模板在宿主启动时校验**:渲染结果不是 JSON 对象、或模板超过 16 KiB(UTF-8 字节),中继整条不挂载,日志留一行 warning 写明原因,状态回包与设置页也显示中继未启用——配错一次就能发现,而不是每条提醒都回 500。
25
+ - **渲染后的请求体另有 256 KiB 上限**:模板可以重复占位符把 64 KiB 的载荷放大,所以渲染结果超过上限时回 `500 {reason:'rendered-body-too-large'}` 且不发送;运行期的 `invalid-body-template` / `template-too-large` 作为配置漂移的兜底保留。
26
+
27
+ ### 测试
28
+
29
+ - `smoke/relay-route-test.mjs` 新增:模板字段渲染、标题引号与换行的 JSON 转义、凭据仍由宿主提供、模板请求体不添加 Apprise 的 `type`、坏模板启动即不注册(warning 写明原因)、超大模板同样拦下、重复占位符放大超过上限时回 500 且不发送。
30
+
31
+ ### 文档
32
+
33
+ - README 中英补 `relay.bodyTemplate` 的配置示例、占位符与转义规则、启动校验与两级体积上限;POST 契约与回包口径同步。
34
+ - `cordis.patch.yml` 的 relay 段补 `bodyTemplate` 行;致谢补 [#34](https://github.com/chromoany/dsh-notify-me/pull/34)(sakurakugu);版本升到 1.20.0。
35
+
5
36
  ## [1.19.0] — 2026-11-09
6
37
 
7
38
  「回到页面也保留提醒」把 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 原生通道的几个边界。
@@ -47,7 +78,7 @@ All notable changes to **dsh-notify-me** are documented here.
47
78
  - README 中英新增「Windows 桌面端怎么发带按钮的通知」一节;「macOS 桌面端怎么发系统通知」补上原生通知参与收起 / 自动消失、启动时排队的等待会重放、助手 `--id` / `--remove`;顶部导读、提醒渠道表、已知限制与开发自检的测试清单同步。
48
79
  - `docs/console-config.md` / `.en.md` 补 `winToast`(profile patch 层配置,`{enabled:false}` 关掉宿主原生审批 Toast)与 `debug().winNative` / `winNativeLast`。
49
80
  - `cordis.patch.yml` 补 `winToast` 配置行与注释;`docs/listing.md` 的 `latest` 更新到 1.19.0。
50
- - 设置页截图未重拍:两张都还是 1.18.0 的界面,1.19.0 在「什么时候提醒」里多了一行「前台也提醒(一键)」,`docs/README.md` 的尺寸表已按这个口径标注。
81
+ - 设置页截图按 1.19.0 重拍:中文 592×1170、英文 592×1188(比 1.18.0 多「前台也提醒(一键)」与「回到页面也保留提醒」两行,页脚版本号已是 `dsh-notify-me v1.19.0`),`docs/README.md` 的尺寸表与版本标注同步更新。
51
82
 
52
83
  ## [1.18.0] — 2026-11-08
53
84
 
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 chromoany
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 chromoany
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md CHANGED
@@ -18,7 +18,7 @@
18
18
 
19
19
  </div>
20
20
 
21
- [Install](#installation) · [Preview](#ui-preview) · [Settings](#configure-it-from-dsh-settings) · [Compatibility](#compatibility) · [Known limitations](#known-limitations) · [Changelog](CHANGELOG.md)
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
 
@@ -26,11 +26,7 @@ A notification plugin for DSH Web / Desktop, so you can afford to keep full acce
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
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 "After the page closes" under [Advanced](#advanced)).
30
-
31
- > **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)).
32
-
33
- > 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 Web gets them through the page's own notification; Windows Desktop gets them through a native toast posted by the host, while macOS Desktop notifications still carry no buttons — 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)).
34
30
 
35
31
  ## UI Preview
36
32
 
@@ -47,6 +43,10 @@ Just the plugin's own panel (the real component, on the same dark theme as the h
47
43
 
48
44
  </details>
49
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
+
50
50
  ## Installation
51
51
 
52
52
  ### DSH Web
@@ -74,9 +74,12 @@ The Electron application manages the `desktop` profile. Do not change the Web co
74
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.
75
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.
76
76
 
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 also carries the buttons (see [How Windows Desktop raises buttoned notifications](#how-windows-desktop-raises-buttoned-notifications)); macOS Desktop has no Service Worker and its native helper carries no buttons, so this test sends a plain notification — real approval alerts work the same way, and clicking one takes you back to the conversation to decide.
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>
78
81
 
79
- **Optional console check** — in environments with DevTools, you can also run:
82
+ In environments with DevTools, you can also run:
80
83
 
81
84
  ```js
82
85
  window.__dshNotifyMe.test("done") // "reply finished" sample
@@ -85,6 +88,8 @@ window.__dshNotifyMe.test("approval") // Approve / Reject when the bridge is
85
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
86
89
  ```
87
90
 
91
+ </details>
92
+
88
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.
89
94
 
90
95
  ## Why you need it
@@ -136,7 +141,7 @@ Open **Settings → Notify me**. The page lays out three blocks — how you get
136
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.
137
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.
138
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.
139
- - **"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. All of them are withdrawn when you come back to the page (and kept when that switch is on).
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.
140
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.
141
146
 
142
147
  </details>
@@ -197,7 +202,20 @@ Off by default. Supports Discord Webhook / Bark / Gotify / Feishu group bots / S
197
202
 
198
203
  </details>
199
204
 
200
- #### After the page closes: host-side fallback and the same-origin relay
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
201
219
 
202
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.
203
221
 
@@ -232,6 +250,7 @@ An override example for the profile (`~/.dsh/profiles/<profile>/cordis.patch.yml
232
250
  path: ''
233
251
  target: ''
234
252
  credentialsFile: ''
253
+ bodyTemplate: '' # optional JSON template, see "Same-origin relay"
235
254
  ```
236
255
 
237
256
  Key by key (defaults in parentheses):
@@ -272,6 +291,25 @@ The page is left reporting "sent but unverifiable". The same-origin relay moves
272
291
 
273
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>`.
274
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
+
275
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.
276
314
 
277
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.
@@ -281,27 +319,15 @@ Behind a tunnel or reverse proxy the relay passes the same `Host` gate as the br
281
319
  What comes back (which is how the page turns "sent but unverifiable" into something checkable):
282
320
 
283
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;
284
- - `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 not 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;
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;
285
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;
286
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).
287
326
 
288
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.
289
328
 
290
329
  </details>
291
330
 
292
- #### Runtime & diagnostics
293
-
294
- 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.
295
-
296
- <details>
297
- <summary>Alert language, Desktop window raising, and reset</summary>
298
-
299
- - **Alert language**: follow the UI / Simplified Chinese / English — governs the alert copy and the `🔔 …` title marker;
300
- - **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));
301
- - **Reset settings**: restores every switch and sound setting to the factory defaults (external push targets and chosen custom audio files are kept).
302
-
303
- </details>
304
-
305
331
  ## Alert channels
306
332
 
307
333
  | Channel | What it does |
@@ -374,6 +400,7 @@ That header is only a "this came from the page" marker, not the defence — a DN
374
400
  The cases where it will not raise are the same ones listed under [Known limitations](#known-limitations) (elevated window, another virtual desktop, a foreground repeatedly stolen, a window hidden to the tray with `SW_HIDE`); they all answer `202` truthfully and the conversation switch still happens.
375
401
 
376
402
  </details>
403
+
377
404
  ### How macOS Desktop raises system notifications
378
405
 
379
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.
@@ -400,8 +427,6 @@ The page's own `new Notification()` is not refused on Windows Desktop, but it ca
400
427
 
401
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.
402
429
 
403
-
404
-
405
430
  ## Known limitations
406
431
 
407
432
  **Runtime prerequisites**
@@ -417,7 +442,7 @@ Like the other routes, this one registers exactly one exact path and refuses eve
417
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.
418
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)).
419
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.
420
- - macOS: alerts, sound, the title marker and toast-click navigation carry no platform assumptions and work as usual; but DSH Desktop (Electron) system notifications require the app to be signed — an unsigned build simply emits no notification — and whether the official macOS build meets that precondition is untested; notification button rendering on the macOS desktop host is likewise untested (the Windows desktop host now posts its approval toasts as native toasts, which do render buttons).
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)).
421
446
 
422
447
  **Alert content and timing**
423
448
 
@@ -444,9 +469,12 @@ npm test # smoke-test (state machine) + host-route-test
444
469
  npm pack --dry-run # preview the published tarball
445
470
  ```
446
471
 
472
+ <details>
473
+ <summary>What each suite covers, and the manual raise check</summary>
474
+
447
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.
448
476
 
449
- 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.
450
478
 
451
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.
452
480
 
@@ -460,6 +488,8 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # the last line
460
488
 
461
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`.
462
490
 
491
+ </details>
492
+
463
493
  ## Credits & how contributions land
464
494
 
465
495
  | Contributor | Contribution |
@@ -475,15 +505,31 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # the last line
475
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 |
476
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 |
477
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 |
478
- | <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 |
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 |
479
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 |
480
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 |
481
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 |
482
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 |
483
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 |
484
515
 
485
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.
486
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
+
487
533
  ## License
488
534
 
489
535
  MIT — see [LICENSE](LICENSE).
package/README.md CHANGED
@@ -18,7 +18,7 @@
18
18
 
19
19
  </div>
20
20
 
21
- [安装](#安装) · [效果预览](#效果预览) · [配置](#在-dsh-设置里改配置) · [兼容性](#兼容性) · [已知限制](#已知限制) · [更新日志](CHANGELOG.md)
21
+ [效果预览](#效果预览) · [安装](#安装) · [配置](#在-dsh-设置里改配置) · [兼容性](#兼容性) · [已知限制](#已知限制) · [更新日志](CHANGELOG.md)
22
22
 
23
23
  DSH Web / Desktop 的通知插件,让你敢不开完整访问,也不必一直守着页面。
24
24
 
@@ -26,12 +26,7 @@ DSH Web / Desktop 的通知插件,让你敢不开完整访问,也不必一
26
26
  - **后台回复完成时**:及时回来查看结果,点击通知可回到对应对话;提醒时机可选「仅后台 / 仅当前对话静默 / 总是提醒」。
27
27
  - **人走开但窗口没走**:窗口留在最前台、人却离开座位,超过 3 分钟没有输入也算离开,该提醒的照常提醒;收到的那条通知不会在你回来之前自己消失,一回到页面(点任务栏、Alt+Tab、点通知都算)就收起(想让它在回到页面后继续留着,打开「回到页面也保留提醒」)。
28
28
  - **离开电脑时**:可选转发到 Discord、Bark、Gotify、飞书群机器人、Server酱、WxPusher 或自己的 Webhook。
29
- - **连页面都关掉时**:可选让宿主进程兜底——页面不在时宿主继续把「需要你操作」「回复完成」推到你的网关;也可以只开同源中继,让页面够到要认证的网关。两项默认关,配置写在 profile 的 patch 层(见[高级设置](#高级设置)里的「页面关闭后:宿主侧兜底与同源中继」)。
30
-
31
- > **macOS 桌面端(DSH Desktop)** 的系统通知由宿主拉起的小助手 `DSH Notify.app` 发出,需先执行一次 `bash macos/build.sh` 并在系统设置里允许它发通知(见 [macOS 桌面端怎么发系统通知](#macos-桌面端怎么发系统通知))。
32
-
33
- > 页面或桌面应用需保持运行(后台 / 最小化可以);系统通知需要通知权限。审批按钮依赖 Service Worker,Web 端由页面自己的通知提供;Windows 桌面端由宿主发原生 Toast,同样带按钮;macOS 桌面端的通知仍不带按钮,点通知回到对话里裁决。开启宿主侧兜底后,页面关闭仍能收到外部推送——本地通知与审批按钮仍要页面在。
34
-
29
+ - **连页面都关掉时**:可选让宿主进程兜底——页面不在时宿主继续把「需要你操作」「回复完成」推到你的网关;也可以只开同源中继,让页面够到要认证的网关。两项默认关,配置写在 profile 的 patch 层(见[页面关闭后:宿主侧兜底与同源中继](#页面关闭后宿主侧兜底与同源中继))。
35
30
 
36
31
  ## 效果预览
37
32
 
@@ -48,6 +43,10 @@ DSH Web / Desktop 的通知插件,让你敢不开完整访问,也不必一
48
43
 
49
44
  </details>
50
45
 
46
+ > **macOS 桌面端(DSH Desktop)** 的系统通知由宿主拉起的小助手 `DSH Notify.app` 发出,需先执行一次 `bash macos/build.sh` 并在系统设置里允许它发通知(见 [macOS 桌面端怎么发系统通知](#macos-桌面端怎么发系统通知))。
47
+
48
+ > 页面或桌面应用需保持运行(后台 / 最小化可以);系统通知需要通知权限。审批按钮在 Web 与 Windows 桌面端可用,macOS 桌面端与没有 Service Worker 的页面点通知回对话里裁决(见[提醒渠道](#提醒渠道))。开启宿主侧兜底后,页面关闭仍能收到外部推送——本地通知与审批按钮仍要页面在。
49
+
51
50
  ## 安装
52
51
 
53
52
  ### DSH Web
@@ -75,9 +74,12 @@ dsh plugin --profile web add dsh-notify-me
75
74
  2. 打开 **设置 → 通知提醒**,确认出现该分区及底部插件版本号,保持「启用提醒」「提示音」开启。
76
75
  3. 点击设置页的「测试『回复完成』」按钮:应出现一条测试通知,并按当前音效设置播放声音。这个本地测试不会转发到外部通知端点,也不受「窗口在前台时也提醒」开关限制。
77
76
 
78
- Web 用户可再测审批按钮,通知上会带「同意 / 拒绝」。Windows 桌面端由宿主发原生 Toast,同样带按钮(见 [Windows 桌面端怎么发带按钮的通知](#windows-桌面端怎么发带按钮的通知));macOS 桌面端拿不到 Service Worker、原生助手也不带按钮,这条测试只发一条普通通知——真实审批的提醒同理,点它回到对话里裁决。
77
+ Web 用户可再测审批按钮,通知上会带「同意 / 拒绝」。Windows 桌面端由宿主发原生 Toast,同样带按钮;macOS 桌面端只发普通通知(渠道差异见[提醒渠道](#提醒渠道))。
79
78
 
80
- **控制台验证(可选)** — 支持 DevTools 的环境也可执行:
79
+ <details>
80
+ <summary>控制台验证(可选)</summary>
81
+
82
+ 支持 DevTools 的环境也可执行:
81
83
 
82
84
  ```js
83
85
  window.__dshNotifyMe.test("done") // 「完成」示例
@@ -86,6 +88,8 @@ window.__dshNotifyMe.test("approval") // Web 桥可用、或 Windows 桌面
86
88
  window.__dshNotifyMe.debug() // 桥接看 bridge(active = 按钮可用)、抬窗通道 raiseChannel、最近一次尝试 raiseLast、平台拒发原文 lastToastReject、设置是否真存下来 configStored、宿主协调看 hostBridge、原生通道看 macNative / winNative 与各自 last;切回页面后收通知看 toastsLive / toastsWithdrawn / lastToastWithdrawAt(还挂着几条 / 累计收起几条 / 最后一次的时间)
87
89
  ```
88
90
 
91
+ </details>
92
+
89
93
  没有测试通知时,先检查:通知权限是否被拒绝(在页面上点一下 → 选「允许」;或地址栏锁 → 站点设置 → 通知 → 允许 → 刷新)、装完没重启 DSH、系统设置里浏览器通知被关。
90
94
 
91
95
  ## 为什么需要它
@@ -198,7 +202,20 @@ dsh-notify-me 把「监督」和「守在屏幕前」解耦:只在真的出现
198
202
 
199
203
  </details>
200
204
 
201
- #### 页面关闭后:宿主侧兜底与同源中继
205
+ #### 运行环境与诊断
206
+
207
+ 在「高级设置」最后一块。默认自动识别当前是 Web 端还是桌面端(DSH Desktop,`dsh-app://`);识别不准时可手动指定——Windows 桌面点通知走宿主路由做原生抬窗、macOS / Linux 走 `dsh://open` 深链(见[桌面端怎么抬窗的](#桌面端怎么抬窗的));抬窗通道本身不带快捷裁决按钮——按钮来自 Web 的 Service Worker 桥,或 Windows 桌面端的宿主原生 Toast。手动覆盖与自动识别不一致时,设置页会明示检测结果。
208
+
209
+ <details>
210
+ <summary>通知语言、桌面端抬窗与恢复默认</summary>
211
+
212
+ - **通知语言**:跟随界面 / 简体中文 / English——决定通知文字与 `🔔 …` 标题标记使用的语言;
213
+ - **桌面端抬窗**:Windows 走宿主路由做原生激活、macOS / Linux 走 `dsh://open` 深链;最小化、被别的窗口盖住的窗口在 Windows 与 Linux 上都实测能抬回来(见[桌面端怎么抬窗的](#桌面端怎么抬窗的));
214
+ - **恢复默认设置**:把所有开关与音效设置还原成出厂值(不动外部推送目标和已选的自定义音频文件)。
215
+
216
+ </details>
217
+
218
+ ## 页面关闭后:宿主侧兜底与同源中继
202
219
 
203
220
  这两块能力住在宿主进程里(`lib/host-fallback.js`、`lib/relay.js`,都是包内的可选模块),默认关:没有配置时宿主只注册抬窗那一条路由,升级前后行为一致。它们的配置写在 profile 的 patch 层,不在设置页里——它们让宿主替页面干活,不是浏览器偏好;设置页只如实显示探测到的状态。
204
221
 
@@ -233,6 +250,7 @@ profile 覆盖示例(`~/.dsh/profiles/<profile>/cordis.patch.yml`)。**`conf
233
250
  path: ''
234
251
  target: ''
235
252
  credentialsFile: ''
253
+ bodyTemplate: '' # 可选:JSON 请求体模板,见「同源中继」
236
254
  ```
237
255
 
238
256
  逐键说明(括号内是默认值):
@@ -273,6 +291,25 @@ profile 覆盖示例(`~/.dsh/profiles/<profile>/cordis.patch.yml`)。**`conf
273
291
 
274
292
  启用需要 `relay.enabled: true`、`relay.path`(必须是绝对路径)、`relay.target`(留空回落到 `gateway.target`)和 `relay.credentialsFile`(留空回落到 `gateway.credentialsFile`)。路径本身就是能力——知道它就能让宿主替你发一条通知,价值等同口令,所以建议带一段随机 token:`/__dsh-notify-me/relay/<32 hex token>`。
275
293
 
294
+ `relay.bodyTemplate`(可选)给不接受 Apprise `{title, body, type}` 形状的网关用:写一段 JSON 模板,宿主按模板渲染请求体。占位符是 `{{title}}` `{{body}}` `{{text}}` `{{event}}` `{{time}}` `{{session}}`(取载荷里的 `sessionId`)`{{source}}` `{{version}}`,要写在 JSON 字符串里;代入的值先按 JSON 字符串转义,所以标题里的引号、换行不会把模板弄坏,载荷里没有的字段渲染成空串,模板里没写的字段不会出现在请求体里。
295
+
296
+ 模板在宿主启动时就校验:渲染结果不是 JSON 对象、或模板超过 16 KiB(按 UTF-8 字节算),整条中继不挂载,日志里留一行 warning 写明原因,状态回包与设置页也显示中继未启用——配错一次就能看见,不用等每条提醒都回 500。渲染后的请求体另有 256 KiB 上限(模板可以重复占位符放大体积),超了回 `500 {reason:'rendered-body-too-large'}` 且不发送。不写这个键时保持原来的 `{title, body, type:'info'}` 不变。
297
+
298
+ 例:把提醒推给自己的推送服务(下面以 MagicPush 风格接口为例,它要求 `channel_ids` + `title` + `content`,Bearer 令牌放在宿主的 0600 凭据文件里):
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
+ YAML 的单引号里模板原样保留;页面设置里把「自定义 Webhook」的地址填成同一个 `target`,请求会自动折叠到中继路由,凭据仍只留在宿主。
312
+
276
313
  用法:**设置 → 通知提醒 → 高级设置 → 外部推送** 里多出两行只读状态,「同源中继」一行显示 `已启用 · 地址:<origin><relay.path>`;把那个绝对地址填进同页「自定义 Webhook」目标的地址即可,页面不必知道凭据。
277
314
 
278
315
  不想改地址也行:**「自定义 Webhook」目标里如果填的是中继上游网关本身的地址,发送时会自动折叠到中继路由**。这类地址在浏览器里注定失败(上面三条 CORS 事实各堵一次,其中 `no-cors` 兜底还会被 Apprise 当成跨站请求直接 `403 Cross-site request rejected`),旧版把它记成 `unverified`——设置页显示「上次已送出(不可确认)」、测试按钮报「已送出不可确认」,**而手机一声不响**。折叠之后请求走同源、凭据由宿主补,回执就是网关的真实状态。折叠要同时满足:目标类型是「自定义」、URL 主机名等于 `relay.upstreamHost`、路径也等于 `relay.upstreamPath`、目标没配签名密钥(签名在页面算,中继带不过去)、且目标不是本页同源。主机名或路径有一项对不上就原样直发(一个网关常按路径分多个 notify key,只比主机名会把 A key 的提醒发到 B key 去),设置页会在会被折叠的目标下写一行说明。
@@ -282,27 +319,15 @@ profile 覆盖示例(`~/.dsh/profiles/<profile>/cordis.patch.yml`)。**`conf
282
319
  回包口径(页面据此把「已送出不可确认」变成可核对的状态):
283
320
 
284
321
  - `GET` / `HEAD` `<relay.path>` → `200 {ok, route, version, enabled}`:只读探针,不转发、不带凭据,但**和其它宿主入口走同一道闸门**——路径本身就是能力,不设闸门的探针会把「猜对了」告诉猜的人;拿它确认「这个进程挂的是不是我配的那条路径」;
285
- - `POST` → 读 body(上限 64 KiB)、要求是 JSON 对象,映射成网关的 `{title, body, type:'info'}`(页面载荷里的 `tag` 不透传:Apprise 把 tag 当服务过滤,不匹配会回 424),附上 `gateway.headers` 与凭据;请求必须带 `x-dsh-notify-me-relay: relay` 意图头,缺了回 `403 {reason:'missing-intent'}`——跨站表单发不出自定义头,要发就得多一次预检,而预检在网关这里必然失败;
322
+ - `POST` → 读 body(上限 64 KiB)、要求是 JSON 对象,映射成网关的 `{title, body, type:'info'}`(配了 `relay.bodyTemplate` 时改为按模板渲染出的 JSON 对象;页面载荷里的 `tag` 一律不透传:Apprise 把 tag 当服务过滤,不匹配会回 424),附上 `gateway.headers` 与凭据;请求必须带 `x-dsh-notify-me-relay: relay` 意图头,缺了回 `403 {reason:'missing-intent'}`——跨站表单发不出自定义头,要发就得多一次预检,而预检在网关这里必然失败;
286
323
  - `200 {ok, upstreamStatus, upstreamBody}`(`upstreamBody` 最多 500 字符)=转发成功;上游非 2xx 回 `502`,同为这一形状;
324
+ - `500 {reason}`:模板配错(`invalid-body-template` / `template-too-large` / `rendered-body-too-large`)——前两种正常在宿主启动校验时就拦下了,这里只是运行期的兜底,且什么都不发;
287
325
  - `400`(坏 JSON 或空 body)、`413`(body 超限)、`405`(方法不对)、`403`(闸门拒绝或缺少意图头)、`503`(配了凭据文件但读不出来)、`502 {reason:'upstream-error'}`(上游异常或网关回了 3xx——跳转不跟,因为跟过去会把 body 和 `Authorization` 重放到别处)。
288
326
 
289
327
  凭据只在宿主:页面拿不到它,它也不会回显在响应或日志里。`POST` 走与其它宿主入口同一道闸门,所以跨站页面或 DNS rebinding 的伪造来源即使猜到路径也会被拒。
290
328
 
291
329
  </details>
292
330
 
293
- #### 运行环境与诊断
294
-
295
- 在「高级设置」最后一块。默认自动识别当前是 Web 端还是桌面端(DSH Desktop,`dsh-app://`);识别不准时可手动指定——Windows 桌面点通知走宿主路由做原生抬窗、macOS / Linux 走 `dsh://open` 深链(见[桌面端怎么抬窗的](#桌面端怎么抬窗的));抬窗通道本身不带快捷裁决按钮——按钮来自 Web 的 Service Worker 桥,或 Windows 桌面端的宿主原生 Toast。手动覆盖与自动识别不一致时,设置页会明示检测结果。
296
-
297
- <details>
298
- <summary>通知语言、桌面端抬窗与恢复默认</summary>
299
-
300
- - **通知语言**:跟随界面 / 简体中文 / English——决定通知文字与 `🔔 …` 标题标记使用的语言;
301
- - **桌面端抬窗**:Windows 走宿主路由做原生激活、macOS / Linux 走 `dsh://open` 深链;最小化、被别的窗口盖住的窗口在 Windows 与 Linux 上都实测能抬回来(见[桌面端怎么抬窗的](#桌面端怎么抬窗的));
302
- - **恢复默认设置**:把所有开关与音效设置还原成出厂值(不动外部推送目标和已选的自定义音频文件)。
303
-
304
- </details>
305
-
306
331
  ## 提醒渠道
307
332
 
308
333
  | 渠道 | 表现 |
@@ -375,6 +400,7 @@ Windows 的激活顺序是实的:已经在前台就什么都不做(最常见
375
400
  抬不起来的几种场合与[已知限制](#已知限制)里列的一致(提权窗口、另一虚拟桌面、前台被反复抢走、`SW_HIDE` 托盘隐藏),一律如实回 `202`、对话照常切。
376
401
 
377
402
  </details>
403
+
378
404
  ### macOS 桌面端怎么发系统通知
379
405
 
380
406
  页面里的 `new Notification()` 在 macOS 的 DSH Desktop(`dsh-app://app`)上进不了通知中心——不弹,也不报错(`Notification.permission` 照样是 `granted`)。插件在这一平台上改走宿主:页面 POST `/__dsh-notify-me/mac-notify`,宿主(`lib/mac-notify.js`)拉起 `macos/` 下的小助手 `DSH Notify.app`,由它用 `UNUserNotificationCenter` 发一条真正的系统通知。
@@ -401,7 +427,6 @@ Windows 的激活顺序是实的:已经在前台就什么都不做(最常见
401
427
 
402
428
  路由只开一个 exact 路径,其余一律拒:非 GET / POST 回 `405`,非 loopback 或未放行的 `Host` / `Origin` 回 `403`,POST 缺 `x-dsh-notify-me-win: toast` 头回 `403`,请求体不合法回 `400`。响应只回报投递状态,不含系统信息。
403
429
 
404
-
405
430
  ## 已知限制
406
431
 
407
432
  **运行前提**
@@ -444,9 +469,12 @@ npm test # smoke-test(状态机)+ host-route-test(
444
469
  npm pack --dry-run # 预览发布包
445
470
  ```
446
471
 
472
+ <details>
473
+ <summary>各测试套件覆盖范围与手动检查</summary>
474
+
447
475
  `smoke/smoke-test.cjs` 是离线状态机测试:三代宿主 + 主开关 + 中英语言用例 + 快捷裁决桥(Service Worker 半侧一并跑)+ 闲置判定与通知自收 + 回到页面即收起残留通知 + 通知标签长度收口 + 页面侧 host-bridge 探测/心跳/释放与 `debug().hostBridge` 形状。`smoke/host-route-test.mjs` 不需要本机 DSH,`lib/index.js` 的路由、探针与 403/405/501 闸门在任何平台都会跑。
448
476
 
449
- 新增的三个套件同样自带假 `ctx`、不联网、不需要本机 DSH:`smoke/page-bridge-test.mjs` 跑页面桥接路由的状态回包形状、心跳与释放、缺意图头 `403`、跨源 `403`、坏 JSON `400`、超长 `413`,以及 `allowedOrigins` 派生的 `Host`(模拟隧道)放行与路径冲突;`smoke/host-fallback-test.mjs` 跑宿主兜底——审批去重、`turn/end` 节流、子代理跳过、租约新鲜时不发、租约过期后发、`alive:false` 后立刻发、语言跟随心跳、401 后重读凭据、健康探针;`smoke/relay-route-test.mjs` 跑中继——`GET` 探针、`405`、跨源 `403`、`413`、`400`、`503`、`200` / `502` 映射与「401 只重试一次」。
477
+ 新增的三个套件同样自带假 `ctx`、不联网、不需要本机 DSH:`smoke/page-bridge-test.mjs` 跑页面桥接路由的状态回包形状、心跳与释放、缺意图头 `403`、跨源 `403`、坏 JSON `400`、超长 `413`,以及 `allowedOrigins` 派生的 `Host`(模拟隧道)放行与路径冲突;`smoke/host-fallback-test.mjs` 跑宿主兜底——审批去重、`turn/end` 节流、子代理跳过、租约新鲜时不发、租约过期后发、`alive:false` 后立刻发、语言跟随心跳、401 后重读凭据、健康探针;`smoke/relay-route-test.mjs` 跑中继——`GET` 探针、`405`、跨源 `403`、`413`、`400`、`503`、`200` / `502` 映射与「401 只重试一次」、`relay.bodyTemplate` 的模板渲染与 JSON 转义、坏模板启动即不注册、渲染体积上限。
450
478
 
451
479
  `smoke/mac-notify-test.mjs` 跑 macOS 通知路由:只在 macOS 桌面宿主注册、探测、`405` / `403` / `501` / `400` 的拒绝、传给助手的参数(含 `--id` / `--sound` 与 `{remove:id}` 撤回)、点击回传只被取走一次。它用假的平台与 Electron 版本号驱动,不需要真的编译助手,在任何平台都会跑。
452
480
 
@@ -460,6 +488,8 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # 末行应是 F
460
488
 
461
489
  `cordis-host-test.mjs` 会从本机 DSH 安装借 `@deepseek-ai/cordis`(依次探测 npm 全局目录、`~/.dsh/profiles/web/node_modules` 与 `~/.dsh/profiles/node_modules` 平铺回退目录);源码 checkout 里没有 profile 依赖时,用 `DSH_CORDIS_PATH=<checkout>/vendor/cordis/lib/index.js` 指定即可。
462
490
 
491
+ </details>
492
+
463
493
  ## 致谢与贡献须知
464
494
 
465
495
  | 贡献者 | 贡献 |
@@ -481,11 +511,15 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # 末行应是 F
481
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):`keepOnReturn`(回到页面也保留提醒)的提案与最小实现,以及「前台也提醒」一键预设的诉求,1.19.0 起支持 |
482
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):macOS 桌面端页面通知不响的排查与宿主助手方案(`lib/mac-notify.js` + `macos/`),1.19.0 起支持 |
483
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):Windows 桌面端审批通知没有「同意 / 拒绝」按钮的反馈,以及 Electron 丢弃 `actions` / 桌面端注册不了 Service Worker 的源码级定位,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):同源中继自定义 JSON 请求体模板(`relay.bodyTemplate`),含测试与文档,1.20.0 起支持 |
484
515
 
485
516
  署名口径:本仓库收编外部 PR 时以维护者提交落地——不沿用原 commit、不挂 Co-authored-by,GitHub 的 contributors 图只显示维护者,贡献者以上面的致谢署名。
486
517
 
487
518
  ## Star History
488
519
 
520
+ <details>
521
+ <summary>展开 Star History 图表</summary>
522
+
489
523
  <a href="https://www.star-history.com/?repos=chromoany%2Fdsh-notify-me&type=timeline&legend=bottom-right">
490
524
  <picture>
491
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" />
@@ -494,6 +528,8 @@ powershell -NoProfile -File lib/focus-window.ps1 -ProcessId 0 # 末行应是 F
494
528
  </picture>
495
529
  </a>
496
530
 
531
+ </details>
532
+
497
533
  ## License
498
534
 
499
535
  MIT — 见 [LICENSE](LICENSE)。
package/cordis.patch.yml CHANGED
@@ -84,6 +84,7 @@
84
84
  path: '' # exact route, e.g. /__dsh-notify-me/relay/<32 hex token>
85
85
  target: ''
86
86
  credentialsFile: ''
87
+ bodyTemplate: '' # optional JSON template, see "Same-origin relay"
87
88
  # Native Windows approval toasts with real Approve / Reject buttons. On
88
89
  # by default whenever the host runs the Windows desktop shell: the host
89
90
  # posts the toast through WinRT and registers a HKCU protocol handler on
package/lib/client.js CHANGED
@@ -3300,7 +3300,7 @@
3300
3300
  });
3301
3301
  } catch (e) {}
3302
3302
  // keep in sync with package.json "version" on every release
3303
- api.version = "1.19.0";
3303
+ api.version = "1.20.1";
3304
3304
  api.setConfig = function (patch) { return setConfigLocal(patch); };
3305
3305
  api.resetConfig = function () {
3306
3306
  try {
package/lib/index.js CHANGED
@@ -48,7 +48,7 @@ import {
48
48
  respond,
49
49
  } from "./page-bridge.js";
50
50
  import { mountHostFallback } from "./host-fallback.js";
51
- import { mountRelay } from "./relay.js";
51
+ import { bodyTemplateProblem, mountRelay } from "./relay.js";
52
52
  import { MAC_NOTIFY_ROUTE, mountMacNotify } from "./mac-notify.js";
53
53
  import { WIN_TOAST_ROUTE, mountWinToast } from "./win-toast.js";
54
54
 
@@ -124,6 +124,10 @@ const DEFAULTS = {
124
124
  target: "",
125
125
  credentialsFile: "",
126
126
  headers: null,
127
+ // Optional JSON template for gateways that do not accept the Apprise
128
+ // `{ title, body, type }` shape (for example an own push service with its
129
+ // own field names). Empty keeps the historical payload unchanged.
130
+ bodyTemplate: "",
127
131
  },
128
132
  };
129
133
 
@@ -273,20 +277,26 @@ function normalizeConfig(config, logger) {
273
277
  target: text(relay.target, gatewayTarget),
274
278
  credentialsFile: text(relay.credentialsFile, gatewayCredentials),
275
279
  headers: headerBag(relay.headers, gatewayHeaders),
280
+ bodyTemplate: text(relay.bodyTemplate, DEFAULTS.relay.bodyTemplate),
276
281
  };
277
282
 
278
283
  // Whether each half can actually run. `mountHostFallback` leaves a fallback
279
284
  // without a gateway unmounted — there is nowhere to push — and `mountRelay`
280
- // leaves a relay without an absolute path or a target unmounted, so neither
281
- // the status reply nor the feature list may claim it is on: the page would
282
- // otherwise hold a lease for a takeover that can never happen, or post alerts
283
- // to a route that was never mounted, while the settings row read "on" and
284
- // every alert was silently dropped.
285
+ // leaves a relay without an absolute path, a target, or a `bodyTemplate` that
286
+ // renders to a JSON object unmounted, so neither the status reply nor the
287
+ // feature list may claim it is on: the page would otherwise hold a lease for
288
+ // a takeover that can never happen, or post alerts to a route that was never
289
+ // mounted, while the settings row read "on" and every alert was silently
290
+ // dropped.
285
291
  host.active = host.enabled && host.target.length > 0;
286
292
 
287
293
  host.healthPath = freePath("hostFallback.healthPath", host.healthPath, logger);
288
294
  relayConfig.path = freePath("relay.path", relayConfig.path, logger);
289
- relayConfig.active = relayConfig.enabled && relayConfig.target.length > 0 && relayConfig.path.startsWith("/");
295
+ relayConfig.active =
296
+ relayConfig.enabled &&
297
+ relayConfig.target.length > 0 &&
298
+ relayConfig.path.startsWith("/") &&
299
+ bodyTemplateProblem(relayConfig.bodyTemplate) === null;
290
300
 
291
301
  const features = ["page-bridge"];
292
302
  if (host.active) features.push("host-fallback");
package/lib/relay.js CHANGED
@@ -13,6 +13,11 @@
13
13
  * server-side and answers with the gateway's real status, which is what turns
14
14
  * the page's delivery verdict from "unverified" into "sent".
15
15
  *
16
+ * The forwarded body is the Apprise `{ title, body, type }` shape by default.
17
+ * For gateways with their own schema (an own push service, a MagicPush-style
18
+ * REST API) `relay.bodyTemplate` overrides it with a JSON template rendered
19
+ * from the event's fields; see {@link toGatewayPayload}.
20
+ *
16
21
  * Security posture: the route path is a capability (recommended to contain a
17
22
  * random token) and the gateway credential lives in a mode-0600 file the host
18
23
  * reads — never in the page, never in the patch layer, never in a reply. GET is
@@ -45,6 +50,96 @@ export const RELAY_HEADER_VALUE = "relay";
45
50
  /** Longest upstream response quoted back to the page for its own diagnostics. */
46
51
  const UPSTREAM_BODY_LIMIT = 500;
47
52
 
53
+ /** Longest `bodyTemplate` accepted; a template bigger than this is a mistake. */
54
+ const MAX_BODY_TEMPLATE_BYTES = 16 * 1024;
55
+
56
+ /**
57
+ * Longest body a `bodyTemplate` may render to.
58
+ *
59
+ * The template cap bounds the template, not the request: a template may repeat
60
+ * `{{text}}`, so a 64 KiB event can render to several times its own size. The
61
+ * rendered body is what reaches the gateway, so it is bounded on its own.
62
+ */
63
+ const MAX_RENDERED_BODY_BYTES = 256 * 1024;
64
+
65
+ /**
66
+ * Payload a `bodyTemplate` is dry-run with at boot.
67
+ *
68
+ * Short ASCII values are enough for the only question asked there: does the
69
+ * template render to a JSON object at all? Whether the event's real values can
70
+ * make the body too large is a per-request question, answered in
71
+ * {@link toGatewayPayload}.
72
+ */
73
+ const TEMPLATE_PROBE = Object.freeze({
74
+ title: "x",
75
+ body: "x",
76
+ text: "x",
77
+ event: "x",
78
+ time: "x",
79
+ sessionId: "x",
80
+ source: "x",
81
+ version: "x",
82
+ });
83
+
84
+ /**
85
+ * Escape one placeholder value for embedding inside a JSON string literal.
86
+ *
87
+ * A template is JSON text, and the event's title/body are user content: a quote
88
+ * or a newline copied in raw would turn the rendered template into malformed
89
+ * JSON. Quoting through `JSON.stringify` and dropping the outer quotes is the
90
+ * exact inverse of the unescape a JSON parser applies.
91
+ * @param value - the placeholder value.
92
+ * @returns it ready to sit between two JSON quotes.
93
+ */
94
+ function escapeJsonStringValue(value) {
95
+ return JSON.stringify(value === undefined || value === null ? "" : String(value)).slice(1, -1);
96
+ }
97
+
98
+ /**
99
+ * Render a JSON `bodyTemplate` with the event's fields.
100
+ *
101
+ * Supported placeholders: `{{title}}` `{{body}}` `{{text}}` `{{event}}`
102
+ * `{{time}}` `{{session}}` `{{source}}` `{{version}}`. `{{session}}` reads
103
+ * `sessionId` because that is the field the page sends; the others are used
104
+ * verbatim. Whitespace inside the braces is allowed; a field the event does not
105
+ * carry renders as the empty string. Only placeholders inside JSON string
106
+ * literals make sense: anywhere else the substitution produces invalid JSON,
107
+ * which is reported rather than forwarded.
108
+ * @param template - the configured JSON template.
109
+ * @param payload - parsed request body.
110
+ * @returns the rendered JSON text.
111
+ */
112
+ function renderBodyTemplate(template, payload) {
113
+ return template.replace(
114
+ /\{\{\s*(title|body|text|event|time|session|source|version)\s*\}\}/g,
115
+ (_match, key) => escapeJsonStringValue(key === "session" ? payload.sessionId : payload[key]),
116
+ );
117
+ }
118
+
119
+ /**
120
+ * Check that a configured `bodyTemplate` can render to a JSON object.
121
+ *
122
+ * Asked twice, both before any alert: once while the config is normalized (so
123
+ * the status reply does not promise a relay that cannot mount) and once while
124
+ * the route is mounted (so the warning and the missing route land together).
125
+ * A template that cannot work would answer 500 on every alert, which is worse
126
+ * than no route at all.
127
+ * @param template - the configured template; empty means "not configured".
128
+ * @returns `null` when usable, otherwise the failure reason.
129
+ */
130
+ export function bodyTemplateProblem(template) {
131
+ if (typeof template !== "string" || template.length === 0) return null;
132
+ if (Buffer.byteLength(template, "utf8") > MAX_BODY_TEMPLATE_BYTES) return "template-too-large";
133
+ let parsed;
134
+ try {
135
+ parsed = JSON.parse(renderBodyTemplate(template, TEMPLATE_PROBE));
136
+ } catch {
137
+ return "invalid-body-template";
138
+ }
139
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return "invalid-body-template";
140
+ return null;
141
+ }
142
+
48
143
  /**
49
144
  * Map the page's event payload onto the gateway's notify schema.
50
145
  *
@@ -53,18 +148,45 @@ const UPSTREAM_BODY_LIMIT = 500;
53
148
  * Apprise treats a tag as a service filter, so an unmatched tag turns the
54
149
  * delivery into 424 "nothing could be sent" — the notify key's own
55
150
  * configuration decides the destinations, not the payload.
151
+ *
152
+ * A configured `bodyTemplate` replaces that fixed shape: a gateway with its own
153
+ * schema (an own push service, a MagicPush-style API, …) gets exactly the fields
154
+ * it documents. The template must render to a JSON object no larger than
155
+ * {@link MAX_RENDERED_BODY_BYTES}; anything else is reported instead of sending
156
+ * a body the gateway cannot parse.
56
157
  * @param payload - parsed request body.
57
- * @returns the JSON body to forward.
158
+ * @param bodyTemplate - optional JSON template from `relay.bodyTemplate`.
159
+ * @returns `{ ok: true, body }` with the JSON body to forward, or
160
+ * `{ ok: false, reason }` when the template cannot produce a JSON object.
58
161
  */
59
- function toGatewayPayload(payload) {
60
- const title = typeof payload.title === "string" && payload.title.length > 0 ? payload.title : "DSH";
61
- const body =
62
- typeof payload.body === "string" && payload.body.length > 0
63
- ? payload.body
64
- : typeof payload.text === "string"
65
- ? payload.text
66
- : "";
67
- return { title, body, type: "info" };
162
+ function toGatewayPayload(payload, bodyTemplate) {
163
+ if (typeof bodyTemplate !== "string" || bodyTemplate.length === 0) {
164
+ const title = typeof payload.title === "string" && payload.title.length > 0 ? payload.title : "DSH";
165
+ const body =
166
+ typeof payload.body === "string" && payload.body.length > 0
167
+ ? payload.body
168
+ : typeof payload.text === "string"
169
+ ? payload.text
170
+ : "";
171
+ return { ok: true, body: { title, body, type: "info" } };
172
+ }
173
+ if (Buffer.byteLength(bodyTemplate, "utf8") > MAX_BODY_TEMPLATE_BYTES) {
174
+ return { ok: false, reason: "template-too-large" };
175
+ }
176
+ const rendered = renderBodyTemplate(bodyTemplate, payload);
177
+ if (Buffer.byteLength(rendered, "utf8") > MAX_RENDERED_BODY_BYTES) {
178
+ return { ok: false, reason: "rendered-body-too-large" };
179
+ }
180
+ let parsed;
181
+ try {
182
+ parsed = JSON.parse(rendered);
183
+ } catch {
184
+ return { ok: false, reason: "invalid-body-template" };
185
+ }
186
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
187
+ return { ok: false, reason: "invalid-body-template" };
188
+ }
189
+ return { ok: true, body: parsed };
68
190
  }
69
191
 
70
192
  /**
@@ -126,7 +248,14 @@ function createHandler(config, credentials, shared, logger) {
126
248
  return;
127
249
  }
128
250
 
129
- const result = await deliverNote(delivery, toGatewayPayload(payload));
251
+ const mapped = toGatewayPayload(payload, config.bodyTemplate);
252
+ if (mapped.ok === false) {
253
+ // A broken template is a configuration error that would fail on every
254
+ // alert; report it instead of forwarding a body the gateway cannot read.
255
+ respond(res, 500, { ok: false, reason: mapped.reason });
256
+ return;
257
+ }
258
+ const result = await deliverNote(delivery, mapped.body);
130
259
  if (result.reason === "credentials-unavailable") {
131
260
  respond(res, 503, { ok: false, reason: "credentials-unavailable" });
132
261
  return;
@@ -162,9 +291,10 @@ function createHandler(config, credentials, shared, logger) {
162
291
  * current even when this module mounted before the web server existed.
163
292
  */
164
293
  export function mountRelay(ctx, config, shared) {
165
- // Nothing is registered without a path that can be an exact route and a
166
- // reachable gateway: a half-configured relay would answer 502 on every POST,
167
- // which is harder to diagnose than no route at all.
294
+ // Nothing is registered without a path that can be an exact route, a
295
+ // reachable gateway, and a template that renders to a JSON object: a
296
+ // half-configured relay would answer 502 or 500 on every POST, which is
297
+ // harder to diagnose than no route at all.
168
298
  if (typeof config.path !== "string" || !config.path.startsWith("/")) {
169
299
  ctx.logger?.warn?.("dsh-notify-me: relay.enabled is true but relay.path is not an absolute path, nothing registered");
170
300
  return;
@@ -173,6 +303,11 @@ export function mountRelay(ctx, config, shared) {
173
303
  ctx.logger?.warn?.("dsh-notify-me: relay.enabled is true but no relay.target and no gateway.target, nothing registered");
174
304
  return;
175
305
  }
306
+ const templateProblem = bodyTemplateProblem(config.bodyTemplate);
307
+ if (templateProblem !== null) {
308
+ ctx.logger?.warn?.(`dsh-notify-me: relay.bodyTemplate cannot be used (${templateProblem}), nothing registered`);
309
+ return;
310
+ }
176
311
  const credentials = createCredentialReader(config.credentialsFile, ctx.logger);
177
312
 
178
313
  ctx.inject(["webServer"], (webCtx) => {
package/lib/win-toast.js CHANGED
@@ -57,10 +57,26 @@ function wscriptPath() {
57
57
  }
58
58
 
59
59
  /**
60
- * The protocol handler: record the clicked URL, then raise DSH. Paths are
61
- * baked in because the script lives next to the actions directory that the
62
- * host polls.
60
+ * The protocol handler: record the clicked URL, then raise DSH.
61
+ *
62
+ * The script stays pure ASCII: the actions directory is resolved from
63
+ * %LOCALAPPDATA% when the click happens rather than baked into the file. A
64
+ * profile path like C:\Users\<中文名>\... written as UTF-8 without a BOM is
65
+ * decoded by WSH with the system ANSI code page, which ate the backslash after
66
+ * the user name and made FolderExists fail with 800A004C (issue #36). Even so
67
+ * the file is written as UTF-16LE with a BOM: any non-ASCII that ever reaches
68
+ * it would then decode correctly.
63
69
  */
70
+ function actionsDirExpression(actionsDir) {
71
+ const defaultDir = process.env.LOCALAPPDATA
72
+ ? join(process.env.LOCALAPPDATA, "dsh-notify-me", "actions")
73
+ : "";
74
+ if (defaultDir && actionsDir.toLowerCase() === defaultDir.toLowerCase()) {
75
+ return 'sh.ExpandEnvironmentStrings("%LOCALAPPDATA%") & "\\dsh-notify-me\\actions"';
76
+ }
77
+ return '"' + actionsDir + '"';
78
+ }
79
+
64
80
  function handlerVbs(actionsDir) {
65
81
  return [
66
82
  "' Generated by dsh-notify-me. Records a toast action click and raises DSH.",
@@ -69,7 +85,7 @@ function handlerVbs(actionsDir) {
69
85
  'Set fso = CreateObject("Scripting.FileSystemObject")',
70
86
  'Set sh = CreateObject("WScript.Shell")',
71
87
  "url = WScript.Arguments(0)",
72
- 'dir = "' + actionsDir + '"',
88
+ "dir = " + actionsDirExpression(actionsDir),
73
89
  "If Not fso.FolderExists(dir) Then fso.CreateFolder(dir)",
74
90
  "name = fso.GetTempName()",
75
91
  "Set out = fso.CreateTextFile(dir & \"\\\" & name, True)",
@@ -80,6 +96,12 @@ function handlerVbs(actionsDir) {
80
96
  ].join("\r\n");
81
97
  }
82
98
 
99
+ /** UTF-16LE with a BOM: WSH must not decode the handler with the ANSI code page. */
100
+ function writeHandlerScript(vbsPath, actionsDir) {
101
+ const body = Buffer.from(handlerVbs(actionsDir), "utf16le");
102
+ writeFileSync(vbsPath, Buffer.concat([Buffer.from([0xff, 0xfe]), body]));
103
+ }
104
+
83
105
  /**
84
106
  * Register the route — only on the packed Windows desktop shell.
85
107
  * @param webCtx - cordis context holding `webServer`.
@@ -155,7 +177,7 @@ export function mountWinToast(webCtx, config, shared, logger, deps = {}) {
155
177
  protocolReady = (async () => {
156
178
  try {
157
179
  mkdirSync(actionsDir, { recursive: true });
158
- writeFileSync(vbsPath, handlerVbs(actionsDir), "utf8");
180
+ writeHandlerScript(vbsPath, actionsDir);
159
181
  } catch (e) {
160
182
  return false;
161
183
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-notify-me",
3
- "version": "1.19.0",
3
+ "version": "1.20.1",
4
4
  "description": "离开 DSH 页面也能收到提醒:需要你操作 / 后台回复完成时发系统通知、标题标记与提示音,支持审批快捷裁决与外部推送,Web 版与桌面版均可用。",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -5,7 +5,8 @@
5
5
  // PowerShell helper cannot reasonably run in CI, so spawn/exec are injected:
6
6
  // what is pinned here is the route contract (405/403/501/400, GET actions,
7
7
  // POST send/remove), the decoded toast payload, the HKCU protocol registration,
8
- // and the token rules — single use, bound to one approval key, expiring.
8
+ // the encoding of the generated VBS handler, and the token rules — single use,
9
+ // bound to one approval key, expiring.
9
10
  import fs from 'node:fs';
10
11
  import os from 'node:os';
11
12
  import path from 'node:path';
@@ -20,11 +21,15 @@ const win = await import(pathToFileURL(path.join(ROOT, 'lib', 'win-toast.js')).h
20
21
  assert(win.WIN_TOAST_ROUTE === '/__dsh-notify-me/win-toast', 'WIN_TOAST_ROUTE is the path the page calls');
21
22
 
22
23
  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-notify-me-win-'));
24
+ // mountWinToast derives its directories from %LOCALAPPDATA% on Windows; point
25
+ // that at the scratch dir so the test never touches the real profile directory.
26
+ const realLocalAppData = process.env.LOCALAPPDATA;
27
+ process.env.LOCALAPPDATA = tmp;
23
28
  const psPath = path.join(tmp, 'powershell.exe');
24
29
  const scriptPath = path.join(tmp, 'win-toast.ps1');
25
30
  fs.writeFileSync(psPath, '');
26
31
  fs.writeFileSync(scriptPath, '');
27
- const actionsDir = path.join(tmp, 'actions');
32
+ const actionsDir = path.join(tmp, 'dsh-notify-me', 'actions');
28
33
 
29
34
  const spawned = [];
30
35
  const execCalls = [];
@@ -61,7 +66,6 @@ function mount(config = {}, deps = {}) {
61
66
  win.mountWinToast(ctx, config, { bindHost: undefined, allowedOrigins: [] }, undefined, {
62
67
  spawn: fakeSpawn,
63
68
  execFile: fakeExec,
64
- dir: tmp,
65
69
  psPath: psPath,
66
70
  scriptPath: scriptPath,
67
71
  aumid: 'test.aumid',
@@ -153,9 +157,15 @@ try {
153
157
  assert(execCalls.length === 3, 'first approval registers the protocol with three reg.exe calls');
154
158
  assert(execCalls[0].file === 'reg' && execCalls[0].args.join(' ').includes('HKCU\\Software\\Classes\\dsh-notify-me'),
155
159
  'the protocol is registered under HKCU\\Software\\Classes');
156
- const handlerVbs = path.join(tmp, 'notify-handler.vbs');
160
+ const handlerVbs = path.join(tmp, 'dsh-notify-me', 'notify-handler.vbs');
157
161
  assert(fs.existsSync(handlerVbs), 'the protocol handler script is written');
158
- assert(fs.readFileSync(handlerVbs, 'utf8').includes(actionsDir), 'the handler writes into the actions directory');
162
+ const vbsBytes = fs.readFileSync(handlerVbs);
163
+ assert(vbsBytes[0] === 0xff && vbsBytes[1] === 0xfe, 'the handler script carries a UTF-16LE BOM');
164
+ const vbsText = vbsBytes.subarray(2).toString('utf16le');
165
+ assert(/^[\x00-\x7f]*$/.test(vbsText), 'the handler script is pure ASCII, so a non-ASCII profile path cannot be garbled');
166
+ assert(vbsText.includes('sh.ExpandEnvironmentStrings("%LOCALAPPDATA%") & "\\dsh-notify-me\\actions"'),
167
+ 'the actions directory is resolved from %LOCALAPPDATA% at click time');
168
+ assert(!vbsText.includes(tmp), 'no profile path is baked into the handler script');
159
169
 
160
170
  // 3b. Approve click: single use, bound to the approval key.
161
171
  writeAction('a1.txt', 'dsh-notify-me://approve?token=' + sentBody.token);
@@ -194,6 +204,8 @@ try {
194
204
  assert(spawned.length === 1 && spawned[0].args.includes('-RemoveTag') && spawned[0].args.includes(sentBody.id),
195
205
  'the remove spawns -RemoveTag for the history tag');
196
206
  } finally {
207
+ if (realLocalAppData === undefined) delete process.env.LOCALAPPDATA;
208
+ else process.env.LOCALAPPDATA = realLocalAppData;
197
209
  Object.defineProperty(process, 'platform', realPlatform);
198
210
  if (realElectron === undefined) delete process.versions.electron;
199
211
  else Object.defineProperty(process.versions, 'electron', { value: realElectron, configurable: true, writable: true });