@arkstack/notifications 0.17.8 → 0.17.9

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { DotPath, DotPathValue, MergedConfig } from "@arkstack/common";
-import { Transporter } from "nodemailer";
+import { Transport, Transporter } from "nodemailer";
 import { Model } from "@arkstack/database";
 import { Logger } from "nodemailer/lib/shared/index.js";
 import { User } from "@app/models/User";
@@ -83,8 +83,8 @@ type FirebaseTransportConfig = {
   app_name?: string;
   admin_sdk_path?: string;
 };
-type RealtimeDriverOptions = {
-  transport?: RealtimeDriverName; /** Channel/topic to broadcast on. Defaults to `${channel_prefix}${user.id}`. */
+type RealtimeDriverOptions<T extends RealtimeDriverName = RealtimeDriverName> = {
+  transport?: T; /** 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;
@@ -126,11 +126,11 @@ type NotificationDriverMap = {
   db: UserNotification;
   realtime: RealtimeBroadcastResult;
 };
-interface NotificationConfig {
+interface NotificationConfig<T = any> {
   default_driver: 'mail' | 'sms' | 'db';
   drivers: {
     mail: {
-      transport: 'smtp' | 'file' | 'sendmail' | 'ses';
+      transport: 'smtp' | 'file' | 'sendmail' | 'ses' | Transport<T>;
       from: string | {
         name: string;
         address: string;
@@ -223,6 +223,9 @@ interface NotificationConfig {
   };
 }
 type MergedTransportConfig = MergedConfig<Required<NotificationConfig['transports']>[NonNullable<MailDriverOptions['transport']>]>;
+type MailNotificationOptions = MailDriverOptions & {
+  transport?: MailDriverOptions['transport'] | Transport;
+};
 //#endregion
 //#region src/Contracts/NotificationContract.d.ts
 declare abstract class NotificationContract<TResult = DriverResult> {
@@ -281,7 +284,7 @@ declare class MailNotification extends NotificationContract {
   private htmlTemplate?;
   private textTemplate?;
   private fileDirectory?;
-  constructor(options?: MailDriverOptions);
+  constructor(options?: MailNotificationOptions);
   /**
    * Prepare the mail driver so we can use it to relay the message
    */
@@ -343,6 +346,56 @@ declare class MailNotification extends NotificationContract {
   private normalizeRecipient;
 }
 //#endregion
+//#region src/drivers/realtime/FirebaseRealtimeDriver.d.ts
+/**
+ * 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.
+ * 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 | 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/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 | string[], event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
+}
+//#endregion
 //#region src/Contracts/RealtimeDriver.d.ts
 /**
  * A realtime transport (Pusher, Firebase, …) broadcasts a notification payload
@@ -355,6 +408,7 @@ declare class MailNotification extends NotificationContract {
 interface RealtimeDriver {
   broadcast(channel: string | string[], event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
 }
+type RealtimeNotificationDriver<T extends RealtimeDriverName> = T extends 'firebase' ? FirebaseRealtimeDriver : T extends 'firebase' ? PusherRealtimeDriver : RealtimeDriver;
 //#endregion
 //#region src/drivers/RealtimeNotification.d.ts
 /**
@@ -362,20 +416,28 @@ interface RealtimeDriver {
  * (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> {
+declare class RealtimeNotification<T extends RealtimeDriverName = RealtimeDriverName> extends NotificationContract<RealtimeBroadcastResult> {
   /**
    * The underlying transport; assignable so tests can inject a fake.
    */
-  driver: RealtimeDriver;
+  driver: RealtimeNotificationDriver<T>;
   private user?;
   private channelName?;
   private eventName;
   private channelPrefix;
   private shouldStore;
   private payload;
-  constructor(options?: RealtimeDriverOptions);
-  from(_from: string): this;
+  constructor(options?: RealtimeDriverOptions<T>);
+  from(_: string): this;
   subject(subject: string): this;
+  /**
+   * Overide the default transport
+   *
+   * @param transport
+   * @param options
+   * @returns
+   */
+  transport(transport: T, options?: RealtimeDriverOptions[T]): this;
   /**
    * Set the recipient: a `User` (derives the channel), an explicit channel
    * string, or an array of channels (Pusher) / device tokens (Firebase).
@@ -464,16 +526,66 @@ type DriverMap = {
 };
 //#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?: DriverOptions);
+  constructor(driver: 'sms', options?: SmsDriverOptions);
+  constructor(driver: 'realtime', options?: RealtimeDriverOptions);
+  constructor(driver: 'mail' | 'email', options?: MailDriverOptions);
+  constructor(driver: 'db');
+  /**
+   * Send an email notification
+   *
+   * @param options
+   * @returns
+   */
   static mail(options?: MailDriverOptions): MailNotification;
+  /**
+   * Send an email notification
+   *
+   * @param options
+   * @alias {@link mail}
+   * @returns
+   */
   static email(options?: MailDriverOptions): MailNotification;
+  /**
+   * Send an sms notification
+   *
+   * @param options
+   * @returns
+   */
   static sms(options?: SmsDriverOptions): SmsNotification;
+  /**
+   * Send a database notification
+   *
+   * @param options
+   * @returns
+   */
   static db(): DbNotification;
-  static realtime(options?: RealtimeDriverOptions): RealtimeNotification;
-  static channel(channel?: NotificationChannel | 'email', options?: DriverOptions): MailNotification | SmsNotification | DbNotification | RealtimeNotification;
+  /**
+   * Send a realtime notification
+   *
+   * @param options
+   * @returns
+   */
+  static realtime(options?: RealtimeDriverOptions): RealtimeNotification<RealtimeDriverName>;
+  /**
+   * Use a specific channel to send this notification
+   *
+   * @param channel
+   * @param options
+   */
+  static channel(channel: 'sms', options?: SmsDriverOptions): SmsNotification;
+  static channel(channel: 'realtime', options?: RealtimeDriverOptions): RealtimeNotification;
+  static channel(channel: 'mail' | 'email', options?: MailDriverOptions): MailNotification;
+  static channel(channel: 'db'): DbNotification;
+  static channel(): MailNotification | SmsNotification | DbNotification | RealtimeNotification;
+  /**
+   * Prepare the notification
+   *
+   * @param recipient
+   * @param data
+   * @returns
+   */
   prepare(recipient?: null | MailRecipient | NotificationRecipient | User, data?: NotificationData): DriverMap[D];
   private static createDriver;
 }
@@ -533,57 +645,7 @@ 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 | string[], event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
-}
-//#endregion
-//#region src/drivers/realtime/FirebaseRealtimeDriver.d.ts
-/**
- * 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.
- * 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 | 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, 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 };
+export { AfricasTalkingSmsDriver, DbNotification, DbNotificationPayload, DbNotificationType, DriverResult, FirebaseMulticastResult, FirebaseRealtimeDriver, FirebaseTransportConfig, MailDriverOptions, MailNotification, MailNotificationOptions, MailRecipient, MailRecipientAddress, MergedTransportConfig, Notification, NotificationChannel, NotificationConfig, NotificationContract, NotificationData, NotificationDriverMap, NotificationRecipient, PusherRealtimeDriver, PusherTransportConfig, RealtimeBroadcastResult, RealtimeDriver, RealtimeDriverName, RealtimeDriverOptions, RealtimeNotification, RealtimeNotificationDriver, RealtimeNotificationPayload, SmsDriverName, SmsDriverOptions, SmsNotification, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };

package/dist/index.js

@@ -222,6 +222,10 @@ var MailNotification = class extends NotificationContract {
 	* Prepare the mail driver so we can use it to relay the message
 	*/
 	async prepareDriver() {
+		if (typeof this.transport !== "string") {
+			this.driver = nodemailer.createTransport(this.transport);
+			return;
+		}
 		const options = this.options;
 		const transport = configure(`transports.${this.transport}`, {});
 		/**
@@ -422,7 +426,8 @@ var MailNotification = class extends NotificationContract {
 		const recipients = recipient ?? this.recipients;
 		const resolved = (Array.isArray(recipients) ? [...recipients] : recipients ? [recipients] : []).flatMap((recipient) => this.normalizeRecipient(recipient));
 		const driver = configure("drivers.mail", {});
-		const transport = configure(`transports.${driver.transport ?? "smtp"}`, {});
+		const trpt = driver.transport ?? "smtp";
+		const transport = typeof trpt === "string" ? configure(`transports.${trpt}`, {}) : { test_address: "" };
 		const testAddress = driver.test_address ?? driver.test_address ?? transport.test_address ?? transport.test_address ?? env("MAIL_TEST_ADDRESS");
 		if (env("NODE_ENV") !== "production" && testAddress) resolved.push(testAddress);
 		return resolved;
@@ -591,7 +596,7 @@ var RealtimeNotification = class extends NotificationContract {
 			...options.pusher
 		});
 	}
-	from(_from) {
+	from(_) {
 		return this;
 	}
 	subject(subject) {
@@ -599,6 +604,24 @@ var RealtimeNotification = class extends NotificationContract {
 		return this;
 	}
 	/**
+	* Overide the default transport
+	* 
+	* @param transport 
+	* @param options 
+	* @returns 
+	*/
+	transport(transport, options) {
+		const transportConfig = configure(`transports.${transport}`, {});
+		this.driver = transport === "firebase" ? new FirebaseRealtimeDriver({
+			...transportConfig,
+			...options
+		}) : new PusherRealtimeDriver({
+			...transportConfig,
+			...options
+		});
+		return this;
+	}
+	/**
 	* Set the recipient: a `User` (derives the channel), an explicit channel
 	* string, or an array of channels (Pusher) / device tokens (Firebase).
 	*
@@ -804,24 +827,63 @@ var Notification = class Notification {
 	constructor(driver, options = {}) {
 		this.driver = Notification.createDriver(driver, options);
 	}
+	/**
+	* Send an email notification
+	* 
+	* @param options 
+	* @returns 
+	*/
 	static mail(options) {
 		return new MailNotification(options);
 	}
+	/**
+	* Send an email notification
+	* 
+	* @param options 
+	* @alias {@link mail}
+	* @returns 
+	*/
 	static email(options) {
 		return this.mail(options);
 	}
+	/**
+	* Send an sms notification
+	* 
+	* @param options 
+	* @returns 
+	*/
 	static sms(options) {
 		return new SmsNotification(options);
 	}
+	/**
+	* Send a database notification
+	* 
+	* @param options 
+	* @returns 
+	*/
 	static db() {
 		return new DbNotification();
 	}
+	/**
+	* Send a realtime notification
+	* 
+	* @param options 
+	* @returns 
+	*/
 	static realtime(options) {
 		return new RealtimeNotification(options);
 	}
 	static channel(channel, options) {
-		return Notification.createDriver(channel ?? configure("default_driver", "mail"), options);
+		channel ??= configure("default_driver", "mail");
+		return Notification.createDriver(channel, options);
 	}
+	/**
+	* Prepare the notification
+	* 
+	* @param recipient 
+	* @param data 
+	* @returns 
+	*/
 	prepare(recipient, data = {}) {
 		this.driver.data(data);
 		if (recipient && typeof recipient === "object" && !Array.isArray(recipient) && typeof recipient.id !== "undefined") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/notifications",
-  "version": "0.17.8",
+  "version": "0.17.9",
   "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.17.8"
+    "@arkstack/common": "^0.17.9"
   },
   "peerDependencies": {
     "@kanun-hq/plugin-phone": "^0.1.8",
     "firebase-admin": "^13.0.0",
     "pusher": "^5.2.0",
-    "@arkstack/contract": "^0.17.8",
-    "@arkstack/database": "^0.17.8"
+    "@arkstack/contract": "^0.17.9",
+    "@arkstack/database": "^0.17.9"
   },
   "peerDependenciesMeta": {
     "pusher": {