@facteurjs/core 1.0.0-beta.0

package/dist/options.js

@@ -0,0 +1,57 @@
+import { errors } from "./errors/index.js";
+import EventEmitter from "node:events";
+import { noopLogger } from "@julr/utils/logger";
+import { invoke } from "@julr/utils/functions";
+
+//#region src/options.ts
+var FacteurOptions = class {
+	logger = noopLogger();
+	emitter = new EventEmitter();
+	channels;
+	queueAdapter;
+	databaseAdapter = null;
+	notificationResolver;
+	defaultPreferences;
+	#resolveDefaultPreferences(preferences) {
+		preferences = preferences || {};
+		const allChannels = Object.keys(this.channels);
+		/**
+		* Pick global preferences or set all channels to true
+		*/
+		const globalChannelPreferences = preferences.global?.channels || Object.fromEntries(allChannels.map((channel) => [channel, true]));
+		/**
+		* Build categories preferences
+		*/
+		const categories = Object.entries(preferences.categories || {}).map(([category, config]) => {
+			const value = invoke(() => {
+				if (typeof config === "boolean") return Object.fromEntries(allChannels.map((channel) => [channel, config]));
+				return Object.assign({}, globalChannelPreferences, config.channels || {});
+			});
+			return [category, { channels: value }];
+		});
+		return {
+			enabled: preferences.enabled ?? true,
+			global: { channels: globalChannelPreferences },
+			categories: Object.fromEntries(categories)
+		};
+	}
+	constructor(config) {
+		this.logger = config.logger ?? this.logger;
+		this.emitter = config.emitter ?? this.emitter;
+		this.channels = config.channels;
+		this.databaseAdapter = config.databaseAdapter ?? null;
+		this.defaultPreferences = this.#resolveDefaultPreferences(config.preferences);
+		this.notificationResolver = config.notificationResolver || ((notification, ctx) => new notification(ctx));
+		const throwIfQueueNotSet = () => {
+			throw new errors.E_QUEUE_NOT_SET();
+		};
+		this.queueAdapter = config.queueAdapter || {
+			queue: throwIfQueueNotSet,
+			startQueueProcessor: throwIfQueueNotSet,
+			disconnect: throwIfQueueNotSet
+		};
+	}
+};
+
+//#endregion
+export { FacteurOptions };

package/dist/types/channel.d.ts

@@ -0,0 +1,18 @@
+import { Identifier } from "../database/types.js";
+import { Awaitable } from "@julr/utils/types";
+
+//#region src/types/channel.d.ts
+type ChannelSendParams<Message, Targets> = {
+  notifiable?: any;
+  message: Message;
+  targets?: Targets;
+  tenantId?: Identifier | undefined;
+};
+declare const kTargetSymbol: unique symbol;
+interface Channel<_Options = any, Message = any, Response = any, Targets = any> {
+  [kTargetSymbol]: Targets;
+  name: string;
+  send: (options: ChannelSendParams<Message, Targets>) => Awaitable<Response>;
+}
+//#endregion
+export { Channel, ChannelSendParams, kTargetSymbol };

package/dist/types/channel.js

@@ -0,0 +1,5 @@
+//#region src/types/channel.ts
+const kTargetSymbol = Symbol("facteur:targets");
+
+//#endregion
+export { kTargetSymbol };

package/dist/types/events.d.ts

@@ -0,0 +1,27 @@
+import { facteurEvents } from "../events/events.js";
+
+//#region src/types/events.d.ts
+
+/**
+ * Shape of the emitter accepted by facteur
+ * Should be compatible with node's EventEmitter and Emittery
+ */
+interface Emitter {
+  on: (event: string, callback: (...values: any[]) => void) => void;
+  once: (event: string, callback: (...values: any[]) => void) => void;
+  off: (event: string, callback: (...values: any[]) => void) => void;
+  emit: (event: string, ...values: any[]) => void;
+}
+/**
+ * Name/payload of the events emitted by facteur
+ */
+type FacteurEvents = {
+  'facteur:message:sending': ReturnType<typeof facteurEvents.messageSending>['data'];
+  'facteur:message:sent': ReturnType<typeof facteurEvents.messageSent>['data'];
+  'facteur:message:failed': ReturnType<typeof facteurEvents.messageFailed>['data'];
+  'facteur:notification:sending': ReturnType<typeof facteurEvents.notificationSending>['data'];
+  'facteur:notification:sent': ReturnType<typeof facteurEvents.notificationSent>['data'];
+  'facteur:notification:failed': ReturnType<typeof facteurEvents.notificationFailed>['data'];
+};
+//#endregion
+export { Emitter, FacteurEvents };

