@stone-js/notifications 0.8.17

package/dist/index.js

@@ -0,0 +1,1481 @@
+import { IntegrationError, classDecoratorLegacyWrapper, setMetadata, SERVICE_KEY, addBlueprint } from '@stone-js/core';
+import { cloneValue } from '@stone-js/config';
+
+/**
+ * Raised for a setup mistake, so a misconfigured application never looks like a failed delivery.
+ *
+ * The distinction earns its place here: a failed delivery is retried, and a channel that answered
+ * "provider unavailable" to "no channel named that" would be retried forever, on work that cannot
+ * succeed.
+ */
+class NotificationConfigurationError extends IntegrationError {
+    constructor(message, options = {}) {
+        super(message, { code: 'NOTIFICATION_CONFIGURATION_ERROR', ...options });
+        this.name = 'NotificationConfigurationError';
+    }
+}
+
+/**
+ * Finds the notice a name or an event refers to, and builds it.
+ *
+ * Built for one event, like everything else in the container: it is a lookup over what the blueprint
+ * declared, and holds nothing between events. A notice class is built through the container, so it
+ * gets its services, and it is the container that decides whether that instance is shared.
+ */
+class NoticeRegistry {
+    blueprint;
+    container;
+    /**
+     * @param dependencies - Auto-wired services.
+     */
+    constructor({ blueprint, container }) {
+        this.blueprint = blueprint;
+        this.container = container;
+    }
+    /** Every notice this application declared, from `@Notice` and from configuration alike. */
+    all() {
+        return this.blueprint.get('stone.notifications', {}).notices ?? [];
+    }
+    /**
+     * What was declared under this name.
+     *
+     * @param name - The notice's name.
+     * @returns The declaration, or nothing.
+     */
+    declaration(name) {
+        return this.all().find((notice) => notice.name === name);
+    }
+    /**
+     * What reacts to this event.
+     *
+     * @param event - The domain event's name.
+     * @returns The declaration, or nothing.
+     */
+    forEvent(event) {
+        return this.all().find((notice) => notice.on === event);
+    }
+    /**
+     * The notice itself, built.
+     *
+     * @param declaration - What was declared.
+     * @returns The notice.
+     * @throws {NotificationConfigurationError} When it cannot be built, or does not answer `notify`.
+     */
+    build(declaration) {
+        const module = declaration.module;
+        if (module === undefined) {
+            throw new NotificationConfigurationError(`The notice '${declaration.name}' declares no module, so there is nothing to say. Declare a ` +
+                'class with `@Notice`, or pass one to `defineNotice`.');
+        }
+        const built = declaration.isClass === false || typeof module !== 'function'
+            ? module
+            : this.container?.resolve?.(module, true);
+        if (built === undefined || typeof built.notify !== 'function') {
+            throw new NotificationConfigurationError(`The notice '${declaration.name}' does not answer \`notify(event, context)\`. A notice is a ` +
+                'class that says what it says: the decorator carries the metadata, the class carries the ' +
+                'content.');
+        }
+        return built;
+    }
+}
+
+/**
+ * Holds the configured channels and hands one out by name.
+ *
+ * The same shape every driver-based module in the framework uses, and the same lifetime: built for
+ * one event, like the container it belongs to. It is a registry of factories, so rebuilding it costs
+ * nothing. Nothing here holds state between events; a channel that needs a connection holds it
+ * itself, because a connection is a resource and the channel is the boundary that owns it.
+ */
+class NotificationManager {
+    static current;
+    channels = new Map();
+    factories = new Map();
+    /**
+     * @returns A manager.
+     */
+    static create() {
+        return new this();
+    }
+    /** Publish the manager, so code outside the container can reach it. */
+    static setInstance(manager) {
+        NotificationManager.current = manager;
+    }
+    /** The published manager, if there is one. */
+    static getInstance() {
+        return NotificationManager.current;
+    }
+    /**
+     * Register a built channel.
+     *
+     * @param channel - The channel.
+     * @returns This manager.
+     */
+    register(channel) {
+        this.channels.set(channel.name, channel);
+        return this;
+    }
+    /**
+     * Register a channel to be built on first use.
+     *
+     * @param name - The name notifications refer to it by.
+     * @param factory - How to build it.
+     * @returns This manager.
+     */
+    registerFactory(name, factory) {
+        this.factories.set(name, factory);
+        return this;
+    }
+    /** Whether a channel is registered under this name. */
+    has(name) {
+        return this.channels.has(name) || this.factories.has(name);
+    }
+    /** The names of every registered channel. */
+    names() {
+        return [...new Set([...this.channels.keys(), ...this.factories.keys()])];
+    }
+    /**
+     * The channel a notification named.
+     *
+     * @param name - The channel's name.
+     * @returns The channel.
+     * @throws {NotificationConfigurationError} When nothing is registered under that name.
+     */
+    channel(name) {
+        const built = this.channels.get(name);
+        if (built !== undefined) {
+            return built;
+        }
+        const factory = this.factories.get(name);
+        if (factory === undefined) {
+            throw new NotificationConfigurationError(`No notification channel is registered as '${name}'. Configure it under ` +
+                '`stone.notifications.channels`, or register your own with ' +
+                '`channels: [{ name, factory }]`. Ships with \'log\', \'in-app\' and \'smtp\'.');
+        }
+        const channel = factory();
+        this.channels.set(name, channel);
+        return channel;
+    }
+}
+
+/**
+ * A template key and its params, become text in the recipient's language.
+ *
+ * **The locale is the recipient's, never the request's.** A French-speaking guardian invited by an
+ * English-speaking member of staff reads French. Getting that backwards is invisible in every test
+ * written by one person in one language, and obvious to the person who receives it.
+ *
+ * Three sources, in order: a template the application declared outright, the translation catalogue,
+ * and failing both the key itself.
+ *
+ * That last fallback is the point. A missing translation renders its **key**, never an empty string:
+ * an empty subject looks like a broken mail client and gets ignored for months, while
+ * `guardianship.consent_needed` is visibly ours and gets reported the same day.
+ *
+ * @param context - What to render, and what to render it from.
+ * @returns The rendered notification.
+ */
+function render(context) {
+    const { template, params, locale } = context;
+    const declared = context.templates?.[template];
+    if (declared !== undefined) {
+        const { subject, body } = fromDeclared(declared, params, locale);
+        return { template, params, locale, subject: subject ?? template, body };
+    }
+    const translated = context.translator === undefined
+        ? undefined
+        : fromCatalogue(context.translator, template, params, locale);
+    return {
+        template,
+        params,
+        locale,
+        subject: translated?.subject ?? template,
+        body: translated?.body ?? template
+    };
+}
+/**
+ * What the application declared for this key.
+ *
+ * @param declared - The template.
+ * @param params - What to render it with.
+ * @param locale - The recipient's language.
+ * @returns The subject and the body.
+ */
+function fromDeclared(declared, params, locale) {
+    if (typeof declared === 'function') {
+        return declared(params, locale);
+    }
+    if (typeof declared === 'string') {
+        return { body: interpolate(declared, params) };
+    }
+    return {
+        subject: declared.subject === undefined ? undefined : interpolate(declared.subject, params),
+        body: interpolate(declared.body, params)
+    };
+}
+/**
+ * What the catalogue holds for this key, under `<key>.subject` and `<key>.body`.
+ *
+ * Two keys rather than one, because a subject and a body are translated separately by whoever
+ * translates them, and a channel with no subject simply ignores it.
+ *
+ * @param translator - The catalogue.
+ * @param template - The key.
+ * @param params - What to render it with.
+ * @param locale - The recipient's language.
+ * @returns The subject and the body, or nothing when the catalogue has neither.
+ */
+function fromCatalogue(translator, template, params, locale) {
+    const subjectKey = `${template}.subject`;
+    const bodyKey = `${template}.body`;
+    const subject = translator.t(subjectKey, { ...params, lng: locale });
+    const body = translator.t(bodyKey, { ...params, lng: locale });
+    // A catalogue that cannot find a key answers the key, which is exactly the signal wanted here:
+    // nothing was translated, so say nothing rather than repeating a key twice.
+    const found = subject !== subjectKey || body !== bodyKey;
+    return found
+        ? { subject: subject === subjectKey ? undefined : subject, body: body === bodyKey ? undefined : body }
+        : undefined;
+}
+/**
+ * Fill `{{ name }}` from the params.
+ *
+ * The smallest thing that works for a declared template, and not a template engine: an application
+ * that wants one renders it itself, through the function form.
+ *
+ * @param text - The template text.
+ * @param params - What to fill it from.
+ * @returns The filled text.
+ */
+function interpolate(text, params) {
+    return text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (match, name) => {
+        return primitive(params[name]) ?? match;
+    });
+}
+/**
+ * A parameter as text, or nothing when it is not something a message can carry.
+ *
+ * An object or an array would stringify to `[object Object]` in the middle of a sentence somebody
+ * reads. Leaving the placeholder is better: it is visibly unfinished, and it gets reported.
+ *
+ * @param value - The parameter.
+ * @returns Its text, or nothing.
+ */
+function primitive(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'object') {
+        return undefined;
+    }
+    return String(value);
+}
+
+/** The queue job that performs a delivery. */
+const DELIVERY_JOB = 'stone-js/notifications:deliver';
+/** The channel used when nothing is configured. It delivers nothing, and says so. */
+const DEFAULT_CHANNEL = 'log';
+/** The event an in-app client listens for. */
+const IN_APP_EVENT = 'notification';
+
+/**
+ * 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.
+ */
+class Notifier {
+    blueprint;
+    container;
+    /**
+     * @param dependencies - Auto-wired services.
+     */
+    constructor({ blueprint, container }) {
+        this.blueprint = blueprint;
+        this.container = container;
+    }
+    /**
+     * 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.
+     */
+    async notify(to, template, params = {}, options = {}) {
+        if (await this.alreadySent(template, options.dedupe)) {
+            return { queued: false, duplicate: true, deliveries: [] };
+        }
+        const declaration = this.notices().declaration(template);
+        const recipients = await this.resolveAll([to].flat());
+        const channels = options.channels ?? declaration?.channels ?? this.options().default ?? [DEFAULT_CHANNEL];
+        this.warnOnceAboutTheDefault(channels);
+        const queue = this.queue(options);
+        if (queue !== undefined) {
+            await Promise.all(recipients.map(async (recipient) => {
+                await this.enqueue(queue, recipient, template, params, channels, options, declaration);
+            }));
+            return { queued: true, deliveries: [] };
+        }
+        const deliveries = [];
+        for (const recipient of recipients) {
+            deliveries.push(...await this.deliver({
+                recipient,
+                template,
+                params,
+                channels,
+                notice: declaration?.name,
+                locale: this.localeFor(recipient, options)
+            }));
+        }
+        return { queued: false, deliveries };
+    }
+    /**
+     * 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.
+     */
+    async deliverNotice(name, event) {
+        const declaration = this.notices().declaration(name);
+        if (declaration === undefined) {
+            // Subscribed and then removed, or renamed: worth saying, because nothing else will fail.
+            this.logger()?.warn(`[@stone-js/notifications] no notice is declared as '${name}'`);
+            return { queued: false, deliveries: [] };
+        }
+        const notice = this.notices().build(declaration);
+        if (notice.recipients === undefined) {
+            // The one thing a notice reacting to an event must answer: the event carries the account, and
+            // only the notice knows which field that is. Without it there is nobody to tell.
+            this.logger()?.error?.(`[@stone-js/notifications] the notice '${name}' reacts to an event and does not answer ` +
+                '`recipients(event)`, so nobody can be told. Add it, or drop `on` and call the notifier.');
+            return { queued: false, deliveries: [] };
+        }
+        const dedupe = notice.dedupe === undefined ? undefined : await notice.dedupe(event);
+        return await this.notify(await notice.recipients(event), name, (event ?? {}), dedupe === undefined ? {} : { dedupe });
+    }
+    /**
+     * 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.
+     */
+    async preview(to, template, params = {}, options = {}) {
+        const declaration = this.notices().declaration(template);
+        const recipients = await this.resolveAll([to].flat());
+        const channels = options.channels ?? declaration?.channels ?? this.options().default ?? [DEFAULT_CHANNEL];
+        const previewed = [];
+        for (const recipient of recipients) {
+            const locale = this.localeFor(recipient, options);
+            const content = await this.contentFrom(declaration, params, { locale, recipient });
+            for (const channel of channels) {
+                previewed.push({ recipient, channel, message: this.messageFor(channel, template, params, locale, content) });
+            }
+        }
+        return previewed;
+    }
+    /**
+     * 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.
+     */
+    async deliver(payload) {
+        const manager = this.manager();
+        const declaration = payload.notice === undefined ? undefined : this.notices().declaration(payload.notice);
+        // Asked once per recipient, never once per channel: a name in the body is rendered once, and the
+        // channel-specific body is chosen from what it answered.
+        const content = await this.contentFrom(declaration, payload.params, {
+            locale: payload.locale,
+            recipient: payload.recipient
+        });
+        const outcomes = [];
+        for (const name of payload.channels) {
+            const message = this.messageFor(name, payload.template, payload.params, payload.locale, content);
+            const outcome = await this.sendOn(manager, name, message, payload.recipient);
+            outcomes.push(outcome);
+            await this.announce(outcome, payload);
+        }
+        return outcomes;
+    }
+    /**
+     * 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.
+     */
+    async contentFrom(declaration, params, context) {
+        if (declaration === undefined) {
+            return undefined;
+        }
+        try {
+            return await this.notices().build(declaration).notify(params, context);
+        }
+        catch (error) {
+            this.logger()?.error?.(`[@stone-js/notifications] the notice '${declaration.name}' threw`, {
+                reason: error?.message
+            });
+            return undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    messageFor(channel, template, params, locale, content) {
+        const chosen = this.contentFor(channel, content);
+        if (chosen !== undefined) {
+            return { template, params, locale, subject: chosen.subject ?? template, body: chosen.body };
+        }
+        return render({
+            template,
+            params,
+            locale,
+            templates: this.options().templates,
+            translator: this.translator()
+        });
+    }
+    /**
+     * 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.
+     */
+    contentFor(channel, content) {
+        if (content === undefined) {
+            return undefined;
+        }
+        if (typeof content === 'string') {
+            return { body: content };
+        }
+        if (typeof content.body === 'string') {
+            return content;
+        }
+        const forChannel = content[channel];
+        if (forChannel === undefined) {
+            return undefined;
+        }
+        return typeof forChannel === 'string' ? { body: forChannel } : forChannel;
+    }
+    /**
+     * 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.
+     */
+    async sendOn(manager, name, message, recipient) {
+        try {
+            const outcome = await manager.channel(name).send(message, recipient);
+            if (outcome.status !== 'sent') {
+                this.logger()?.warn(`[@stone-js/notifications] ${message.template} not delivered on '${name}'`, {
+                    status: outcome.status,
+                    retryable: outcome.retryable,
+                    reason: outcome.reason
+                });
+            }
+            return { ...outcome, channel: name };
+        }
+        catch (error) {
+            // A setup mistake will fail identically on every attempt, so it is reported as permanent. Every
+            // other throw is an adapter bug rather than a verdict, and is worth one more try: burying a
+            // channel's whole traffic the day a provider client changes its error shapes would be worse.
+            const configuration = error instanceof NotificationConfigurationError;
+            this.logger()?.error?.(`[@stone-js/notifications] the '${name}' channel threw`, {
+                template: message.template,
+                configuration,
+                reason: error?.message
+            });
+            return {
+                status: 'failed',
+                retryable: !configuration,
+                reason: String(error?.message ?? 'The channel threw.'),
+                channel: name
+            };
+        }
+    }
+    /**
+     * 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.
+     */
+    async enqueue(queue, recipient, template, params, channels, options, declaration) {
+        const payload = {
+            recipient,
+            template,
+            params,
+            channels,
+            notice: declaration?.name,
+            locale: this.localeFor(recipient, options)
+        };
+        const settings = this.options();
+        const jobOptions = {
+            ...(settings.queue !== undefined ? { queue: settings.queue } : {}),
+            ...(settings.attempts !== undefined ? { attempts: settings.attempts } : {})
+        };
+        try {
+            // A delayed delivery is the queue's own capability, so it is asked rather than reimplemented:
+            // a timer held in a process that a cold start can end is not a reminder.
+            if (options.delay !== undefined && queue.later !== undefined) {
+                await queue.later(options.delay, DELIVERY_JOB, payload, jobOptions);
+            }
+            else {
+                if (options.delay !== undefined) {
+                    this.logger()?.warn('[@stone-js/notifications] a delay was asked for and this queue cannot defer, so the ' +
+                        'notification goes out now.', { template, delay: options.delay });
+                }
+                await queue.dispatch(DELIVERY_JOB, payload, jobOptions);
+            }
+        }
+        catch (error) {
+            // A queue that cannot take the work must not take down the operation that caused it. It is
+            // logged rather than raised, and loudly, because a notification nobody queued is one nobody
+            // will ever see fail.
+            this.logger()?.error?.('[@stone-js/notifications] a delivery could not be queued', {
+                template,
+                reason: error?.message
+            });
+        }
+    }
+    /**
+     * 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.
+     */
+    async resolveAll(inputs) {
+        const resolver = this.options().recipients;
+        const resolved = [];
+        for (const input of inputs) {
+            if (typeof input !== 'string') {
+                resolved.push(input);
+                continue;
+            }
+            if (resolver === undefined) {
+                this.logger()?.warn('[@stone-js/notifications] a notification named a recipient by id, and nothing can turn an ' +
+                    'id into a person. Set `stone.notifications.recipients`, or pass the recipient itself.', { id: input });
+                continue;
+            }
+            const recipient = await resolver(input);
+            if (recipient === undefined) {
+                this.logger()?.warn('[@stone-js/notifications] a recipient could not be resolved', { id: input });
+                continue;
+            }
+            resolved.push(recipient);
+        }
+        return resolved;
+    }
+    /**
+     * 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.
+     */
+    localeFor(recipient, options) {
+        return options.locale ??
+            recipient.locale ??
+            this.blueprint.get('stone.i18n.locale', 'en');
+    }
+    /**
+     * The queue to dispatch on, or nothing when this delivery happens here.
+     *
+     * @param options - What the caller asked for.
+     * @returns The queue, or nothing.
+     */
+    queue(options) {
+        if (options.inline === true) {
+            return undefined;
+        }
+        const configured = this.options().dispatch;
+        const queue = this.container?.has?.('queue') === true
+            ? this.container.make('queue')
+            : undefined;
+        if (configured === 'inline') {
+            return undefined;
+        }
+        if (queue?.dispatch === undefined) {
+            if (configured === 'queue') {
+                this.logger()?.warn('[@stone-js/notifications] delivery is configured to be queued, and no queue is enabled, ' +
+                    'so it happens in the request instead. Enable @stone-js/queue, or set ' +
+                    '`stone.notifications.dispatch` to \'inline\' to say you meant it.');
+            }
+            return undefined;
+        }
+        return 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.
+     */
+    warnOnceAboutTheDefault(channels) {
+        if (this.warned || channels.length !== 1 || channels[0] !== DEFAULT_CHANNEL) {
+            return;
+        }
+        if (this.options().channels?.some((channel) => channel.name === DEFAULT_CHANNEL) === true) {
+            return;
+        }
+        this.warned = true;
+        this.logger()?.warn('[@stone-js/notifications] notifications are going to the log, which reaches nobody. Configure ' +
+            'a channel and name it in `stone.notifications.default` when you want them delivered.');
+    }
+    /** Whether the default has already been reported, for this notifier. */
+    warned = false;
+    /**
+     * 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.
+     */
+    async alreadySent(template, key) {
+        if (key === undefined) {
+            return false;
+        }
+        const cache = this.cache();
+        if (cache === undefined) {
+            // Silently sending twice is exactly what this exists to prevent, so the absence is named.
+            this.warnOnce('dedupe', '[@stone-js/notifications] a notification asked to be sent once and no cache is enabled to ' +
+                'remember it, so a repeat cannot be recognised. Enable @stone-js/cache.');
+            return false;
+        }
+        const ttl = this.options().dedupe?.ttl ?? 86_400;
+        try {
+            const claimed = await cache.add(`notifications:${template}:${key}`, 1, { ttl });
+            if (!claimed) {
+                this.logger()?.info?.('[@stone-js/notifications] a repeated notification was dropped', { template });
+            }
+            return !claimed;
+        }
+        catch (error) {
+            // A cache that cannot answer must not stop a notification: better one duplicate than a message
+            // nobody receives. Named, because a deduplication that quietly stopped working is worth seeing.
+            this.logger()?.warn('[@stone-js/notifications] the deduplication store could not answer', {
+                template,
+                reason: error?.message
+            });
+            return false;
+        }
+    }
+    /**
+     * 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.
+     */
+    async announce(outcome, payload) {
+        if (this.options().announce === false) {
+            return;
+        }
+        const bus = this.bus();
+        if (bus === undefined) {
+            return;
+        }
+        try {
+            await bus.emit(outcome.status === 'sent' ? 'notification.delivered' : 'notification.failed', {
+                template: payload.template,
+                notice: payload.notice,
+                channel: outcome.channel,
+                status: outcome.status,
+                retryable: outcome.retryable,
+                reason: outcome.reason,
+                // The recipient's id, never their address: this leaves the process, and an address in an
+                // event is an address in every log that event passes through.
+                recipientId: payload.recipient.id,
+                locale: payload.locale
+            });
+        }
+        catch (error) {
+            // Announcing is a courtesy to whoever is listening, and it must not undo a delivery that
+            // already happened.
+            this.logger()?.warn('[@stone-js/notifications] a delivery could not be announced', {
+                reason: error?.message
+            });
+        }
+    }
+    /** Say something once per notifier, so a standing condition is stated rather than repeated. */
+    warnOnce(topic, message) {
+        if (this.said.has(topic)) {
+            return;
+        }
+        this.said.add(topic);
+        this.logger()?.warn(message);
+    }
+    /** What has already been said. */
+    said = new Set();
+    /** The notice registry, built for this event like everything else. */
+    notices() {
+        this.registry = this.registry ?? new NoticeRegistry({ blueprint: this.blueprint, container: this.container });
+        return this.registry;
+    }
+    /** The registry, once. */
+    registry;
+    /** The cache store deduplication is remembered in, when one is bound. */
+    cache() {
+        const name = this.options().dedupe?.store;
+        if (this.container?.has?.('cacheManager') === true) {
+            return this.container.make('cacheManager').store(name);
+        }
+        return this.container?.has?.('cache') === true ? this.container.make('cache') : undefined;
+    }
+    /** The event bus, when one is bound. */
+    bus() {
+        return this.container?.has?.('eventBus') === true
+            ? this.container.make('eventBus')
+            : undefined;
+    }
+    /** The `stone.notifications` bucket. */
+    options() {
+        return this.blueprint.get('stone.notifications', {});
+    }
+    /** The channel registry, from the container when there is one. */
+    manager() {
+        const fromContainer = this.container?.has?.(NotificationManager) === true
+            ? this.container.make(NotificationManager)
+            : undefined;
+        return fromContainer ?? NotificationManager.getInstance() ?? NotificationManager.create();
+    }
+    /** The translation catalogue, when one is bound. */
+    translator() {
+        return this.container?.has?.('i18n') === true ? this.container.make('i18n') : undefined;
+    }
+    /** The logger, when one is bound. */
+    logger() {
+        return this.container?.has?.('logger') === true ? this.container.make('logger') : undefined;
+    }
+}
+
+/** What an unconfigured log channel is, as one value rather than a literal rebuilt per call. */
+const DEFAULT_CONFIG$1 = { name: 'log' };
+/**
+ * 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.
+ */
+class LogChannel {
+    name;
+    logger;
+    /**
+     * @param config - Names the channel.
+     * @param logger - Where the message goes, when one is bound.
+     * @returns A channel.
+     */
+    static create(config = DEFAULT_CONFIG$1, logger) {
+        return new this(config.name ?? 'log', logger);
+    }
+    constructor(name = 'log', logger) {
+        this.name = name;
+        this.logger = logger;
+    }
+    /**
+     * 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.
+     */
+    async send(message, recipient) {
+        this.logger?.info?.(`[@stone-js/notifications] ${message.template} -> ${this.addresseeOf(recipient)}`, {
+            subject: message.subject,
+            locale: message.locale
+        });
+        return { status: 'sent' };
+    }
+    /**
+     * 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.
+     */
+    addresseeOf(recipient) {
+        if (typeof recipient.id === 'string' && recipient.id !== '') {
+            return `user:${recipient.id}`;
+        }
+        if (typeof recipient.email === 'string') {
+            return 'an email address';
+        }
+        if (typeof recipient.phone === 'string') {
+            return 'a phone number';
+        }
+        return 'someone with no address';
+    }
+}
+
+/**
+ * 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.
+ */
+class SmtpChannel {
+    name;
+    config;
+    transportPromise;
+    /**
+     * @param config - The channel's configuration.
+     * @returns A channel.
+     */
+    static create(config) {
+        return new this(config);
+    }
+    constructor(config) {
+        this.config = config;
+        this.name = config.name ?? 'smtp';
+    }
+    /**
+     * Send the message as mail.
+     *
+     * @param message - The rendered notification.
+     * @param recipient - Who it is for.
+     * @returns How it ended.
+     */
+    async send(message, recipient) {
+        if (typeof recipient.email !== 'string' || recipient.email === '') {
+            // Not retryable, and not a failure of this channel: the person simply has no mailbox here.
+            // Reported rather than thrown, so the caller sees which channel could not reach them and why.
+            return { status: 'unreachable', retryable: false, reason: 'The recipient has no email address.' };
+        }
+        if (typeof this.config.from !== 'string' || this.config.from === '') {
+            // A setup mistake, and one no default could fix: a from address nobody chose would be refused
+            // by the first receiving server that checks it.
+            return {
+                status: 'failed',
+                retryable: false,
+                reason: 'The SMTP channel needs a `from` address. Set it on the channel configuration.'
+            };
+        }
+        try {
+            const transport = await this.transport();
+            const sent = await transport.sendMail({
+                from: this.config.from,
+                to: recipient.email,
+                subject: message.subject,
+                text: message.body
+            });
+            return { status: 'sent', id: sent?.messageId };
+        }
+        catch (error) {
+            // A setup mistake is not a delivery outcome and must not be dressed as one: it would go to the
+            // retry queue and fail identically forever. It leaves as itself, and the notifier reports it
+            // as the permanent failure it is.
+            if (error instanceof NotificationConfigurationError) {
+                throw error;
+            }
+            // A provider being down is worth another attempt; a rejected address is not, and SMTP says
+            // which by its status code: 5xx is permanent, everything else is worth retrying.
+            const permanent = typeof error?.responseCode === 'number' && error.responseCode >= 500 && error.responseCode < 600;
+            return {
+                status: 'failed',
+                retryable: !permanent,
+                reason: String(error?.message ?? 'The mail could not be sent.')
+            };
+        }
+    }
+    /** The transport, built once for this instance. */
+    async transport() {
+        this.transportPromise = this.transportPromise ?? this.build();
+        return await this.transportPromise;
+    }
+    /** Build the transport from what was configured, or say what is missing. */
+    async build() {
+        const configured = this.config.transport;
+        // A transport the application built is the application's to manage, connection pool included.
+        if (configured !== undefined && configured !== null && typeof configured.sendMail === 'function') {
+            return configured;
+        }
+        const nodemailer = await this.loadNodemailer();
+        return nodemailer.createTransport(configured ?? {});
+    }
+    /**
+     * 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.
+     */
+    async loadNodemailer() {
+        const missing = () => {
+            throw new NotificationConfigurationError('The SMTP channel requires "nodemailer". Install it: npm i nodemailer');
+        };
+        // Typed as unknown on purpose: `nodemailer` is an optional peer, so this package must compile
+        // whether or not its types are installed, and what comes back is checked below anyway.
+        const mod = await import('nodemailer').catch(missing);
+        // It ships a default export, and which one a dynamic import lands on depends on the interop the
+        // application was built with. Either is fine; neither is a delivery failure.
+        const candidate = mod?.default ?? mod;
+        return typeof candidate?.createTransport === 'function' ? candidate : missing();
+    }
+}
+
+/** What an unconfigured in-app channel is, as one value rather than a literal rebuilt per call. */
+const DEFAULT_CONFIG = { name: 'in-app' };
+/**
+ * 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.
+ */
+class InAppChannel {
+    name;
+    event;
+    broadcaster;
+    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 = DEFAULT_CONFIG, broadcaster) {
+        return new this(config, broadcaster);
+    }
+    constructor(config = DEFAULT_CONFIG, broadcaster) {
+        this.name = config.name ?? 'in-app';
+        this.event = config.event ?? IN_APP_EVENT;
+        this.broadcaster = broadcaster;
+        this.channelFor = config.channelFor ?? ((recipient) => `user.${String(recipient.id)}.notifications`);
+    }
+    /**
+     * Broadcast the message on the recipient's own channel.
+     *
+     * @param message - The rendered notification.
+     * @param recipient - Who it is for.
+     * @returns How it ended.
+     */
+    async send(message, recipient) {
+        if (this.broadcaster === undefined) {
+            // A setup gap, not a delivery failure, and it must not be retried: nothing will change on the
+            // second attempt. Named plainly so the fix is obvious.
+            return {
+                status: 'failed',
+                retryable: false,
+                reason: 'The in-app channel needs a realtime broadcaster. Enable @stone-js/realtime, or ' +
+                    'register a channel of your own with `channels: [{ name, factory }]`.'
+            };
+        }
+        if (typeof recipient.id !== 'string' || recipient.id === '') {
+            // Without an id there is no channel to broadcast on. Not retryable: the recipient will not
+            // grow one between attempts.
+            return { status: 'unreachable', retryable: false, reason: 'The recipient has no id to address.' };
+        }
+        await this.broadcaster.to(this.channelFor(recipient)).emit(this.event, {
+            template: message.template,
+            params: message.params,
+            subject: message.subject,
+            body: message.body,
+            locale: message.locale
+        });
+        return { status: 'sent' };
+    }
+}
+
+/**
+ * Binds the channels and the notifier.
+ *
+ * Everything is built for this event, like the rest of the container. A channel holding a connection
+ * holds it itself, because a connection is a resource and the channel is the boundary that owns it;
+ * nothing here keeps state between events.
+ */
+class NotificationServiceProvider {
+    container;
+    constructor(container) {
+        this.container = container;
+    }
+    register() {
+        const blueprint = this.container.make('blueprint');
+        const config = blueprint.get('stone.notifications', {});
+        const manager = NotificationManager.create();
+        // Always available, so an application that calls `notify()` and configures nothing sees what it
+        // would have sent instead of a configuration error.
+        manager.registerFactory('log', () => LogChannel.create({ name: 'log' }, this.logger()));
+        for (const channel of config.channels ?? []) {
+            this.registerChannel(manager, channel);
+        }
+        NotificationManager.setInstance(manager);
+        this.container
+            .instanceIf(NotificationManager, manager)
+            .alias(NotificationManager, ['notificationManager', 'channels'])
+            .singletonIf(NoticeRegistry, () => new NoticeRegistry({ blueprint, container: this.container }))
+            .alias(NoticeRegistry, ['notices'])
+            .singletonIf(Notifier, () => new Notifier({ blueprint, container: this.container }))
+            .alias(Notifier, ['notifier']);
+    }
+    /**
+     * Register one configured channel, lazily: a transport is built when first used, not at boot, so an
+     * application configured for production does not need a mail server to start locally.
+     *
+     * @param manager - The registry to register into.
+     * @param config - What the application declared.
+     */
+    registerChannel(manager, config) {
+        // A channel the application builds itself, declared where the others are. Registering it on the
+        // manager from a provider reads well and does not survive: the container is rebuilt per event.
+        if (typeof config.factory === 'function') {
+            manager.registerFactory(config.name, () => config.factory?.(config));
+            return;
+        }
+        // A class the application declared with `@NotificationChannel`. Built through the container, so
+        // its constructor is auto-wired: a channel needing a provider client asks for it.
+        if (typeof config.module === 'function') {
+            manager.registerFactory(config.name, () => this.build(config));
+            return;
+        }
+        const driver = config.driver ?? 'log';
+        const factory = this.driverFor(driver);
+        if (factory === undefined) {
+            throw new NotificationConfigurationError(`Unknown notification driver '${driver}'. Ships with 'log', 'in-app' and 'smtp'. To reach a ` +
+                'provider this package has never heard of, and that is how `sms` and `push` are done, ' +
+                'declare the channel with a `factory` instead of a `driver`: ' +
+                '`channels: [{ name: \'sms\', factory: () => myChannel }]`.');
+        }
+        manager.registerFactory(config.name, () => factory(config));
+    }
+    /**
+     * A declared channel class, built.
+     *
+     * @param config - What the application declared.
+     * @returns The channel.
+     * @throws {NotificationConfigurationError} When the class cannot be built.
+     */
+    build(config) {
+        const built = this.container.resolve?.(config.module, true);
+        if (built === undefined || typeof built.send !== 'function') {
+            throw new NotificationConfigurationError(`The channel declared as '${config.name}' does not answer \`send(message, recipient)\`. ` +
+                'A channel is anything with that method, and it returns an outcome rather than throwing.');
+        }
+        return built;
+    }
+    /**
+     * The builder for a driver this package ships.
+     *
+     * @param driver - The driver's name.
+     * @returns The factory, or nothing when the name is not one of ours.
+     */
+    driverFor(driver) {
+        return {
+            log: (config) => LogChannel.create(config, this.logger()),
+            'in-app': (config) => InAppChannel.create(config, this.broadcaster()),
+            smtp: (config) => SmtpChannel.create(config)
+        }[driver];
+    }
+    /** The realtime broadcaster, when one is bound. */
+    broadcaster() {
+        // The container is not optional here, so `has` answers a boolean outright.
+        return this.container.has('broadcaster')
+            ? this.container.make('broadcaster')
+            : undefined;
+    }
+    /** The logger, when one is bound. */
+    logger() {
+        return this.container.has('logger') ? this.container.make('logger') : undefined;
+    }
+}
+
+/**
+ * Declare a notice imperatively.
+ *
+ * The imperative half of `@Notice`, and it says exactly the same thing: metadata here, content in
+ * the module. Put the result on `stone.notifications.notices`.
+ *
+ * @param module - The notice: a class, or an object answering `notify`.
+ * @param options - The notice's metadata.
+ * @param isClass - Whether `module` is a class the container should build. Defaults to true.
+ * @returns The declaration.
+ *
+ * @example
+ * ```ts
+ * blueprint.set('stone.notifications.notices', [
+ *   defineNotice(ConsentNeeded, { name: 'guardianship.consent_needed', on: 'identity.guardian.invited.v1' })
+ * ])
+ * ```
+ */
+function defineNotice(module, options, isClass = true) {
+    return { ...options, module, isClass };
+}
+
+/**
+ * Where a class declares itself a notification channel.
+ *
+ * A string rather than a symbol, by the convention every first-party module follows: another package
+ * can read it without importing this one.
+ */
+const CHANNEL_KEY = '@stone-js/notifications/channel';
+/**
+ * Where a class declares itself a notice.
+ *
+ * A string rather than a symbol, by the convention every first-party module follows: another package
+ * can read what an application declared without importing this one.
+ */
+const NOTICE_KEY = '@stone-js/notifications/notice';
+
+/**
+ * The worker side of a notification: it performs the delivery the request decided on.
+ *
+ * It runs the same code the inline path runs, which is what makes a retry mean exactly what the first
+ * attempt meant. The payload carries the template key and its params rather than a rendered body, so
+ * a message queued before a translation was fixed goes out fixed.
+ *
+ * **It throws when, and only when, another attempt could work.** That is the whole contract with the
+ * queue: a permanent failure that threw would be retried until the attempts ran out, filling the
+ * queue with work that cannot succeed, and an unreachable recipient would look like an outage.
+ */
+class DeliverNotification {
+    notifier;
+    /**
+     * @param dependencies - Auto-wired services.
+     */
+    constructor({ notifier }) {
+        this.notifier = notifier;
+    }
+    /**
+     * Deliver one notification.
+     *
+     * @param payload - Who, what, where, in which language.
+     * @returns What each channel answered.
+     * @throws {Error} When at least one channel failed in a way another attempt could fix.
+     */
+    async handle(payload) {
+        const outcomes = await this.notifier.deliver(payload);
+        const retryable = outcomes.filter((outcome) => outcome.status === 'failed' && outcome.retryable === true);
+        if (retryable.length > 0) {
+            const channels = retryable.map((outcome) => `'${String(outcome.channel)}'`).join(', ');
+            const reasons = retryable.map((outcome) => outcome.reason ?? 'no reason given').join('; ');
+            throw new Error(`Notification '${payload.template}' failed on ${channels}: ${reasons}`);
+        }
+        return outcomes;
+    }
+}
+
+/**
+ * Build-phase middleware: subscribes every notice that named a domain event.
+ *
+ * **This is what makes calling the notifier optional.** A notice declaring `on` becomes a handler of
+ * the light key router, the same one `@stone-js/event-bus` routes incoming domain events through. So
+ * a module emits what happened, and the notice says who learns about it: the emitting module imports
+ * nothing, and is never reopened when a channel is added.
+ *
+ * A middleware rather than a static entry, because the notices are only known once everything has
+ * been collected: `@Notice` contributes them, and so does configuration, and both are read here.
+ *
+ * The entry is a plain object of the shape the key router already accepts, so nothing here depends on
+ * `@stone-js/router`. The handler is the **factory** form, which receives the container, so the
+ * closure carries only the notice's name and the notifier is resolved for the event that arrives.
+ *
+ * @param context - The blueprint context.
+ * @param next - The next blueprint middleware.
+ * @returns The blueprint.
+ */
+const NoticeSubscriptionsMiddleware = async (context, next) => {
+    const blueprint = await next(context);
+    const options = blueprint.get('stone.notifications', {});
+    const subscribed = (options.notices ?? []).filter((notice) => typeof notice.on === 'string');
+    if (subscribed.length === 0) {
+        return blueprint;
+    }
+    blueprint.add('stone.keyRouting.handlers', subscribed.map(handlerFor));
+    return blueprint;
+};
+/**
+ * One key-router handler, for one notice.
+ *
+ * @param notice - What was declared.
+ * @returns The handler entry.
+ */
+function handlerFor(notice) {
+    return {
+        key: notice.on,
+        isFactory: true,
+        action: 'handle',
+        module: (container) => ({
+            handle: async (event) => await container.make('notifier').deliverNotice(notice.name, event)
+        })
+    };
+}
+/**
+ * Meta blueprint middleware for the notice subscriptions.
+ */
+const MetaNoticeSubscriptionsMiddleware = {
+    module: NoticeSubscriptionsMiddleware,
+    priority: 5
+};
+
+/**
+ * Opt-in blueprint: register it to reach people.
+ *
+ * The imperative half of the pair; `@Notifications()` is the declarative one. It binds the notifier
+ * and the channels, and contributes the delivery job so a worker performs what a request decided.
+ *
+ * The job is declared on `stone.queue.handlers`, the array the worker scans, so nothing here depends
+ * on the queue package. An application with no queue simply never has a worker to read it, and
+ * delivery happens in the request instead.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, defineStoneApp } from '@stone-js/core'
+ * import { notificationsBlueprint } from '@stone-js/notifications'
+ *
+ * export const App = defineStoneApp({ name: 'app' }, [notificationsBlueprint])
+ *
+ * export const AppConfig = defineConfig((blueprint) => blueprint.set('stone.notifications', {
+ *   default: ['smtp', 'in-app'],
+ *   channels: [{ name: 'smtp', driver: 'smtp', from: 'Noowow <no-reply@example.test>' }],
+ *   recipients: async (id) => await accounts.contactFor(id)
+ * }))
+ * ```
+ */
+const notificationsBlueprint = {
+    stone: {
+        notifications: {},
+        providers: [
+            NotificationServiceProvider
+        ],
+        blueprint: {
+            middleware: [
+                MetaNoticeSubscriptionsMiddleware
+            ]
+        },
+        queue: {
+            handlers: [
+                { name: DELIVERY_JOB, module: DeliverNotification, isClass: true, action: 'handle' }
+            ]
+        }
+    }
+};
+
+/**
+ * Declare a class as a notice: something a person receives.
+ *
+ * **The decorator says what it is; the class says what it says.** There is no `content` option, and
+ * that is deliberate: a decorator carrying message bodies would put text in the one place it cannot
+ * be translated, formatted, or computed from the event. The class answers `notify(event, context)`,
+ * and it is built through the container, so it can ask for i18n, a repository, a URL signer.
+ *
+ * With `on`, **nobody calls the notifier**. A module emits what happened, and the notice that named
+ * that event decides who learns about it. The emitting module imports nothing and is never reopened
+ * when a channel is added, which is the whole reason this exists rather than a service call.
+ *
+ * @param options - The notice's metadata.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```ts
+ * @Notice({
+ *   name: 'guardianship.consent_needed',
+ *   on: 'identity.guardian.invited.v1',
+ *   channels: ['smtp', 'in-app']
+ * })
+ * export class ConsentNeeded {
+ *   constructor ({ i18n }) { this.i18n = i18n }
+ *
+ *   recipients (event) { return event.guardianId }
+ *
+ *   notify (event, { locale }) {
+ *     return {
+ *       smtp: {
+ *         subject: this.i18n.t('consent.subject', { lng: locale }),
+ *         body: this.i18n.t('consent.body', { lng: locale, child: event.childHandle })
+ *       },
+ *       'in-app': { body: this.i18n.t('consent.short', { lng: locale }) }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+const Notice = (options) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        // A service, and a notice: the container builds it, and the registry finds it by name. Registering
+        // it rather than reaching into it is what lets the class ask for whatever it needs.
+        setMetadata(context, SERVICE_KEY, { singleton: true, isClass: true, alias: [`notice:${options.name}`] });
+        setMetadata(context, NOTICE_KEY, options);
+        const declaration = { ...options, module: target, isClass: true };
+        addBlueprint(target, context, notificationsBlueprint, {
+            stone: { notifications: { notices: [declaration] } }
+        });
+    });
+};
+
+/**
+ * Declare a class as a notification channel.
+ *
+ * The declaration form for a channel of your own, next to the configuration form: this is how `sms`
+ * and `push` are done, and anything else a provider offers. The class is registered as a service, so
+ * its constructor is auto-wired like any other, and the channel is registered under the name given
+ * here.
+ *
+ * The class must answer `send(message, recipient)` and **return** an outcome rather than throw, which
+ * is the whole port. A channel that throws is treated as retryable.
+ *
+ * @param name - The name notifications refer to it by.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```ts
+ * @NotificationChannel('sms')
+ * export class TwilioChannel {
+ *   readonly name = 'sms'
+ *
+ *   constructor ({ twilio }) { this.twilio = twilio }
+ *
+ *   async send (message, recipient) {
+ *     if (recipient.phone === undefined) {
+ *       return { status: 'unreachable', retryable: false, reason: 'No phone number.' }
+ *     }
+ *     await this.twilio.messages.create({ to: recipient.phone, body: message.body })
+ *     return { status: 'sent' }
+ *   }
+ * }
+ * ```
+ */
+const NotificationChannel = (name) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        // A service, and a channel: the container builds it, and the registry finds it. Registering it
+        // rather than reaching into it is what lets the class ask for whatever it needs.
+        setMetadata(context, SERVICE_KEY, { singleton: true, isClass: true, alias: [`channel:${name}`] });
+        setMetadata(context, CHANNEL_KEY, { name });
+        const blueprint = {
+            stone: { notifications: { channels: [{ name, module: target, isClass: true }] } }
+        };
+        addBlueprint(target, context, notificationsBlueprint, blueprint);
+    });
+};
+
+/**
+ * Enable notifications on the application.
+ *
+ * The declarative half of the module's activation; `notificationsBlueprint` is the imperative half,
+ * and neither can do what the other cannot. With nothing configured, notifications go to the log and
+ * say so: reaching real people is a decision, so it is written down.
+ *
+ * @param options - What to configure, if anything.
+ * @returns A class decorator.
+ *
+ * @example
+ * ```ts
+ * @Notifications({
+ *   default: ['smtp', 'in-app'],
+ *   channels: [{ name: 'smtp', driver: 'smtp', from: 'Noowow <no-reply@example.test>' }]
+ * })
+ * @StoneApp()
+ * export class Application {}
+ * ```
+ */
+const Notifications = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        const blueprint = cloneValue(notificationsBlueprint);
+        // The blueprint is the single source of truth for what the module declares; the decorator
+        // overrides only what it can, its own options bucket.
+        blueprint.stone.notifications = { ...blueprint.stone.notifications, ...options };
+        addBlueprint(target, context, blueprint);
+    });
+};
+
+export { CHANNEL_KEY, DEFAULT_CHANNEL, DELIVERY_JOB, DeliverNotification, IN_APP_EVENT, InAppChannel, LogChannel, MetaNoticeSubscriptionsMiddleware, NOTICE_KEY, Notice, NoticeRegistry, NoticeSubscriptionsMiddleware, NotificationChannel, NotificationConfigurationError, NotificationManager, NotificationServiceProvider, Notifications, Notifier, SmtpChannel, defineNotice, notificationsBlueprint, render };