@stone-js/notifications 0.8.17

package/dist/Notifier.d.ts

@@ -0,0 +1,260 @@
+import { IBlueprint, IContainer } from '@stone-js/core';
+import { DeliveryOutcome, NotificationReceipt, NotifyOptions, Recipient, RecipientInput, RenderedNotification } from './declarations.js';
+/** The shape this module needs from a queue, duck-typed so `@stone-js/queue` is never imported. */
+export interface QueueLike {
+    dispatch: <T>(name: string, payload: T, options?: Record<string, unknown>) => Promise<string>;
+    later?: <T>(delay: number, name: string, payload: T, options?: Record<string, unknown>) => Promise<string>;
+}
+/** The shape this module needs from a cache store, for deduplication only. */
+export interface CacheLike {
+    add: <T>(key: string, value: T, options?: Record<string, unknown>) => Promise<boolean>;
+}
+/** The shape this module needs from a cache manager, to reach a named store. */
+export interface CacheManagerLike {
+    store: (name?: string) => CacheLike;
+}
+/** The shape this module needs from an event bus, to announce what it delivered. */
+export interface EventBusLike {
+    emit: <T>(name: string, payload?: T, options?: Record<string, unknown>) => Promise<void>;
+}
+/** What a queued delivery carries. Resolved and rendered already: a worker guesses nothing. */
+export interface DeliveryPayload {
+    recipient: Recipient;
+    template: string;
+    params: Record<string, unknown>;
+    locale: string;
+    channels: string[];
+    /** The notice that produced it, when one did, so the worker asks the same class for the content. */
+    notice?: string;
+}
+/**
+ * What an application calls to reach someone.
+ *
+ * The one sentence that shapes everything here: **decide now, deliver later.** A request resolves who
+ * the person is, renders the message in their language, and hands the delivery to a queue. Reaching a
+ * mail provider takes as long as it takes, and a request that waits for one is a request that times
+ * out on a function-as-a-service platform, from the endpoint the user is watching.
+ *
+ * It also never throws at its caller. A notification is almost always a side effect of something that
+ * already succeeded: an account was created, a guardian was invited. Failing that operation because a
+ * mail provider was down would undo work that was correct. Every failure comes back as an outcome and
+ * goes to the log.
+ */
+export declare class Notifier {
+    private readonly blueprint;
+    private readonly container?;
+    /**
+     * @param dependencies - Auto-wired services.
+     */
+    constructor({ blueprint, container }: {
+        blueprint: IBlueprint;
+        container?: IContainer;
+    });
+    /**
+     * Tell someone something.
+     *
+     * @param to - Who to tell: a recipient, an id, or several of either.
+     * @param template - The template key. Never a rendered body: what is not copied does not have to
+     *                   be erased, and a key survives a translation being fixed.
+     * @param params - What the template needs.
+     * @param options - Which channels, which language, whether to wait.
+     * @returns What happened, or that it was queued.
+     */
+    notify(to: RecipientInput | RecipientInput[], template: string, params?: Record<string, unknown>, options?: NotifyOptions): Promise<NotificationReceipt>;
+    /**
+     * Deliver what a notice says about a domain event.
+     *
+     * The entry the event subscription calls, and the reason this module is not a service somebody has
+     * to remember to call: a module emits what happened, and the notice that named that event decides
+     * who learns about it. The emitting module knows nothing about any of this.
+     *
+     * @param name - The notice's name.
+     * @param event - The domain event, as the bus delivered it.
+     * @returns What happened, or that it was queued.
+     */
+    deliverNotice(name: string, event: unknown): Promise<NotificationReceipt>;
+    /**
+     * What a notice would send, without sending it.
+     *
+     * For a screen that shows a member of staff what a guardian is about to receive, and for a test
+     * that checks a notice without a channel. It renders exactly what delivery would render, per
+     * channel, which is what makes it worth having rather than approximating.
+     *
+     * @param to - Who it would be for.
+     * @param template - The notice or template name.
+     * @param params - What it needs.
+     * @param options - Which channels, which language.
+     * @returns One rendered message per recipient and channel.
+     */
+    preview(to: RecipientInput | RecipientInput[], template: string, params?: Record<string, unknown>, options?: NotifyOptions): Promise<Array<{
+        recipient: Recipient;
+        channel: string;
+        message: RenderedNotification;
+    }>>;
+    /**
+     * Perform one delivery, to one person, on every channel it names.
+     *
+     * Called here when nothing is queued, and by the queue job when something is. Same code either way,
+     * which is what makes a retry mean exactly what the first attempt meant.
+     *
+     * @param payload - Who, what, where, in which language.
+     * @returns What each channel answered.
+     */
+    deliver(payload: DeliveryPayload): Promise<DeliveryOutcome[]>;
+    /**
+     * What the notice says, for this person, or nothing when there is no notice.
+     *
+     * Failing here must not fail the delivery: a notice is application code, and application code
+     * throws. The message then falls back to the template path, which at worst renders the key, and
+     * the failure is named rather than swallowed.
+     *
+     * @param declaration - The notice, when one is declared.
+     * @param params - The event or params it is given.
+     * @param context - Who it is for, and in which language.
+     * @returns The content, or nothing.
+     */
+    private contentFrom;
+    /**
+     * The message one channel receives.
+     *
+     * A notice's content wins, per channel, because that is the whole reason it returns a map: a text
+     * message is not an email, one having a subject and room to explain and the other a hundred and
+     * sixty characters. Failing that, the template path renders it.
+     *
+     * @param channel - The channel about to send.
+     * @param template - The notice or template name.
+     * @param params - What it was given.
+     * @param locale - The recipient's language.
+     * @param content - What the notice said, if anything.
+     * @returns The rendered message.
+     */
+    private messageFor;
+    /**
+     * The content for one channel, out of what a notice returned.
+     *
+     * Three shapes, all useful: a map keyed by channel, one content for every channel, or a bare
+     * string. A map that names no content for this channel falls through to the template path rather
+     * than sending an empty body.
+     *
+     * @param channel - The channel about to send.
+     * @param content - What the notice said.
+     * @returns The content, or nothing.
+     */
+    private contentFor;
+    /**
+     * One channel, one message, and an answer whatever happens.
+     *
+     * A channel that throws is treated as **retryable**, because a throw is an adapter bug rather than
+     * a verdict, and burying a channel's whole traffic the day a provider client changes its error
+     * shapes would be worse than one retry too many.
+     *
+     * @param manager - The channel registry.
+     * @param name - The channel to use.
+     * @param message - The rendered notification.
+     * @param recipient - Who it is for.
+     * @returns The outcome, always.
+     */
+    private sendOn;
+    /**
+     * Hand one delivery to the queue.
+     *
+     * Rendered arguments are **not** carried: the payload holds the key and the params, so a message
+     * queued before a translation was fixed goes out fixed, and a queue dump holds no message bodies.
+     *
+     * @param queue - The queue.
+     * @param recipient - Who it is for.
+     * @param template - The template key.
+     * @param params - What it needs.
+     * @param channels - Where to send it.
+     * @param options - What the caller asked for.
+     */
+    private enqueue;
+    /**
+     * Everyone this notification is for, as people rather than ids.
+     *
+     * An id is resolved through the application's own directory, so the address is read at send time.
+     * One that resolves to nobody is dropped with a warning: sending to an id nobody recognises is not
+     * something to guess at.
+     *
+     * @param inputs - The recipients, or their ids.
+     * @returns The recipients that could be resolved.
+     */
+    private resolveAll;
+    /**
+     * The language to write in.
+     *
+     * The recipient's own, first and almost always. An explicit override exists because a few messages
+     * are genuinely about the sender's context, and it is rarely the right answer.
+     *
+     * @param recipient - Who it is for.
+     * @param options - What the caller asked for.
+     * @returns The locale.
+     */
+    private localeFor;
+    /**
+     * The queue to dispatch on, or nothing when this delivery happens here.
+     *
+     * @param options - What the caller asked for.
+     * @returns The queue, or nothing.
+     */
+    private queue;
+    /**
+     * Say once that nothing is being delivered.
+     *
+     * The zero-config default writes to the log and reaches nobody. That is the right default, and a
+     * module that delivered nothing while looking like one that delivers is the failure this warning
+     * exists to prevent.
+     *
+     * @param channels - The channels in use.
+     */
+    private warnOnceAboutTheDefault;
+    /** Whether the default has already been reported, for this notifier. */
+    private warned;
+    /**
+     * Whether this exact occurrence has already gone out.
+     *
+     * The answer to the most common production failure of any notification system: the same message
+     * twice, because a queue is at-least-once, because a retry half succeeded, or because two events
+     * describe one fact. Keys live in `@stone-js/cache`, so the store is the one the application
+     * already chose and this module stores nothing of its own.
+     *
+     * `add` is the atomic set-if-absent every store implements, which is what makes this a claim rather
+     * than a read followed by a hopeful write.
+     *
+     * @param template - The notice or template name, so two notices cannot collide on one key.
+     * @param key - What makes this occurrence unique, when anything does.
+     * @returns True when it was already sent.
+     */
+    private alreadySent;
+    /**
+     * Announce one delivery on the event bus.
+     *
+     * How an application keeps a delivery ledger without this module owning one. "Why did they never
+     * receive it" is the question a notification system exists to answer, and the answer belongs in
+     * whatever the application already queries: it listens, and writes what it needs.
+     *
+     * @param outcome - What the channel answered.
+     * @param payload - What was being delivered.
+     */
+    private announce;
+    /** Say something once per notifier, so a standing condition is stated rather than repeated. */
+    private warnOnce;
+    /** What has already been said. */
+    private readonly said;
+    /** The notice registry, built for this event like everything else. */
+    private notices;
+    /** The registry, once. */
+    private registry?;
+    /** The cache store deduplication is remembered in, when one is bound. */
+    private cache;
+    /** The event bus, when one is bound. */
+    private bus;
+    /** The `stone.notifications` bucket. */
+    private options;
+    /** The channel registry, from the container when there is one. */
+    private manager;
+    /** The translation catalogue, when one is bound. */
+    private translator;
+    /** The logger, when one is bound. */
+    private logger;
+}