package/dist/types/extend.d.ts

@@ -0,0 +1,25 @@
+import { FacteurConfiguration } from "./options.js";
+import { Facteur } from "../facteur.js";
+
+//#region src/types/extend.d.ts
+
+/**
+ * List of available channels
+ */
+type ChannelName = keyof NotificationChannels;
+/**
+ * The list of channels configured in the Facteur instance. This must
+ * be extended user-land with module augmentation
+ */
+interface NotificationChannels {}
+/**
+ * The type of the notification.content in database notifications.
+ * This must be extended user-land with module augmentation
+ */
+interface DatabaseContent {}
+/**
+ * Infer the channels from the Facteur instance
+ */
+type InferChannelsFromConfig<T> = T extends Facteur<infer U> ? U : T extends FacteurConfiguration<infer X> ? X : never;
+//#endregion
+export { ChannelName, DatabaseContent, InferChannelsFromConfig, NotificationChannels };

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+import { Channel, ChannelSendParams, kTargetSymbol } from "./channel.js";
+import { Emitter, FacteurEvents } from "./events.js";
+import { QueueAdapter, QueueItemOptions } from "./queue.js";
+import { DefaultPreferences, ResolvedDefaultPreferences } from "./preferences.js";
+import { ChannelName, DatabaseContent, InferChannelsFromConfig, NotificationChannels } from "./extend.js";
+import { ChannelSpecificConfig, CommonSendOptions, DeliverByOptions, ExtractChannelTargets, ExtractNotifiable, ExtractParams, FacteurConfiguration, MessageCtx, NotificationOptions, NotificationParams, NotificationResolver, ProviderTarget, SendOptions } from "./options.js";
+import { ChannelSendResult, Notifiable, NotifiableTargets, Notification, NotificationClass, NotificationSendResult } from "./notifications.js";
+export { Channel, ChannelName, ChannelSendParams, ChannelSendResult, ChannelSpecificConfig, CommonSendOptions, DatabaseContent, DefaultPreferences, DeliverByOptions, Emitter, ExtractChannelTargets, ExtractNotifiable, ExtractParams, FacteurConfiguration, FacteurEvents, InferChannelsFromConfig, MessageCtx, Notifiable, NotifiableTargets, Notification, NotificationChannels, NotificationClass, NotificationOptions, NotificationParams, NotificationResolver, NotificationSendResult, ProviderTarget, QueueAdapter, QueueItemOptions, ResolvedDefaultPreferences, SendOptions, kTargetSymbol };

package/dist/types/index.js

@@ -0,0 +1,4 @@
+import { kTargetSymbol } from "./channel.js";
+import { Notification } from "./notifications.js";
+
+export { Notification, kTargetSymbol };

package/dist/types/notifications.d.ts

