@facteurjs/core 1.0.0-beta.0

package/dist/database/message.js

@@ -0,0 +1,51 @@
+//#region src/database/message.ts
+var DatabaseMessage = class DatabaseMessage {
+	static create() {
+		return new DatabaseMessage();
+	}
+	#type = "default";
+	#tags = [];
+	#content = {};
+	#notifiableId;
+	#tenantId;
+	#status = "unread";
+	setType(type) {
+		this.#type = type;
+		return this;
+	}
+	setTags(tags) {
+		this.#tags = tags;
+		return this;
+	}
+	setNotifiableId(notifiableId) {
+		this.#notifiableId = notifiableId;
+		return this;
+	}
+	setTenantId(tenantId) {
+		this.#tenantId = tenantId;
+		return this;
+	}
+	setStatus(status) {
+		this.#status = status;
+		return this;
+	}
+	setContent(content) {
+		this.#content = content;
+		return this;
+	}
+	serialize() {
+		return {
+			type: this.#type,
+			content: this.#content,
+			notifiableId: this.#notifiableId,
+			tenantId: this.#tenantId,
+			status: this.#status,
+			tags: this.#tags,
+			createdAt: /* @__PURE__ */ new Date(),
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+	}
+};
+
+//#endregion
+export { DatabaseMessage };

package/dist/database/types.d.ts

@@ -0,0 +1,147 @@
+import { ChannelName } from "../types/extend.js";
+import { Knex } from "knex";
+import { Kysely } from "kysely";
+
+//#region src/database/types.d.ts
+type NotificationStatus = 'read' | 'seen' | 'unread' | 'unseen';
+type Identifier = string | number;
+interface AdapterGetNotificationsParams {
+  notifiableId: Identifier;
+  tenantId: Identifier | undefined;
+  page?: number | undefined;
+  status?: NotificationStatus | undefined;
+  limit?: number;
+}
+interface GetNotificationsParams {
+  notifiableId: Identifier;
+  tenantId?: Identifier;
+  page?: number;
+  limit?: number;
+  status?: NotificationStatus;
+}
+interface Notification {
+  id: Identifier;
+  notifiableId: Identifier;
+  tenantId?: Identifier | undefined;
+  type: string;
+  content: Record<string, any>;
+  status: NotificationStatus;
+  tags?: string[];
+  readAt?: Date;
+  seenAt?: Date;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+interface SaveToDatabaseParams extends Omit<Notification, 'id'> {}
+interface UpdateNotificationParams {
+  id: Identifier;
+  status: NotificationStatus;
+}
+interface UpdateAllNotificationsParams {
+  notifiableId: Identifier;
+  tenantId?: Identifier | undefined;
+  status: NotificationStatus;
+}
+interface PruneNotificationsParams {
+  notifiableId?: Identifier;
+  tenantId?: Identifier;
+  olderThan?: Date;
+}
+/**
+ * Options accepted by the database provider
+ */
+interface DatabaseConfig {
+  adapter: DatabaseAdapter;
+}
+interface DatabaseAdapterCommonOptions {
+  tableNames?: {
+    /**
+     * The table name to use for storing notifications
+     * @default 'notifications'
+     */
+    notifications?: string | undefined;
+    /**
+     * The table name to use for storing notification preferences
+     * @default 'notification_preferences'
+     */
+    preferences?: string | undefined;
+  };
+}
+/**
+ * Options accepted by the Kysely adapter
+ */
+interface KyselyConfig extends DatabaseAdapterCommonOptions {
+  connection: Kysely<any>;
+}
+/**
+ * Options accepted by the Knex adapter
+ */
+interface KnexConfig extends DatabaseAdapterCommonOptions {
+  connection: Knex;
+}
+interface GetPreferencesParams {
+  notifiableId: Identifier;
+  tenantId?: Identifier;
+}
+interface RawPreferenceRow {
+  id: Identifier;
+  user_id: Identifier;
+  tenant_id?: Identifier | null;
+  notification_name?: string | null;
+  channels: Record<string, boolean>;
+  created_at: Date;
+  updated_at?: Date | null;
+}
+interface NotificationsPreferences {
+  /**
+   * Global preferences
+   */
+  global: {
+    channels: Record<ChannelName, boolean>;
+  };
+  /**
+   * Per-notification preferences
+   */
+  notifications: Array<{
+    notification: {
+      name?: string;
+      identifier: string;
+    };
+    channels: Record<ChannelName, boolean>;
+  }>;
+}
+interface Preferences {
+  /**
+   * Global preferences
+   */
+  global: NotificationsPreferences;
+  /**
+   * Per-tenant per-notification preferences
+   */
+  tenants?: Record<Identifier, NotificationsPreferences>;
+}
+interface SavePreferencesParams {
+  notifiableId: Identifier;
+  tenantId?: Identifier;
+  preferences: Preferences;
+}
+interface UpdatePreferencesParams {
+  notifiableId: Identifier;
+  tenantId?: Identifier;
+  notificationName: string;
+  channelPreferences: Record<ChannelName, boolean>;
+}
+/**
+ * The interface for implementing a new database adapter
+ */
+interface DatabaseAdapter {
+  save: (options: SaveToDatabaseParams) => Promise<void>;
+  getNotifications: (options: AdapterGetNotificationsParams) => Promise<Notification[]>;
+  updateNotification: (options: UpdateNotificationParams) => Promise<void>;
+  updateAllNotifications: (options: UpdateAllNotificationsParams) => Promise<void>;
+  pruneNotifications: (options: PruneNotificationsParams) => Promise<void>;
+  getPreferences: (options: GetPreferencesParams) => Promise<RawPreferenceRow[]>;
+  updatePreferences: (options: UpdatePreferencesParams) => Promise<void>;
+}
+//#endregion
+export { AdapterGetNotificationsParams, DatabaseAdapter, DatabaseAdapterCommonOptions, DatabaseConfig, GetNotificationsParams, GetPreferencesParams, Identifier, KnexConfig, KyselyConfig, Notification, NotificationStatus, NotificationsPreferences, Preferences, PruneNotificationsParams, RawPreferenceRow, SavePreferencesParams, SaveToDatabaseParams, UpdateAllNotificationsParams, UpdateNotificationParams, UpdatePreferencesParams };

package/dist/debug.js

@@ -0,0 +1,7 @@
+import { debuglog } from "node:util";
+
+//#region src/debug.ts
+var debug_default = debuglog("facteur:core");
+
+//#endregion
+export { debug_default as default };

package/dist/errors/duplicate_notification_exception.d.ts

@@ -0,0 +1,13 @@
+//#region src/errors/duplicate_notification_exception.d.ts
+interface DuplicateNotification {
+  notificationName: string;
+  notifications: Array<{
+    notification: any;
+    file: URL | string;
+  }> | undefined;
+}
+declare class E_DUPLICATE_NOTIFICATION extends Error {
+  constructor(appRoot: URL, duplicates: DuplicateNotification[]);
+}
+//#endregion
+export { E_DUPLICATE_NOTIFICATION };

package/dist/errors/duplicate_notification_exception.js

@@ -0,0 +1,21 @@
+import { fileURLToPath } from "node:url";
+
+//#region src/errors/duplicate_notification_exception.ts
+var E_DUPLICATE_NOTIFICATION = class extends Error {
+	constructor(appRoot, duplicates) {
+		let errorMessage = "Duplicate notification names detected:";
+		for (const { notificationName, notifications = [] } of duplicates) {
+			errorMessage += `\n\nNotification name "${notificationName}" is used in multiple files:\n`;
+			errorMessage += notifications.map(({ file }) => {
+				const relativePath = fileURLToPath(file).replace(appRoot.pathname, "");
+				return `- ${relativePath}`;
+			}).join("\n");
+		}
+		errorMessage += "\n\nEach notification must have a unique name. You can use a static \"notificationName\" property to customize the notification name.";
+		super(errorMessage);
+		this.name = "DuplicateNotificationException";
+	}
+};
+
+//#endregion
+export { E_DUPLICATE_NOTIFICATION };

package/dist/errors/http_error.d.ts

@@ -0,0 +1,16 @@
+//#region src/errors/http_error.d.ts
+
+/**
+ * Represents an HTTP error with decoded response body
+ */
+interface HTTPErrorInfo {
+  url: string;
+  status: number;
+  statusText: string;
+  responseBody: string;
+}
+/**
+ * Extracts information from an HTTPError with async response body decoding
+ */
+//#endregion
+export { HTTPErrorInfo };

package/dist/errors/http_error.js

@@ -0,0 +1,30 @@
+//#region src/errors/http_error.ts
+/**
+* Extracts information from an HTTPError with async response body decoding
+*/
+var HTTPErrorExtractor = class {
+	/**
+	* Extracts HTTP error information with properly decoded response body
+	*/
+	static async extract(httpError) {
+		const url = httpError.request.url;
+		const status = httpError.response.status;
+		const statusText = httpError.response.statusText;
+		let responseBody;
+		try {
+			const jsonBody = await httpError.response.clone().json();
+			responseBody = JSON.stringify(jsonBody, null, 2);
+		} catch {
+			responseBody = await httpError.response.text();
+		}
+		return {
+			url,
+			status,
+			statusText,
+			responseBody
+		};
+	}
+};
+
+//#endregion
+export { HTTPErrorExtractor };

package/dist/errors/index.d.ts

@@ -0,0 +1,38 @@
+import { E_DUPLICATE_NOTIFICATION } from "./duplicate_notification_exception.js";
+import * as _poppinss_exception0 from "@poppinss/exception";
+
+//#region src/errors/index.d.ts
+
+/**
+ * Thrown when the notification targets for a channel cannot be determined
+ * before sending the notification.
+ */
+declare const E_UNAVAILABLE_TARGETS: new (args: [channelName: string], options?: ErrorOptions) => _poppinss_exception0.Exception;
+/**
+ * Thrown when the queue adapter is not set before using jobs specific features.
+ */
+declare const E_QUEUE_NOT_SET: new (args?: any, options?: ErrorOptions) => _poppinss_exception0.Exception;
+/**
+ * Thrown when a `as<ChannelName>Message` method is not defined
+ */
+declare const E_MISSING_MESSAGE_METHOD: new (args: [channelName: string], options?: ErrorOptions) => _poppinss_exception0.Exception;
+/**
+ * Thrown when a send() operation fails. Could be due to one or more channels
+ * failing to send the notification.
+ */
+declare class E_SEND_NOTIFICATION_FAILED extends AggregateError {
+  code: string;
+  status: number;
+  constructor(errors: Array<{
+    error: any;
+  }>);
+}
+declare const errors: {
+  E_QUEUE_NOT_SET: new (args?: any, options?: ErrorOptions) => _poppinss_exception0.Exception;
+  E_UNAVAILABLE_TARGETS: new (args: [channelName: string], options?: ErrorOptions) => _poppinss_exception0.Exception;
+  E_DUPLICATE_NOTIFICATION: typeof E_DUPLICATE_NOTIFICATION;
+  E_MISSING_MESSAGE_METHOD: new (args: [channelName: string], options?: ErrorOptions) => _poppinss_exception0.Exception;
+  E_SEND_NOTIFICATION_FAILED: typeof E_SEND_NOTIFICATION_FAILED;
+};
+//#endregion
+export { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, errors };

package/dist/errors/index.js

@@ -0,0 +1,39 @@
+import { E_DUPLICATE_NOTIFICATION } from "./duplicate_notification_exception.js";
+import { createError } from "@poppinss/exception";
+
+//#region src/errors/index.ts
+/**
+* Thrown when the notification targets for a channel cannot be determined
+* before sending the notification.
+*/
+const E_UNAVAILABLE_TARGETS = createError(`Not able to determine targets for channel "%s". Provide targets or implement 'notificationTargets()' method.`, "E_UNAVAILABLE_TARGETS", 500);
+/**
+* Thrown when the queue adapter is not set before using jobs specific features.
+*/
+const E_QUEUE_NOT_SET = createError(`Queue adapter is not set. Set it via "setQueueAdapter" method before using jobs specific features.`, "E_QUEUE_NOT_SET", 500);
+/**
+* Thrown when a `as<ChannelName>Message` method is not defined
+*/
+const E_MISSING_MESSAGE_METHOD = createError(`Notification is missing "as%sMessage" method. Define it to build the message content for the channel.`, "E_MISSING_MESSAGE_METHOD", 500);
+/**
+* Thrown when a send() operation fails. Could be due to one or more channels
+* failing to send the notification.
+*/
+var E_SEND_NOTIFICATION_FAILED = class extends AggregateError {
+	code = "E_SEND_NOTIFICATION_FAILED";
+	status = 500;
+	constructor(errors$1) {
+		const message = "Failed to send notification due to errors in one or more channels.";
+		super(errors$1, message);
+	}
+};
+const errors = {
+	E_QUEUE_NOT_SET,
+	E_UNAVAILABLE_TARGETS,
+	E_DUPLICATE_NOTIFICATION,
+	E_MISSING_MESSAGE_METHOD,
+	E_SEND_NOTIFICATION_FAILED
+};
+
+//#endregion
+export { E_MISSING_MESSAGE_METHOD, E_QUEUE_NOT_SET, E_SEND_NOTIFICATION_FAILED, E_UNAVAILABLE_TARGETS, errors };

package/dist/events/events.d.ts

@@ -0,0 +1,90 @@
+import { ChannelName } from "../types/extend.js";
+import { Notification } from "../types/notifications.js";
+
+//#region src/events/events.d.ts
+interface MessageEventOptions {
+  notification: Notification<any, any>;
+  channelName: ChannelName;
+  message: any;
+}
+interface NotificationEventOptions {
+  notification: Notification<any, any>;
+}
+declare class FacteurEvents {
+  #private;
+  /**
+   * Sent when a message is about to be sent.
+   */
+  messageSending(options: MessageEventOptions): {
+    name: "facteur:message:sending";
+    data: {
+      notification: Notification<any, any>;
+      channelName: never;
+      message: any;
+    };
+  };
+  /**
+   * Sent when a message has been successfully sent.
+   */
+  messageSent(options: MessageEventOptions): {
+    name: "facteur:message:sent";
+    data: {
+      notification: Notification<any, any>;
+      channelName: never;
+      message: any;
+    };
+  };
+  /**
+   * Sent when a message failed to send.
+   */
+  messageFailed(options: MessageEventOptions & {
+    error: Error;
+  }): {
+    name: "facteur:message:failed";
+    data: {
+      error: Error;
+      notification: Notification<any, any>;
+      channelName: never;
+      message: any;
+    };
+  };
+  /**
+   * Sent when a notification is about to be sent.
+   */
+  notificationSending(options: NotificationEventOptions & {
+    resolvedChannels: Record<string, any>;
+  }): {
+    name: "facteur:notification:sending";
+    data: {
+      resolvedChannels: Record<string, any>;
+      notification: Notification<any, any>;
+    };
+  };
+  /**
+   * Sent when a notification has been successfully sent.
+   */
+  notificationSent(options: NotificationEventOptions & {
+    results: any[];
+  }): {
+    name: "facteur:notification:sent";
+    data: {
+      results: any[];
+      notification: Notification<any, any>;
+    };
+  };
+  /**
+   * Sent when a notification failed to send.
+   */
+  notificationFailed(options: NotificationEventOptions & {
+    errors: Error[];
+  }): {
+    name: "facteur:notification:failed";
+    data: {
+      errors: Error[];
+      notification: Notification<any, any>;
+    };
+  };
+}
+declare const facteurEvents: FacteurEvents;
+//#endregion
+export { facteurEvents };

package/dist/events/events.js

@@ -0,0 +1,83 @@
+//#region src/events/events.ts
+var FacteurEvents = class {
+	#buildMessageEventData(options) {
+		return {
+			notification: options.notification,
+			channelName: options.channelName,
+			message: options.message
+		};
+	}
+	#buildNotificationEventData(options) {
+		return { notification: options.notification };
+	}
+	/**
+	* Sent when a message is about to be sent.
+	*/
+	messageSending(options) {
+		return {
+			name: "facteur:message:sending",
+			data: this.#buildMessageEventData(options)
+		};
+	}
+	/**
+	* Sent when a message has been successfully sent.
+	*/
+	messageSent(options) {
+		return {
+			name: "facteur:message:sent",
+			data: this.#buildMessageEventData(options)
+		};
+	}
+	/**
+	* Sent when a message failed to send.
+	*/
+	messageFailed(options) {
+		return {
+			name: "facteur:message:failed",
+			data: {
+				...this.#buildMessageEventData(options),
+				error: options.error
+			}
+		};
+	}
+	/**
+	* Sent when a notification is about to be sent.
+	*/
+	notificationSending(options) {
+		return {
+			name: "facteur:notification:sending",
+			data: {
+				...this.#buildNotificationEventData(options),
+				resolvedChannels: options.resolvedChannels
+			}
+		};
+	}
+	/**
+	* Sent when a notification has been successfully sent.
+	*/
+	notificationSent(options) {
+		return {
+			name: "facteur:notification:sent",
+			data: {
+				...this.#buildNotificationEventData(options),
+				results: options.results
+			}
+		};
+	}
+	/**
+	* Sent when a notification failed to send.
+	*/
+	notificationFailed(options) {
+		return {
+			name: "facteur:notification:failed",
+			data: {
+				...this.#buildNotificationEventData(options),
+				errors: options.errors
+			}
+		};
+	}
+};
+const facteurEvents = new FacteurEvents();
+
+//#endregion
+export { facteurEvents };

