@arkstack/notifications 0.16.10 → 0.16.12

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Model } from "@arkstack/database";
 import { User } from "@app/models/User";
 import { User as User$1 } from "@arkstack/auth";
 import { PhoneNumber } from "@kanun-hq/plugin-phone";
+import { ArkormCollection, LengthAwarePaginator } from "arkormx";
 
 //#region src/Contracts/UserNotification.d.ts
 declare abstract class UserNotification extends Model {
@@ -67,6 +68,8 @@ type FirebaseTransportConfig = {
   project_id?: string;
   client_email?: string;
   private_key?: string;
+  app_name?: string;
+  admin_sdk_path?: string;
 };
 type RealtimeDriverOptions = {
   transport?: RealtimeDriverName; /** Channel/topic to broadcast on. Defaults to `${channel_prefix}${user.id}`. */
@@ -90,7 +93,7 @@ type RealtimeNotificationPayload = {
 };
 /** The result of a realtime broadcast (plus the stored record when `store` is on). */
 type RealtimeBroadcastResult = {
-  channel: string;
+  channel: string | string[];
   event: string;
   payload: RealtimeNotificationPayload;
   stored?: UserNotification;
@@ -186,6 +189,10 @@ interface NotificationConfig {
       project_id: string;
       client_email: string;
       private_key: string;
+      app_name?: string;
+    } | {
+      app_name?: string;
+      admin_sdk_path: string;
     };
   };
 }
@@ -290,9 +297,13 @@ declare class MailNotification extends NotificationContract {
 /**
  * A realtime transport (Pusher, Firebase, …) broadcasts a notification payload
  * to a channel/topic that connected clients subscribe to.
+ *
+ * `channel` may be an array: for Pusher it fans out to multiple channels, and
+ * for Firebase it is treated as a list of device registration tokens delivered
+ * via a multicast send.
  */
 interface RealtimeDriver {
-  broadcast(channel: string, event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
+  broadcast(channel: string | string[], event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
 }
 //#endregion
 //#region src/drivers/RealtimeNotification.d.ts
@@ -316,7 +327,8 @@ declare class RealtimeNotification extends NotificationContract<RealtimeBroadcas
   from(_from: string): this;
   subject(subject: string): this;
   /**
-   * Set the recipient: a `User` (derives the channel) or an explicit channel string.
+   * Set the recipient: a `User` (derives the channel), an explicit channel
+   * string, or an array of channels (Pusher) / device tokens (Firebase).
    *
    * @param recipient
    * @returns
@@ -324,11 +336,14 @@ declare class RealtimeNotification extends NotificationContract<RealtimeBroadcas
   recipient(recipient: NotificationRecipient | User): this;
   /**
    * Broadcast on an explicit channel/topic instead of the per-user default.
-    *
-    * @param channel
-    * @returns
-    */
+   * An array broadcasts to multiple Pusher channels, or — for Firebase — to a
+   * list of device registration tokens (multicast).
+   *
+   * @param channel
+   * @returns
+   */
   channel(channel: string): this;
+  channel(channel: string[]): this;
   /**
    * The event name clients subscribe to (default `notification`).
    *
@@ -343,7 +358,7 @@ declare class RealtimeNotification extends NotificationContract<RealtimeBroadcas
    * @returns
    */
   store(store?: boolean): this;
-  type(type: DbNotificationType | null): this;
+  type(type?: DbNotificationType | null): this;
   action(text?: string | null, link?: string | null): this;
   meta(meta?: NotificationData | null): this;
   private resolveChannel;
@@ -407,12 +422,52 @@ declare class Notification<D extends keyof DriverMap = keyof DriverMap> {
 //#region src/UserNotificationCenter.d.ts
 declare class UserNotificationCenter {
   private static getModel;
+  /**
+   * Create a database notification then broadcast it using the configured realtime driver
+   *
+   * @param user
+   * @param payload
+   */
+  static send(user: User, payload: DbNotificationPayload, channel?: string[]): Promise<RealtimeBroadcastResult>;
+  /**
+   * Create a database notification
+   *
+   * @param user
+   * @param payload
+   */
   static create(user: User, payload: DbNotificationPayload): Promise<UserNotification>;
-  static forUser(user: User): Promise<import("arkormx").ArkormCollection<UserNotification, UserNotification[]>>;
-  static unreadForUser(user: User): Promise<import("arkormx").ArkormCollection<UserNotification, UserNotification[]>>;
-  static markRead(notification: UserNotification | UserNotification['id']): Promise<void>;
-  static markAllRead(user: User): Promise<void>;
-  static delete(notification: UserNotification | UserNotification['id']): Promise<void>;
+  static forUser(user: User): Promise<ArkormCollection<UserNotification, UserNotification[]>>;
+  /**
+   * Fetch all the users unread messages
+   *
+   * @param user
+   */
+  static unreadForUser(user: User): Promise<ArkormCollection<UserNotification, UserNotification[]>>;
+  /**
+   * Fetch all the users unread messages with a lenght aware paginator instance
+   *
+   * @param user
+   * @param perPage
+   */
+  static unreadForUser(user: User, perPage: number): Promise<LengthAwarePaginator<UserNotification>>;
+  /**
+   * Mark the notification as read
+   *
+   * @param notification
+   */
+  static markRead(notification: UserNotification | string | number): Promise<void>;
+  /**
+   * Mark all unread notifications as read
+   *
+   * @param user
+   */
+  static markAllRead(user: User, ids?: string[] | number[]): Promise<void>;
+  /**
+   * Delete the indicated notifications
+   *
+   * @param notification
+   */
+  static delete(notification: UserNotification | string | number | UserNotification[] | string[] | number[]): Promise<void>;
 }
 //#endregion
 //#region src/config.d.ts
@@ -430,13 +485,26 @@ declare class PusherRealtimeDriver implements RealtimeDriver {
   private clientPromise?;
   constructor(options?: PusherTransportConfig);
   private client;
-  broadcast(channel: string, event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
+  broadcast(channel: string | 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).
+ * The outcome of a token multicast: totals plus the tokens FCM rejected as dead.
+ */
+interface FirebaseMulticastResult {
+  successCount: number;
+  failureCount: number;
+  /**
+   * Tokens FCM reported as unregistered/invalid — delete these from your store.
+   */
+  invalidTokens: string[];
+}
+/**
+ * Broadcasts notifications over [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging).
+ * A single channel maps to an FCM topic; an array of channels is treated as
+ * device registration tokens and delivered via a multicast send (chunked to
+ * FCM's 500-token limit), returning the tokens that should be pruned.
  *
  * `firebase-admin` is an optional peer dependency, imported lazily so the
  * package installs without it; it is only required when this transport is used.
@@ -447,10 +515,15 @@ declare class FirebaseRealtimeDriver implements RealtimeDriver {
   private messagingPromise?;
   constructor(options?: FirebaseTransportConfig);
   private messaging;
-  broadcast(channel: string, event: string, payload: RealtimeNotificationPayload): Promise<string>;
+  broadcast(channel: string | string[], event: string, payload: RealtimeNotificationPayload): Promise<string | FirebaseMulticastResult>;
+  /**
+   * Send to many device tokens at once, chunked to FCM's 500-token limit, and
+   * collect the tokens FCM rejects as dead so the caller can prune them.
+   */
+  private multicast;
 }
 //#endregion
 //#region src/utils/template.d.ts
 declare const interpolate: (value: string, data?: NotificationData) => string;
 //#endregion
-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 };
+export { AfricasTalkingSmsDriver, DbNotification, DbNotificationPayload, DbNotificationType, DriverResult, FirebaseMulticastResult, 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

@@ -1,8 +1,9 @@
 import { config, env, getModel } from "@arkstack/common";
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import path, { join } from "node:path";
 import nodemailer from "nodemailer";
 import { Arkstack } from "@arkstack/contract";
+import { existsSync, readFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import africastalking from "africastalking";
 import twilio from "twilio";
@@ -28,6 +29,21 @@ var UserNotificationCenter = class {
 	static async getModel() {
 		return await getModel("UserNotification");
 	}
+	/**
+	* Create a database notification then broadcast it using the configured realtime driver
+	* 
+	* @param user 
+	* @param payload 
+	*/
+	static async send(user, payload, channel = []) {
+		return await Notification.realtime().store().channel(user.pushTokens ?? channel).meta(payload.meta).type(payload.type).subject(payload.title).action(payload.actionText, payload.actionLink).send(payload.description, payload.title, void 0, payload);
+	}
+	/**
+	* Create a database notification
+	* 
+	* @param user 
+	* @param payload 
+	*/
 	static async create(user, payload) {
 		return await (await this.getModel()).query().create({
 			userId: user.id,
@@ -42,12 +58,19 @@ var UserNotificationCenter = class {
 	static async forUser(user) {
 		return await (await this.getModel()).query().where({ userId: user.id }).get();
 	}
-	static async unreadForUser(user) {
-		return await (await this.getModel()).query().where({
+	static async unreadForUser(user, perPage) {
+		const query = (await this.getModel()).query().where({
 			userId: user.id,
 			readAt: null
-		}).get();
+		});
+		if (perPage) return await query.paginate();
+		return await query.get();
 	}
+	/**
+	* Mark the notification as read
+	* 
+	* @param notification 
+	*/
 	static async markRead(notification) {
 		const Model = await this.getModel();
 		const id = typeof notification === "object" ? notification.id : notification;
@@ -55,16 +78,33 @@ var UserNotificationCenter = class {
 		await Model.query().where({ id }).update({ readAt });
 		if (typeof notification === "object") notification.readAt = readAt;
 	}
-	static async markAllRead(user) {
-		await (await this.getModel()).query().where({
+	/**
+	* Mark all unread notifications as read
+	* 
+	* @param user 
+	*/
+	static async markAllRead(user, ids) {
+		const query = (await this.getModel()).query().where({
 			userId: user.id,
 			readAt: null
-		}).update({ readAt: /* @__PURE__ */ new Date() });
+		});
+		if (ids) query.whereIn("id", ids);
+		await query.update({ readAt: /* @__PURE__ */ new Date() });
 	}
+	/**
+	* Delete the indicated notifications
+	* 
+	* @param notification 
+	*/
 	static async delete(notification) {
 		const Model = await this.getModel();
-		const id = typeof notification === "object" ? notification.id : notification;
-		await Model.query().where({ id }).delete();
+		if (Array.isArray(notification)) {
+			const ids = notification.map((e) => typeof e === "object" ? e.id : e);
+			await Model.query().whereIn("id", ids).delete();
+		} else {
+			const id = typeof notification === "object" ? notification.id : notification;
+			await Model.query().where({ id }).delete();
+		}
 	}
 };
 //#endregion
@@ -323,9 +363,19 @@ var MailNotification = class extends NotificationContract {
 };
 //#endregion
 //#region src/drivers/realtime/FirebaseRealtimeDriver.ts
+/** FCM caps a multicast at 500 tokens per call. */
+const MULTICAST_LIMIT = 500;
+/** Error codes that mean a token is dead and should be pruned by the app. */
+const DEAD_TOKEN_CODES = /* @__PURE__ */ new Set([
+	"messaging/registration-token-not-registered",
+	"messaging/invalid-registration-token",
+	"messaging/invalid-argument"
+]);
 /**
-* Broadcasts notifications over [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)
-* topics (the channel name maps to an FCM topic).
+* Broadcasts notifications over [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging).
+* A single channel maps to an FCM topic; an array of channels is treated as
+* device registration tokens and delivered via a multicast send (chunked to
+* FCM's 500-token limit), returning the tokens that should be pruned.
 *
 * `firebase-admin` is an optional peer dependency, imported lazily so the
 * package installs without it; it is only required when this transport is used.
@@ -338,16 +388,23 @@ var FirebaseRealtimeDriver = class {
 		this.options = options;
 	}
 	messaging() {
+		const appSpecifier = "firebase-admin/app";
+		const messagingSpecifier = "firebase-admin/messaging";
 		this.messagingPromise ??= (async () => {
-			const [app, messaging] = await Promise.all([import("firebase-admin/app"), import("firebase-admin/messaging")]).catch(() => {
+			const [app, messaging] = await Promise.all([import(appSpecifier), import(messagingSpecifier)]).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({
+			const adminsdk = path.join(process.cwd(), this.options.admin_sdk_path ?? env("FIREBASE_ADMINSDK", "firebase-adminsdk.json"));
+			let serviceAccount;
+			try {
+				if (existsSync(adminsdk)) serviceAccount = JSON.parse(readFileSync(adminsdk, { encoding: "utf-8" }));
+			} catch {}
+			const credential = app.cert(serviceAccount ?? {
 				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 name = String(this.options.app_name ?? env("FIREBASE_APP_NAME", "arkstack-realtime")).replaceAll(" ", "-").toLowerCase();
 			const instance = app.getApps().find((a) => a.name === name) ?? app.initializeApp({ credential }, name);
 			return messaging.getMessaging(instance);
 		})();
@@ -355,15 +412,41 @@ var FirebaseRealtimeDriver = class {
 	}
 	async broadcast(channel, event, payload) {
 		const messaging = await this.messaging();
+		const data = {
+			event,
+			payload: JSON.stringify(payload)
+		};
+		if (Array.isArray(channel)) return await this.multicast(messaging, channel, data);
 		const topic = channel.replace(/[^a-zA-Z0-9-_.~%]/g, "_");
 		return await messaging.send({
 			topic,
-			data: {
-				event,
-				payload: JSON.stringify(payload)
-			}
+			data
 		});
 	}
+	/**
+	* Send to many device tokens at once, chunked to FCM's 500-token limit, and
+	* collect the tokens FCM rejects as dead so the caller can prune them.
+	*/
+	async multicast(messaging, tokens, data) {
+		const result = {
+			successCount: 0,
+			failureCount: 0,
+			invalidTokens: []
+		};
+		for (let i = 0; i < tokens.length; i += MULTICAST_LIMIT) {
+			const batch = tokens.slice(i, i + MULTICAST_LIMIT);
+			const response = await messaging.sendEachForMulticast({
+				tokens: batch,
+				data
+			});
+			result.successCount += response.successCount;
+			result.failureCount += response.failureCount;
+			response.responses.forEach((res, index) => {
+				if (!res.success && res.error?.code && DEAD_TOKEN_CODES.has(res.error.code)) result.invalidTokens.push(batch[index]);
+			});
+		}
+		return result;
+	}
 };
 //#endregion
 //#region src/drivers/realtime/PusherRealtimeDriver.ts
@@ -380,8 +463,9 @@ var PusherRealtimeDriver = class {
 		this.options = options;
 	}
 	client() {
+		const specifier = "pusher";
 		this.clientPromise ??= (async () => {
-			const mod = await import("pusher").catch(() => {
+			const mod = await import(specifier).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)({
@@ -440,29 +524,24 @@ var RealtimeNotification = class extends NotificationContract {
 		this.payload.title = subject;
 		return this;
 	}
-	/** 
-	* Set the recipient: a `User` (derives the channel) or an explicit channel string. 
-	* 
-	* @param recipient 
-	* @returns 
+	/**
+	* Set the recipient: a `User` (derives the channel), an explicit channel
+	* string, or an array of channels (Pusher) / device tokens (Firebase).
+	*
+	* @param recipient
+	* @returns
 	*/
 	recipient(recipient) {
 		if (typeof recipient === "object" && !Array.isArray(recipient) && typeof recipient.id !== "undefined") {
 			this.user = recipient;
 			return this;
 		}
-		if (typeof recipient === "string") {
+		if (typeof recipient === "string" || Array.isArray(recipient)) {
 			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;
@@ -501,7 +580,7 @@ var RealtimeNotification = class extends NotificationContract {
 		return this;
 	}
 	resolveChannel() {
-		if (this.channelName) return this.channelName;
+		if (this.channelName !== void 0) 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)");
 	}
@@ -528,7 +607,7 @@ var RealtimeNotification = class extends NotificationContract {
 			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);
+		if (channel && channel.length > 0) await this.driver.broadcast(channel, this.eventName, payload);
 		return {
 			channel,
 			event: this.eventName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/notifications",
-  "version": "0.16.10",
+  "version": "0.16.12",
   "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,14 +34,14 @@
     "africastalking": "^0.8.0",
     "nodemailer": "^8.0.7",
     "twilio": "^6.0.0",
-    "@arkstack/common": "^0.16.10"
+    "@arkstack/common": "^0.16.12"
   },
   "peerDependencies": {
     "@kanun-hq/plugin-phone": "^0.1.8",
     "firebase-admin": "^13.0.0",
     "pusher": "^5.2.0",
-    "@arkstack/contract": "^0.16.10",
-    "@arkstack/database": "^0.16.10"
+    "@arkstack/contract": "^0.16.12",
+    "@arkstack/database": "^0.16.12"
   },
   "peerDependenciesMeta": {
     "pusher": {