@@ -0,0 +1,60 @@
+import { Identifier } from "../database/types.js";
+import { ChannelName, NotificationChannels } from "./extend.js";
+import { ExtractChannelTargets, MessageCtx, NotificationOptions } from "./options.js";
+import { Awaitable } from "@julr/utils/types";
+
+//#region src/types/notifications.d.ts
+
+/**
+ * Constructor type for notification classes
+ */
+type NotificationClass<TNotifiable extends Notifiable | undefined, TParams extends Record<string, any> = Record<string, any>> = new (...args: any[]) => Notification<TNotifiable, TParams>;
+/**
+ * Base abstract class for all notifications
+ */
+declare abstract class Notification<N extends Notifiable | undefined = Notifiable | undefined, Params extends Record<string, any> = any> {
+  protected notifiable: N;
+  protected params: Params;
+  protected tenantId: Identifier | undefined;
+  constructor(ctx: MessageCtx<N, Params>);
+  static options: NotificationOptions<any>;
+  /**
+   * Determine if the notification should be sent or not
+   */
+  shouldSend(): Awaitable<boolean>;
+  /**
+   * Method invoked before sending the notification.
+   * Can be used to perform any pre-send logic.
+   */
+  beforeSend(): Awaitable<void>;
+  /**
+   * Method invoked after the notification has been sent.
+   * Can be used to perform any post-send logic.
+   */
+  afterSend(): Awaitable<void>;
+}
+/**
+ * Result of sending notification through a specific channel
+ */
+interface ChannelSendResult {
+  channel: ChannelName;
+  status: 'success' | 'failed';
+  error?: any;
+}
+/**
+ * Overall result of sending a notification across all channels
+ */
+interface NotificationSendResult {
+  success: number;
+  failed: number;
+  results: ChannelSendResult[];
+}
+/**
+ * Interface for entities that can receive notifications
+ */
+interface Notifiable {
+  notificationTargets?(): NotifiableTargets;
+}
+type NotifiableTargets = { [K in keyof NotificationChannels]?: ExtractChannelTargets<NotificationChannels[K]> };
+//#endregion
+export { ChannelSendResult, Notifiable, NotifiableTargets, Notification, NotificationClass, NotificationSendResult };

package/dist/types/notifications.js

@@ -0,0 +1,38 @@
+//#region src/types/notifications.ts
+/**
+* Base abstract class for all notifications
+*/
+var Notification = class {
+	notifiable;
+	params;
+	tenantId;
+	constructor(ctx) {
+		this.notifiable = ctx.notifiable;
+		this.params = ctx.params;
+		this.tenantId = ctx.tenantId;
+	}
+	static options = {
+		name: "",
+		tags: [],
+		deliverBy: {}
+	};
+	/**
+	* Determine if the notification should be sent or not
+	*/
+	shouldSend() {
+		return true;
+	}
+	/**
+	* Method invoked before sending the notification.
+	* Can be used to perform any pre-send logic.
+	*/
+	beforeSend() {}
+	/**
+	* Method invoked after the notification has been sent.
+	* Can be used to perform any post-send logic.
+	*/
+	afterSend() {}
+};
+
+//#endregion
+export { Notification };

package/dist/types/options.d.ts