package/dist/facteur.d.ts

@@ -0,0 +1,37 @@
+import { DatabaseAdapter } from "./database/types.js";
+import { Channel } from "./types/channel.js";
+import { FacteurConfiguration, SendOptions } from "./types/options.js";
+import { Notification, NotificationClass, NotificationSendResult } from "./types/notifications.js";
+import { FacteurFake } from "./fake.js";
+import { FacteurDatabase } from "./database/database.js";
+
+//#region src/facteur.d.ts
+declare function createFacteur<T extends Record<string, Channel>>(config: FacteurConfiguration<T>): Facteur<T, null>;
+/**
+ * Main manager class for Facteur library.
+ */
+declare class Facteur<KnownChannels extends Record<string, Channel>, DBAdapter extends DatabaseAdapter | null = null> {
+  #private;
+  constructor(config: FacteurConfiguration<KnownChannels, DBAdapter>);
+  get db(): DBAdapter extends DatabaseAdapter ? FacteurDatabase : never;
+  get discoverer(): {
+    discoverNotifications: () => Promise<(new (...args: any[]) => Notification)[]>;
+    getNotifications: () => Promise<(new (...args: any[]) => Notification)[]>;
+    getNotificationTags: () => Promise<string[]>;
+    clearCache: () => void;
+  };
+  /**
+   * Fake the notification sending process for testing purposes
+   */
+  fake(): FacteurFake;
+  /**
+   * Restore the original notification sending process after faking it
+   */
+  restore(): void;
+  /**
+   * Send a notification
+   */
+  send<TNotificationClass extends NotificationClass<any, any>>(options: SendOptions<TNotificationClass>): Promise<NotificationSendResult>;
+}
+//#endregion
+export { Facteur, createFacteur };

