@voltro/plugin-notifications 0.85.0 → 0.87.0

package/dist/apnsPush.js

@@ -0,0 +1,97 @@
+import { PushTokenRejected as e } from "./errors.js";
+import { sign as t } from "node:crypto";
+//#region src/apnsPush.ts
+var n = {
+	production: "https://api.push.apple.com",
+	sandbox: "https://api.sandbox.push.apple.com"
+}, r = 3e6, i = /* @__PURE__ */ new Set([
+	"BadDeviceToken",
+	"Unregistered",
+	"DeviceTokenNotForTopic",
+	"ExpiredToken"
+]), a = (e) => Buffer.from(e).toString("base64url"), o = (e, n) => {
+	let r = a(JSON.stringify({
+		alg: "ES256",
+		kid: e.keyId
+	})), i = a(JSON.stringify({
+		iss: e.teamId,
+		iat: Math.floor(n / 1e3)
+	}));
+	return `${r}.${i}.${a(t("sha256", Buffer.from(`${r}.${i}`), {
+		key: e.privateKey,
+		dsaEncoding: "ieee-p1363"
+	}))}`;
+}, s = (e) => ({
+	aps: {
+		alert: {
+			title: e.title,
+			body: e.body
+		},
+		...e.badge === void 0 ? {} : { badge: e.badge },
+		sound: "default",
+		...e.image === void 0 ? {} : { "mutable-content": 1 },
+		...e.actions !== void 0 && typeof e.data.notification == "string" ? { category: e.data.notification } : {}
+	},
+	...e.data
+}), c = async ({ url: e, headers: t, body: n }) => {
+	let r = await import("node:http2"), i = new URL(e), a = r.connect(i.origin);
+	try {
+		return await new Promise((e, r) => {
+			a.once("error", r);
+			let o = a.request({
+				":method": "POST",
+				":path": i.pathname,
+				...t
+			}), s = 0, c = [];
+			o.on("response", (e) => {
+				s = Number(e[":status"] ?? 0);
+			}), o.on("data", (e) => c.push(e)), o.on("end", () => e({
+				status: s,
+				body: Buffer.concat(c).toString("utf8")
+			})), o.on("error", r), o.end(n);
+		});
+	} finally {
+		a.close();
+	}
+}, l = (t) => {
+	let a = [
+		"keyId",
+		"teamId",
+		"privateKey",
+		"bundleId"
+	].filter((e) => !t[e]);
+	if (a.length > 0) throw Error(`apnsTransport: ${a.join(", ")} required — supply APNS_KEY_ID, APNS_TEAM_ID, APNS_PRIVATE_KEY (the .p8) and APNS_BUNDLE_ID from the environment`);
+	let l = t.request ?? c, u = t.now ?? Date.now, d = n[t.environment ?? "production"], f = null, p = () => {
+		let e = u();
+		return (f === null || e - f.at > r) && (f = {
+			token: o(t, e),
+			at: e
+		}), f.token;
+	};
+	return async (n) => {
+		let r = await l({
+			url: `${d}/3/device/${encodeURIComponent(n.token)}`,
+			headers: {
+				authorization: `bearer ${p()}`,
+				"apns-topic": t.bundleId,
+				"apns-push-type": "alert",
+				"apns-priority": "10",
+				"content-type": "application/json"
+			},
+			body: JSON.stringify(s(n))
+		});
+		if (r.status === 200) return;
+		let a = "";
+		try {
+			a = String(JSON.parse(r.body).reason ?? "");
+		} catch {
+			a = "";
+		}
+		throw r.status === 410 || i.has(a) ? new e({
+			token: n.token,
+			reason: a || "Unregistered"
+		}) : Error(`apns: HTTP ${r.status}${a ? ` — ${a}` : ""}`);
+	};
+};
+//#endregion
+export { n as APNS_HOSTS, i as APNS_TOKEN_REJECTIONS, s as apnsBody, o as apnsProviderToken, l as apnsTransport };

package/dist/channels.js