@@ -0,0 +1,157 @@
+import { DatabaseAdapter, Identifier } from "../database/types.js";
+import { Channel } from "./channel.js";
+import { Emitter } from "./events.js";
+import { QueueAdapter } from "./queue.js";
+import { DefaultPreferences } from "./preferences.js";
+import { ChannelName, NotificationChannels } from "./extend.js";
+import { Notifiable, Notification, NotificationClass } from "./notifications.js";
+import { Logger } from "@julr/utils/logger";
+import { Awaitable } from "@julr/utils/types";
+
+//#region src/types/options.d.ts
+
+/**
+ * Configuration options for the Facteur library
+ */
+interface FacteurConfiguration<KnownChannels extends Record<string, Channel> = Record<string, Channel>, DBAdapter extends DatabaseAdapter | null = null> {
+  logger?: Logger;
+  emitter?: Emitter;
+  /**
+   * Channels to use for sending notifications.
+   */
+  channels: KnownChannels;
+  /**
+   * A queue adapter to use for sending notifications.
+   * Needs to be provided if you want to use some queueing capabilities.
+   */
+  queueAdapter?: QueueAdapter;
+  /**
+   * Database adapter to use for storing things, like topics and preferences.
+   * If not provided, you will not be able these features.
+   */
+  databaseAdapter?: DBAdapter;
+  /**
+   * Discoverer configuration
+   */
+  discoverer: {
+    /**
+     * Directory to search for notification classes. Will scan recursively.
+     */
+    searchDirectory: URL;
+    /**
+     * Suffix for notification files.
+     * @default '_notification.ts'
+     */
+    fileSuffix?: string;
+  };
+  /**
+   * The default preferences for the users.
+   */
+  preferences?: DefaultPreferences<KnownChannels>;
+  /**
+   * A callback that will be called to instantiate a notification class.
+   * Can be handy for using dependency injection or other custom instantiation logic.
+   * If not provided, the default constructor will be used.
+   */
+  notificationResolver?: NotificationResolver;
+}
+/**
+ * Resolver function type for notifications
+ */
+type NotificationResolver = (notification: new (ctx: MessageCtx<any, any>, ...args: any[]) => Notification, ctx: MessageCtx<any, any>) => Awaitable<Notification>;
+interface NotificationOptions<N extends Notifiable = Notifiable> {
+  /**
+   * A human readable name for the notification.
+   * Used for UI purpose
+   */
+  name: string;
+  /**
+   * A unique identifier for the notification.
+   * Used to identify the notification in the database and preferences.
+   *
+   * By default it is the class name
+   */
+  identifier?: string;
+  /**
+   * Bypass preferences and send the notification regardless of user settings.
+   * Useful for critical notifications that should always be sent.
+   */
+  critical?: boolean;
+  /**
+   * Human readable tags. Also used for UI purpose
+   */
+  tags?: string[];
+  /**
+   * Channel category
+   */
+  category?: string;
+  /**
+   * Channels to deliver the notification by.
+   */
+  deliverBy: Partial<Record<ChannelName, boolean | DeliverByOptions<N>>>;
+}
+interface DeliverByOptions<N extends Notifiable = Notifiable> {
+  if: (options: {
+    notifiable: N;
+    params?: any;
+    preferences?: Record<string, boolean | undefined>;
+  }) => boolean;
+}
+/**
+ * Parameters received by the `as*Message` methods of a notification.
+ */
+interface MessageCtx<N extends Notifiable | undefined = Notifiable, Params extends Record<string, any> = {}> {
+  notifiable: N;
+  params: Params;
+  tenantId?: Identifier | undefined;
+}
+/**
+ * Extract the parameters type from a notification class
+ */
+type ExtractParams<T> = T extends NotificationClass<any, infer P> ? P : never;
+/**
+ * Extract the notifiable type from a notification class
+ */
+type ExtractNotifiable<T> = T extends NotificationClass<infer N, any> ? N : never;
+/**
+ * Determine if a notification requires parameters or if they are optional
+ */
+type NotificationParams<TNotificationClass extends NotificationClass<any, any>> = ExtractParams<TNotificationClass> extends unknown ? unknown extends ExtractParams<TNotificationClass> ? {
+  params?: ExtractParams<TNotificationClass>;
+} : {
+  params: ExtractParams<TNotificationClass>;
+} : {
+  params: ExtractParams<TNotificationClass>;
+};
+/**
+ * Common options available for all send operations
+ */
+type CommonSendOptions<TNotificationClass extends NotificationClass<any, any>> = NotificationParams<TNotificationClass> & {
+  /**
+   * Throw an error if at least one channel fails to send
+   * If false, the result will contain the details of each channel send attempt
+   */
+  throwOnError?: boolean;
+};
+/**
+ * Helper type to determine if a notification is anonymous (notifiable is undefined)
+ */
+type IsAnonymousNotification<T> = T extends NotificationClass<infer N, any> ? (N extends undefined ? true : false) : false;
+/**
+ * Options for the `send` method
+ */
+type SendOptions<TNotificationClass extends NotificationClass<any, any>> = IsAnonymousNotification<TNotificationClass> extends true ? CommonSendOptions<TNotificationClass> & {
+  notification: TNotificationClass;
+  via: { [K in ChannelName]?: ProviderTarget<any, K> };
+  tenantId?: Identifier;
+} : CommonSendOptions<TNotificationClass> & {
+  notification: TNotificationClass;
+  notifiable: NonNullable<ExtractNotifiable<TNotificationClass>>;
+  via?: ChannelSpecificConfig<ExtractNotifiable<TNotificationClass>>;
+  tenantId?: Identifier;
+};
+type ChannelSpecificConfig<N extends Notifiable> = { [K in ChannelName]?: boolean | ProviderTarget<N, K> };
+type ExtractChannelTargets<T> = T extends Channel<any, any, any, infer U> ? U : never;
+type ProviderTarget<_N extends Notifiable, K extends ChannelName> = ExtractChannelTargets<NotificationChannels[K]>;
+//#endregion
+export { ChannelSpecificConfig, CommonSendOptions, DeliverByOptions, ExtractChannelTargets, ExtractNotifiable, ExtractParams, FacteurConfiguration, MessageCtx, NotificationOptions, NotificationParams, NotificationResolver, ProviderTarget, SendOptions };

