notifx/dist/index.d.ts

Pluggable notification dispatcher to send notifications to various channels.

import * as nodemailer_lib_smtp_pool from 'nodemailer/lib/smtp-pool';

type Dispatcher = (...arg: any[]) => any;
type Notification = {
    channel: string;
    args: any[];
};

/**
 * NotifX notification manager.
 *
 * Responsible for:
 * - Registering notification channels (e.g., email, SMS, Telegram)
 * - Registering named notifications using those channels
 * - Dispatching notifications dynamically with support for sync/async channels
 */
declare class Notifx {
    /**
     * Registered dispatch channels, indexed by name.
     * @private
     */
    _channels: {
        [key: string]: Dispatcher;
    };
    /**
     * Registered notifications, each mapped to a channel and its arguments.
     * @private
     */
    _notifications: {
        [key: string]: Notification;
    };
    /**
     * Registers a named dispatch channel.
     *
     * The dispatcher function must have a fixed signature, meaning:
     * - It must accept the same number and order of arguments as those provided when registering notifications for this channel.
     * - It must be a function that is either synchronous or asynchronous.
     *
     * @param {string} name - Unique name for the channel.
     * @param {Dispatcher} dispatcher - The dispatcher function to call when sending.
     * @throws {TypeError} If the name is not a string or dispatcher is not a function.
     */
    registerChannel(name: string, dispatcher: Dispatcher): void;
    /**
     * Registers a named notification to be sent through a channel.
     *
     * The arguments must match the expected signature of the channel's dispatcher function.
     *
     * @param {string} notificationName - Unique name for this notification.
     * @param {string} channelName - Name of the registered channel to use.
     * @param {...any[]} args - Arguments that will be passed to the dispatcher when the notification is sent.
     * @throws {TypeError} If names are not strings.
     * @throws {Error} If the channel is not registered.
     */
    registerNotification(notificationName: string, channelName: string, args: any[]): void;
    /**
     * Sends a previously registered notification via its associated channel by invoking the channel's dispatcher function.
     *
     * The dispatcher will be called with the same arguments provided when registering the notification,
     * unless additional arguments are provided at send-time.
     *
     * @param {string} notificationName - Name of the registered notification.
     * @param {...any[]} args - Optional override of arguments to pass to the dispatcher.
     * @returns {Promise<any>} The return value from the dispatcher function.
     * @throws {Error} If notification or channel is missing, or argument count mismatches.
     */
    send(notificationName: string, ...args: any[]): Promise<any>;
}
declare const notifx: Notifx;

/**
 * Email plugin.
 */
declare const emailPlugin: {
    /**
     * Creates an email sender function that can be used as a notifx channel dispatcher.
     *
     * @param {object} mailerOptions - Nodemailer transport configuration (SMTP options).
     * @returns {Function} An async function that sends an email using provided parameters.
     *
     * @example
     * const send = emailPlugin.sendEmail(smtpConfig);
     * await send("template.html", "from@example.com", "to@example.com", "Hello {{username}}", {
     *   body: { username: "jonhdoe" },
     *   title: { username: "jonhdoe" },
     * });
     */
    sendEmail: (mailerOptions: any) => (body: string, from: string, to: string, title: string, replacements: {
        body: Record<string, any>;
        title: Record<string, any>;
    }, attachments?: any[]) => Promise<nodemailer_lib_smtp_pool.SentMessageInfo>;
};

/**
 * Telegram plugin for sending messages using the Telegram Bot API.
 */
declare const telegramPlugin: {
    /**
     * Creates a Telegram message sender function that can be used as a notifx channel dispatcher.
     *
     * @param {string} botToken - The Telegram bot token.
     * @returns {Function} An async function that sends a message via Telegram.
     *
     * @example
     * const send = telegramPlugin.sendTelegramMessage(botToken);
     * await send("123456789", "Hello <b>{{username}}</b>!", {
     *   message: { username: "jonhdoe" }
     * });
     */
    sendTelegramMessage: (botToken: string) => (chatId: string, message: string, replacements: {
        message: Record<string, any>;
    }) => Promise<any>;
};

export { notifx as default, emailPlugin, telegramPlugin };