@stone-js/notifications 0.8.17

package/dist/jobs/DeliverNotification.d.ts

@@ -0,0 +1,30 @@
+import { DeliveryPayload, Notifier } from '../Notifier.js';
+import { DeliveryOutcome } from '../declarations.js';
+/**
+ * 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.
+ */
+export declare class DeliverNotification {
+    private readonly notifier;
+    /**
+     * @param dependencies - Auto-wired services.
+     */
+    constructor({ notifier }: {
+        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.
+     */
+    handle(payload: DeliveryPayload): Promise<DeliveryOutcome[]>;
+}

package/dist/middleware/NoticeSubscriptionsMiddleware.d.ts

@@ -0,0 +1,25 @@
+import { BlueprintContext, IBlueprint, NextMiddleware, type MetaMiddleware } from '@stone-js/core';
+/**
+ * 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.
+ */
+export declare const NoticeSubscriptionsMiddleware: (context: BlueprintContext<IBlueprint>, next: NextMiddleware<BlueprintContext<IBlueprint>, IBlueprint>) => Promise<IBlueprint>;
+/**
+ * Meta blueprint middleware for the notice subscriptions.
+ */
+export declare const MetaNoticeSubscriptionsMiddleware: MetaMiddleware<BlueprintContext<IBlueprint>, IBlueprint>;

package/dist/options/NotificationsBlueprint.d.ts

@@ -0,0 +1,37 @@
+import { NotificationsConfig } from '../declarations.js';
+import { AppConfig, StoneBlueprint } from '@stone-js/core';
+/** Application config augmented with the notifications bucket. */
+export interface NotificationsAppConfig extends Partial<AppConfig> {
+    notifications: NotificationsConfig;
+    /** Contributed so a worker finds the delivery job. Ignored when the queue module is absent. */
+    queue?: Record<string, unknown>;
+}
+/** Blueprint for the notifications module. */
+export interface NotificationsBlueprint extends StoneBlueprint {
+    stone: NotificationsAppConfig;
+}
+/**
+ * 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)
+ * }))
+ * ```
+ */
+export declare const notificationsBlueprint: NotificationsBlueprint;

package/dist/render.d.ts

@@ -0,0 +1,36 @@
+import { RenderedNotification, TemplateInput } from './declarations.js';
+/** The shape this module needs from a translator, duck-typed so i18n is never imported. */
+export interface TranslatorLike {
+    t: (key: string, options?: Record<string, unknown>) => string;
+}
+/** What rendering is given, so it can be tested without an application around it. */
+export interface RenderContext {
+    /** The template key. */
+    template: string;
+    /** What to render it with. */
+    params: Record<string, unknown>;
+    /** The language the **recipient** reads. */
+    locale: string;
+    /** Templates the application declared. */
+    templates?: Record<string, TemplateInput>;
+    /** The catalogue, when `@stone-js/i18n` is enabled. */
+    translator?: TranslatorLike;
+}
+/**
+ * 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.
+ */
+export declare function render(context: RenderContext): RenderedNotification;

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@stone-js/notifications",
+  "version": "0.8.17",
+  "description": "Notifications for Stone.js: one declaration reaches a person wherever they are, delivered out of band.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stone-foundation/stone-js-framework.git",
+    "directory": "stone-js-notifications"
+  },
+  "homepage": "https://stonejs.dev",
+  "bugs": {
+    "url": "https://github.com/stone-foundation/stone-js-framework/issues"
+  },
+  "keywords": [
+    "StoneJS",
+    "notifications",
+    "email",
+    "sms",
+    "push",
+    "in-app"
+  ],
+  "files": [
+    "/dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "peerDependencies": {
+    "nodemailer": "^9.0.1",
+    "@stone-js/core": "0.8.17",
+    "@stone-js/queue": "0.8.17",
+    "@stone-js/realtime": "0.8.17",
+    "@stone-js/i18n": "0.8.17"
+  },
+  "dependencies": {
+    "@stone-js/config": "0.8.17"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-multi-entry": "^6.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "nodemailer": "^9.0.5",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.44.1",
+    "rollup-plugin-node-externals": "^8.0.1",
+    "ts-standard": "^12.0.2",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.6",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@stone-js/core": "0.8.17",
+    "@stone-js/http-core": "0.8.17",
+    "@stone-js/i18n": "0.8.17",
+    "@stone-js/queue": "0.8.17",
+    "@stone-js/realtime": "0.8.17",
+    "@stone-js/router": "0.8.17"
+  },
+  "ts-standard": {
+    "globals": [
+      "it",
+      "test",
+      "vi",
+      "expect",
+      "describe",
+      "beforeEach",
+      "afterEach"
+    ]
+  },
+  "peerDependenciesMeta": {
+    "@stone-js/queue": {
+      "optional": true
+    },
+    "@stone-js/realtime": {
+      "optional": true
+    },
+    "@stone-js/i18n": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "lint": "ts-standard src",
+    "lint:fix": "ts-standard --fix src tests",
+    "predoc": "rimraf docs",
+    "doc": "typedoc",
+    "clean": "rimraf dist",
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage",
+    "test:text": "npm run test:cvg -- --coverage.reporter=text",
+    "test:html": "npm run test:cvg -- --coverage.reporter=html",
+    "test:clover": "npm run test:cvg -- --coverage.reporter=clover"
+  }
+}