dsh-notify-me 1.19.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 +20 -1
- package/README.en.md +75 -29
- package/README.md +62 -26
- package/cordis.patch.yml +1 -0
- package/lib/client.js +1 -1
- package/lib/index.js +17 -7
- package/lib/relay.js +149 -14
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,25 @@
|
|
|
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
|
+
|
|
5
24
|
## [1.19.0] — 2026-11-09
|
|
6
25
|
|
|
7
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 原生通道的几个边界。
|
|
@@ -47,7 +66,7 @@ All notable changes to **dsh-notify-me** are documented here.
|
|
|
47
66
|
- README 中英新增「Windows 桌面端怎么发带按钮的通知」一节;「macOS 桌面端怎么发系统通知」补上原生通知参与收起 / 自动消失、启动时排队的等待会重放、助手 `--id` / `--remove`;顶部导读、提醒渠道表、已知限制与开发自检的测试清单同步。
|
|
48
67
|
- `docs/console-config.md` / `.en.md` 补 `winToast`(profile patch 层配置,`{enabled:false}` 关掉宿主原生审批 Toast)与 `debug().winNative` / `winNativeLast`。
|
|
49
68
|
- `cordis.patch.yml` 补 `winToast` 配置行与注释;`docs/listing.md` 的 `latest` 更新到 1.19.0。
|
|
50
|
-
-
|
|
69
|
+
- 设置页截图按 1.19.0 重拍:中文 592×1170、英文 592×1188(比 1.18.0 多「前台也提醒(一键)」与「回到页面也保留提醒」两行,页脚版本号已是 `dsh-notify-me v1.19.0`),`docs/README.md` 的尺寸表与版本标注同步更新。
|
|
51
70
|
|
|
52
71
|
## [1.18.0] — 2026-11-08
|
|
53
72
|
|
package/README.en.md
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
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
|
|
|
@@ -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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
-
####
|
|
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
|
|
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:
|
|
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
|
|
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
|
-
[
|
|
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
|
|
77
|
+
Web 用户可再测审批按钮,通知上会带「同意 / 拒绝」。Windows 桌面端由宿主发原生 Toast,同样带按钮;macOS 桌面端只发普通通知(渠道差异见[提醒渠道](#提醒渠道))。
|
|
79
78
|
|
|
80
|
-
|
|
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'}
|
|
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.
|
|
3303
|
+
api.version = "1.20.0";
|
|
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
|
|
281
|
-
//
|
|
282
|
-
//
|
|
283
|
-
//
|
|
284
|
-
// every alert was silently
|
|
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 =
|
|
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
|
-
* @
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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
|
|
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
|
|
166
|
-
// reachable gateway
|
|
167
|
-
//
|
|
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) => {
|