@facteurjs/core 1.0.0-beta.0

package/dist/fake.d.ts

@@ -0,0 +1,47 @@
+import { SendOptions } from "./types/options.js";
+import { Notification, NotificationSendResult } from "./types/notifications.js";
+
+//#region src/fake.d.ts
+interface SentNotification<N extends Notification = Notification> {
+  notification: N;
+  notifiable: N extends Notification<infer TNotifiable, any> ? TNotifiable : never;
+  params?: N extends Notification<any, infer P> ? P : never;
+  via?: any;
+}
+declare class FacteurFake {
+  #private;
+  /**
+   * Record a notification as sent during fake mode
+   */
+  recordSent(options: SendOptions<any>): NotificationSendResult;
+  /**
+   * Assert a total of expected number of notifications were sent
+   */
+  assertSentCount(count: number): void;
+  /**
+   * Assert the mentioned notification was sent for expected number of times
+   */
+  assertSentCount<N extends Notification>(notificationClass: new (...args: any[]) => N, count: number): void;
+  /**
+   * Assert zero notifications were sent
+   */
+  assertNoneSent(): void;
+  /**
+   * Returns a list of sent notifications captured by the fake
+   */
+  sent(): SentNotification[];
+  /**
+   * Returns a list of sent notifications of a specific type captured by the fake
+   */
+  sent<N extends Notification>(notificationClass: new (...args: any[]) => N): SentNotification<N>[];
+  /**
+   * Assert the mentioned notification was sent during the fake mode
+   */
+  assertSent<N extends Notification>(notificationClass: new (...args: any[]) => N, callback?: (sentNotification: SentNotification<N>) => void): void;
+  /**
+   * Clear all sent notifications from the fake
+   */
+  clear(): void;
+}
+//#endregion
+export { FacteurFake };

package/dist/fake.js

@@ -0,0 +1,85 @@
+import { AssertionError } from "node:assert";
+
+//#region src/fake.ts
+var FacteurFake = class {
+	#sentNotifications = [];
+	/**
+	* Record a notification as sent during fake mode
+	*/
+	recordSent(options) {
+		const notification = new options.notification();
+		this.#sentNotifications.push({
+			notification,
+			notifiable: options.notifiable,
+			params: options.params,
+			via: options.via
+		});
+		return {
+			success: 1,
+			failed: 0,
+			results: [{
+				channel: "fake",
+				status: "success"
+			}]
+		};
+	}
+	assertSentCount(notificationClassOrCount, count) {
+		if (typeof notificationClassOrCount === "number") {
+			const totalCount = notificationClassOrCount;
+			if (this.#sentNotifications.length !== totalCount) throw new AssertionError({
+				message: `Expected ${totalCount} notifications to be sent, but ${this.#sentNotifications.length} were sent`,
+				actual: this.#sentNotifications.length,
+				expected: totalCount
+			});
+			return;
+		}
+		const notificationClass = notificationClassOrCount;
+		const actualCount = this.#sentNotifications.filter((sent) => sent.notification instanceof notificationClass).length;
+		if (actualCount !== count) throw new AssertionError({
+			message: `Expected ${count} notifications of type ${notificationClass.name} to be sent, but ${actualCount} were sent`,
+			actual: actualCount,
+			expected: count
+		});
+	}
+	/**
+	* Assert zero notifications were sent
+	*/
+	assertNoneSent() {
+		if (this.#sentNotifications.length > 0) throw new AssertionError({
+			message: `Expected no notifications to be sent, but ${this.#sentNotifications.length} were sent`,
+			actual: this.#sentNotifications.length,
+			expected: 0
+		});
+	}
+	sent(notificationClass) {
+		if (!notificationClass) return this.#sentNotifications;
+		return this.#sentNotifications.filter((sent) => sent.notification instanceof notificationClass);
+	}
+	/**
+	* Assert the mentioned notification was sent during the fake mode
+	*/
+	assertSent(notificationClass, callback) {
+		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) => {
+				try {
+					callback(sent);
+					return true;
+				} catch {
+					return false;
+				}
+			});
+			if (!found) throw new AssertionError({ message: `No notifications of type ${notificationClass.name} matched the given callback` });
+		}
+	}
+	/**
+	* Clear all sent notifications from the fake
+	*/
+	clear() {
+		this.#sentNotifications = [];
+	}
+};
+
+//#endregion
+export { FacteurFake };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+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";
+
+//#region src/index.d.ts
+
+/**
+ * Define a new provider
+ */
+declare function defineProvider<Name, Options, Message, Response, Targets>(name: Name, factory: (options: Options) => Channel<Options, Message, Response, Targets>): (options: Options) => {
+  name: Name;
+  provider: Channel<Options, Message, Response, Targets>;
+};
+//#endregion
+export { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, Facteur, createFacteur, defineProvider, errors };

