@selvajs/notifications 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Selva VektorNode AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @selvajs/notifications
+
+Message templates for Selva's outbound mail. Pure render: data in,
+`OutboundMessage` out. No I/O, no env, no transport.
+
+```ts
+import { renderInviteEmail } from '@selvajs/notifications';
+
+const message = renderInviteEmail({ to, acceptUrl, orgName, expiresAt });
+await getNotificationProvider().send(message, log);
+```
+
+## Where this sits
+
+Three pieces, deliberately kept apart:
+
+| Piece                      | Owns                          | Lives               |
+| -------------------------- | ----------------------------- | ------------------- |
+| `INotificationProvider`    | putting a message on the wire | `@selvajs/platform` |
+| `SmtpNotificationProvider` | doing that over SMTP          | `@selvajs/server`   |
+| Templates (this package)   | what the message says         | here                |
+
+A template never fetches. It takes resolved values — `orgName`, not `orgId` —
+because a template that can fetch is a template that can fail, and mail is
+rendered on a path where failing is not an option.
+
+## Adding a template
+
+Build on `renderLayout` rather than writing a fresh document. The wrapper owns the
+card chrome, type stack, and colours, so mail written by different people at
+different times still reads as coming from one product.
+
+Two rules the invite template demonstrates and the tests enforce:
+
+- **Both parts carry the payload.** A mail that degrades to plain text must still
+  contain the link. If the point of the mail is a URL, the text part needs it.
+- **Everything interpolated goes through `escapeHtml`** — including URLs. An accept
+  URL carries a token, and a token can contain characters that close an `href`
+  early.
+
+Tag the result with its `NotificationKind` (declared in
+`@selvajs/platform/notifications`) so the dispatcher can route it and honour a
+user's per-kind preferences.
+
+## Not published
+
+Private on purpose. Everything here is Selva's own content — templates about Selva
+orgs, Selva invites, Selva branding — with one consumer, the Selva app.
+
+The extension point is already public and lives elsewhere: `OutboundMessage` and
+`INotificationProvider` ship in `@selvajs/platform`, so a self-hoster can implement
+a transport or hand-build a message without this package existing.
+
+**Worth revisiting.** Publish this if someone outside the app needs to render Selva
+mail — most plausibly a self-hoster customising invite or magic-link copy rather
+than replacing it wholesale. Two things should settle first, because both are
+likely to move the exported shape:
+
+- `notify()` may change what a template receives (channel, preference metadata,
+  resolved-vs-id inputs).
+- The magic-link template lands in the same pass and is the second data point on
+  what a template signature wants to look like.
+
+Publishing makes every export semver-protected, and that is a bad trade while the
+shape is still moving. Going private → public later is a version bump; going back
+is not. See `plans/features/notifications.md`.

package/dist/html.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Escape text for interpolation into an HTML attribute or text node.
+ *
+ * One copy on purpose: per-template copies are how one of them ends up missing
+ * a case. Every value a template interpolates goes through this, including
+ * URLs — an `acceptUrl` carries a token, and a token can contain characters
+ * that would otherwise close the `href` early.
+ */
+export declare function escapeHtml(s: string): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5C"}

package/dist/html.js

@@ -0,0 +1,16 @@
+/**
+ * Escape text for interpolation into an HTML attribute or text node.
+ *
+ * One copy on purpose: per-template copies are how one of them ends up missing
+ * a case. Every value a template interpolates goes through this, including
+ * URLs — an `acceptUrl` carries a token, and a token can contain characters
+ * that would otherwise close the `href` early.
+ */
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+//# sourceMappingURL=html.js.map