package/dist/types/preferences.d.ts

@@ -0,0 +1,40 @@
+import { Channel } from "./channel.js";
+
+//#region src/types/preferences.d.ts
+type ChannelPreferences<KnownChannels extends Record<string, Channel>> = Record<keyof KnownChannels, boolean>;
+/**
+ * Shape for the `preferences` option in facteur configuration
+ */
+interface DefaultPreferences<KnownChannels extends Record<string, Channel>> {
+  /**
+   * If false, user preferences will not be taken into account before sending notifications.
+   */
+  enabled?: boolean;
+  /**
+   * Global preferences for all notifications.
+   */
+  global?: {
+    channels?: ChannelPreferences<KnownChannels>;
+  };
+  /**
+   * Per-category preferences.
+   * Use `Notification.options.category` to define category on a notification.
+   */
+  categories?: Record<string, {
+    channels?: Partial<ChannelPreferences<KnownChannels>>;
+  } | boolean>;
+}
+/**
+ * Shape for the resolved/processed `preferences` option in facteur configuration
+ */
+interface ResolvedDefaultPreferences<KnownChannels extends Record<string, Channel>> {
+  enabled: boolean;
+  global: {
+    channels: ChannelPreferences<KnownChannels>;
+  };
+  categories: Record<string, {
+    channels: ChannelPreferences<KnownChannels>;
+  }>;
+}
+//#endregion
+export { DefaultPreferences, ResolvedDefaultPreferences };

package/dist/types/queue.d.ts

@@ -0,0 +1,11 @@
+//#region src/types/queue.d.ts
+interface QueueItemOptions {
+  delay?: number;
+}
+interface QueueAdapter {
+  queue(message: any, options?: QueueItemOptions): Promise<void>;
+  startQueueProcessor(): void;
+  disconnect(): void;
+}
+//#endregion
+export { QueueAdapter, QueueItemOptions };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@facteurjs/core",
+  "type": "module",
+  "version": "1.0.0-beta.0",
+  "description": "Core package for facteur",
+  "author": "Julien Ripouteau <julien@ripouteau.com>",
+  "license": "ISC",
+  "keywords": [],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./api": "./dist/api/index.js",
+    "./api/types": "./dist/api/types.js",
+    "./channels/discord": "./dist/channels/discord/index.js",
+    "./channels/discord/types": "./dist/channels/discord/types.js",
+    "./channels/fcm": "./dist/channels/fcm/index.js",
+    "./channels/fcm/types": "./dist/channels/fcm/types.js",
+    "./channels/slack": "./dist/channels/slack/index.js",
+    "./channels/slack/types": "./dist/channels/slack/types.js",
+    "./channels/transmit": "./dist/channels/transmit/index.js",
+    "./channels/transmit/types": "./dist/channels/transmit/types.js",
+    "./channels/twilio": "./dist/channels/twilio/index.js",
+    "./channels/twilio/types": "./dist/channels/twilio/types.js",
+    "./channels/webhook": "./dist/channels/webhook/index.js",
+    "./channels/webhook/types": "./dist/channels/webhook/types.js",
+    "./channels/webpush": "./dist/channels/webpush/index.js",
+    "./channels/webpush/types": "./dist/channels/webpush/types.js",
+    "./database/adapters/knex": "./dist/database/adapters/knex.js",
+    "./database/adapters/kysely": "./dist/database/adapters/kysely.js",
+    "./database": "./dist/database/index.js",
+    "./database/types": "./dist/database/types.js",
+    "./types": "./dist/types/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@julr/utils": "1.9.0",
+    "@poppinss/exception": "^1.2.2",
+    "ky": "^1.8.2"
+  },
+  "devDependencies": {
+    "@boringnode/transmit": "^0.3.0",
+    "@types/web-push": "^3.6.4",
+    "firebase-admin": "^13.4.0",
+    "knex": "^3.1.0",
+    "kysely": "^0.28.3",
+    "p-event": "^6.0.1",
+    "twilio": "^5.8.0",
+    "web-push": "^3.6.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "stub": "tsdown",
+    "test": "tsx tests/index.ts",
+    "typecheck": "tsc --noEmit",
+    "quick:test": "tsx tests/index.ts"
+  }
+}