@facteurjs/core 1.0.0-beta.3 → 2.0.0-beta.0

package/dist/facteur.d.mts

@@ -0,0 +1,45 @@
+import { Channel } from "./types/channel.mjs";
+import { NotificationBuilder } from "./types/builder.mjs";
+import { FacteurFake } from "./fake.mjs";
+import { FacteurDatabase } from "./database/database.mjs";
+import { FacteurConfiguration } from "./types/options.mjs";
+import { Notification, NotificationClass } from "./types/notifications.mjs";
+import { DatabaseAdapter } from "./database/types.mjs";
+
+//#region src/facteur.d.ts
+declare function createFacteur<T extends Record<string, Channel>>(config: FacteurConfiguration<T>): Facteur<T, null>;
+declare class Facteur<KnownChannels extends Record<string, Channel>, DBAdapter extends DatabaseAdapter | null = null> {
+  #private;
+  constructor(config: FacteurConfiguration<KnownChannels, DBAdapter>);
+  /**
+   * Access the database layer for in-app notifications and preferences
+   */
+  get db(): DBAdapter extends DatabaseAdapter ? FacteurDatabase : never;
+  /**
+   * Access notification discovery utilities for finding and managing notifications
+   */
+  get discoverer(): {
+    discoverNotifications: () => Promise<(new (...args: any[]) => Notification)[]>;
+    getNotifications: () => Promise<(new (...args: any[]) => Notification)[]>;
+    getNotificationTags: () => Promise<string[]>;
+    clearCache: () => void;
+  };
+  /**
+   * Enable fake mode for testing - captures sent notifications instead of sending
+   */
+  fake(): FacteurFake;
+  /**
+   * Restore normal sending behavior after fake mode
+   */
+  restore(): void;
+  /**
+   * Create a notification builder for fluent API
+   */
+  notification<TNotification extends NotificationClass<any, any>>(notificationClass: TNotification): NotificationBuilder<TNotification, {
+    hasParams: false;
+    hasTo: false;
+    hasVia: false;
+  }>;
+}
+//#endregion
+export { Facteur, createFacteur };

package/dist/facteur.mjs

