Initial checkin

2026-06-02 23:00:35 +10:00
commit 6f5be7b451
8 changed files with 1312 additions and 0 deletions
@@ -0,0 +1,85 @@
+# sh3d — Web Push Notification PoC
+
+Tests the full Web Push loop: browser subscription → server-side send → notification
+delivered even when the tab is closed.
+
+## Prerequisites (for the cattletrack staging server)
+
+- The node server must be running on the staging box:
+  ```bash
+  cd /home/unisolve/sh3d
+  nohup node server.js > server.log 2>&1 &
+  echo $! > server.pid
+  ```
+- nginx must be running with the `/sh3d/` and `/sh3d/api/` location blocks configured.
+
+## Testing from a phone
+
+### One-time setup (do this once per device/browser)
+
+Open a **regular tab** (not private/incognito) in Firefox or Chrome on your phone and
+navigate to:
+
+```
+https://staging.cattletrack.au/sh3d/
+```
+
+Then tap the buttons in order:
+
+1. **Register service worker** — installs the background service worker
+2. **Request permission** — Android will show a system prompt; tap Allow
+3. **Fire a local notification** — confirms notifications work while the tab is open
+4. **Subscribe to push** — registers this device with the server; from this point on
+   the server can reach the device even when the browser is closed
+
+Each step logs its result in the blue status box. All four should succeed before
+proceeding.
+
+> **Private tabs won't work.** Service workers are discarded when a private tab closes,
+> so push subscriptions won't survive. Use a regular tab.
+
+> **Firefox on Android:** go to Android Settings → Apps → Firefox → Notifications and
+> confirm Lock screen, Badge, and Pop-up are all allowed.
+
+### Triggering a push from the command line
+
+Once a device has completed step 4, you can push to it from any terminal — including
+with the browser fully closed:
+
+```bash
+curl -s -X POST https://staging.cattletrack.au/sh3d/api/send \
+  -H "Content-Type: application/json" \
+  -d '{"title": "OGLAS trough alert!", "body": "Trough 21 appears to be empty"}' | jq .
+```
+
+A successful response looks like:
+
+```json
+{ "sent": 1, "results": [{ "endpoint": "https://...", "ok": true }] }
+```
+
+The notification appears on the phone lock screen / notification shade within a few
+seconds.
+
+### Button 5 (in-page send)
+
+**Ask server to push now** does the same thing as the curl command above but from
+within the page. Useful for a quick sanity check when the tab is open; use curl to
+prove it works with the tab backgrounded or closed.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `server.js` | Express server — serves /public, stores subscriptions in memory, exposes /api/send |
+| `public/index.html` | Test page with the 5-step flow |
+| `public/sw.js` | Service worker — handles incoming push events and notification taps |
+| `public/icon.svg` | Notification icon |
+
+## Known limitations (PoC only)
+
+- Subscriptions are stored **in memory** — lost when the server restarts. After a
+  restart each device must repeat step 4.
+- VAPID keys are hardcoded in `server.js` — move them to `.env` before any
+  production use.
+- One server instance, no redundancy.