package/dist/channels/InAppChannel.d.ts

@@ -0,0 +1,43 @@
+import { DeliveryOutcome, InAppChannelConfig, NotificationChannel, Recipient, RenderedNotification } from '../declarations.js';
+/** The shape this channel needs from a broadcaster, duck-typed so no realtime import is required. */
+export interface BroadcasterLike {
+    to: (channel: string) => {
+        emit: <T>(event: string, payload?: T) => Promise<void>;
+    };
+}
+/**
+ * The channel that reaches the tab someone already has open.
+ *
+ * This is the half that makes a notification module worth having in this framework rather than a mail
+ * client wrapped in a service: **one `notify()` reaches the mailbox, the phone and the open screen**,
+ * and the application wires none of the three together.
+ *
+ * It broadcasts through `@stone-js/realtime`, duck-typed from the container, so this package neither
+ * imports it nor requires it. The client side is already written: whoever is subscribed to the
+ * recipient's channel receives a `notification` event, with the same rendered message every other
+ * channel got.
+ *
+ * It reports `unreachable` rather than `failed` when nobody is listening, because that is not an
+ * error: a person who is not looking at the screen is exactly why the other channels exist.
+ */
+export declare class InAppChannel implements NotificationChannel {
+    readonly name: string;
+    private readonly event;
+    private readonly broadcaster?;
+    private readonly channelFor;
+    /**
+     * @param config - Names the channel, and how to address a recipient.
+     * @param broadcaster - The realtime broadcaster, when one is bound.
+     * @returns A channel.
+     */
+    static create(config?: InAppChannelConfig, broadcaster?: BroadcasterLike): InAppChannel;
+    constructor(config?: InAppChannelConfig, broadcaster?: BroadcasterLike);
+    /**
+     * Broadcast the message on the recipient's own channel.
+     *
+     * @param message - The rendered notification.
+     * @param recipient - Who it is for.
+     * @returns How it ended.
+     */
+    send(message: RenderedNotification, recipient: Recipient): Promise<DeliveryOutcome>;
+}