@@ -0,0 +1,167 @@
+import { collect, isAsyncIterable } from "./utils/chunk.mjs";
+import { FacteurOptions } from "./options.mjs";
+import { OrchestrationSender } from "./notifications/orchestration_sender.mjs";
+import { ChannelResolver } from "./notifications/channel_resolver.mjs";
+import { NotificationSender } from "./notifications/notification_sender.mjs";
+import { NotificationDiscoverer } from "./notifications/notification_discoverer.mjs";
+import { createNotificationBuilder } from "./notifications/notification_builder.mjs";
+import { BatchingSender } from "./notifications/batching_sender.mjs";
+import { FacteurFake } from "./fake.mjs";
+import { FacteurDatabase } from "./database/database.mjs";
+
+//#region src/facteur.ts
+function createFacteur(config) {
+	return new Facteur(config);
+}
+var Facteur = class {
+	#sender;
+	#orchestrationSender;
+	#batchingSender;
+	#fake = null;
+	#db = null;
+	#discoverer;
+	#options;
+	constructor(config) {
+		this.#options = new FacteurOptions(config);
+		this.#discoverer = new NotificationDiscoverer({
+			searchDirectory: config.discoverer.searchDirectory,
+			fileSuffix: config.discoverer.fileSuffix
+		});
+		let channelResolver;
+		if (this.#options.databaseAdapter) {
+			const options = this.#options;
+			this.#db = new FacteurDatabase(options, this.#discoverer);
+			channelResolver = new ChannelResolver(this.#db, this.#options.defaultPreferences);
+		} else channelResolver = new ChannelResolver(void 0, this.#options.defaultPreferences);
+		this.#sender = new NotificationSender(this.#options.channels, channelResolver, this.#options.emitter, this.#options.retry);
+		this.#orchestrationSender = new OrchestrationSender(this.#sender);
+		this.#batchingSender = new BatchingSender(this.#sender, channelResolver);
+	}
+	/**
+	* Converts recipients input to an array, handling single values, arrays, and async iterables
+	*/
+	async #resolveRecipients(to) {
+		if (!to) return [];
+		if (Array.isArray(to)) return to;
+		if (isAsyncIterable(to)) return collect(to);
+		return [to];
+	}
+	/**
+	* Resolves notification instance and runs lifecycle hooks
+	*/
+	async #prepareNotification(recipient, options) {
+		const notification = await this.#options.notificationResolver(options.notification, {
+			to: recipient,
+			params: options.params,
+			tenantId: options.tenantId
+		});
+		await notification.beforeSend();
+		return {
+			notification,
+			shouldSkip: await notification.shouldSend() === false
+		};
+	}
+	/**
+	* Handles anonymous sends (via without to) - e.g., sending to a fixed webhook
+	*/
+	async #sendAnonymous(options) {
+		const { notification, shouldSkip } = await this.#prepareNotification(void 0, options);
+		if (shouldSkip) return {
+			success: 0,
+			failed: 0,
+			results: []
+		};
+		if (this.#fake) return this.#fake.recordSent(options);
+		return this.#sender.send(options, notification);
+	}
+	/**
+	* Main send entry point - unified handling for all recipient types
+	*/
+	async #send(options) {
+		if (options.via && !options.to) return this.#sendAnonymous(options);
+		const recipients = await this.#resolveRecipients(options.to);
+		if (recipients.length === 0) return {
+			success: 0,
+			failed: 0,
+			results: []
+		};
+		if (this.#fake) {
+			for (const recipient of recipients) this.#fake.recordSent({
+				...options,
+				to: recipient
+			});
+			return {
+				success: recipients.length,
+				failed: 0,
+				results: []
+			};
+		}
+		if (recipients.length === 1) return this.#sendSingle({
+			...options,
+			to: recipients[0]
+		});
+		const prepareNotification = this.#prepareNotification.bind(this);
+		if (options.useDriverBatching) return this.#batchingSender.send({
+			recipients,
+			builderOptions: options,
+			prepareNotification
+		});
+		return this.#orchestrationSender.send({
+			recipients,
+			builderOptions: options,
+			prepareNotification
+		});
+	}
+	/**
+	* Fast path for single recipient - passes options directly to sender
+	*/
+	async #sendSingle(options) {
+		const { notification, shouldSkip } = await this.#prepareNotification(options.to, options);
+		if (shouldSkip) return {
+			success: 0,
+			failed: 0,
+			results: []
+		};
+		return this.#sender.send(options, notification);
+	}
+	/**
+	* Access the database layer for in-app notifications and preferences
+	*/
+	get db() {
+		if (!this.#options.databaseAdapter) throw new Error("No database adapter configured");
+		return this.#db;
+	}
+	/**
+	* Access notification discovery utilities for finding and managing notifications
+	*/
+	get discoverer() {
+		return {
+			discoverNotifications: () => this.#discoverer.discoverNotifications(),
+			getNotifications: () => this.#discoverer.getNotifications(),
+			getNotificationTags: () => this.#discoverer.getAllNotificationTags(),
+			clearCache: () => this.#discoverer.clearCache()
+		};
+	}
+	/**
+	* Enable fake mode for testing - captures sent notifications instead of sending
+	*/
+	fake() {
+		this.#fake = new FacteurFake();
+		return this.#fake;
+	}
+	/**
+	* Restore normal sending behavior after fake mode
+	*/
+	restore() {
+		this.#fake = null;
+	}
+	/**
+	* Create a notification builder for fluent API
+	*/
+	notification(notificationClass) {
+		return createNotificationBuilder((options) => this.#send(options), notificationClass);
+	}
+};
+
+//#endregion
+export { Facteur, createFacteur };

package/dist/{fake.d.ts → fake.d.mts}

@@ -1,5 +1,5 @@
-import { SendOptions } from "./types/options.js";
-import { Notification, NotificationSendResult } from "./types/notifications.js";
+import { InternalSendOptions } from "./types/builder.mjs";
+import { Notification, NotificationSendResult } from "./types/notifications.mjs";
 
 //#region src/fake.d.ts
 interface SentNotification<N extends Notification = Notification> {
@@ -13,7 +13,7 @@ declare class FacteurFake {
   /**
    * Record a notification as sent during fake mode
    */
-  recordSent(options: SendOptions<any>): NotificationSendResult;
+  recordSent(options: InternalSendOptions): NotificationSendResult;
   /**
    * Assert a total of expected number of notifications were sent
    */

package/dist/{fake.js → fake.mjs}

@@ -66,15 +66,14 @@ var FacteurFake = class {
 		const sentNotifications = this.sent(notificationClass);
 		if (sentNotifications.length === 0) throw new AssertionError({ message: `Expected notification "${notificationClass.name}" was not sent` });
 		if (callback) {
-			const found = sentNotifications.some((sent) => {
+			if (!sentNotifications.some((sent) => {
 				try {
 					callback(sent);
 					return true;
 				} catch {
 					return false;
 				}
-			});
-			if (!found) throw new AssertionError({ message: `No notifications of type ${notificationClass.name} matched the given callback` });
+			})) throw new AssertionError({ message: `No notifications of type ${notificationClass.name} matched the given callback` });
 		}
 	}
 	/**

package/dist/{index.d.ts → index.d.mts}

@@ -1,6 +1,6 @@
-import { Channel } from "./types/channel.js";
-import { Facteur, createFacteur } from "./facteur.js";
-import { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, errors } from "./errors/index.js";
+import { Channel } from "./types/channel.mjs";
+import { Facteur, createFacteur } from "./facteur.mjs";
+import { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, errors } from "./errors/index.mjs";
 
 //#region src/index.d.ts
 

package/dist/{index.js → index.mjs}

@@ -1,5 +1,5 @@
-import { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, errors } from "./errors/index.js";
-import { Facteur, createFacteur } from "./facteur.js";
+import { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, errors } from "./errors/index.mjs";
+import { Facteur, createFacteur } from "./facteur.mjs";
 
 //#region src/index.ts
 /**

package/dist/notifications/batching_sender.mjs

@@ -0,0 +1,148 @@
+import { chunk } from "../utils/chunk.mjs";
+import { Tenace, backoff } from "@julr/tenace";
+
+//#region src/notifications/batching_sender.ts
+/**
+* Handles bulk notification sending using driver batching mode.
+*
+* In driver batching mode, messages are grouped by channel and sent using
+* the channel's batch API when available. This is more efficient for channels
+* that support batch operations (e.g., FCM, Expo push notifications).
+*/
+var BatchingSender = class {
+	#sender;
+	#channelResolver;
+	constructor(sender, channelResolver) {
+		this.#sender = sender;
+		this.#channelResolver = channelResolver;
+	}
+	/**
+	* Sends notifications to multiple recipients using channel batch APIs
+	*/
+	async send(options) {
+		const { builderOptions, recipients, prepareNotification } = options;
+		const { chunkSize = Infinity, concurrency = 10, continueOnError = false, retries = 0, timeout, onProgress } = builderOptions;
+		const allResults = [];
+		let completedCount = 0;
+		for (const recipientChunk of chunk(recipients, chunkSize)) {
+			const chunkResults = await this.#processChunk({
+				recipientChunk,
+				builderOptions,
+				prepareNotification,
+				concurrency,
+				continueOnError,
+				retries,
+				...timeout && { timeout }
+			});
+			allResults.push(...chunkResults);
+			completedCount += recipientChunk.length;
+			onProgress?.(completedCount, recipients.length);
+		}
+		return {
+			success: allResults.filter((r) => r.status === "success").length,
+			failed: allResults.filter((r) => r.status === "failed").length,
+			results: allResults
+		};
+	}
+	/**
+	* Processes a single chunk: prepare recipients, group by channel, send batches
+	*/
+	async #processChunk(options) {
+		const preparedRecipients = await this.#prepareRecipients({
+			recipients: options.recipientChunk,
+			builderOptions: options.builderOptions,
+			prepareNotification: options.prepareNotification,
+			concurrency: options.concurrency,
+			continueOnError: options.continueOnError,
+			...options.timeout && { timeout: options.timeout }
+		});
+		const messagesByChannel = this.#groupByChannel(preparedRecipients);
+		return this.#sendBatches({
+			messagesByChannel,
+			builderOptions: options.builderOptions,
+			retries: options.retries,
+			...options.timeout && { timeout: options.timeout }
+		});
+	}
+	/**
+	* Prepares all recipients for batching by resolving notifications and channels in parallel
+	*/
+	async #prepareRecipients(options) {
+		const { recipients, builderOptions, prepareNotification, concurrency, continueOnError, timeout } = options;
+		const builder = Tenace.map(recipients, (recipient) => this.#prepareRecipient(recipient, builderOptions, prepareNotification)).withConcurrency(concurrency);
+		if (timeout) builder.withTimeoutPerTask(timeout);
+		return (continueOnError ? (await builder.settle()).map((r) => r.status === "fulfilled" ? r.value : null) : await builder.execute()).filter((p) => p !== null);
+	}
+	/**
+	* Prepares a single recipient by resolving notification and channel targets
+	*/
+	async #prepareRecipient(recipient, builderOptions, prepareNotification) {
+		const { notification, shouldSkip } = await prepareNotification(recipient, builderOptions);
+		if (shouldSkip) return null;
+		return {
+			recipient,
+			notification,
+			resolvedChannels: await this.#channelResolver.resolveChannels({
+				to: recipient,
+				params: builderOptions.params,
+				tenantId: builderOptions.tenantId,
+				notification: builderOptions.notification,
+				...builderOptions.via ? { via: builderOptions.via } : {}
+			}),
+			options: {
+				...builderOptions,
+				to: recipient
+			}
+		};
+	}
+	/**
+	* Groups prepared messages by channel name for batch sending
+	*/
+	#groupByChannel(preparedRecipients) {
+		const messagesByChannel = /* @__PURE__ */ new Map();
+		for (const prepared of preparedRecipients) for (const [channelName, channelConfig] of Object.entries(prepared.resolvedChannels)) {
+			if (!channelConfig.shouldSend || !channelConfig.target) continue;
+			const message = this.#sender.prepareMessage({
+				notification: prepared.notification,
+				channelName,
+				sendOptions: prepared.options,
+				channelConfig
+			});
+			if (!message) continue;
+			const messages = messagesByChannel.get(channelName) ?? [];
+			messages.push(message);
+			messagesByChannel.set(channelName, messages);
+		}
+		return messagesByChannel;
+	}
+	/**
+	* Sends batched messages per channel with optional retries and timeout
+	*/
+	async #sendBatches(options) {
+		const { messagesByChannel, builderOptions, retries, timeout } = options;
+		const { retries: _r, timeout: _t, ...sendOptions } = builderOptions;
+		const sendChannel = async (channelName, messages) => {
+			const sendBatch = () => this.#sender.sendChannelBatch({
+				channelName,
+				messages,
+				sendOptions
+			});
+			if (!retries && !timeout) return sendBatch();
+			let builder = Tenace.call(sendBatch);
+			if (timeout) builder = builder.withTimeout(timeout, "aggressive");
+			if (retries > 0) builder = builder.withRetry({
+				times: retries,
+				delay: backoff.exponentialWithJitter({
+					initial: 100,
+					max: 5e3
+				})
+			});
+			return builder.execute();
+		};
+		const promises = Array.from(messagesByChannel.entries()).map(([channel, msgs]) => sendChannel(channel, msgs));
+		return (await Promise.all(promises)).flat();
+	}
+};
+
+//#endregion
+export { BatchingSender };