package/dist/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,CAAS;IACnC,OAAO,CAAC;SACN,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC3B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { renderInviteEmail, type InviteMailInput } from './templates/invite.js';
+export { escapeHtml } from './html.js';
+export { renderLayout, renderButton, renderUrlFallback, type LayoutInput } from './layout.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { renderInviteEmail } from './templates/invite.js';
+export { escapeHtml } from './html.js';
+export { renderLayout, renderButton, renderUrlFallback } from './layout.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAwB,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAoB,MAAM,aAAa,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,27 @@
+export interface LayoutInput {
+    /** Shown as the mail's heading. Escaped here — pass plain text. */
+    heading: string;
+    /** Body HTML. Already-escaped markup; templates build this themselves. */
+    body: string;
+    /** Small print under the rule. Already-escaped markup, omitted when absent. */
+    footer?: string;
+}
+/**
+ * The frame every Selva mail shares: card chrome, type stack, colours.
+ * Templates supply a body; this supplies the look, so mail written by
+ * different people at different times still reads as coming from one product.
+ *
+ * Deliberately plain — no images, no tracking pixel, no external stylesheet.
+ * Inline styles with a table-free layout survive the common clients, and mail
+ * clients that strip the styling still get readable, ordered content.
+ */
+export declare function renderLayout({ heading, body, footer }: LayoutInput): string;
+/** The primary action button. One definition so every mail's call to action matches. */
+export declare function renderButton(href: string, label: string): string;
+/**
+ * Fallback for clients that do not make the button clickable. Every mail whose
+ * point is a link needs this: a button that does not render leaves the reader
+ * with no way to continue.
+ */
+export declare function renderUrlFallback(href: string): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC3B,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,WAAW,GAAG,MAAM,CAkB3E;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD"}

package/dist/layout.js

@@ -0,0 +1,43 @@
+import { escapeHtml } from './html.js';
+/**
+ * The frame every Selva mail shares: card chrome, type stack, colours.
+ * Templates supply a body; this supplies the look, so mail written by
+ * different people at different times still reads as coming from one product.
+ *
+ * Deliberately plain — no images, no tracking pixel, no external stylesheet.
+ * Inline styles with a table-free layout survive the common clients, and mail
+ * clients that strip the styling still get readable, ordered content.
+ */
+export function renderLayout({ heading, body, footer }) {
+    return `<!doctype html>
+<html>
+<body style="margin:0;padding:24px;background:#f6f7f9;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;color:#1a1a1a;">
+	<div style="max-width:480px;margin:0 auto;background:#ffffff;border:1px solid #e4e6eb;border-radius:12px;padding:32px;">
+		<h1 style="margin:0 0 16px;font-size:20px;font-weight:600;">${escapeHtml(heading)}</h1>
+${body}${footer
+        ? `
+		<hr style="border:none;border-top:1px solid #e4e6eb;margin:24px 0;" />
+		<p style="margin:0;font-size:12px;line-height:1.5;color:#8a8a8a;">
+			${footer}
+		</p>`
+        : ''}
+	</div>
+</body>
+</html>`;
+}
+/** The primary action button. One definition so every mail's call to action matches. */
+export function renderButton(href, label) {
+    return `<a href="${escapeHtml(href)}" style="display:inline-block;padding:11px 20px;background:#1a1a1a;color:#ffffff;text-decoration:none;border-radius:8px;font-size:15px;font-weight:500;">${escapeHtml(label)}</a>`;
+}
+/**
+ * Fallback for clients that do not make the button clickable. Every mail whose
+ * point is a link needs this: a button that does not render leaves the reader
+ * with no way to continue.
+ */
+export function renderUrlFallback(href) {
+    return `<p style="margin:24px 0 0;font-size:13px;line-height:1.5;color:#6b6b6b;">
+			Or paste this into your browser:<br />
+			<span style="word-break:break-all;color:#4a4a4a;">${escapeHtml(href)}</span>
+		</p>`;
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAWvC;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAe;IAClE,OAAO;;;;gEAIwD,UAAU,CAAC,OAAO,CAAC;EACjF,IAAI,GACJ,MAAM;QACL,CAAC,CAAC;;;KAGA,MAAM;OACJ;QACJ,CAAC,CAAC,EACJ;;;QAGO,CAAC;AACT,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IACvD,OAAO,YAAY,UAAU,CAAC,IAAI,CAAC,4JAA4J,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC;AACxN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC7C,OAAO;;uDAE+C,UAAU,CAAC,IAAI,CAAC;OAChE,CAAC;AACR,CAAC"}

package/dist/templates/invite.d.ts

@@ -0,0 +1,17 @@
+import type { OutboundMessage } from '@selvajs/platform/notifications';
+export interface InviteMailInput {
+    to: string;
+    acceptUrl: string;
+    orgName: string;
+    /** Display name or email of the admin who minted the invite, when known. */
+    invitedBy?: string;
+    expiresAt: string;
+}
+/**
+ * "An admin invited you to an org" — the mail carrying an invite's accept link.
+ *
+ * The text part must always carry the URL: a mail that degrades to plain text
+ * is still the only way the invitee can accept.
+ */
+export declare function renderInviteEmail(input: InviteMailInput): OutboundMessage;
+//# sourceMappingURL=invite.d.ts.map

package/dist/templates/invite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite.d.ts","sourceRoot":"","sources":["../../src/templates/invite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAIvE,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CAClB;AASD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,CA8BzE"}

package/dist/templates/invite.js

@@ -0,0 +1,42 @@
+import { escapeHtml } from '../html.js';
+import { renderButton, renderLayout, renderUrlFallback } from '../layout.js';
+function formatExpiry(iso) {
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime())
+        ? 'soon'
+        : d.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+}
+/**
+ * "An admin invited you to an org" — the mail carrying an invite's accept link.
+ *
+ * The text part must always carry the URL: a mail that degrades to plain text
+ * is still the only way the invitee can accept.
+ */
+export function renderInviteEmail(input) {
+    const { to, acceptUrl, orgName, invitedBy } = input;
+    const expiry = formatExpiry(input.expiresAt);
+    const inviter = invitedBy ? `${invitedBy} invited you` : 'You have been invited';
+    const subject = `${inviter} to join ${orgName} on Selva`;
+    const text = [
+        `${inviter} to join ${orgName} on Selva.`,
+        '',
+        'Open this link to accept and set up your account:',
+        acceptUrl,
+        '',
+        `The link expires on ${expiry} and can only be used once.`,
+        '',
+        "If you weren't expecting this invitation, you can ignore this email."
+    ].join('\n');
+    const html = renderLayout({
+        heading: `Join ${orgName} on Selva`,
+        body: `		<p style="margin:0 0 24px;font-size:15px;line-height:1.5;color:#4a4a4a;">
+			${escapeHtml(inviter)} to join <strong>${escapeHtml(orgName)}</strong>. Open the link below to accept and set up your account.
+		</p>
+		${renderButton(acceptUrl, 'Accept invitation')}
+		${renderUrlFallback(acceptUrl)}`,
+        footer: `This link expires on ${escapeHtml(expiry)} and can only be used once.
+			If you weren't expecting this invitation, you can ignore this email.`
+    });
+    return { kind: 'org.invite', to, subject, text, html };
+}
+//# sourceMappingURL=invite.js.map