@@ -0,0 +1,92 @@
+import { PushTokenRejected as e } from "./errors.js";
+//#region src/channels.ts
+var t = () => ({
+	id: "console",
+	deliver: async (e) => {
+		process.stdout.write(`[notify:${e.category}] → ${e.to}: ${e.title} — ${e.body}\n`);
+	}
+}), n = (e) => ({
+	id: e.id ?? "slack",
+	deliver: async (t) => {
+		let n = e.format ? e.format(t) : { text: `*${t.title}*\n${t.body}` }, r = await fetch(e.url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				...e.headers ?? {}
+			},
+			body: JSON.stringify(n)
+		});
+		if (!r.ok) throw Error(`webhook ${e.id ?? "slack"} POST ${r.status}`);
+	}
+}), r = (e) => ({
+	id: "email",
+	deliver: (t) => e({
+		to: t.to,
+		subject: t.title,
+		html: `<p>${t.body}</p>`,
+		text: t.body
+	})
+}), i = (e) => ({
+	id: "sms",
+	deliver: (t) => e(t.to, `${t.title}: ${t.body}`)
+}), a = (e, t) => ({
+	id: e,
+	deliver: t
+}), o = (e) => {
+	let t = typeof e?.image == "string" ? e.image : void 0, n = e?.actions, r = Array.isArray(n) ? n.filter((e) => typeof e == "object" && !!e && typeof e.id == "string" && typeof e.title == "string").map((e) => ({
+		id: e.id,
+		title: e.title
+	})) : void 0;
+	return {
+		...t === void 0 ? {} : { image: t },
+		...r !== void 0 && r.length > 0 ? { actions: r } : {}
+	};
+}, s = (t) => {
+	let n = async (n, r, i) => {
+		let a = {
+			token: r,
+			title: n.title,
+			body: n.body,
+			...i === void 0 ? {} : { badge: i },
+			data: n.data ?? {},
+			...o(n.data)
+		};
+		try {
+			return await t.transport(a), {
+				endpoint: r,
+				status: "sent"
+			};
+		} catch (n) {
+			let i = n instanceof e, a = i ? n.reason : n instanceof Error ? n.message : String(n);
+			if (i && t.onTokenRejected !== void 0) try {
+				await t.onTokenRejected(r, a);
+			} catch {}
+			return {
+				endpoint: r,
+				status: "failed",
+				error: a,
+				...i ? { pruned: t.onTokenRejected !== void 0 } : {}
+			};
+		}
+	}, r = async (e) => {
+		let r = await t.tokensFor(e.to), i = e.data?.badge, a = typeof i == "number" ? i : void 0, o = [];
+		for (let t of r) o.push(await n(e, t, a));
+		return o;
+	};
+	return {
+		id: t.id ?? "push",
+		deliver: async (t) => {
+			let n = await r(t), i = n.filter((e) => e.status === "failed");
+			if (n.length > 0 && i.length === n.length) throw new e({
+				token: n[0].endpoint,
+				reason: i[0].error ?? "all tokens rejected"
+			});
+		},
+		deliverDetailed: r
+	};
+}, c = (e, t, n, r, i) => {
+	let a = n ? e.filter((e) => n.includes(e)) : [...e], o = new Set(r.filter((e) => e.subjectId === i && e.category === t && e.enabled === !1).map((e) => e.channel));
+	return a.filter((e) => !o.has(e));
+};
+//#endregion
+export { t as consoleChannel, a as customChannel, r as emailChannel, s as pushChannel, c as resolveChannels, o as richPushOf, i as smsChannel, n as webhookChannel };

package/dist/durable.js

@@ -0,0 +1,42 @@
+import { defaultRecipients as e, sendInputFor as t } from "./sendNotification.js";
+import { Schema as n } from "effect";
+//#region src/durable.ts
+var r = "voltro.notification.send", i = async (t, i, a) => {
+	let o = n.decodeUnknownSync(i.audience)(a.audience), s = n.is(i.payload)(a.payload) ? n.encodeUnknownSync(i.payload)(a.payload) : (n.decodeUnknownSync(i.payload)(a.payload), a.payload), c = a.recipients ? await a.recipients(o) : e(o), l = [];
+	for (let e of c) {
+		let n = (a.localeFor ? await a.localeFor(e) : null) ?? a.defaultLocale ?? "en", o = {
+			notification: i.name,
+			recipientId: e,
+			locale: n,
+			payload: s,
+			tenantId: a.tenantId ?? null
+		}, c = await t.enqueue(r, { ...o }, {
+			...a.idempotencyKey === void 0 ? {} : { idempotencyKey: `${i.name}:${e}:${a.idempotencyKey}` },
+			...a.maxAttempts === void 0 ? {} : { maxAttempts: a.maxAttempts },
+			...a.delayMs === void 0 ? {} : { delayMs: a.delayMs }
+		});
+		l.push({
+			recipientId: e,
+			locale: n,
+			outboxId: c
+		});
+	}
+	return l;
+}, a = (e) => typeof e.notification == "string" && typeof e.recipientId == "string" && typeof e.locale == "string", o = (e) => {
+	let i = new Map(e.notifications.map((e) => [e.name, e]));
+	return {
+		effect: r,
+		maxAttempts: e.maxAttempts ?? 5,
+		handler: async ({ payload: o }) => {
+			if (!a(o)) throw Error(`${r}: row payload needs notification, recipientId and locale — got keys ${Object.keys(o).join(", ") || "(none)"}`);
+			let s = i.get(o.notification);
+			if (s === void 0) throw Error(`${r}: no descriptor named ${JSON.stringify(o.notification)} in this handler — list it in notificationOutboxHandler({ notifications })`);
+			let c = e.service();
+			if (c === void 0) throw Error(`${r}: the notification service is not available in this process`);
+			let l = n.decodeUnknownSync(s.payload)(o.payload);
+			return c.send(t(s, l, o.recipientId, o.locale, o.tenantId));
+		}
+	};
+};
+//#endregion
+export { r as NOTIFICATION_SEND_EFFECT, i as enqueueNotification, o as notificationOutboxHandler };