package/dist/notifications/{channel_resolver.js → channel_resolver.mjs}

@@ -5,8 +5,10 @@ import { is } from "@julr/utils/is";
 //#region src/notifications/channel_resolver.ts
 var ChannelResolver = class {
 	#database = null;
-	constructor(database) {
+	#defaultPreferences = null;
+	constructor(database, defaultPreferences) {
 		this.#database = database || null;
+		this.#defaultPreferences = defaultPreferences || null;
 	}
 	/**
 	* Resolve channels and targets provided by via
@@ -14,14 +16,12 @@ var ChannelResolver = class {
 	#resolveVia(options) {
 		const notifiableTargets = options.to?.notificationTargets?.();
 		return mapEntries(options.via, (channelName, channelConfig) => {
-			const shouldSend = typeof channelConfig === "boolean" ? channelConfig : true;
-			const target = invoke(() => {
-				if (typeof channelConfig === "object") return channelConfig;
-				return notifiableTargets?.[channelName] || null;
-			});
 			return [channelName, {
-				shouldSend,
-				target
+				shouldSend: typeof channelConfig === "boolean" ? channelConfig : true,
+				target: invoke(() => {
+					if (typeof channelConfig === "object") return channelConfig;
+					return notifiableTargets?.[channelName] || null;
+				})
 			}];
 		});
 	}
@@ -35,32 +35,41 @@ var ChannelResolver = class {
 		*/
 		if (via) return this.#resolveVia(options);
 		/**
-		* Get preferences for the notifiable and tenant
-		*/
-		const preferences = await this.#database?.getPreferences({
-			notifiableId: to.id,
-			tenantId
-		});
-		/**
 		* Resolve channels based on deliverBy options
 		*/
 		const fromDeliverBy = mapEntries(notificationOptions.deliverBy, (channelName, deliverBy) => {
-			const shouldSend = invoke(() => {
-				if (typeof deliverBy === "boolean") return deliverBy;
-				return deliverBy.if({
-					to,
-					params,
-					preferences
-				});
-			});
-			const target = notifiableTargets?.[channelName] || null;
 			return [channelName, {
-				shouldSend,
-				target
+				shouldSend: invoke(() => {
+					if (typeof deliverBy === "boolean") return deliverBy;
+					if (!to) return true;
+					return deliverBy.if({
+						to,
+						params
+					});
+				}),
+				target: notifiableTargets?.[channelName] || null
 			}];
 		});
 		/**
-		* And then we can apply user preferences
+		* If the notification is critical, bypass all user preferences
+		*/
+		if (notificationOptions.critical) return fromDeliverBy;
+		/**
+		* Get preferences for the notifiable and tenant.
+		* Skip if no notifiable (anonymous notification) or no database.
+		*/
+		const notifiableId = to?.id;
+		const preferences = notifiableId ? await this.#database?.getPreferences({
+			notifiableId,
+			tenantId
+		}) : void 0;
+		/**
+		* Get category preferences from default config
+		*/
+		const category = notificationOptions.category;
+		const categoryPreferences = category ? this.#defaultPreferences?.categories[category]?.channels : void 0;
+		/**
+		* Apply user preferences with priority order
 		*/
 		const currentTenant = preferences?.tenants?.[tenantId || -1];
 		const tenantPreferences = currentTenant?.global;
