@soffits/dsh-notify-inbox 0.0.0-stage → 0.1.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 ADDED
@@ -0,0 +1,5 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ - First release: per-person inbox from JSON lines, read and unread kept on the server, Web Push (RFC 8291 encryption and VAPID on node:crypto) with deep links, buttons on notifications (ask about this, done, snooze, event, link) whose presses become `ui.action.<kind>` events, English and Chinese.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sakina
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.md CHANGED
@@ -1,3 +1,97 @@
1
- # Temporary Holding Version
1
+ # dsh-notify-inbox
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A notification inbox for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Something outside DSH (your assistant's notification router, a cron script, a watcher) files notifications as JSON lines, one folder per person. The plugin shows each signed-in person their own inbox in the Web UI, keeps read and unread per person on the server, pushes new ones to the browsers and installed home-screen apps they turned notifications on for, and gives every notification buttons: ask the agent about it, mark it done, remind me later.
4
+
5
+ The contract is files, so nothing gets lost while DSH restarts: the writer keeps appending, and the plugin pushes whatever arrived once it's back.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ npx @deepseek-ai/dsh plugin --profile web add @soffits/dsh-notify-inbox@latest
11
+ ```
12
+
13
+ Restart `dsh web`. The inbox appears in the sidebar. Then set `dataDir` in a profile override of the `notify-inbox` row:
14
+
15
+ ```yaml
16
+ - override:
17
+ - id: notify-inbox
18
+ config:
19
+ dataDir: ~/notify-inbox
20
+ # For a DSH several people sign in to (needs a sign-in plugin that provides requestIdentity):
21
+ peopleFile: ~/people.json
22
+ peopleKey: oidc_users
23
+ vapidFile: ~/secrets/notify-inbox/vapid.json
24
+ vapidSubject: mailto:you@example.org
25
+ ```
26
+
27
+ | Option | Default | Meaning |
28
+ |---|---|---|
29
+ | `dataDir` | `~/.dsh/notify-inbox` | Where the writer files notifications: `<dataDir>/<person>/inbox.jsonl`. |
30
+ | `people` | `{}` | Verified user id (an OIDC `sub`) → person id (the folder name, compared case-insensitively). |
31
+ | `peopleFile`, `peopleKey` | | A JSON file with more of the same mapping, re-read when it changes; `peopleKey` picks a top-level key. |
32
+ | `vapidFile` | `<dataDir>/.push/vapid.json` | The Web Push key pair, made on first start with mode 600. Keep it: a new key means every device subscribes again. |
33
+ | `vapidSubject` | `mailto:admin@example.invalid` | A contact push services can reach. Set your own. |
34
+ | `pollSeconds` | `5` | How often new lines are looked for (to push them). |
35
+
36
+ **Who sees what.** With a mapping, every request is checked on the server: a person sees, marks and presses only their own inbox, and a request without a verified identity sees nothing. The identity comes from any plugin that provides a `requestIdentity` service (`current()` → `{ provider, issuer, id, name } | null`), such as [dsh-oidc](https://github.com/soffits/dsh-oidc) 0.3.0-alpha.9 or later. Without a mapping (a DSH only you use), you see every folder.
37
+
38
+ ## Writing notifications
39
+
40
+ Append one JSON object per line to `<dataDir>/<person>/inbox.jsonl` (person ids are lower-case letters, digits, `-` and `_`). Append whole lines in one write; a line still being written is picked up when it ends.
41
+
42
+ ```json
43
+ {"v": 1, "id": "20261117T155012Z-3f9a1c", "time": "2026-11-17T15:50:12Z", "lane": "interrupt",
44
+ "domain": "home", "title": "Water leak", "spoken": "The kitchen sensor is wet.",
45
+ "text": "The sensor under the sink reported water at 15:50.", "links": ["https://example.org/cam"],
46
+ "files": [{"name": "photo.jpg", "size": 48213, "stored": true}],
47
+ "source": "leak-watch", "key": "leak-kitchen", "test": false, "push": true,
48
+ "actions": [{"kind": "done", "id": "done", "label": "Dealt with it", "payload": {}},
49
+ {"kind": "snooze", "id": "snooze", "label": "", "payload": {}}],
50
+ "routed": [{"destination": "chat", "type": "telegram", "ok": true},
51
+ {"destination": "phone", "type": "ntfy", "ok": false, "detail": "timed out"}]}
52
+ ```
53
+
54
+ - `id` (required, unique), `time` (required, ISO 8601). `lane: "interrupt"` marks it urgent (red dot, high push urgency).
55
+ - `title`, `spoken` (one short line: the push body), `text` (the full text), `links` (http/https).
56
+ - `files`: attachments the writer copied to `<dataDir>/<person>/files/<id>/<name>`; only those are served, and only to that person.
57
+ - `push: false` files it without a push. `test: true` labels it as a test.
58
+ - `routed`: where else the notification went and whether that worked; shown under the text.
59
+ - `actions`: buttons, see below.
60
+
61
+ A line `{"v": 1, "type": "handled", "record": "<id>", "press": "<press id>", "action": "done", "result": "done", "time": "..."}` tells the inbox that a press on that record was dealt with (`result: "snoozed"` with `until` shows when it comes back). Bad lines are skipped and counted.
62
+
63
+ ## Buttons
64
+
65
+ Every notification gets **Ask about this**: it opens a new session with the notification quoted into the message box, ready to edit and send. Since the person sends it from the Web UI, the sign-in plugin records them as the sender.
66
+
67
+ Declared `actions` add more: `done`, `snooze` (a small picker: in an hour, this evening, tomorrow morning; or a fixed `payload.until`), `event` (anything else) and `link` (`payload.url`). A press on `done`, `snooze` or `event` is checked on the server (the record must be the caller's and declare that button), appended to `<dataDir>/<person>/actions.jsonl`, and published on the event channel `ui.action.<kind>` when [dsh-cron-jobs](https://github.com/soffits/dsh-cron-jobs) is installed, so a job listening there can act on it:
68
+
69
+ ```json
70
+ {"action": "snooze", "id": "snooze", "payload": {"until": "2026-11-18T09:00:00-05:00"}, "person": "ana",
71
+ "at": "2026-11-17T21:04:11Z", "source": {"plugin": "notify-inbox", "record": "20261117T155012Z-3f9a1c", "key": "leak-kitchen"},
72
+ "press": "9f2c41aa07b3"}
73
+ ```
74
+
75
+ The page shows the press as waiting until a `handled` line for it shows up.
76
+
77
+ ## Push notifications
78
+
79
+ Open the inbox on the device and press **Turn on**. The browser picks its own push service, and the plugin only ever talks to that service, with the message encrypted end to end (RFC 8291, VAPID per RFC 8292, no third-party library):
80
+
81
+ - **iPhone and iPad** (iOS 16.4+): add DSH to the Home Screen, open it from there, then turn notifications on. Pushes go through Apple's service.
82
+ - **Chrome, Edge, Android**: pushes go through Google's Firebase Cloud Messaging, so they don't arrive where Google is blocked.
83
+ - **Firefox**: Mozilla's push service.
84
+
85
+ Tapping a notification opens the inbox on it. A device whose subscription expired is dropped the first time its push service says so.
86
+
87
+ ## Files the plugin writes
88
+
89
+ All under `dataDir`: `<person>/read.json` (read marks), `<person>/actions.jsonl` (presses), `.push/subscriptions.json` and `.push/cursor.json` (how far each inbox was pushed, so a restart doesn't push the backlog), and the VAPID key unless `vapidFile` says otherwise. It never rewrites `inbox.jsonl`.
90
+
91
+ ## Removing it
92
+
93
+ Remove the plugin from the profile. The data folder stays until you delete it; browsers keep a dormant service worker under `/api/notify-inbox/` until their site data is cleared.
94
+
95
+ ## License
96
+
97
+ MIT