@voltro/plugin-notifications 0.52.0 → 0.53.0

package/dist/rpc.d.ts

@@ -79,4 +79,31 @@ export declare const unsubscribeDescriptor: MutationProcedureDescriptor<"notific
     ok: typeof Schema.Boolean;
 }>, typeof Schema.Never>;
 
+export declare const webPushPublicKeyDescriptor: QueryProcedureDescriptor<"notifications.webPushPublicKey", Schema.Struct<{}>, Schema.Struct<{
+    key: typeof Schema.String;
+}>, typeof Schema.Never>;
+
+/** Registered only when the app configures a web-push channel — see
+ *  `notificationsPlugin`. */
+export declare const webPushRpcClientImports: ReadonlyArray<PluginRpcClientDescriptor>;
+
+export declare const webPushStatusDescriptor: QueryProcedureDescriptor<"notifications.webPushStatus", Schema.Struct<{}>, Schema.Struct<{
+    endpoints: typeof Schema.Number;
+}>, typeof Schema.Never>;
+
+export declare const webPushSubscribeDescriptor: MutationProcedureDescriptor<"notifications.webPushSubscribe", Schema.Struct<{
+    endpoint: typeof Schema.String;
+    p256dh: typeof Schema.String;
+    auth: typeof Schema.String;
+    ua: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, typeof Schema.Never>;
+
+export declare const webPushUnsubscribeDescriptor: MutationProcedureDescriptor<"notifications.webPushUnsubscribe", Schema.Struct<{
+    endpoint: typeof Schema.String;
+}>, Schema.Struct<{
+    ok: typeof Schema.Boolean;
+}>, typeof Schema.Never>;
+
 export { }

package/dist/rpc.js

@@ -84,7 +84,65 @@ var r = n({
 	input: e.Struct({}),
 	output: e.Struct({ ok: e.Boolean }),
 	openAccess: "self-scoped write: clears only the calling subject's own quiet-hours window"
-}), g = [
+}), g = n({
+	name: "notifications.webPushPublicKey",
+	input: e.Struct({}),
+	output: e.Struct({ key: e.String }),
+	openAccess: "public application-server key — the value every subscribing browser is handed by design"
+}), _ = t({
+	name: "notifications.webPushSubscribe",
+	input: e.Struct({
+		endpoint: e.String,
+		p256dh: e.String,
+		auth: e.String,
+		ua: e.optional(e.String)
+	}),
+	output: e.Struct({ ok: e.Boolean }),
+	openAccess: "self-scoped write: registers the calling subject's own browser subscription (the subject is never caller-supplied)"
+}), v = t({
+	name: "notifications.webPushUnsubscribe",
+	input: e.Struct({ endpoint: e.String }),
+	output: e.Struct({ ok: e.Boolean }),
+	openAccess: "self-scoped write: removes only a subscription the calling subject owns"
+}), y = n({
+	name: "notifications.webPushStatus",
+	input: e.Struct({}),
+	output: e.Struct({ endpoints: e.Number }),
+	openAccess: "self-scoped read: counts only the calling subject's own subscriptions"
+}), b = [
+	{
+		tag: "notifications.webPushPublicKey",
+		kind: "query",
+		import: {
+			module: "@voltro/plugin-notifications/rpc",
+			name: "webPushPublicKeyDescriptor"
+		}
+	},
+	{
+		tag: "notifications.webPushSubscribe",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-notifications/rpc",
+			name: "webPushSubscribeDescriptor"
+		}
+	},
+	{
+		tag: "notifications.webPushUnsubscribe",
+		kind: "mutation",
+		import: {
+			module: "@voltro/plugin-notifications/rpc",
+			name: "webPushUnsubscribeDescriptor"
+		}
+	},
+	{
+		tag: "notifications.webPushStatus",
+		kind: "query",
+		import: {
+			module: "@voltro/plugin-notifications/rpc",
+			name: "webPushStatusDescriptor"
+		}
+	}
+], x = [
 	{
 		tag: "notifications.inbox",
 		kind: "query",
@@ -191,4 +249,4 @@ var r = n({
 	}
 ];
 //#endregion
-export { c as archiveDescriptor, h as clearQuietHoursDescriptor, r as inboxDescriptor, s as markAllReadDescriptor, a as markReadDescriptor, o as markUnreadDescriptor, g as notificationsRpcClientImports, u as preferencesDescriptor, d as setPreferenceDescriptor, m as setQuietHoursDescriptor, f as subscribeDescriptor, l as unarchiveDescriptor, i as unreadCountDescriptor, p as unsubscribeDescriptor };
+export { c as archiveDescriptor, h as clearQuietHoursDescriptor, r as inboxDescriptor, s as markAllReadDescriptor, a as markReadDescriptor, o as markUnreadDescriptor, x as notificationsRpcClientImports, u as preferencesDescriptor, d as setPreferenceDescriptor, m as setQuietHoursDescriptor, f as subscribeDescriptor, l as unarchiveDescriptor, i as unreadCountDescriptor, p as unsubscribeDescriptor, g as webPushPublicKeyDescriptor, b as webPushRpcClientImports, y as webPushStatusDescriptor, _ as webPushSubscribeDescriptor, v as webPushUnsubscribeDescriptor };

package/dist/web.d.ts

@@ -45,4 +45,26 @@ export declare const useTopicSubscription: (apiName?: string) => {
 /** The caller's unread count. */
 export declare const useUnreadCount: (apiName?: string) => number;
 
+/**
+ * Permission flow + service-worker registration + subscribe/unsubscribe for
+ * the web-push channel. The service worker file is the app's to serve —
+ * copy `@voltro/plugin-notifications/sw.js` into `public/` (its scope decides
+ * which pages the worker controls; serving it from the root covers the app).
+ * Requires HTTPS (or localhost) — a push subscription is refused elsewhere.
+ */
+export declare const useWebPush: (opts?: {
+    swUrl?: string;
+    apiName?: string;
+}) => WebPushState;
+
+export declare interface WebPushState {
+    /** `unsupported` — no service worker / PushManager (or iOS Safari outside an
+     *  installed PWA). `denied` — the user refused notification permission.
+     *  `subscribed` reflects THIS browser's registration. */
+    readonly status: 'unsupported' | 'denied' | 'idle' | 'working' | 'subscribed' | 'error';
+    readonly error?: string;
+    readonly subscribe: () => Promise<void>;
+    readonly unsubscribe: () => Promise<void>;
+}
+
 export { }

package/dist/web.js

@@ -1,33 +1,92 @@
-import { useMutation as e, useSubscription as t } from "@voltro/client";
+import { useEffect as e, useState as t } from "react";
+import { useMutation as n, useSubscription as r } from "@voltro/client";
 //#region src/web.ts
-var n = (e = {}, n = "app") => {
-	let { data: r } = t(n, "notifications.inbox", e);
-	return r ?? [];
-}, r = (e = "app") => {
-	let { data: n } = t(e, "notifications.unreadCount", {});
-	return n?.count ?? 0;
-}, i = (t = "app") => {
-	let n = e(t, "notifications.markRead");
-	return (e) => n.mutate({ id: e });
-}, a = (t = "app") => {
-	let n = e(t, "notifications.setPreference");
-	return (e, t, r) => n.mutate({
+var i = (e = {}, t = "app") => {
+	let { data: n } = r(t, "notifications.inbox", e);
+	return n ?? [];
+}, a = (e = "app") => {
+	let { data: t } = r(e, "notifications.unreadCount", {});
+	return t?.count ?? 0;
+}, o = (e = "app") => {
+	let t = n(e, "notifications.markRead");
+	return (e) => t.mutate({ id: e });
+}, s = (e = "app") => {
+	let t = n(e, "notifications.setPreference");
+	return (e, n, r) => t.mutate({
 		category: e,
-		channel: t,
+		channel: n,
 		enabled: r
 	});
-}, o = (t = "app") => {
-	let n = e(t, "notifications.subscribe"), r = e(t, "notifications.unsubscribe");
+}, c = (e = "app") => {
+	let t = n(e, "notifications.subscribe"), r = n(e, "notifications.unsubscribe");
 	return {
-		subscribe: (e) => n.mutate({ topic: e }),
+		subscribe: (e) => t.mutate({ topic: e }),
 		unsubscribe: (e) => r.mutate({ topic: e })
 	};
-}, s = (t = "app") => {
-	let n = e(t, "notifications.setQuietHours"), r = e(t, "notifications.clearQuietHours");
+}, l = (e) => {
+	let t = e.replace(/-/g, "+").replace(/_/g, "/"), n = atob(t), r = new Uint8Array(n.length);
+	for (let e = 0; e < n.length; e++) r[e] = n.charCodeAt(e);
+	return r;
+}, u = (i = {}) => {
+	let a = i.apiName ?? "app", o = i.swUrl ?? "/sw.js", { data: s } = r(a, "notifications.webPushPublicKey", {}), c = n(a, "notifications.webPushSubscribe"), u = n(a, "notifications.webPushUnsubscribe"), d = typeof navigator < "u" && "serviceWorker" in navigator && typeof window < "u" && "PushManager" in window, [f, p] = t(d ? "idle" : "unsupported"), [m, h] = t(void 0);
+	e(() => {
+		if (!d) return;
+		let e = !1;
+		return navigator.serviceWorker.getRegistration(o).then(async (t) => {
+			let n = await t?.pushManager.getSubscription();
+			!e && n && p("subscribed");
+		}).catch(() => {}), () => {
+			e = !0;
+		};
+	}, [d, o]);
+	let g = async () => {
+		if (d) {
+			p("working"), h(void 0);
+			try {
+				if (await Notification.requestPermission() !== "granted") {
+					p("denied");
+					return;
+				}
+				if (s?.key === void 0) throw Error("application server key not loaded yet — retry in a moment");
+				let e = await navigator.serviceWorker.register(o);
+				await navigator.serviceWorker.ready;
+				let t = await e.pushManager.subscribe({
+					userVisibleOnly: !0,
+					applicationServerKey: l(s.key)
+				}), n = t.toJSON();
+				await c.mutate({
+					endpoint: t.endpoint,
+					p256dh: n.keys?.p256dh ?? "",
+					auth: n.keys?.auth ?? "",
+					ua: navigator.userAgent
+				}), p("subscribed");
+			} catch (e) {
+				h(e instanceof Error ? e.message : String(e)), p("error");
+			}
+		}
+	}, _ = async () => {
+		if (d) {
+			p("working"), h(void 0);
+			try {
+				let e = await (await navigator.serviceWorker.getRegistration(o))?.pushManager.getSubscription();
+				e && (await u.mutate({ endpoint: e.endpoint }), await e.unsubscribe()), p("idle");
+			} catch (e) {
+				h(e instanceof Error ? e.message : String(e)), p("error");
+			}
+		}
+	};
+	return {
+		status: f,
+		...m === void 0 ? {} : { error: m },
+		subscribe: g,
+		unsubscribe: _
+	};
+}, d = (e = "app") => {
+	let t = n(e, "notifications.setQuietHours"), r = n(e, "notifications.clearQuietHours");
 	return {
-		set: (e, t, r) => n.mutate({
+		set: (e, n, r) => t.mutate({
 			startMinute: e,
-			endMinute: t,
+			endMinute: n,
 			...r?.tz ? { tz: r.tz } : {},
 			...r?.policy ? { policy: r.policy } : {}
 		}),
@@ -35,4 +94,4 @@ var n = (e = {}, n = "app") => {
 	};
 };
 //#endregion
-export { n as useInbox, i as useMarkRead, s as useQuietHours, a as useSetNotificationPreference, o as useTopicSubscription, r as useUnreadCount };
+export { i as useInbox, o as useMarkRead, d as useQuietHours, s as useSetNotificationPreference, c as useTopicSubscription, a as useUnreadCount, u as useWebPush };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-notifications",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "One unified notification surface — email, Slack/webhook, SMS, push, in-app — with per-subject preference routing, an in-app inbox, and a delivery log. NotificationService + typed routes + useInbox/useUnreadCount hooks.",
   "keywords": [
     "voltro",
@@ -33,7 +33,8 @@
       "import": "./dist/rpc.js",
       "default": "./dist/rpc.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./sw.js": "./sw.js"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -43,12 +44,13 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.52.0",
-    "@voltro/database": "0.52.0",
-    "@voltro/protocol": "0.52.0"
+    "@voltro/client": "0.53.0",
+    "@voltro/database": "0.53.0",
+    "@voltro/protocol": "0.53.0"
   },
   "peerDependencies": {
-    "effect": "^3.22.0"
+    "effect": "^3.22.0",
+    "react": "^19.0.0"
   },
   "publishConfig": {
     "access": "public"

package/sw.js

@@ -0,0 +1,50 @@
+// @voltro/plugin-notifications — the web-push service worker.
+//
+// Copy this file into your web app's `public/` directory (conventionally as
+// `/sw.js` — its URL decides its scope, and the root covers the whole app).
+// It shows the pushed notification, opens the declared `url` on click, and
+// reports the click back to the delivery log via the click token.
+//
+// Self-contained on purpose: a service worker loads outside the bundler, so
+// nothing here may import anything.
+
+self.addEventListener('push', (event) => {
+  let payload = {}
+  try { payload = event.data ? event.data.json() : {} } catch { /* non-JSON push stays an empty notification */ }
+  const title = typeof payload.title === 'string' ? payload.title : 'Notification'
+  event.waitUntil((async () => {
+    // Tell open pages FIRST — an in-page inbox can refresh without a reload,
+    // and the page signal must not depend on the notification display (which
+    // a headless or focus-suppressed environment may decline).
+    const clientList = await self.clients.matchAll({ type: 'window', includeUncontrolled: true })
+    for (const client of clientList) client.postMessage({ type: 'voltro:push', payload })
+    await self.registration.showNotification(title, {
+      body: typeof payload.body === 'string' ? payload.body : '',
+      data: { url: payload.url, clickToken: payload.clickToken },
+      ...(payload.data && typeof payload.data.badge === 'number' ? { badge: payload.data.badge } : {}),
+    })
+  })())
+})
+
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close()
+  const data = event.notification.data || {}
+  event.waitUntil((async () => {
+    // Best-effort click report — the token is the capability, same-origin only.
+    if (typeof data.clickToken === 'string' && data.clickToken !== '') {
+      try {
+        await fetch('/_voltro/notifications/clicked', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ token: data.clickToken }),
+        })
+      } catch { /* a failed report never blocks the open */ }
+    }
+    const url = typeof data.url === 'string' && data.url !== '' ? data.url : '/'
+    const clientList = await self.clients.matchAll({ type: 'window', includeUncontrolled: true })
+    for (const client of clientList) {
+      if ('focus' in client) { await client.focus(); if ('navigate' in client) await client.navigate(url); return }
+    }
+    await self.clients.openWindow(url)
+  })())
+})