@arkstack/notifications 0.16.10 → 0.16.11

package/dist/index.d.ts

@@ -67,6 +67,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 +92,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 +188,10 @@ interface NotificationConfig {
       project_id: string;
       client_email: string;
       private_key: string;
+      app_name?: string;
+    } | {
+      app_name?: string;
+      admin_sdk_path: string;
     };
   };
 }
@@ -290,9 +296,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 +326,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 +335,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`).
    *
@@ -430,13 +444,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 +474,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";
@@ -323,9 +324,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 +349,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 +373,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 +424,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 +485,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 +541,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)");
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/notifications",
-  "version": "0.16.10",
+  "version": "0.16.11",
   "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.11"
   },
   "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.11",
+    "@arkstack/database": "^0.16.11"
   },
   "peerDependenciesMeta": {
     "pusher": {