package/dist/channels/LogChannel.d.ts

@@ -0,0 +1,43 @@
+import { ILogger } from '@stone-js/core';
+import { ChannelConfig, DeliveryOutcome, NotificationChannel, Recipient, RenderedNotification } from '../declarations.js';
+/**
+ * The channel that delivers nothing, and is honest about it.
+ *
+ * The zero-config default, so an application can call `notify()` on its first day and watch what it
+ * would have sent. It is the right choice in development and in a test, and **it is not a channel**
+ * anywhere else: nobody receives anything.
+ *
+ * It exists rather than defaulting to a real one because a default that quietly sent real mail would
+ * send it from the first test run, to real people. The notifier says once, in a warning, that this is
+ * what is configured, for the same reason: a module that delivers nothing must not look like one that
+ * delivers.
+ */
+export declare class LogChannel implements NotificationChannel {
+    readonly name: string;
+    private readonly logger?;
+    /**
+     * @param config - Names the channel.
+     * @param logger - Where the message goes, when one is bound.
+     * @returns A channel.
+     */
+    static create(config?: ChannelConfig, logger?: ILogger): LogChannel;
+    constructor(name?: string, logger?: ILogger);
+    /**
+     * Write the message where the application writes everything else.
+     *
+     * @param message - The rendered notification.
+     * @param recipient - Who it was for.
+     * @returns Sent, because writing it down is all this channel promises.
+     */
+    send(message: RenderedNotification, recipient: Recipient): Promise<DeliveryOutcome>;
+    /**
+     * Who it was for, named without spelling out an address.
+     *
+     * A log line is read by more people than a database row, so it carries enough to follow a message
+     * and not enough to leak one.
+     *
+     * @param recipient - Who it was for.
+     * @returns Something to call them in a log.
+     */
+    private addresseeOf;
+}