package/dist/index.js

@@ -0,0 +1,16 @@
+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";
+
+//#region src/index.ts
+/**
+* Define a new provider
+*/
+function defineProvider(name, factory) {
+	return (options) => ({
+		name,
+		provider: factory(options)
+	});
+}
+
+//#endregion
+export { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, Facteur, createFacteur, defineProvider, errors };

package/dist/notifications/channel_resolver.js

@@ -0,0 +1,91 @@
+import { invoke } from "@julr/utils/functions";
+import { mapEntries } from "@julr/utils/object";
+import { is } from "@julr/utils/is";
+
+//#region src/notifications/channel_resolver.ts
+var ChannelResolver = class {
+	#database = null;
+	constructor(database) {
+		this.#database = database || null;
+	}
+	/**
+	* Resolve channels and targets provided by via
+	*/
+	#resolveVia(options) {
+		const notifiableTargets = options.notifiable?.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
+			}];
+		});
+	}
+	async resolveChannels(options) {
+		const { notification, notifiable, params, via, tenantId } = options;
+		const notificationOptions = notification.options;
+		const notificationIdentifier = notificationOptions.identifier || notification.name;
+		const notifiableTargets = options.notifiable?.notificationTargets?.();
+		/**
+		* First, if via is provided it should override everything.
+		*/
+		if (via) return this.#resolveVia(options);
+		/**
+		* Get preferences for the notifiable and tenant
+		*/
+		const preferences = await this.#database?.getPreferences({
+			notifiableId: notifiable.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({
+					notifiable,
+					params,
+					preferences
+				});
+			});
+			const target = notifiableTargets?.[channelName] || null;
+			return [channelName, {
+				shouldSend,
+				target
+			}];
+		});
+		/**
+		* And then we can apply user preferences
+		*/
+		const currentTenant = preferences?.tenants?.[tenantId || -1];
+		const tenantPreferences = currentTenant?.global;
+		const globalPreferences = preferences?.global.global;
+		const notificationTenantPreference = currentTenant?.notifications?.find(({ notification: notification$1 }) => notification$1.identifier === notificationIdentifier);
+		const notificationGlobalPreference = preferences?.global.notifications.find(({ notification: notification$1 }) => notification$1.identifier === notificationIdentifier);
+		return mapEntries(fromDeliverBy, (channelName, { shouldSend, target }) => {
+			if (shouldSend === false) return [channelName, {
+				shouldSend: false,
+				target
+			}];
+			const preferencesSources = [
+				notificationTenantPreference?.channels[channelName],
+				tenantPreferences?.channels[channelName],
+				notificationGlobalPreference?.channels[channelName],
+				globalPreferences?.channels[channelName]
+			];
+			shouldSend = preferencesSources.find((preference) => !is.undefined(preference)) ?? shouldSend;
+			return [channelName, {
+				shouldSend,
+				target
+			}];
+		});
+	}
+};
+
+//#endregion
+export { ChannelResolver };

package/dist/notifications/notification_discoverer.d.ts