package/dist/templates/invite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invite.js","sourceRoot":"","sources":["../../src/templates/invite.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAW7E,SAAS,YAAY,CAAC,GAAW;IAChC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QAC/B,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;AACtF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACvD,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IACpD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,cAAc,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAEjF,MAAM,OAAO,GAAG,GAAG,OAAO,YAAY,OAAO,WAAW,CAAC;IAEzD,MAAM,IAAI,GAAG;QACZ,GAAG,OAAO,YAAY,OAAO,YAAY;QACzC,EAAE;QACF,mDAAmD;QACnD,SAAS;QACT,EAAE;QACF,uBAAuB,MAAM,6BAA6B;QAC1D,EAAE;QACF,sEAAsE;KACtE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,IAAI,GAAG,YAAY,CAAC;QACzB,OAAO,EAAE,QAAQ,OAAO,WAAW;QACnC,IAAI,EAAE;KACH,UAAU,CAAC,OAAO,CAAC,oBAAoB,UAAU,CAAC,OAAO,CAAC;;IAE3D,YAAY,CAAC,SAAS,EAAE,mBAAmB,CAAC;IAC5C,iBAAiB,CAAC,SAAS,CAAC,EAAE;QAChC,MAAM,EAAE,wBAAwB,UAAU,CAAC,MAAM,CAAC;wEACoB;KACtE,CAAC,CAAC;IAEH,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxD,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@selvajs/notifications",
+  "version": "0.1.0",
+  "description": "Message templates for Selva's outbound notifications — pure render, no transport",
+  "license": "MIT",
+  "author": "VektorNode",
+  "homepage": "https://selva.dev",
+  "bugs": "https://github.com/VektorNode/selva/issues",
+  "keywords": [
+    "selva",
+    "notifications",
+    "email",
+    "templates"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VektorNode/selva.git",
+    "directory": "packages/notifications"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "selva-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/__tests__/**",
+    "!**/*.test.*",
+    "!**/*.spec.*"
+  ],
+  "dependencies": {
+    "@selvajs/platform": "0.19.1"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.10",
+    "@selvajs/config": "0.0.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:types": "eslint . --config eslint.typed.config.js"
+  }
+}