@antelopejs/interface-dms 0.7.1 → 0.7.3

package/docs/4.notifications/2.categories-and-subjects.md

@@ -0,0 +1,214 @@
+---
+title: "Categories and Subjects"
+description: "Every notification is filed under a subject, and every subject belongs to a category."
+---
+
+# Categories and Subjects
+
+## Overview
+
+Every notification is filed under a **subject**, and every subject belongs to a **category**. That two-level taxonomy is what the notification settings screen groups by, and what user preferences are keyed on: a preference entry exists per `categoryId:subjectId` pair.
+
+You declare categories and subjects by calling `NotificationCategory()` and `NotificationSubject()`. Both calls register the declaration with the DMS and return the info object, which you keep as a module-level constant. You pass the category constant to `NotificationSubject()`, and the subject constant to the builder's `.subject()` when you send.
+
+Declarations are values, not decorators: they run when the module that contains them is imported. Declare them at the top level of a module that is imported during startup, so the taxonomy is complete before the first notification is sent.
+
+The [notification preferences walkthrough](/docs/auth-and-tenancy/authentication#notification-preferences) shows the System category expanded, its locked General subject, and the Playground category and subject switched off. The Email column is marked Soon: these controls currently manage in-app delivery, not transactional authentication emails.
+
+## Declaring a Category
+
+`NotificationCategory(id, category)` registers a category and returns the resulting `NotificationCategoryInfo`.
+
+```typescript
+import { NotificationCategory } from "@antelopejs/interface-dms/notifications";
+
+export const shopCategory = NotificationCategory("shop", {
+  labelKey: "shop.notifications.categories.shop",
+  descriptionKey: "shop.notifications.categories.shop_desc",
+  icon: "i-ph-shopping-cart",
+});
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `id` | Identifier of the category. It becomes the first half of every preference key under this category. |
+| `category` | The rest of the `NotificationCategoryInfo` object — every field except `id`. |
+
+### NotificationCategoryInfo
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `id` | `string` | Category identifier. Supplied through the first argument of `NotificationCategory()`. |
+| `labelKey` | `string` | Translation key for the category name. |
+| `descriptionKey` | `string` (optional) | Translation key for a longer description. |
+| `icon` | `string` | Icon name, in the icon syntax used across the dashboard (for example `i-ph-shopping-cart`). |
+| `togglePermission` | [`TogglePermission`](#toggle-permissions) (optional) | Parent toggle stance applied when evaluating this category's subjects. It does not lock the category's own switch. |
+| `tagKey` | `string` (optional) | Translation key of a short module tag (for example `SaaS`) shown next to the category in the settings screen and on each of its notifications in the inbox. Without it, the inbox tags a notification with its subject's label. |
+
+Registering a second category with an `id` that is already taken is ignored: the first declaration wins.
+
+## Declaring a Subject
+
+`NotificationSubject(id, subject)` registers a subject under an already-declared category and returns the resulting `NotificationSubjectInfo`.
+
+```typescript
+import {
+  NotificationCategory,
+  NotificationSubject,
+} from "@antelopejs/interface-dms/notifications";
+
+export const shopCategory = NotificationCategory("shop", {
+  labelKey: "shop.notifications.categories.shop",
+  icon: "i-ph-shopping-cart",
+});
+
+export const orderSubject = NotificationSubject("orders", {
+  category: shopCategory,
+  labelKey: "shop.notifications.subjects.orders",
+  descriptionKey: "shop.notifications.subjects.orders_desc",
+  togglePermission: "default",
+});
+
+export const stockSubject = NotificationSubject("stock", {
+  category: shopCategory,
+  labelKey: "shop.notifications.subjects.stock",
+  togglePermission: "allowed",
+});
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `id` | Identifier of the subject. It is unique within its category, not globally: the preference key is `categoryId:subjectId`. |
+| `subject` | The rest of the `NotificationSubjectInfo` object — every field except `id`. |
+
+### NotificationSubjectInfo
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `id` | `string` | Subject identifier, unique within the category. Supplied through the first argument of `NotificationSubject()`. |
+| `category` | `NotificationCategoryInfo` | The category this subject belongs to — the value returned by `NotificationCategory()`. |
+| `labelKey` | `string` | Translation key for the subject name. |
+| `descriptionKey` | `string` (optional) | Translation key for a longer description. |
+| `togglePermission` | [`TogglePermission`](#toggle-permissions) (optional) | Whether users may turn this subject off, read together with the category's value. |
+| `badgeKey` | `string` (optional) | Translation key of a badge shown next to the subject label in the settings screen (for example `Developer mode`). |
+
+A subject carries the whole category object, not just its id, so `subject.category.id` is always reachable from a subject you hold. That is how a send resolves the preference key from nothing but the subject you passed to the builder.
+
+Registering a second subject with an `id` already taken inside the same category is ignored, the same way categories are.
+
+### Declaration Order
+
+The category has to be registered before any of its subjects: a subject whose category is not registered yet is rejected and never enters the registry, so nothing sent against it is delivered. Registrations run in call order, so declaring the category above its subjects in the same file — as in the example above — is enough.
+
+Registrations are scoped to the module that made them: when that module is unloaded, its categories and subjects are unregistered.
+
+## Toggle Permissions
+
+`TogglePermission` controls whether a user is allowed to opt out of a subject from the notification settings screen.
+
+```typescript
+type TogglePermission = "allowed" | "forbidden" | "default";
+```
+
+The field is optional on both `NotificationCategoryInfo` and `NotificationSubjectInfo`, and the settings screen locks a subject's switch only when both of these hold:
+
+- the subject declares `togglePermission: "forbidden"`, and
+- its category declares `togglePermission` as `"default"` or `"forbidden"`.
+
+Every other combination leaves the subject toggleable. A category's own switch is never locked: the value you put on a category acts as the parent half of the rule above and nothing else.
+
+| Value | Meaning on a subject | Meaning on a category |
+| ----- | -------------------- | --------------------- |
+| `"forbidden"` | The user may not turn the subject off, provided the category declares `"default"` or `"forbidden"`. | Enables the subject-side lock. The category itself stays toggleable. |
+| `"default"` | The subject stays toggleable. | Enables the subject-side lock, same as `"forbidden"`. |
+| `"allowed"` | The subject stays toggleable, same as `"default"`. | Leaves every subject toggleable, same as omitting the field. |
+
+So for a notification a user must always receive, declare `togglePermission: "forbidden"` on the subject **and** `togglePermission: "default"` on the category that holds it. `SystemCategory` declares `"default"`, which is what makes `GeneralSubject` mandatory.
+
+```typescript
+import {
+  NotificationCategory,
+  NotificationSubject,
+} from "@antelopejs/interface-dms/notifications";
+
+export const alertCategory = NotificationCategory("alerts", {
+  labelKey: "shop.notifications.categories.alerts",
+  icon: "i-ph-warning",
+  togglePermission: "default", // required for the forbidden subject below to lock
+});
+
+export const outageSubject = NotificationSubject("outage", {
+  category: alertCategory,
+  labelKey: "shop.notifications.subjects.outage",
+  togglePermission: "forbidden",
+});
+```
+
+`togglePermission` only governs what the settings screen offers. It does not change what `.toUser()` and the other dispatch methods do with a preference the user has already stored — see [Delivery Rules](/docs/interfaces/notifications/sending#delivery-rules).
+
+## Read Scope
+
+`ReadScope` describes how the read state of a multi-recipient notification behaves.
+
+```typescript
+type ReadScope = "individual" | "shared";
+```
+
+| Value | Meaning |
+| ----- | ------- |
+| `"individual"` | Each recipient gets their own copy with its own read state. This is the default. |
+| `"shared"` | The copies are grouped: once one recipient reads the notification, it counts as read for the whole group. |
+
+The scope is chosen per send, not per subject; you pass it through `SendOptions` on the multi-recipient dispatch methods. See [Send Options](/docs/interfaces/notifications/sending#send-options).
+
+## Built-in Categories and Subjects
+
+The DMS declares one category and five subjects of its own. Import them and pass them to `.subject()` when your notification fits one of them, instead of declaring a near-duplicate.
+
+```typescript
+import {
+  AccountSubject,
+  AutomationSubject,
+  CollaborationSubject,
+  GeneralSubject,
+  SecuritySubject,
+  SystemCategory,
+} from "@antelopejs/interface-dms/notifications";
+```
+
+`SystemCategory` is the category all five subjects belong to. Its id is `system`, its icon is `i-ph-gear`, and its `togglePermission` is `"default"` — the parent value that lets `GeneralSubject`'s `"forbidden"` take effect.
+
+| Constant | Id | Toggle permission | Used for |
+| -------- | -- | ----------------- | -------- |
+| `GeneralSubject` | `general` | `"forbidden"` | Unclassified platform messages. Users cannot opt out. |
+| `SecuritySubject` | `security` | `"default"` | Sign-ins, password and email changes, two-factor changes, backup-code regeneration. |
+| `AccountSubject` | `account` | `"default"` | Account lifecycle messages, such as the welcome notification. |
+| `CollaborationSubject` | `collaboration` | `"default"` | Messages about other people in the workspace, such as a collaborator joining. |
+| `AutomationSubject` | `automation` | `"default"` | Messages emitted by automations. |
+
+Their labels and descriptions use the `dms.notifications.*` translation keys shipped with the DMS.
+
+## Importing the Types
+
+The declaration functions and the built-in constants are exported from the interface root. The type definitions live in the `types` subpath:
+
+| Symbol | Import from |
+| ------ | ----------- |
+| `NotificationCategory`, `NotificationSubject`, `SystemCategory`, `GeneralSubject`, `SecuritySubject`, `AccountSubject`, `CollaborationSubject`, `AutomationSubject`, `NotificationTone` | `@antelopejs/interface-dms/notifications` |
+| `NotificationCategoryInfo`, `NotificationSubjectInfo`, `NotificationTone`, `TogglePermission`, `ReadScope` | `@antelopejs/interface-dms/notifications/types` |
+
+```typescript
+import type { NotificationSubjectInfo } from "@antelopejs/interface-dms/notifications/types";
+
+interface NotificationTemplate {
+  icon: string;
+  subject: NotificationSubjectInfo;
+  linkTo: string;
+}
+```
+
+Typing your own helpers against `NotificationSubjectInfo` is the usual reason to reach for the `types` subpath: it lets a template table or a helper function accept any subject, built-in or your own.
+
+## Next Steps
+
+- [Sending Notifications](/docs/interfaces/notifications/sending) - Build a notification against a subject and dispatch it to users, roles, or everyone

package/docs/4.notifications/3.sending.md

@@ -0,0 +1,285 @@
+---
+title: "Sending Notifications"
+description: "Build a notification, then send it to users, roles or everyone, with delivery rules and send options."
+---
+
+# Sending Notifications
+
+## Overview
+
+Sending happens in two steps. `Notification()` starts a builder you fill field by field; `.build()` closes it and gives you a `SendableNotification`, which carries the dispatch methods.
+
+For the visible result, see the [single-recipient notification and second-session update](/docs/auth-and-tenancy/authentication#read-notifications). The walkthrough distinguishes delivery from read state and shows [a disabled subject preventing a new delivery](/docs/auth-and-tenancy/authentication#notification-preferences).
+
+```typescript
+import {
+  GeneralSubject,
+  Notification,
+} from "@antelopejs/interface-dms/notifications";
+
+await Notification()
+  .icon("i-ph-bell")
+  .title("Deployment finished")
+  .description("The staging deployment completed successfully.")
+  .subject(GeneralSubject)
+  .build()
+  .toUser(userId);
+```
+
+A `SendableNotification` is immutable and holds no recipient, so you can build once and dispatch several times.
+
+| Method | Signature | Description |
+| ------ | --------- | ----------- |
+| `toUser` | `(userId: string, options?: SendOptions) => Promise<void>` | Send to one user. |
+| `toUsers` | `(userIds: string[], options?: SendOptions) => Promise<void>` | Send to a list of users. |
+| `toUsersIdempotently` | `(userIds: string[], idempotencyKey: string, options?: SendOptions) => Promise<void>` | Send a durable event once per recipient, including after dismissal. |
+| `toRoles` | `(roleIds: string[], options?: SendOptions) => Promise<void>` | Send to every user holding at least one of the roles. |
+| `broadcast` | `(options?: SendOptions) => Promise<void>` | Send to every user. |
+
+## Building a Notification
+
+`Notification()` takes no arguments and returns a fresh `NotificationBuilder`. Every setter stores its value and returns the builder, so calls chain in any order.
+
+```typescript
+import { Notification } from "@antelopejs/interface-dms/notifications";
+import { orderSubject } from "./notifications";
+
+const shipped = Notification()
+  .icon("i-ph-truck")
+  .title("$shop.notifications.order_shipped.title")
+  .description("$shop.notifications.order_shipped.description")
+  .params({ orderRef: "A-1043" })
+  .subject(orderSubject)
+  .linkTo("/shop/orders")
+  .build();
+```
+
+| Method | Type | Description |
+| ------ | ---- | ----------- |
+| `.icon(value)` | `string` | Icon shown next to the notification, in the dashboard icon syntax (for example `i-ph-truck`). Required. |
+| `.title(value)` | `string` | Title line. Required. |
+| `.description(value)` | `string` | Body line. Required. |
+| `.subject(subject)` | `NotificationSubjectInfo` | The subject the notification is filed under, which decides the category and the user preference it is gated on. Required. |
+| `.linkTo(value)` | `string` | Destination the notification links to, such as `/settings/user/profile`. Optional. |
+| `.params(value)` | `Record<string, string \| number>` | Interpolation values carried alongside the notification. Optional. |
+| `.tone(value)` | `NotificationTone` (`"neutral"`, `"primary"`, `"success"`, `"warning"`, `"error"`) | Colour of the icon well the inbox lists the notification with. Optional: without it the well is `primary` while unread and neutral once read. |
+
+The subject comes from [Categories and Subjects](/docs/interfaces/notifications/categories-and-subjects) — either one you declared with `NotificationSubject()` or one of the built-in constants.
+
+Titles and descriptions can be literal text or, following the DMS translation convention, a `$`-prefixed translation key; in the latter case the values passed to `.params()` are the interpolation values for that key. The DMS's own account notifications are written that way:
+
+```typescript
+import {
+  Notification,
+  SecuritySubject,
+} from "@antelopejs/interface-dms/notifications";
+
+await Notification()
+  .icon("i-ph-sign-in")
+  .title("$dms.notifications.messages.new_login.title")
+  .description("$dms.notifications.messages.new_login.description")
+  .params({ device: "Firefox on Linux", origin: " (203.0.113.4)" })
+  .subject(SecuritySubject)
+  .linkTo("/settings/user/profile")
+  .build()
+  .toUser(userId);
+```
+
+### Required Fields Are Checked by the Type System
+
+`NotificationBuilder<Set>` tracks in its type parameter which fields you have supplied: `.icon()` returns `NotificationBuilder<Set | "icon">`, `.title()` adds `"title"`, and so on. `build()` is declared with a `this` parameter that only accepts a builder whose `Set` covers `RequiredFields`:
+
+```typescript
+type RequiredFields = "icon" | "title" | "description" | "subject";
+```
+
+So a chain that skips one of the four does not compile — `this` is typed `never` at the `build()` call:
+
+```typescript
+// Compile error: description and subject were never supplied
+const broken = Notification().icon("i-ph-bell").title("Hello").build();
+```
+
+The check is purely static and happens at the call site. Nothing is validated again at runtime, and `.linkTo()` and `.params()` never affect it, and neither does `.tone()`.
+
+`build()` returns a `SendableNotification` holding a frozen copy of the data, so reusing the builder afterwards cannot change a notification you already built.
+
+## Sending to a Single User
+
+`toUser(userId, options?)` sends one copy to one user. It accepts an idempotency key; `readScope` has no effect for this method.
+
+```typescript
+import { Controller, Post } from "@antelopejs/interface-api";
+import { AuthRawUser } from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import {
+  GeneralSubject,
+  Notification,
+} from "@antelopejs/interface-dms/notifications";
+
+export class NotificationDemoController extends Controller("/api/notification") {
+  @Post("send")
+  async send(@AuthRawUser() user: User) {
+    await Notification()
+      .icon("i-ph-bell")
+      .title("Notification sent")
+      .description("This notification was sent from a route handler.")
+      .subject(GeneralSubject)
+      .build()
+      .toUser(user._id);
+
+    return { success: true };
+  }
+}
+```
+
+## Sending to Several Users
+
+`toUsers(userIds, options?)` sends to a list of user ids. Duplicate ids in the list produce a single notification per user. The examples in this section and the two below dispatch the `shipped` notification built earlier on this page.
+
+```typescript
+await shipped.toUsers([ownerId, managerId], { readScope: "shared" });
+```
+
+## Sending to Roles
+
+`toRoles(roleIds, options?)` resolves the users that hold any of the given roles and sends to them. An empty `roleIds` array sends nothing, and so does a set of roles nobody holds.
+
+```typescript
+await shipped.toRoles([adminRoleId], { readScope: "shared" });
+```
+
+Role ids are the DMS role identifiers described in the DMS tenancy and permissions guide; membership is resolved across tenants, so a user holding the role in any tenant is included.
+
+## Broadcasting
+
+`broadcast(options?)` sends to every user.
+
+```typescript
+await shipped.broadcast();
+```
+
+## Send Options
+
+Every dispatch method accepts an optional `SendOptions` object.
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `readScope` | `ReadScope` (optional) | Read-state grouping for a multi-recipient send. Defaults to `"individual"` — see [Read Scope](/docs/interfaces/notifications/categories-and-subjects#read-scope). |
+| `idempotencyKey` | `string` (optional) | Stable event key, unique across producers: prefix it with your module ID. Reusing it for a recipient preserves the original notification and dismissal state. |
+| `dedupe` | `boolean` (optional) | `false` stores every unkeyed send, even one identical to a notification the recipient got less than 10 seconds earlier. Defaults to `true`; see below. |
+
+Pick `"shared"` for alerts that only need one person to act on them, and `"individual"` for anything each recipient has to see for themselves.
+
+```typescript
+import type { SendOptions } from "@antelopejs/interface-dms/notifications/types";
+
+const forEveryone: SendOptions = { readScope: "individual" };
+const handleOnce: SendOptions = { readScope: "shared" };
+```
+
+## Repeated Sends
+
+An unkeyed notification identical to one the same user received less than 10 seconds earlier is dropped: same recipient, title, description, params, link, category, subject, tone and icon. A form submitted twice, or a hook firing on every instance, leaves one row; two notices worded alike but filed under different subjects, or drawn with a different tone or icon, are two notices. A sender whose repeats are all meant to arrive (a counter ticking, a chat) passes `{ dedupe: false }` to any send method. The check holds across instances: the row ID derives from the recipient, the content and a 10-second window, so the database refuses the second insert, and a copy from the window before also counts. The same notification sent again later arrives as usual, and so does one whose params differ (a count, a timestamp). Keyed sends are deduplicated by their key instead, as described below.
+
+## Retrying Durable Events
+
+Use the same event key on every outbox retry. The first delivery stored under a key wins: a later send under the same key returns without storing anything, even when its content differs (a count recomputed on retry, a timestamp), so a producer that keys a notification per period does not have to guard against a duplicate-key error. The explicit method is equivalent to passing `idempotencyKey` to `toUsers`; its key argument takes precedence over a key in `options`.
+
+The key is shared by every module of the deployment: the DMS stores one row per key and recipient, whatever module or category sent it. Because a reused key counts as already delivered, two modules that happen to build the same key for the same user would lose the second notification without any error. Namespace your keys with your module ID (`mailing:digest:2026-10-13T09`, not `digest:2026-10-13T09`).
+
+```typescript
+await shipped.toUsers([ownerId, managerId], { idempotencyKey: event.id });
+await shipped.toUsersIdempotently([ownerId, managerId], event.id);
+```
+
+The DMS derives a namespaced SHA-256 row ID from the event key and recipient ID and performs a plain atomic insert. After an insert error, it reads that exact ID and accepts only a matching stored delivery, including its subject, content, and read group. Other errors propagate so an outbox can retry; duplicate attempts never replace the row or reset its timestamps or read state.
+
+Single and bulk dismissal retain keyed rows as hidden delivery receipts. Lists, previews, counts, individual lookups, and read operations exclude these rows; retries do not recreate them. Unkeyed notifications retain physical deletion and fresh delivery on every send outside the 10-second [repeat window](#repeated-sends). Receipts retain notification content indefinitely: do not hard-delete or expire these rows while their event keys can still be retried, and account for this retention when designing data-erasure policies.
+
+Shared-read sends derive a stable group ID from the event key. Recipient membership and preferences are evaluated again on each attempt, so a retry can add previously missing recipients without duplicating successful deliveries. A recipient added after another recipient has already marked the group read starts unread; retries preserve existing recipients' state rather than replaying past read actions.
+
+Realtime publishing remains best-effort and occurs only after a newly inserted delivery. A crash or lost acknowledgement can leave a stored notification without a realtime event; retrying does not replay realtime. Delivery gates still apply, and skipped recipients do not receive receipts.
+
+Consumers that support older DMS packages must fail closed instead of passing an option an old runtime silently ignores. Feature-detect the explicit method and retain pending outbox work until the DMS package and runtime are upgraded together to a version containing it:
+
+```typescript
+if (!("toUsersIdempotently" in shipped) || typeof shipped.toUsersIdempotently !== "function") {
+  throw new Error("DMS idempotent notification delivery is unavailable");
+}
+await shipped.toUsersIdempotently([ownerId, managerId], event.id);
+```
+
+Every keyed dispatch also checks the implementation's `SupportsIdempotency` interface capability before sending. A new local builder paired with an old DMS implementation therefore rejects rather than silently delivering without deduplication.
+
+## Delivery Rules
+
+The DMS applies the same rules to every dispatch method, since `toUsers`, `toRoles` and `broadcast` all resolve to per-user deliveries:
+
+- **The subject must be registered.** A notification whose subject was never declared through `NotificationSubject()` is dropped. This is what makes registration order matter — see [Declaration Order](/docs/interfaces/notifications/categories-and-subjects#declaration-order).
+- **The user preference is honored.** Delivery is skipped when the recipient has turned off the `categoryId:subjectId` pair in their notification settings. Preferences default to enabled, so a subject a user has never touched is delivered.
+- **Skipping is silent.** A gated-out delivery is not an error: the promise resolves normally, and there is no per-recipient result to inspect.
+- **Delivery is per recipient.** Each recipient gets their own stored notification. With `readScope: "shared"` those copies are tied together for read state; they are still separate rows.
+- **Stored notifications are pushed live.** Each delivery is also published on the recipient's realtime stream, so the dashboard's badge and preview update without a reload.
+
+Because a send can be skipped for reasons outside your control, treat notifications as best-effort: do not make a workflow depend on one having been stored. Wrapping the call so a failure cannot break the operation that triggered it is a common pattern:
+
+```typescript
+import { Logging } from "@antelopejs/interface-core/logging";
+import {
+  AccountSubject,
+  Notification,
+} from "@antelopejs/interface-dms/notifications";
+
+export async function notifyWelcome(userId: string, name: string) {
+  try {
+    await Notification()
+      .icon("i-ph-hand-waving")
+      .title("$dms.notifications.messages.welcome.title")
+      .description("$dms.notifications.messages.welcome.description")
+      .params({ name })
+      .subject(AccountSubject)
+      .linkTo("/settings/user/profile")
+      .build()
+      .toUser(userId);
+  } catch (error) {
+    Logging.Error(`Failed to notify "${userId}": ${String(error)}`);
+  }
+}
+```
+
+## Importing the Types
+
+`Notification()` is exported from the interface root, and the data types from the `types` subpath. The two classes are exported from the modules that define them, which you only need when you want to name them explicitly:
+
+| Symbol | Import from |
+| ------ | ----------- |
+| `Notification` | `@antelopejs/interface-dms/notifications` |
+| `NotificationData`, `SendOptions`, `RequiredFields` | `@antelopejs/interface-dms/notifications/types` |
+| `NotificationBuilder` | `@antelopejs/interface-dms/notifications/builder` |
+| `SendableNotification` | `@antelopejs/interface-dms/notifications/sendable` |
+
+`NotificationData` is the shape the builder assembles — `icon`, `title`, `description` and `subject`, plus the optional `linkTo` and `params`. Naming it is useful when you carry notification content around before building it:
+
+```typescript
+import { Notification } from "@antelopejs/interface-dms/notifications";
+import type { NotificationData } from "@antelopejs/interface-dms/notifications/types";
+import type { SendableNotification } from "@antelopejs/interface-dms/notifications/sendable";
+
+function fromData(data: NotificationData): SendableNotification {
+  const builder = Notification()
+    .icon(data.icon)
+    .title(data.title)
+    .description(data.description)
+    .subject(data.subject);
+
+  if (data.linkTo) {
+    builder.linkTo(data.linkTo);
+  }
+  if (data.params) {
+    builder.params(data.params);
+  }
+
+  return builder.build();
+}
+```

package/docs/5.html-render/.navigation.yml

@@ -0,0 +1,2 @@
+title: HTML render
+icon: i-lucide-mail