@@ -0,0 +1,40 @@
+import { Notification } from "../types/notifications.js";
+
+//#region src/notifications/notification_discoverer.d.ts
+interface NotificationDiscovererConfig {
+  /**
+   * The root directory to search for notifications
+   */
+  searchDirectory: URL;
+  /**
+   * The file suffix pattern for notification files
+   * @default '_notification'
+   */
+  fileSuffix?: string | undefined;
+}
+/**
+ * Discover and load notification classes from the application directory.
+ * Ensure that all notification names are unique.
+ */
+declare class NotificationDiscoverer {
+  #private;
+  constructor(config: NotificationDiscovererConfig);
+  getNotifications(): Promise<Array<new (...args: any[]) => Notification>>;
+  discoverNotifications(): Promise<(new (...args: any[]) => Notification)[]>;
+  getAllNotificationTags(): Promise<string[]>;
+  /**
+   * Get notification identities with both display name and class identifier
+   */
+  getNotificationIdentities(): Promise<Array<{
+    name: string;
+    identifier: string;
+    tags?: string[];
+    category?: string;
+  }>>;
+  /**
+   * Clear the cache of discovered notifications
+   */
+  clearCache(): void;
+}
+//#endregion
+export { NotificationDiscoverer };

package/dist/notifications/notification_discoverer.js

@@ -0,0 +1,113 @@
+import { errors } from "../errors/index.js";
+import { Notification } from "../types/notifications.js";
+import "../types/index.js";
+import { fileURLToPath } from "node:url";
+import { fsReadAll, isScriptFile } from "@poppinss/utils";
+
+//#region src/notifications/notification_discoverer.ts
+/**
+* Discover and load notification classes from the application directory.
+* Ensure that all notification names are unique.
+*/
+var NotificationDiscoverer = class {
+	#config;
+	#cachedNotifications = null;
+	constructor(config) {
+		this.#config = {
+			fileSuffix: config.fileSuffix || "_notification",
+			searchDirectory: config.searchDirectory
+		};
+	}
+	/**
+	* Import notification files from the configured directory
+	*/
+	async #importNotifications() {
+		const searchDir = this.#config.searchDirectory;
+		const notificationFiles = await fsReadAll(searchDir, {
+			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;
+				const fileName = file.toString().split("/").pop() || "";
+				return fileName.endsWith(`${this.#config.fileSuffix}.ts`) || fileName.endsWith(`${this.#config.fileSuffix}.js`);
+			}
+		});
+		return this.#importNotificationsFromFiles(notificationFiles);
+	}
+	/**
+	* Import notification classes from an array of file paths
+	*/
+	async #importNotificationsFromFiles(files) {
+		const promises = files.map(async (file) => {
+			const i = await import(file.toString());
+			if (!i.default) return {
+				notification: null,
+				file
+			};
+			return {
+				notification: i.default,
+				file
+			};
+		});
+		return Promise.all(promises);
+	}
+	/**
+	* Validate that all notification names are unique and throw if duplicates are found
+	*/
+	#validateUniqueNotificationNames(notifications) {
+		const notificationsByName = Object.groupBy(notifications, (i) => i.notification.name);
+		const duplicates = Object.entries(notificationsByName).filter(([_, notifications$1]) => (notifications$1?.length || 0) > 1).map(([notificationName, notifications$1]) => ({
+			notificationName,
+			notifications: notifications$1
+		}));
+		if (duplicates.length > 0) throw new errors.E_DUPLICATE_NOTIFICATION(this.#config.searchDirectory, duplicates);
+	}
+	async getNotifications() {
+		await this.#ensureNotificationsDiscovered();
+		return this.#cachedNotifications || [];
+	}
+	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);
+		this.#validateUniqueNotificationNames(validNotifications);
+		this.#cachedNotifications = validNotifications.map(({ notification }) => notification);
+		return this.#cachedNotifications;
+	}
+	async #ensureNotificationsDiscovered() {
+		if (this.#cachedNotifications !== null) return;
+		throw new Error(`Notifications have not been discovered yet. Call 'discoverAndLoadNotifications' first.`);
+	}
+	async getAllNotificationTags() {
+		await this.#ensureNotificationsDiscovered();
+		const notifications = this.#cachedNotifications;
+		return notifications.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) => {
+			const options = NotificationClass.options || {};
+			return {
+				name: options.name,
+				identifier: NotificationClass.name || options.identifier,
+				tags: options.tags || [],
+				category: options.category
+			};
+		});
+	}
+	/**
+	* Clear the cache of discovered notifications
+	*/
+	clearCache() {
+		this.#cachedNotifications = null;
+	}
+};
+
+//#endregion
+export { NotificationDiscoverer };

