#4352

feat(puter-js): puter.notifications

Openjfcastro92wants to merge intofrom

puter.notifications in puter.js. Part of PUT-2170. Stacks on #4351. Replaces #4322.

What

MethodDoes
notify(notification)creates an app.message for the current user; resolves to its uid
onNotification(handler, { catchUp?, since?, onError? })the app's own notifications: missed ones first (oldest first), then live ones, each delivered once; catches up again after a reconnect
on('click', handler) / offthe user tapped a push or a notification in the panel: { uid, target, data }
requestPermission() / hasPermission()asks for or checks notifications:push
registerDevice / listDevices / removeDevicefor Puter's own shells only (/push/devices)
  • There's no onPush, and apps never choose between live delivery and push; the server decides.
  • Clicks come only from the desktop's notificationClick broadcast. A click that arrived before the first handler goes to that handler once, after on() returns.
  • onNotification needs an app context (app_required otherwise) and live notifications on the server (events_disabled otherwise).
  • Typings in index.d.ts, a docs page per method with sidebar entries, and a playground example.

Deployments without a push service. The /push/devices routes come from an extension and are absent on a plain self-hosted install. The device methods turn that 404 into push_unavailable ("Push notifications aren't available on this deployment"). A missing device is device_not_found, so the two can't be confused. Documented on each method.

Tests

  • Unit (mocked fetch): 58 passed, including push_unavailable for each device method, a non-JSON 404, and device_not_found passing through.
  • API suite on node against a core server with no push service: the notifications and perms cases pass. The device cases that needed a push service were removed from this suite, along with its push capability.
  • check:puterjs:types is clean. Typecheck: no new errors.

Not verified

Clicks from a real desktop are covered by unit tests only.

Activity

6
github-actions[bot]4d ago

Coverage Report for puter.js SDK

StatusCategoryPercentageCovered / Total
🔵Lines59.58%
⬆️ +0.10 pp
5425 / 9105
🔵Statements57.61%
⬆️ +0.02 pp
5775 / 10023
🔵Functions59.12%
⬇️ -0.21 pp
991 / 1676
🔵Branches52.34%
⬇️ -0.35 pp
3655 / 6982
File Coverage
FileStmtsBranchesFunctionsLinesUncovered Lines
Changed Files
src/puter-js/src/index.js69.59%
⬆️ +0.05 pp
58.55%
🟰 ±0 pp
75.28%
🟰 ±0 pp
69.95%
⬆️ +0.05 pp
226, 238, 383-389, 432, 445, 455, 493, 495, 503-507, 546, 552-554, 563-565, 571-573, 579, 584-586, 592, 602-604, 606, 642-644, 649-725, 749, 751, 755-759, 791-801, 891, 899, 945, 958, 992-993, 1011, 1017-1018, 1056-1070, 1088-1094, 1100-1108, 1144, 1208-1259, 1297-1300, 1375, 1388-1389, 1407-1424, 1434-1435, 1451-1473, 1777, 1794, 1811, 1861-1886, 1999-2008, 2015-2069
src/puter-js/src/modules/UI.js6.63%
🟰 ±0 pp
3.45%
🟰 ±0 pp
4.44%
🟰 ±0 pp
6.95%
🟰 ±0 pp
258-262, 283-286, 293, 314-501, 567-569, 575-576, 587-682, 703, 706, 710-715, 727-730, 737-1007, 1016, 1027-1036, 1063-1882, 1911, 1918, 1922-1923, 1935-2397, 2415-2424, 2433-2519, 2536-2687, 2714-2763, 2767-2777, 2799-3068, 3083-3233
src/puter-js/src/modules/notifications/index.js53.57%0%25%55.55%62-77
src/puter-js/src/modules/notifications/listDevices.js0%0%0%0%12-14
src/puter-js/src/modules/notifications/notify.js80%70.58%100%83.33%8, 25-28, 34, 60-63
src/puter-js/src/modules/notifications/onNotification.js75%63.63%100%80%16, 19, 22
src/puter-js/src/modules/notifications/registerDevice.js0%0%0%0%14-28
src/puter-js/src/modules/notifications/removeDevice.js0%0%0%0%13-23
src/puter-js/src/modules/notifications/requestPermission.js66.66%100%50%66.66%11
src/puter-js/src/modules/notifications/lib/api.js7.69%0%0%8.33%12-44
src/puter-js/src/modules/notifications/lib/feed.js64.23%46.37%50%69.91%15, 18, 22-33, 37, 97-100, 102, 107-113, 119-120, 122, 138, 140-141, 144-145, 151-156, 179, 182-187, 194-195, 198, 207, 209, 215, 217, 222, 232-254
src/puter-js/src/modules/notifications/lib/shapes.js57.69%48.64%60%73.68%8, 10, 21, 22, 42-47, 51-61
Generated in workflow #1679 for commit 352a2fb by the Vitest Coverage Report Action
papa-pichita2d ago

upload file with puter.js can run this file html.