package/dist/errors.js

@@ -0,0 +1,8 @@
+import { Schema as e } from "effect";
+//#region src/errors.ts
+var t = class extends e.TaggedError()("PushTokenRejected", {
+	token: e.String,
+	reason: e.String
+}) {};
+//#endregion
+export { t as PushTokenRejected };

package/dist/expoPush.js

@@ -0,0 +1,35 @@
+import { PushTokenRejected as e } from "./errors.js";
+//#region src/expoPush.ts
+var t = "https://exp.host/--/api/v2/push/send", n = (e) => /^Expo(nent)?PushToken\[[^\]]+\]$/.test(e), r = (t = {}) => async (r) => {
+	if (!n(r.token)) throw new e({
+		token: r.token,
+		reason: "not an Expo push token"
+	});
+	let i = await (t.fetch ?? fetch)(t.endpoint ?? "https://exp.host/--/api/v2/push/send", {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			accept: "application/json",
+			...t.accessToken ? { authorization: `Bearer ${t.accessToken}` } : {}
+		},
+		body: JSON.stringify({
+			to: r.token,
+			title: r.title,
+			body: r.body,
+			data: r.data,
+			...r.badge === void 0 ? {} : { badge: r.badge },
+			...r.image === void 0 ? {} : { richContent: { image: r.image } },
+			...r.actions !== void 0 && typeof r.data.notification == "string" ? { categoryId: r.data.notification } : {}
+		})
+	}), a = await i.json().catch(() => ({}));
+	if (!i.ok) throw Error(`expo push: HTTP ${i.status}${a.errors?.[0]?.message ? ` — ${a.errors[0].message}` : ""}`);
+	let o = Array.isArray(a.data) ? a.data[0] : a.data;
+	if (!o || o.status === "ok") return;
+	let s = o.details?.error;
+	throw s === "DeviceNotRegistered" || s === "InvalidCredentials" ? new e({
+		token: r.token,
+		reason: s
+	}) : Error(`expo push: ${s ?? "error"}${o.message ? ` — ${o.message}` : ""}`);
+};
+//#endregion
+export { t as EXPO_PUSH_ENDPOINT, r as expoPushTransport, n as isExpoPushToken };

package/dist/fcmPush.js