package/dist/notifications/notification_sender.js

@@ -0,0 +1,210 @@
+import { errors } from "../errors/index.js";
+import debug_default from "../debug.js";
+import { facteurEvents } from "../events/events.js";
+import "./channel_resolver.js";
+import { capitalize } from "@julr/utils/string";
+
+//#region src/notifications/notification_sender.ts
+/**
+* Responsible for sending notifications and messages
+*/
+var NotificationSender = class {
+	constructor(channels, channelResolver, emitter) {
+		this.channels = channels;
+		this.channelResolver = channelResolver;
+		this.emitter = emitter;
+	}
+	/**
+	* Emit notification sending event
+	*/
+	#emitNotificationSending(notification, resolvedChannels) {
+		const event = facteurEvents.notificationSending({
+			notification,
+			resolvedChannels
+		});
+		this.emitter.emit(event.name, event.data);
+	}
+	/**
+	* Emit notification sent event
+	*/
+	#emitNotificationSent(notification, results) {
+		const event = facteurEvents.notificationSent({
+			notification,
+			results
+		});
+		this.emitter.emit(event.name, event.data);
+	}
+	/**
+	* Emit notification failed event
+	*/
+	#emitNotificationFailed(notification, errors$1) {
+		const event = facteurEvents.notificationFailed({
+			notification,
+			errors: errors$1
+		});
+		this.emitter.emit(event.name, event.data);
+	}
+	/**
+	* Emit message sending event
+	*/
+	#emitMessageSending(notification, channelName, message) {
+		const event = facteurEvents.messageSending({
+			notification,
+			channelName,
+			message
+		});
+		this.emitter.emit(event.name, event.data);
+	}
+	/**
+	* Emit message sent event
+	*/
+	#emitMessageSent(notification, channelName, message) {
+		const event = facteurEvents.messageSent({
+			notification,
+			channelName,
+			message
+		});
+		this.emitter.emit(event.name, event.data);
+	}
+	/**
+	* Emit message failed event
+	*/
+	#emitMessageFailed(notification, channelName, message, error) {
+		const event = facteurEvents.messageFailed({
+			notification,
+			channelName,
+			message,
+			error
+		});
+		this.emitter.emit(event.name, event.data);
+	}
+	/**
+	* Get a channel by its name
+	*/
+	#getChannel(channelName) {
+		const channel = this.channels[channelName];
+		if (!channel) throw new Error(`Channel '${channelName}' is not registered`);
+		return channel;
+	}
+	/**
+	* Send a single message through a specific channel
+	*/
+	async #sendMessage(options) {
+		const { channelName, options: sendOptions, channelConfig } = options;
+		/**
+		* First build the message content using the notification's
+		* `as<ChannelName>Message` method
+		*/
+		const channel = this.#getChannel(channelName);
+		const channelMethodName = `as${capitalize(channelName)}Message`;
+		const messageBuilder = options.notification[channelMethodName];
+		if (typeof messageBuilder !== "function") throw new errors.E_MISSING_MESSAGE_METHOD([capitalize(channelName)]);
+		const messageContent = messageBuilder.call(options.notification, {
+			notifiable: sendOptions.notifiable,
+			params: sendOptions.params,
+			tenantId: sendOptions.tenantId
+		});
+		if (!messageContent) return null;
+		/**
+		* Send the message and emit appropriate events
+		*/
+		debug_default(`Sending message via ${channelName}: %O`, messageContent);
+		this.#emitMessageSending(options.notification, channelName, messageContent);
+		try {
+			await channel.send({
+				tenantId: sendOptions.tenantId,
+				message: messageContent,
+				targets: channelConfig.target,
+				notifiable: sendOptions.notifiable
+			});
+			debug_default(`Message sent via ${channelName}`);
+			this.#emitMessageSent(options.notification, channelName, messageContent);
+			return {
+				channel: channelName,
+				status: "success"
+			};
+		} catch (error) {
+			this.#emitMessageFailed(options.notification, channelName, messageContent, error);
+			throw error;
+		}
+	}
+	/**
+	* Process results from sending messages and emit appropriate events
+	*/
+	async #processResults(options) {
+		const { results, throwOnError, notification } = options;
+		const channelResults = results.filter((result) => result !== null);
+		const successes = channelResults.filter((r) => r.status === "success");
+		const failures = channelResults.filter((r) => r.status === "failed");
+		/**
+		* Everything succeeded
+		*/
+		if (!failures.length) {
+			this.#emitNotificationSent(notification, channelResults);
+			await notification.afterSend();
+			return {
+				failed: failures.length,
+				success: successes.length,
+				results: channelResults
+			};
+		}
+		/**
+		* Some channels failed
+		*/
+		const failureReasons = failures.map((r) => r.error);
+		this.#emitNotificationFailed(notification, failureReasons);
+		await notification.afterSend();
+		if (throwOnError !== false) throw new errors.E_SEND_NOTIFICATION_FAILED(failureReasons);
+		return {
+			failed: failures.length,
+			success: successes.length,
+			results: channelResults
+		};
+	}
+	/**
+	* Send a notification through all resolved channels
+	*/
+	async send(options, notification) {
+		const { via, params, tenantId } = options;
+		const notifiable = "notifiable" in options ? options.notifiable : void 0;
+		const resolvedChannels = await this.channelResolver.resolveChannels({
+			notifiable,
+			params,
+			tenantId,
+			notification: options.notification,
+			...via ? { via } : {}
+		});
+		debug_default(`Resolved channels: %O`, resolvedChannels);
+		this.#emitNotificationSending(notification, resolvedChannels);
+		/**
+		* Send messages for each resolved channel
+		*/
+		const promises = Object.entries(resolvedChannels).map(async ([name, config]) => {
+			if (!config.shouldSend || !config.target) return null;
+			return await this.#sendMessage({
+				notification,
+				channelConfig: config,
+				channelName: name,
+				options
+			}).catch((error) => {
+				debug_default(`Failed to send notification via ${name}: %O`, error);
+				return {
+					channel: name,
+					status: "failed",
+					error
+				};
+			});
+		});
+		/**
+		* Process results and emit appropriate events
+		*/
+		return await this.#processResults({
+			notification,
+			results: await Promise.all(promises),
+			throwOnError: options.throwOnError !== false
+		});
+	}
+};
+
+//#endregion
+export { NotificationSender };

package/dist/options.d.ts

@@ -0,0 +1,22 @@
+import { DatabaseAdapter } from "./database/types.js";
+import { Channel } from "./types/channel.js";
+import { Emitter } from "./types/events.js";
+import { QueueAdapter } from "./types/queue.js";
+import { ResolvedDefaultPreferences } from "./types/preferences.js";
+import { FacteurConfiguration, NotificationResolver } from "./types/options.js";
+import { Logger } from "@julr/utils/logger";
+
+//#region src/options.d.ts
+declare class FacteurOptions<KnownChannels extends Record<string, Channel>, DBAdapter extends DatabaseAdapter | null = null> {
+  #private;
+  logger: Logger;
+  emitter: Emitter;
+  channels: KnownChannels;
+  queueAdapter: QueueAdapter;
+  databaseAdapter: DBAdapter | null;
+  notificationResolver: NotificationResolver;
+  readonly defaultPreferences: ResolvedDefaultPreferences<KnownChannels>;
+  constructor(config: FacteurConfiguration<KnownChannels, DBAdapter>);
+}
+//#endregion
+export { FacteurOptions };