@antelopejs/interface-dms 0.7.1 → 0.7.3

package/docs/3.base/9.helpers.md

@@ -0,0 +1,414 @@
+---
+title: "Helpers"
+description: "A few small surfaces sit beside the components and support them: the `@Searchable` decorator that tells a list route which columns free-text search covers, the export-job runner behind every long download, the…"
+---
+
+# Helpers
+
+## Overview
+
+A few small surfaces sit beside the components and support them: the `@Searchable` decorator that tells a list route which columns free-text search covers, the export-job runner behind every long download, the tenant-export archive built on top of it, and two helper modules — file references and archive-mode defaults — that the table view uses internally and that are available when you build equivalent routes yourself.
+
+```typescript
+import { Searchable, SearchableMeta } from "@antelopejs/interface-dms/base/searchable";
+import { runExportJob } from "@antelopejs/interface-dms/base/export-jobs";
+import { collectFileRefs } from "@antelopejs/interface-dms/base/helpers/file-refs";
+import { applyArchiveModeDefaultRules } from "@antelopejs/interface-dms/base/helpers/archive-mode-helpers";
+import { startTenantExportJob } from "@antelopejs/interface-dms/base/tenant-export-archive";
+```
+
+`Searchable`, `SearchableMeta` and everything in `export-jobs` and `tenant-export-archive` are also exported from the package root, `@antelopejs/interface-dms/base`. The two `helpers/*` modules are not in that barrel and are imported from their own subpath.
+
+## Make Columns Searchable
+
+`@Searchable(compareMode?)` is a property decorator on a data controller field. It records the field, and the compare mode used to match it, on the controller's `SearchableMeta`. The list route reads that record when the request carries a `search` query parameter and ORs one condition per recorded field into the query. A field does not have to be `filterable` to be searched: it is matched with its data-api filter when it has one, and otherwise with the filter of its `@Column` type. A controller with no searchable field ignores the parameter.
+
+```typescript
+import { Listable } from "@antelopejs/interface-data-api/metadata";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types";
+import { Searchable } from "@antelopejs/interface-dms/base/searchable";
+import {
+  Column,
+  Exported,
+} from "@antelopejs/interface-dms/base/table-view";
+
+export class customerDataAPI extends DataController(/* … */) {
+  @Searchable()
+  @Listable()
+  @Exported()
+  @Column({ name: "Name", type: new DefaultDataTypes.StringType() })
+  declare name: string;
+
+  @Searchable("is")
+  @Listable()
+  @Column({ name: "Reference", type: new DefaultDataTypes.StringType() })
+  declare reference: string;
+}
+```
+
+| Parameter | Description |
+| --- | --- |
+| `compareMode` | Id of a registered `DataCompareMode` used to match this field. Defaults to `"contains"`. |
+
+The id is the one the mode was registered under with `@RegisterDataCompareMode` — `"contains"`, `"is"`, `"array_contains_string"` and the rest of the catalogue are listed in [Data Types](/docs/interfaces/base/data-types).
+
+### SearchableMeta
+
+`SearchableMeta` is the metadata object the decorator writes to. Read it with `GetMetadata(controller, SearchableMeta)` from `@antelopejs/interface-core`.
+
+| Member | Description |
+| --- | --- |
+| `searchableFields` | `Record<string, string>` mapping field name to compare-mode id. |
+| `setSearchableField(key, compareMode)` | Records one field. Called by the decorator. |
+| `getSearchableFields()` | Returns the same record. |
+
+## Run an Export Job
+
+`runExportJob` starts a background job, hands you a ticket immediately, and leaves the generation running. The pattern is three routes: one that starts the job, one that reports its progress, one that streams the finished file. The table view's export action is built on exactly these three, and any route of your own can reuse them.
+
+```typescript
+import fs from "node:fs";
+import {
+  Context,
+  Get,
+  Parameter,
+  type RequestContext,
+} from "@antelopejs/interface-api";
+import {
+  PageController,
+  pagesCategory,
+  RegisterPage,
+} from "@antelopejs/interface-dms/page";
+import { AuthUser } from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import {
+  downloadExportJob,
+  getExportJobStatus,
+  runExportJob,
+} from "@antelopejs/interface-dms/base/export-jobs";
+
+const SCOPE = "customer-report";
+
+@RegisterPage()
+export class ReportPage extends PageController("report", {
+  displayName: "Reports",
+  icon: "i-ph-file-csv",
+  category: pagesCategory,
+}) {
+  @Get("/report/start")
+  start(@Context() ctx: RequestContext, @AuthUser() user: User) {
+    return runExportJob<{ year: number }>({
+      ctx,
+      user,
+      scope: SCOPE,
+      context: { year: new Date().getFullYear() },
+      filename: "customers",
+      extension: "csv",
+      contentType: "text/csv; charset=utf-8",
+      generate: async ({ localPath, context, reportProgress }) => {
+        fs.writeFileSync(localPath, "id,name\n");
+        // … append rows, calling reportProgress(0-99) as you go
+        await reportProgress(50);
+      },
+    });
+  }
+
+  @Get("/report/status/:jobId")
+  status(
+    @Context() ctx: RequestContext,
+    @Parameter("jobId", "param") jobId: string,
+    @AuthUser() user: User,
+  ) {
+    return getExportJobStatus(ctx, user, jobId, { scope: SCOPE });
+  }
+
+  @Get("/report/download/:jobId")
+  download(
+    @Context() ctx: RequestContext,
+    @Parameter("jobId", "param") jobId: string,
+    @AuthUser() user: User,
+  ) {
+    return downloadExportJob(ctx, user, jobId, { scope: SCOPE });
+  }
+}
+```
+
+### RunExportJobOptions
+
+```typescript
+function runExportJob<TContext = unknown>(
+  opts: RunExportJobOptions<TContext>,
+): Promise<ExportJobTicket>;
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `ctx` | `RequestContext` | The request. The job is stored in the schema of the tenant the request resolves to. Required. |
+| `user` | `User` | The owner of the job. Required; a missing user fails with `401`. |
+| `scope` | `string` | Free-form identifier for the origin of the job, checked again on status and download when you pass it there. Required. |
+| `context` | `TContext` | Scope-specific payload stored with the job and handed back to `generate` and to `isOwnedBy`. |
+| `filename` | `string` | Base name of the produced file, without extension or timestamp. Required. |
+| `extension` | `string` | File extension. Required. |
+| `contentType` | `string` | MIME type used when uploading and when streaming the file back. Required. |
+| `delivery` | `string` | Delivery mode id. Defaults to `DEFAULT_DELIVERY`; an unknown id fails with `400`. |
+| `deliveryPath` | `string` | Client-side path a delivered link points at. Required by email delivery. |
+| `retainUntilExpiry` | `boolean` | Keep the record and its stored file after a download, until the stale-export sweep expires them. |
+| `maxExecutionTimeMs` | `number` | Abort budget for `generate`. Defaults to 10 minutes. |
+| `generate` | `(ctx: ExportJobGenerateContext<TContext>) => Promise<ExportJobResultSummary \| void>` | Writes the file. Required. |
+
+`runExportJob` creates the job record, then starts `generate` without awaiting it and returns the ticket. When `generate` resolves, the file at `localPath` is uploaded to file storage and the job is marked completed; when it throws or the abort budget expires, the scratch file is removed and the job is marked failed.
+
+A generator that assembled its output from several sources reports what was missing by returning a summary instead of nothing:
+
+```typescript
+interface ExportJobResultSummary {
+  partial: boolean;
+  failures: ExportJobFailure[];
+}
+
+interface ExportJobFailure {
+  source: string;
+  error: string;
+}
+```
+
+The summary is stored on the job and surfaced on its status, so a consumer can tell a complete export from one that succeeded with holes. `source` names the part that failed — a contributing module id, typically.
+
+By default a job is deleted once it has been downloaded. Set `retainUntilExpiry` for a scope whose jobs outlive their first download: one that surfaces a job history, or one whose result is reached through a delivered link.
+
+| `ExportJobTicket` field | Type | Description |
+| --- | --- | --- |
+| `jobId` | `string` | Identifier to poll and download with. |
+| `extension` | `string` | Echo of the requested extension. |
+| `filename` | `string` | Echo of the requested base name. |
+
+### ExportJobGenerateContext
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `jobId` | `string` | Identifier of this job. |
+| `tenantId` | `string` | Tenant the job belongs to. |
+| `localPath` | `string` | Path your generator writes the file to. |
+| `context` | `TContext` | The payload passed as `context` to `runExportJob`. |
+| `reportProgress` | `(progress: number) => Promise<void>` | Records progress. The value is floored and clamped to `0`–`99`; repeating the last value writes nothing. Throws once the job is aborted. |
+| `signal` | `AbortSignal` | Aborted when the job exceeds `maxExecutionTimeMs`. |
+
+### Status and Download
+
+```typescript
+function getExportJobStatus<TContext = unknown>(
+  ctx: RequestContext,
+  user: User,
+  jobId: string,
+  access?: ExportJobAccessOptions<TContext>,
+): Promise<ExportJobStatus>;
+
+function downloadExportJob<TContext = unknown>(
+  ctx: RequestContext,
+  user: User,
+  jobId: string,
+  access?: ExportJobAccessOptions<TContext>,
+): Promise<void>;
+```
+
+`ExportJobStatus` carries `status: ExportStatus`, `progress: number`, and the optional `error`, `filename`, `extension`, `result` and `expiresAt`. `ExportStatus` is the `pending` / `completed` / `failed` enum from [Shared Types](/docs/interfaces/base/types). `result` is the `ExportJobResultSummary` the generator returned, present once the job completed; `expiresAt` is when the sweep will drop the record and its stored file.
+
+`getExportJobExpiry(record)` computes that moment from a record directly — `updatedAt` plus `EXPORT_TTL_MS`, which is one day.
+
+`downloadExportJob` requires a completed job with a stored result — anything else fails with `400` or `500`. It sets `Content-Disposition` (with a filename built by `buildExportFilename`), `Content-Length` when the size is known, and `Access-Control-Expose-Headers`, then pipes the stored object to the response. The function returns as soon as the pipe is set up rather than awaiting it; once the response stream closes, the stored object and the job record are both deleted.
+
+`loadExportJobForUser(ctx, user, jobId, access?)` is the shared step underneath both: it resolves the tenant, loads the record, runs the access checks, and returns the model, the record and the parsed context. Use it when you need the record itself rather than its status.
+
+`downloadExportJob` deletes the stored object and the job record once the response stream closes — unless the job was started with `retainUntilExpiry`, in which case both survive until the sweep.
+
+### List a Caller's Jobs
+
+```typescript
+function listExportJobs(
+  ctx: RequestContext,
+  user: User,
+  options?: ListExportJobsOptions,
+): Promise<ExportJobSummary[]>;
+```
+
+Returns the caller's own jobs, most recent first — the history a scope such as a tenant data export surfaces next to its request action. `ListExportJobsOptions` narrows it: `scope` restricts to one scope, `limit` caps the count and defaults to 20.
+
+`ExportJobSummary` extends `ExportJobStatus` with `jobId`, `scope` and `createdAt`. Listing is scoped to the caller, so it needs no access options: another user's jobs are never returned.
+
+### Access Checks
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `scope` | `string` | When set, the job's stored `scope` must match. |
+| `isOwnedBy` | `(record, context, user) => boolean` | Extra ACL evaluated after the ownership and scope checks. |
+
+`ExportJobOwnership<TContext>` carries only `isOwnedBy`; `ExportJobAccessOptions<TContext>` extends it with `scope`. The job's `userId` is always compared against the caller regardless of what you pass, and every failed check answers `403`.
+
+### Formats and Delivery
+
+An export format is an `Exporter`, and a delivery mode is a `Deliverer`. Both are looked up by id.
+
+```typescript
+import {
+  DEFAULT_DELIVERY,
+  DEFAULT_EXPORT_FORMAT,
+  getDeliverer,
+  getExporter,
+} from "@antelopejs/interface-dms/base/export-jobs";
+
+const exporter = getExporter(DEFAULT_EXPORT_FORMAT); // "csv"
+const writer = exporter.createWriter(localPath);
+writer.writeHeaders(["id", "name"]);
+writer.appendRow(["id", "name"], { id: "1", name: "Ada" });
+writer.close();
+```
+
+| Symbol | Shape | Description |
+| --- | --- | --- |
+| `Exporter` | `{ extension, contentType, createWriter(filePath): ExportWriter }` | One output format. |
+| `ExportWriter` | `{ writeHeaders(headers), appendRow(headers, row), close() }` | Incremental writer for one file. |
+| `Deliverer` | `{ validate?(options: ExportJobDeliveryOptions): void; deliver(exportRecord, resultPath): Promise<void> }` | One delivery mode. `validate` runs when the job is created, so an unusable delivery fails fast rather than after generation. |
+| `ExportJobDeliveryOptions` | `{ delivery: string; deliveryPath?: string }` | What `validate` is given. |
+| `getExporter(format)` | `Exporter` | Throws `400` for an unknown format. |
+| `getDeliverer(delivery)` | `Deliverer` | Throws `400` for an unknown delivery mode. |
+| `DEFAULT_EXPORT_FORMAT` | `"csv"` | The format `csv` writes a BOM-prefixed comma-separated file; array values are joined with `;` and dates written as ISO strings. |
+| `DEFAULT_DELIVERY` | `"download"` | Keeps the result in storage for the download route. |
+| `EMAIL_DELIVERY` | `"email"` | Mails the recipient a link instead. Requires `deliveryPath`: the link is that path with `?exportJob=<jobId>` appended. |
+| `EXPORT_JOB_QUERY_PARAM` | `"exportJob"` | The query parameter carrying the job id on a delivered link. Read it on the target page to resume the download. |
+| `EXPORT_TTL_MS` | one day | How long a job and its stored file survive before the sweep drops them. |
+
+`buildExportFilename(base, extension)` produces the name sent to the browser: the base and an ISO timestamp, both stripped of anything outside `[a-zA-Z0-9._-]`, joined by `-` and suffixed with the extension.
+
+### Storage and Maintenance
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `getExportLocalScratchPath` | `(exportId, extension) => string` | Path in the OS temp directory a job writes to. |
+| `uploadExportToStorage` | `(localPath, tenantId, exportId, extension, contentType) => Promise<string>` | Uploads the scratch file through a presigned URL, deletes it locally, and returns the resource key. |
+| `streamExportFromStorage` | `(resourceKey) => Promise<StreamedExport>` | Opens a read stream. `StreamedExport` is `{ body: ReadableStream<Uint8Array>; size: number \| undefined }`. |
+| `deleteExportFromStorage` | `(resourceKey) => Promise<void>` | Removes a stored result, ignoring failures. |
+| `sweepStaleExportsAllTenants` | `(ttlMs) => Promise<void>` | Deletes every job whose `updatedAt` is older than `ttlMs`, in every tenant, along with its stored file. |
+| `deleteAllExportsForTenant` | `(tenantId) => Promise<void>` | Deletes every job of one tenant and its stored files. |
+
+## Export a Tenant's Data
+
+`startTenantExportJob` runs the tenant data export as a background job: it asks every registered contributor for its slice, assembles the answers into one ZIP, and hands you the same ticket `runExportJob` does.
+
+```typescript
+import { Context, Get, type RequestContext } from "@antelopejs/interface-api";
+import { AuthTenantOwner } from "@antelopejs/interface-dms/guards";
+import {
+  PageController,
+  RegisterPage,
+  settingsCategory,
+} from "@antelopejs/interface-dms/page";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import {
+  EMAIL_DELIVERY,
+  listExportJobs,
+} from "@antelopejs/interface-dms/base/export-jobs";
+import { startTenantExportJob } from "@antelopejs/interface-dms/base/tenant-export-archive";
+
+@RegisterPage()
+export class ExportsPage extends PageController("exports", {
+  displayName: "Exports",
+  icon: "i-ph-archive",
+  category: settingsCategory,
+}) {
+  @Get("/exports/start")
+  start(@Context() ctx: RequestContext, @AuthTenantOwner() user: User) {
+    return startTenantExportJob({
+      ctx,
+      user,
+      scope: "tenant-export",
+      filename: "tenant-data",
+      delivery: EMAIL_DELIVERY,
+      deliveryPath: "/settings/exports",
+    });
+  }
+
+  @Get("/exports/history")
+  history(@Context() ctx: RequestContext, @AuthTenantOwner() user: User) {
+    return listExportJobs(ctx, user, { scope: "tenant-export" });
+  }
+}
+```
+
+`StartTenantExportJobOptions` is `ctx`, `user`, `scope`, `filename`, and the optional `delivery`, `deliveryPath` and `maxExecutionTimeMs` — the same fields `runExportJob` takes, minus the ones the archive fixes itself: the extension is `TENANT_EXPORT_EXTENSION` (`"zip"`), the content type `TENANT_EXPORT_CONTENT_TYPE` (`"application/zip"`), and `retainUntilExpiry` is always on, since the archive is reachable from a delivered link and from the job history long after the first download.
+
+`buildTenantExportArchive(options)` is the step underneath, for a caller that runs the archive outside a job. Its `BuildTenantExportArchiveOptions` are `tenantId`, the `localPath` to write the ZIP to, an `AbortSignal`, and an optional `reportProgress`; it resolves to the `ExportJobResultSummary` describing which contributors failed.
+
+Contributing to the archive is the other side of this: a module registers a handler on the `TENANT_DATA_EXPORT` hook of the [Core](/docs/interfaces/core/introduction) domain, and that hook's page covers the archive sink, the manifest and what a failing contributor does to the result.
+
+## Track File References
+
+A `file` or `image` column stores keys into file storage, not the bytes. The helpers in `helpers/file-refs` compare or remap references in the supplied records. They do not authorize access, validate upload provenance, or determine whether another record still references an object. Use the [native save integration](/docs/components/file-storage#custom-save-routes) for promotion and cleanup in custom write routes.
+
+```typescript
+import {
+  collectFileRefs,
+  dedupeRefs,
+  diffRemovedRefs,
+  type FileRef,
+  hasFileColumns,
+  remapRecordFileKeys,
+} from "@antelopejs/interface-dms/base/helpers/file-refs";
+import { GetMetadata } from "@antelopejs/interface-core";
+import { TableViewMeta } from "@antelopejs/interface-dms/base/table-view";
+
+const { columns } = GetMetadata(customerDataAPI, TableViewMeta);
+
+if (hasFileColumns(columns)) {
+  const removed: FileRef[] = diffRemovedRefs(
+    collectFileRefs(columns, rowBeforeEdit),
+    collectFileRefs(columns, rowAfterEdit),
+  );
+  // Other records may still reference these keys.
+}
+```
+
+The three functions that inspect columns take the column map first. An entry only needs a `type`, so `TableViewMeta.columns` is passed straight in; columns whose data type is neither `file` nor `image` are skipped. `dedupeRefs` and `diffRemovedRefs` work on the resulting ref lists alone.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `hasFileColumns` | `(columns) => boolean` | Whether any column's data type is `file` or `image`. |
+| `collectFileRefs` | `(columns, row) => FileRef[]` | Every key the row holds in its file and image columns. Nested objects and arrays are walked; an `image` value contributes its `key` property, a `file` value contributes the string itself. |
+| `dedupeRefs` | `(refs) => FileRef[]` | Drops duplicates, comparing storage and key together. |
+| `diffRemovedRefs` | `(before, after) => FileRef[]` | Deduplicated refs present in `before` and absent from `after`. |
+| `remapRecordFileKeys` | `(columns, record, mapKey) => Promise<Record<string, unknown>>` | Returns a copy of the record with every key in a file or image column replaced by `await mapKey(key, storage)`, preserving the surrounding shape. |
+
+`FileRef` is `{ key: string; storage?: string }`. The `storage` is read from the data type's `storage` option when it declares one, and left undefined otherwise, so a ref always carries the storage its key belongs to.
+
+## Archive-Mode Defaults
+
+`applyArchiveModeDefaultRules(rowActions, archiveField)` derives the row-action rules that make archive mode coherent: archived rows offer restore and delete, live rows offer edit, duplicate and archive. `TableView` calls it for you when `archiveMode` is set; call it directly only when you assemble `TableViewRowActionOptions` yourself.
+
+```typescript
+import { applyArchiveModeDefaultRules } from "@antelopejs/interface-dms/base/helpers/archive-mode-helpers";
+import { startTenantExportJob } from "@antelopejs/interface-dms/base/tenant-export-archive";
+
+const rowActions = applyArchiveModeDefaultRules(
+  { edit: true, delete: true, archive: true, restore: true },
+  "archived",
+);
+```
+
+| Action | Default rule |
+| --- | --- |
+| `edit` | `{ field: archiveField, notEquals: true }` |
+| `duplicate` | `{ field: archiveField, notEquals: true }` |
+| `archive` | `{ field: archiveField, notEquals: true }` |
+| `restore` | `{ field: archiveField, equals: true }` |
+| `delete` | `{ field: archiveField, equals: true }` |
+
+The function returns a new options object and never rewrites a decision you made explicitly:
+
+| Value you passed | Result |
+| --- | --- |
+| Nothing for that action | `{ isEnabled: true, rule: <default> }` |
+| `true` | `{ isEnabled: true, rule: <default> }` |
+| `false`, or a config with `isEnabled: false` | Left as is; no rule added. |
+| A config without a `rule` | The config, plus the default rule. |
+| A config with a `rule` | Left as is. |
+
+Passing `undefined` as `rowActions` yields an object carrying only the five defaults. The rule shapes themselves are documented in [Shared Types](/docs/interfaces/base/types), and how the table view consumes them in [Tables](/docs/interfaces/base/tables).

package/docs/4.notifications/.navigation.yml

@@ -0,0 +1,2 @@
+title: Notifications
+icon: i-lucide-bell

package/docs/4.notifications/1.introduction.md

@@ -0,0 +1,81 @@
+---
+title: "Introduction"
+description: "How backend code puts a message in a user's notification list: categories, subjects and sending."
+---
+
+# Introduction
+
+## Overview
+
+The `notifications` domain of `@antelopejs/interface-dms` is how backend code puts a message in a user's notification list. It has two halves: a taxonomy you declare once, and a builder you use every time you send.
+
+The taxonomy is two levels deep. A **category** groups related notifications, a **subject** sits under a category and names one kind of message, and every notification is filed under a subject. Users manage what they receive per subject from their notification settings, so the subject you pick decides how the message is grouped for the user and whether it is delivered at all.
+
+Both levels are declared at import time: `NotificationCategory()` first, then the `NotificationSubject()` calls that sit under it. Sending is a fluent chain: `Notification()` opens a builder, the setters fill in the icon, title, description and subject, and `.build()` returns an immutable `SendableNotification` you dispatch to one user, a list of users, the holders of a set of roles, or everyone.
+
+See the [notification bell before and after reading](/docs/auth-and-tenancy/authentication#read-notifications) and the [category and subject preferences](/docs/auth-and-tenancy/authentication#notification-preferences) for real dashboard examples. The demonstration sends to one disposable account and checks a second session of that account; it does not broadcast or send email.
+
+## Key Features
+
+- **Two-level taxonomy** — Categories group subjects, and subjects classify notifications; the `categoryId:subjectId` pair is the key a user's preferences are stored under.
+- **Declarative registration** — `NotificationCategory()` and `NotificationSubject()` register at import time and return plain info objects you keep as constants and pass around.
+- **Built-in system subjects** — `GeneralSubject`, `SecuritySubject`, `AccountSubject`, `CollaborationSubject` and `AutomationSubject` cover the common platform messages without declaring anything.
+- **Type-checked builder** — The builder tracks which fields have been supplied in its type parameter, so `.build()` does not compile until icon, title, description and subject are all set.
+- **Four dispatch targets** — Send to one user, a list of users, every user holding at least one of a set of roles, or every user.
+- **Shared or individual read state** — A multi-recipient send can give each recipient their own read state, or group the copies so one recipient reading it clears it for all of them.
+- **Preference-aware delivery** — Sends are silently skipped for users who turned the subject off, and `togglePermission` marks the subjects users may not turn off.
+
+## Dependencies
+
+This interface relies on the following AntelopeJS packages:
+
+- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - Interface function and registration proxies used to reach the DMS implementation.
+
+The implementation lives in the DMS module, so the interface only works in a project that loads `@antelopejs/dms`. Sending to users and roles uses the DMS user and role identifiers described in the DMS auth and tenancy guide.
+
+## Quick Start
+
+The following example declares a category with one subject and sends a notification against it.
+
+```typescript
+import {
+  Notification,
+  NotificationCategory,
+  NotificationSubject,
+} from "@antelopejs/interface-dms/notifications";
+
+// Declared at import time — the category first, then its subjects
+export const shopCategory = NotificationCategory("shop", {
+  labelKey: "shop.notifications.categories.shop",
+  descriptionKey: "shop.notifications.categories.shop_desc",
+  icon: "i-ph-shopping-cart",
+});
+
+export const orderSubject = NotificationSubject("orders", {
+  category: shopCategory,
+  labelKey: "shop.notifications.subjects.orders",
+  togglePermission: "default",
+});
+
+export async function notifyOrderShipped(
+  userId: string,
+  orderRef: string,
+): Promise<void> {
+  await Notification()
+    .icon("i-ph-truck")
+    .title("$shop.notifications.order_shipped.title")
+    .description("$shop.notifications.order_shipped.description")
+    .params({ orderRef })
+    .subject(orderSubject)
+    .linkTo("/shop/orders")
+    .build()
+    .toUser(userId);
+}
+```
+
+The user sees the notification in the dashboard, and finds an `orders` toggle under a `shop` group in their notification settings.
+
+## Documentation Sections
+
+- [Categories and Subjects](/docs/interfaces/notifications/categories-and-subjects) - Declare categories and subjects, control what users may toggle, and use the built-in system subjects
+- [Sending Notifications](/docs/interfaces/notifications/sending) - Build a notification, dispatch it to users, roles or everyone, and understand what gates delivery