@@ -72,13 +81,13 @@ var ChannelResolver = class {
 				shouldSend: false,
 				target
 			}];
-			const preferencesSources = [
+			shouldSend = [
 				notificationTenantPreference?.channels[channelName],
 				tenantPreferences?.channels[channelName],
 				notificationGlobalPreference?.channels[channelName],
-				globalPreferences?.channels[channelName]
-			];
-			shouldSend = preferencesSources.find((preference) => !is.undefined(preference)) ?? shouldSend;
+				globalPreferences?.channels[channelName],
+				categoryPreferences?.[channelName]
+			].find((preference) => !is.undefined(preference)) ?? shouldSend;
 			return [channelName, {
 				shouldSend,
 				target

package/dist/notifications/notification_builder.mjs

@@ -0,0 +1,77 @@
+//#region src/notifications/notification_builder.ts
+/**
+* Fluent builder for sending notifications.
+* Provides a chainable API with full type-safety.
+*/
+var NotificationBuilderImpl = class {
+	#options;
+	#sendFn;
+	constructor(sendFn, notification) {
+		this.#sendFn = sendFn;
+		this.#options = { notification };
+	}
+	params(params) {
+		this.#options.params = params;
+		return this;
+	}
+	to(recipients) {
+		this.#options.to = recipients;
+		return this;
+	}
+	via(config) {
+		this.#options.via = config;
+		return this;
+	}
+	tenant(id) {
+		this.#options.tenantId = id;
+		return this;
+	}
+	chunkSize(size) {
+		this.#options.chunkSize = size;
+		return this;
+	}
+	concurrency(limit) {
+		this.#options.concurrency = limit;
+		return this;
+	}
+	continueOnError(value = true) {
+		this.#options.continueOnError = value;
+		return this;
+	}
+	retries(count) {
+		this.#options.retries = count;
+		return this;
+	}
+	timeout(duration) {
+		this.#options.timeout = duration;
+		return this;
+	}
+	throwOnError(value = true) {
+		this.#options.throwOnError = value;
+		return this;
+	}
+	useDriverBatching(value = true) {
+		this.#options.useDriverBatching = value;
+		return this;
+	}
+	disableDriverBatch(value = true) {
+		this.#options.disableDriverBatch = value;
+		return this;
+	}
+	onProgress(callback) {
+		this.#options.onProgress = callback;
+		return this;
+	}
+	async send() {
+		return this.#sendFn(this.#options);
+	}
+};
+/**
+* Create a new notification builder with proper typing
+*/
+function createNotificationBuilder(sendFn, notification) {
+	return new NotificationBuilderImpl(sendFn, notification);
+}
+
+//#endregion
+export { createNotificationBuilder };

package/dist/notifications/{notification_discoverer.d.ts → notification_discoverer.d.mts}

@@ -1,4 +1,4 @@
-import { Notification } from "../types/notifications.js";
+import { Notification } from "../types/notifications.mjs";
 
 //#region src/notifications/notification_discoverer.d.ts
 interface NotificationDiscovererConfig {

package/dist/notifications/{notification_discoverer.js → notification_discoverer.mjs}

@@ -1,8 +1,8 @@
-import { errors } from "../errors/index.js";
-import { Notification } from "../types/notifications.js";
-import "../types/index.js";
+import { errors } from "../errors/index.mjs";
+import { Notification } from "../types/notifications.mjs";
 import { fileURLToPath } from "node:url";
-import { fsReadAll, isScriptFile } from "@poppinss/utils";
+import { fsReadAll } from "@poppinss/utils/fs";
+import { isScriptFile } from "@poppinss/utils";
 
 //#region src/notifications/notification_discoverer.ts
 /**
@@ -27,10 +27,8 @@ var NotificationDiscoverer = class {
 			pathType: "url",
 			ignoreMissingRoot: true,
 			filter: (file) => {
-				const isScript = isScriptFile(file);
-				if (!isScript) return false;
-				const isNodeModule = fileURLToPath(file).includes("/node_modules/");
-				if (isNodeModule) return false;
+				if (!isScriptFile(file)) return false;
+				if (fileURLToPath(file).includes("/node_modules/")) return false;
 				const fileName = file.toString().split("/").pop() || "";
 				return fileName.endsWith(`${this.#config.fileSuffix}.ts`) || fileName.endsWith(`${this.#config.fileSuffix}.js`);
 			}
@@ -71,8 +69,7 @@ var NotificationDiscoverer = class {
 	}
 	async discoverNotifications() {
 		if (this.#cachedNotifications !== null) return this.#cachedNotifications;
-		const notifications = await this.#importNotifications();
-		const validNotifications = notifications.filter((i) => i.notification && typeof i.notification === "function").filter((i) => i.notification.prototype instanceof Notification);
+		const validNotifications = (await this.#importNotifications()).filter((i) => i.notification && typeof i.notification === "function").filter((i) => i.notification.prototype instanceof Notification);
 		this.#validateUniqueNotificationNames(validNotifications);
 		this.#cachedNotifications = validNotifications.map(({ notification }) => notification);
 		return this.#cachedNotifications;
@@ -83,15 +80,13 @@ var NotificationDiscoverer = class {
 	}
 	async getAllNotificationTags() {
 		await this.#ensureNotificationsDiscovered();
-		const notifications = this.#cachedNotifications;
-		return notifications.map((notification) => notification.name);
+		return this.#cachedNotifications.map((notification) => notification.name);
 	}
 	/**
 	* Get notification identities with both display name and class identifier
 	*/
 	async getNotificationIdentities() {
-		const notifications = await this.getNotifications();
-		return notifications.map((NotificationClass) => {
+		return (await this.getNotifications()).map((NotificationClass) => {
 			const options = NotificationClass.options || {};
 			return {
 				name: options.name,