@@ -0,0 +1,82 @@
+import { PushTokenRejected as e } from "./errors.js";
+import { sign as t } from "node:crypto";
+//#region src/fcmPush.ts
+var n = "https://www.googleapis.com/auth/firebase.messaging", r = "https://oauth2.googleapis.com/token", i = (e) => `https://fcm.googleapis.com/v1/projects/${encodeURIComponent(e)}/messages:send`, a = /* @__PURE__ */ new Set(["UNREGISTERED", "NOT_FOUND"]), o = (e) => Buffer.from(e).toString("base64url"), s = (e) => {
+	let t;
+	if (typeof e == "string") try {
+		t = JSON.parse(e);
+	} catch {
+		throw Error("fcmTransport: FCM_SERVICE_ACCOUNT is not the JSON Google issued");
+	}
+	else t = e;
+	let n = [
+		"project_id",
+		"client_email",
+		"private_key"
+	].filter((e) => typeof t[e] != "string" || t[e].length === 0);
+	if (n.length > 0) throw Error(`fcmTransport: service account is missing ${n.join(", ")} — supply FCM_SERVICE_ACCOUNT from the environment`);
+	return t;
+}, c = (e, r) => {
+	let i = Math.floor(r / 1e3), a = o(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT"
+	})), s = o(JSON.stringify({
+		iss: e.client_email,
+		scope: n,
+		aud: e.token_uri ?? "https://oauth2.googleapis.com/token",
+		iat: i,
+		exp: i + 3600
+	}));
+	return `${a}.${s}.${o(t("sha256", Buffer.from(`${a}.${s}`), e.private_key))}`;
+}, l = (e) => ({ message: {
+	token: e.token,
+	notification: {
+		title: e.title,
+		body: e.body,
+		...e.image === void 0 ? {} : { image: e.image }
+	},
+	data: Object.fromEntries(Object.entries(e.data).map(([e, t]) => [e, typeof t == "string" ? t : JSON.stringify(t)])),
+	...e.badge !== void 0 || e.image !== void 0 ? { apns: {
+		payload: { aps: {
+			...e.badge === void 0 ? {} : { badge: e.badge },
+			...e.image === void 0 ? {} : { "mutable-content": 1 }
+		} },
+		...e.image === void 0 ? {} : { fcm_options: { image: e.image } }
+	} } : {}
+} }), u = (t) => {
+	let n = s(t.serviceAccount), r = t.fetch ?? fetch, o = t.now ?? Date.now, u = t.endpoint ?? i(n.project_id), d = null, f = async () => {
+		let e = o();
+		if (d !== null && d.expiresAt - 6e4 > e) return d.token;
+		let t = await r(n.token_uri ?? "https://oauth2.googleapis.com/token", {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+				assertion: c(n, e)
+			}).toString()
+		}), i = await t.json().catch(() => ({}));
+		if (!t.ok || typeof i.access_token != "string") throw Error(`fcm: token exchange HTTP ${t.status}${i.error ? ` — ${i.error}` : ""}`);
+		return d = {
+			token: i.access_token,
+			expiresAt: e + (i.expires_in ?? 3600) * 1e3
+		}, d.token;
+	};
+	return async (t) => {
+		let n = await r(u, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${await f()}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify(l(t))
+		});
+		if (n.ok) return;
+		let i = await n.json().catch(() => ({})), o = i.error?.details?.find((e) => typeof e.errorCode == "string")?.errorCode ?? i.error?.status ?? "";
+		throw n.status === 404 || a.has(o) ? new e({
+			token: t.token,
+			reason: o || "UNREGISTERED"
+		}) : Error(`fcm: HTTP ${n.status}${o ? ` — ${o}` : ""}${i.error?.message ? ` — ${i.error.message}` : ""}`);
+	};
+};
+//#endregion
+export { n as FCM_SCOPE, a as FCM_TOKEN_REJECTIONS, r as GOOGLE_TOKEN_URI, c as fcmAssertion, l as fcmMessage, i as fcmSendEndpoint, u as fcmTransport, s as parseServiceAccount };

package/dist/index.d.ts

@@ -65,6 +65,7 @@ export declare const buildNotificationService: (deps: {
      *  a specific `channels:` list coalesce into one digest per subject per window.
      *  0 (default) disables digesting — every send goes out immediately. */
     readonly digestWindowMs?: number;
+    readonly deliveryGuards?: Readonly<Record<string, NotificationDeliveryGuard>>;
 }) => NotificationServiceShape;
 
 /** A delivery channel. `id` is the channel key prefs target (e.g. 'email',
@@ -410,6 +411,20 @@ export declare const minuteOfDayInZone: (at: Date, tz: string) => number;
 
 export declare const NOTIFICATION_SEND_EFFECT = "voltro.notification.send";
 
+export declare type NotificationDeliveryGuard = (input: NotificationDeliveryGuardInput) => boolean | Promise<boolean>;
+
+export declare interface NotificationDeliveryGuardInput {
+    readonly recipientId: string;
+    readonly tenantId: string | null;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+
+/** Persisted authorization reference; never forwarded to delivery channels. */
+export declare interface NotificationDeliveryGuardRef {
+    readonly id: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+
 export declare interface NotificationDescriptor<Audience = unknown, Payload = unknown> {
     readonly _tag: 'VoltroNotification';
     readonly name: string;
@@ -533,6 +548,8 @@ export declare interface NotificationsPluginOptions {
      *  boundary by the scheduled flush). A send that forces its own `channels:`
      *  bypasses the digest. 0 (default) = every send delivers immediately. */
     readonly digestWindowMs?: number;
+    /** Re-evaluated before actual delivery, including persisted quiet/digest holds. Unknown guards refuse. */
+    readonly deliveryGuards?: Readonly<Record<string, NotificationDeliveryGuard>>;
     /** How often the scheduled flush drains due digest windows + quiet-hours
      *  deferrals. Default 30s. Only runs once the store is bound at boot. */
     readonly flushIntervalMs?: number;
@@ -839,6 +856,7 @@ export declare const richPushOf: (data: Readonly<Record<string, unknown>> | unde
 
 /** What a caller asks to send. `channels` overrides the default routing. */
 export declare interface SendInput {
+    readonly deliveryGuard?: NotificationDeliveryGuardRef;
     readonly to: string;
     readonly category: string;
     readonly title: string;