@arkstack/notifications 0.16.5 → 0.16.7

package/dist/index.d.ts

@@ -28,7 +28,8 @@ type MailRecipientAddress = Record<string, string>;
 type MailRecipient = string | MailRecipientAddress | Array<string | MailRecipientAddress>;
 type NotificationData = Record<string, unknown>;
 type SmsDriverName = 'africastalking' | 'twilio';
-type NotificationChannel = 'mail' | 'sms' | 'db';
+type RealtimeDriverName = 'pusher' | 'firebase';
+type NotificationChannel = 'mail' | 'sms' | 'db' | 'realtime';
 type MailDriverOptions = {
   transport?: 'africastalking' | 'twilio' | 'file' | 'smtp';
   host?: string;
@@ -54,6 +55,45 @@ type SmsDriverOptions = {
     from?: string;
   };
 };
+type PusherTransportConfig = {
+  app_id?: string;
+  key?: string;
+  secret?: string;
+  cluster?: string;
+  use_tls?: boolean;
+};
+type FirebaseTransportConfig = {
+  project_id?: string;
+  client_email?: string;
+  private_key?: string;
+};
+type RealtimeDriverOptions = {
+  transport?: RealtimeDriverName; /** Channel/topic to broadcast on. Defaults to `${channel_prefix}${user.id}`. */
+  channel?: string; /** Event name clients subscribe to. Defaults to config `event` or `notification`. */
+  event?: string; /** Also persist the notification to the database (requires a User recipient). */
+  store?: boolean;
+  pusher?: PusherTransportConfig;
+  firebase?: FirebaseTransportConfig;
+};
+/** The notification payload delivered to realtime clients. */
+type RealtimeNotificationPayload = {
+  id: string;
+  type: DbNotificationType | null;
+  title: string;
+  description: string;
+  actionText?: string | null;
+  actionLink?: string | null;
+  meta?: NotificationData | null;
+  read_at: string | null;
+  created_at: string;
+};
+/** The result of a realtime broadcast (plus the stored record when `store` is on). */
+type RealtimeBroadcastResult = {
+  channel: string;
+  event: string;
+  payload: RealtimeNotificationPayload;
+  stored?: UserNotification;
+};
 type DbNotificationType = 'transaction' | 'pocket' | 'family' | 'security' | 'promo' | 'bill' | 'goal' | string;
 type DbNotificationPayload = {
   type?: DbNotificationType | null;
@@ -68,13 +108,17 @@ type NotificationDriverMap = {
   mail: DriverResult;
   sms: DriverResult;
   db: UserNotification;
+  realtime: RealtimeBroadcastResult;
 };
 interface NotificationConfig {
   default_driver: 'mail' | 'sms' | 'db';
   drivers: {
     mail: {
       transport: 'smtp' | 'file';
-      from: string;
+      from: string | {
+        name: string;
+        address: string;
+      };
       test_address: string;
     };
     sms: {
@@ -84,6 +128,12 @@ interface NotificationConfig {
     db: {
       table: string;
     };
+    realtime?: {
+      transport: RealtimeDriverName; /** Prefix for the per-user channel/topic (default `user.`). */
+      channel_prefix?: string; /** Event name clients subscribe to (default `notification`). */
+      event?: string; /** Persist broadcasts to the database by default. */
+      store?: boolean;
+    };
   };
   transports: {
     smtp: {
@@ -124,6 +174,18 @@ interface NotificationConfig {
       authToken: string;
       from: string;
     };
+    pusher?: {
+      app_id: string;
+      key: string;
+      secret: string;
+      cluster: string;
+      use_tls?: boolean;
+    };
+    firebase?: {
+      project_id: string;
+      client_email: string;
+      private_key: string;
+    };
   };
 }
 type MergedTransportConfig = MergedConfig<NotificationConfig['transports'][NonNullable<MailDriverOptions['transport']>]>;
@@ -223,6 +285,70 @@ declare class MailNotification extends NotificationContract {
   private normalizeRecipient;
 }
 //#endregion
+//#region src/Contracts/RealtimeDriver.d.ts
+/**
+ * A realtime transport (Pusher, Firebase, …) broadcasts a notification payload
+ * to a channel/topic that connected clients subscribe to.
+ */
+interface RealtimeDriver {
+  broadcast(channel: string, event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
+}
+//#endregion
+//#region src/drivers/RealtimeNotification.d.ts
+/**
+ * Broadcasts a notification to connected clients over a realtime transport
+ * (Pusher or Firebase). The notification is delivered on a per-user channel and,
+ * when `store` is enabled, is also persisted so the client can load history.
+ */
+declare class RealtimeNotification extends NotificationContract<RealtimeBroadcastResult> {
+  /**
+   * The underlying transport; assignable so tests can inject a fake.
+   */
+  driver: RealtimeDriver;
+  private user?;
+  private channelName?;
+  private eventName;
+  private channelPrefix;
+  private shouldStore;
+  private payload;
+  constructor(options?: RealtimeDriverOptions);
+  from(_from: string): this;
+  subject(subject: string): this;
+  /**
+   * Set the recipient: a `User` (derives the channel) or an explicit channel string.
+   *
+   * @param recipient
+   * @returns
+   */
+  recipient(recipient: NotificationRecipient | User): this;
+  /**
+   * Broadcast on an explicit channel/topic instead of the per-user default.
+    *
+    * @param channel
+    * @returns
+    */
+  channel(channel: string): this;
+  /**
+   * The event name clients subscribe to (default `notification`).
+   *
+   * @param channel
+   * @returns
+   */
+  event(event: string): this;
+  /**
+   * Also persist the notification (requires a `User` recipient).
+   *
+   * @param channel
+   * @returns
+   */
+  store(store?: boolean): this;
+  type(type: DbNotificationType | null): this;
+  action(text?: string | null, link?: string | null): this;
+  meta(meta?: NotificationData | null): this;
+  private resolveChannel;
+  send(message: string, subject?: string, _recipient?: NotificationRecipient, data?: NotificationData): Promise<RealtimeBroadcastResult>;
+}
+//#endregion
 //#region src/drivers/sms/AfricasTalkingSmsDriver.d.ts
 declare class AfricasTalkingSmsDriver {
   private driver;
@@ -258,17 +384,20 @@ type DriverMap = {
   email: MailNotification;
   sms: SmsNotification;
   db: DbNotification;
+  realtime: RealtimeNotification;
 };
 //#endregion
 //#region src/Notification.d.ts
+type DriverOptions = MailDriverOptions | SmsDriverOptions | RealtimeDriverOptions;
 declare class Notification<D extends keyof DriverMap = keyof DriverMap> {
   private driver;
-  constructor(driver: D, options?: MailDriverOptions | SmsDriverOptions);
+  constructor(driver: D, options?: DriverOptions);
   static mail(options?: MailDriverOptions): MailNotification;
   static email(options?: MailDriverOptions): MailNotification;
   static sms(options?: SmsDriverOptions): SmsNotification;
   static db(): DbNotification;
-  static channel(channel?: NotificationChannel | 'email', options?: MailDriverOptions | SmsDriverOptions): MailNotification | SmsNotification | DbNotification;
+  static realtime(options?: RealtimeDriverOptions): RealtimeNotification;
+  static channel(channel?: NotificationChannel | 'email', options?: DriverOptions): MailNotification | SmsNotification | DbNotification | RealtimeNotification;
   prepare(recipient?: null | MailRecipient | NotificationRecipient | User, data?: NotificationData): DriverMap[D];
   private static createDriver;
 }
@@ -287,7 +416,39 @@ declare class UserNotificationCenter {
 //#region src/config.d.ts
 declare const configure: <T extends DotPath<NotificationConfig>>(key: T, defaultValue: unknown) => DotPathValue<NotificationConfig, T>;
 //#endregion
+//#region src/drivers/realtime/PusherRealtimeDriver.d.ts
+/**
+ * Broadcasts notifications over [Pusher Channels](https://pusher.com/channels).
+ *
+ * The `pusher` server SDK is an optional peer dependency, imported lazily so the
+ * package installs without it; it is only required when this transport is used.
+ */
+declare class PusherRealtimeDriver implements RealtimeDriver {
+  private options;
+  private clientPromise?;
+  constructor(options?: PusherTransportConfig);
+  private client;
+  broadcast(channel: string, event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
+}
+//#endregion
+//#region src/drivers/realtime/FirebaseRealtimeDriver.d.ts
+/**
+ * Broadcasts notifications over [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)
+ * topics (the channel name maps to an FCM topic).
+ *
+ * `firebase-admin` is an optional peer dependency, imported lazily so the
+ * package installs without it; it is only required when this transport is used.
+ * FCM data values must be strings, so the payload is JSON-encoded.
+ */
+declare class FirebaseRealtimeDriver implements RealtimeDriver {
+  private options;
+  private messagingPromise?;
+  constructor(options?: FirebaseTransportConfig);
+  private messaging;
+  broadcast(channel: string, event: string, payload: RealtimeNotificationPayload): Promise<string>;
+}
+//#endregion
 //#region src/utils/template.d.ts
 declare const interpolate: (value: string, data?: NotificationData) => string;
 //#endregion
-export { AfricasTalkingSmsDriver, DbNotification, DbNotificationPayload, DbNotificationType, DriverResult, MailDriverOptions, MailNotification, MailRecipient, MailRecipientAddress, MergedTransportConfig, Notification, NotificationChannel, NotificationConfig, NotificationContract, NotificationData, NotificationDriverMap, NotificationRecipient, SmsDriverName, SmsDriverOptions, SmsNotification, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };
+export { AfricasTalkingSmsDriver, DbNotification, DbNotificationPayload, DbNotificationType, DriverResult, FirebaseRealtimeDriver, FirebaseTransportConfig, MailDriverOptions, MailNotification, MailRecipient, MailRecipientAddress, MergedTransportConfig, Notification, NotificationChannel, NotificationConfig, NotificationContract, NotificationData, NotificationDriverMap, NotificationRecipient, PusherRealtimeDriver, PusherTransportConfig, RealtimeBroadcastResult, RealtimeDriver, RealtimeDriverName, RealtimeDriverOptions, RealtimeNotification, RealtimeNotificationPayload, SmsDriverName, SmsDriverOptions, SmsNotification, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };

package/dist/index.js

@@ -3,6 +3,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import nodemailer from "nodemailer";
 import { Arkstack } from "@arkstack/contract";
+import { randomUUID } from "node:crypto";
 import africastalking from "africastalking";
 import twilio from "twilio";
 import { Model } from "@arkstack/database";
@@ -321,6 +322,222 @@ var MailNotification = class extends NotificationContract {
 	}
 };
 //#endregion
+//#region src/drivers/realtime/FirebaseRealtimeDriver.ts
+/**
+* Broadcasts notifications over [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)
+* topics (the channel name maps to an FCM topic).
+*
+* `firebase-admin` is an optional peer dependency, imported lazily so the
+* package installs without it; it is only required when this transport is used.
+* FCM data values must be strings, so the payload is JSON-encoded.
+*/
+var FirebaseRealtimeDriver = class {
+	options;
+	messagingPromise;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	messaging() {
+		this.messagingPromise ??= (async () => {
+			const [app, messaging] = await Promise.all([import("firebase-admin/app"), import("firebase-admin/messaging")]).catch(() => {
+				throw new Error("The \"firebase-admin\" package is required for the Firebase realtime transport. Install it with `npm i firebase-admin`.");
+			});
+			const credential = app.cert({
+				projectId: this.options.project_id ?? env("FIREBASE_PROJECT_ID", ""),
+				clientEmail: this.options.client_email ?? env("FIREBASE_CLIENT_EMAIL", ""),
+				privateKey: (this.options.private_key ?? env("FIREBASE_PRIVATE_KEY", ""))?.replace(/\\n/g, "\n")
+			});
+			const name = "arkstack-realtime";
+			const instance = app.getApps().find((a) => a.name === name) ?? app.initializeApp({ credential }, name);
+			return messaging.getMessaging(instance);
+		})();
+		return this.messagingPromise;
+	}
+	async broadcast(channel, event, payload) {
+		const messaging = await this.messaging();
+		const topic = channel.replace(/[^a-zA-Z0-9-_.~%]/g, "_");
+		return await messaging.send({
+			topic,
+			data: {
+				event,
+				payload: JSON.stringify(payload)
+			}
+		});
+	}
+};
+//#endregion
+//#region src/drivers/realtime/PusherRealtimeDriver.ts
+/**
+* Broadcasts notifications over [Pusher Channels](https://pusher.com/channels).
+*
+* The `pusher` server SDK is an optional peer dependency, imported lazily so the
+* package installs without it; it is only required when this transport is used.
+*/
+var PusherRealtimeDriver = class {
+	options;
+	clientPromise;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	client() {
+		this.clientPromise ??= (async () => {
+			const mod = await import("pusher").catch(() => {
+				throw new Error("The \"pusher\" package is required for the Pusher realtime transport. Install it with `npm i pusher`.");
+			});
+			return new (mod.default ?? mod)({
+				appId: this.options.app_id ?? env("PUSHER_APP_ID", ""),
+				key: this.options.key ?? env("PUSHER_KEY", ""),
+				secret: this.options.secret ?? env("PUSHER_SECRET", ""),
+				cluster: this.options.cluster ?? env("PUSHER_CLUSTER", "mt1"),
+				useTLS: this.options.use_tls ?? true
+			});
+		})();
+		return this.clientPromise;
+	}
+	async broadcast(channel, event, payload) {
+		return await (await this.client()).trigger(channel, event, payload);
+	}
+};
+//#endregion
+//#region src/drivers/RealtimeNotification.ts
+/**
+* Broadcasts a notification to connected clients over a realtime transport
+* (Pusher or Firebase). The notification is delivered on a per-user channel and,
+* when `store` is enabled, is also persisted so the client can load history.
+*/
+var RealtimeNotification = class extends NotificationContract {
+	/** 
+	* The underlying transport; assignable so tests can inject a fake. 
+	*/
+	driver;
+	user;
+	channelName;
+	eventName;
+	channelPrefix;
+	shouldStore;
+	payload = {};
+	constructor(options = {}) {
+		super();
+		const driverConfig = configure("drivers.realtime", {});
+		const transport = options.transport ?? driverConfig?.transport ?? "pusher";
+		const transportConfig = configure(`transports.${transport}`, {});
+		this.channelName = options.channel;
+		this.eventName = options.event ?? driverConfig?.event ?? "notification";
+		this.channelPrefix = driverConfig?.channel_prefix ?? "user.";
+		this.shouldStore = options.store ?? driverConfig?.store ?? false;
+		this.driver = transport === "firebase" ? new FirebaseRealtimeDriver({
+			...transportConfig,
+			...options.firebase
+		}) : new PusherRealtimeDriver({
+			...transportConfig,
+			...options.pusher
+		});
+	}
+	from(_from) {
+		return this;
+	}
+	subject(subject) {
+		this.payload.title = subject;
+		return this;
+	}
+	/** 
+	* Set the recipient: a `User` (derives the channel) or an explicit channel string. 
+	* 
+	* @param recipient 
+	* @returns 
+	*/
+	recipient(recipient) {
+		if (typeof recipient === "object" && !Array.isArray(recipient) && "id" in recipient) {
+			this.user = recipient;
+			return this;
+		}
+		if (typeof recipient === "string") {
+			this.channelName = recipient;
+			return this;
+		}
+		throw new Error("Realtime notifications require a user recipient or a channel name");
+	}
+	/**
+	* Broadcast on an explicit channel/topic instead of the per-user default. 
+	* 
+	* @param channel 
+	* @returns 
+	*/
+	channel(channel) {
+		this.channelName = channel;
+		return this;
+	}
+	/**
+	* The event name clients subscribe to (default `notification`). 
+	* 
+	* @param channel 
+	* @returns 
+	*/
+	event(event) {
+		this.eventName = event;
+		return this;
+	}
+	/**
+	* Also persist the notification (requires a `User` recipient). 
+	* 
+	* @param channel 
+	* @returns 
+	*/
+	store(store = true) {
+		this.shouldStore = store;
+		return this;
+	}
+	type(type) {
+		this.payload.type = type;
+		return this;
+	}
+	action(text, link) {
+		this.payload.actionText = text;
+		this.payload.actionLink = link;
+		return this;
+	}
+	meta(meta) {
+		this.payload.meta = meta;
+		return this;
+	}
+	resolveChannel() {
+		if (this.channelName) return this.channelName;
+		if (this.user) return `${this.channelPrefix}${this.user.id}`;
+		throw new Error("No channel resolved for realtime notification (provide a user or channel)");
+	}
+	async send(message, subject, _recipient, data) {
+		const channel = this.resolveChannel();
+		const mergedData = this.mergeData(data);
+		const base = {
+			type: this.payload.type ?? null,
+			title: interpolate(subject ?? this.payload.title ?? "", mergedData),
+			description: interpolate(message, mergedData),
+			actionText: this.payload.actionText ?? null,
+			actionLink: this.payload.actionLink ?? null,
+			meta: this.payload.meta ?? null
+		};
+		const stored = this.shouldStore && this.user ? await UserNotificationCenter.create(this.user, base) : void 0;
+		const payload = {
+			id: stored ? String(stored.id) : randomUUID(),
+			type: base.type ?? null,
+			title: base.title,
+			description: base.description,
+			actionText: base.actionText ?? null,
+			actionLink: base.actionLink ?? null,
+			meta: base.meta ?? null,
+			read_at: stored?.readAt ? new Date(stored.readAt).toISOString() : null,
+			created_at: stored?.createdAt ? new Date(stored.createdAt).toISOString() : (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await this.driver.broadcast(channel, this.eventName, payload);
+		return {
+			channel,
+			event: this.eventName,
+			payload,
+			stored
+		};
+	}
+};
+//#endregion
 //#region src/drivers/sms/AfricasTalkingSmsDriver.ts
 var AfricasTalkingSmsDriver = class {
 	driver;
@@ -433,6 +650,9 @@ var Notification = class Notification {
 	static db() {
 		return new DbNotification();
 	}
+	static realtime(options) {
+		return new RealtimeNotification(options);
+	}
 	static channel(channel, options) {
 		return Notification.createDriver(channel ?? configure("default_driver", "mail"), options);
 	}
@@ -455,6 +675,7 @@ var Notification = class Notification {
 			case "email": return new MailNotification(options);
 			case "sms": return new SmsNotification(options);
 			case "db": return new DbNotification();
+			case "realtime": return new RealtimeNotification(options);
 			default: throw new Error(`Unsupported notification driver: ${driver}`);
 		}
 	}
@@ -466,4 +687,4 @@ var UserNotification = class extends Model {
 	casts = { meta: "json" };
 };
 //#endregion
-export { AfricasTalkingSmsDriver, DbNotification, MailNotification, Notification, NotificationContract, SmsNotification, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };
+export { AfricasTalkingSmsDriver, DbNotification, FirebaseRealtimeDriver, MailNotification, Notification, NotificationContract, PusherRealtimeDriver, RealtimeNotification, SmsNotification, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/notifications",
-  "version": "0.16.5",
+  "version": "0.16.7",
   "type": "module",
   "description": "Framework-agnostic notification module for Arkstack and Nodejs, providing support for multi-channel notification delivery.",
   "homepage": "https://arkstack.toneflix.net/guide/notifications",
@@ -34,11 +34,21 @@
     "africastalking": "^0.8.0",
     "nodemailer": "^8.0.7",
     "twilio": "^6.0.0",
-    "@arkstack/common": "^0.16.5"
+    "@arkstack/common": "^0.16.7"
   },
   "peerDependencies": {
-    "@arkstack/database": "^0.16.5",
-    "@arkstack/contract": "^0.16.5"
+    "pusher": "^5.2.0",
+    "firebase-admin": "^13.0.0",
+    "@arkstack/database": "^0.16.7",
+    "@arkstack/contract": "^0.16.7"
+  },
+  "peerDependenciesMeta": {
+    "pusher": {
+      "optional": true
+    },
+    "firebase-admin": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/nodemailer": "^7.0.11"