package/dist/facteur.js

@@ -0,0 +1,83 @@
+import { FacteurFake } from "./fake.js";
+import { FacteurOptions } from "./options.js";
+import { FacteurDatabase } from "./database/database.js";
+import { ChannelResolver } from "./notifications/channel_resolver.js";
+import { NotificationSender } from "./notifications/notification_sender.js";
+import "./types/index.js";
+import { NotificationDiscoverer } from "./notifications/notification_discoverer.js";
+
+//#region src/facteur.ts
+function createFacteur(config) {
+	return new Facteur(config);
+}
+/**
+* Main manager class for Facteur library.
+*/
+var Facteur = class {
+	#sender;
+	#fake = null;
+	#db = null;
+	#discoverer;
+	#channelResolver;
+	#options;
+	constructor(config) {
+		this.#options = new FacteurOptions(config);
+		this.#discoverer = new NotificationDiscoverer({
+			searchDirectory: config.discoverer.searchDirectory,
+			fileSuffix: config.discoverer.fileSuffix
+		});
+		if (this.#options.databaseAdapter) {
+			const options = this.#options;
+			this.#db = new FacteurDatabase(options, this.#discoverer);
+			this.#channelResolver = new ChannelResolver(this.#db);
+		} else this.#channelResolver = new ChannelResolver();
+		this.#sender = new NotificationSender(this.#options.channels, this.#channelResolver, this.#options.emitter);
+	}
+	get db() {
+		if (!this.#options.databaseAdapter) throw new Error("No database adapter configured");
+		return this.#db;
+	}
+	get discoverer() {
+		return {
+			discoverNotifications: () => this.#discoverer.discoverNotifications(),
+			getNotifications: () => this.#discoverer.getNotifications(),
+			getNotificationTags: () => this.#discoverer.getAllNotificationTags(),
+			clearCache: () => this.#discoverer.clearCache()
+		};
+	}
+	/**
+	* Fake the notification sending process for testing purposes
+	*/
+	fake() {
+		this.#fake = new FacteurFake();
+		return this.#fake;
+	}
+	/**
+	* Restore the original notification sending process after faking it
+	*/
+	restore() {
+		this.#fake = null;
+	}
+	/**
+	* Send a notification
+	*/
+	async send(options) {
+		const notification = await this.#options.notificationResolver(options.notification, {
+			notifiable: "notifiable" in options ? options.notifiable : void 0,
+			params: options.params,
+			tenantId: options.tenantId
+		});
+		await notification.beforeSend();
+		const shouldSend = await notification.shouldSend();
+		if (shouldSend === false) return {
+			success: 0,
+			failed: 0,
+			results: []
+		};
+		if (this.#fake) return this.#fake.recordSent(options);
+		return this.#sender.send(options, notification);
+	}
+};
+
+//#endregion
+export { Facteur, createFacteur };