package/dist/channels/SmtpChannel.d.ts

@@ -0,0 +1,46 @@
+import { DeliveryOutcome, NotificationChannel, Recipient, RenderedNotification, SmtpChannelConfig } from '../declarations.js';
+/**
+ * Email, over SMTP.
+ *
+ * SMTP rather than a provider's API, deliberately: every provider speaks it, so shipping this one
+ * channel reaches all of them without this package choosing a vendor for you. A provider with an API
+ * you prefer is a `factory` away.
+ *
+ * `nodemailer` is an optional peer, imported lazily, so an application that sends no mail carries no
+ * mail dependency. The transport is built once per channel instance and the instance is rebuilt with
+ * the container: a transport is a **resource**, not state, and nodemailer pools its own connections,
+ * so an application under load should pass a transport it owns.
+ */
+export declare class SmtpChannel implements NotificationChannel {
+    readonly name: string;
+    private readonly config;
+    private transportPromise?;
+    /**
+     * @param config - The channel's configuration.
+     * @returns A channel.
+     */
+    static create(config: SmtpChannelConfig): SmtpChannel;
+    constructor(config: SmtpChannelConfig);
+    /**
+     * Send the message as mail.
+     *
+     * @param message - The rendered notification.
+     * @param recipient - Who it is for.
+     * @returns How it ended.
+     */
+    send(message: RenderedNotification, recipient: Recipient): Promise<DeliveryOutcome>;
+    /** The transport, built once for this instance. */
+    private transport;
+    /** Build the transport from what was configured, or say what is missing. */
+    private build;
+    /**
+     * Load `nodemailer`, an optional peer, and say plainly when it is not there.
+     *
+     * A missing package is a setup mistake, never a delivery failure: answering "could not send" would
+     * put it in the retry queue forever, and the retry would fail identically every time.
+     *
+     * @returns The nodemailer module.
+     * @throws {NotificationConfigurationError} When the package is absent.
+     */
+    private loadNodemailer;
+}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+/** The queue job that performs a delivery. */
+export declare const DELIVERY_JOB: string;
+/** The channel used when nothing is configured. It delivers nothing, and says so. */
+export declare const DEFAULT_CHANNEL: string;
+/** The event an in-app client listens for. */
+export declare const IN_APP_EVENT: string;