Notification

Master switch for the whole notification feature. When false or omitted, nothing fires: the verification notification handler returns early (guarded by notificationConfig?.enabled), the REST notification routes are never registered, and the client generator emits no NOTIFICATION_* actions — even though channels.portal defaults to true. DEFAULT_NOTIFICATION_CONFIG.enabled is false and that default is never merged at runtime, so an omitted enabled behaves as false. Set it to true (alongside verification.enabled and a database) to power the approval-notification experience.

The set of enabled delivery channels.

The channel fallback for POST /send: when the request body omits `channels`, the service delivers over [defaultChannel ?? 'portal']. It is NOT consumed by the rule-driven fan-out — rules with no explicit channel rows always fall back to portal regardless of this value. Set per-rule channels to route those to louder surfaces.

Global key→value pairs interpolated into every template. Call-time context wins for overlapping keys, then these fill the rest. Ideal for {{appName}}, {{supportUrl}} and the like.

List, mark-as-read, manage and send in-app notifications. The NotificationCenter component talks to the read routes. Note the documented { enabled: true } default is not auto-applied at runtime (DEFAULT_NOTIFICATION_CONFIG is defined but never merged), and the two sides read an omitted endpoints block differently: the SERVER registers the routes whenever notification.enabled is true, a database is present, and endpoints.enabled !== false (no verification gate), but the client generator additionally requires verification.enabled AND notification.enabled AND notification.endpoints.enabled to all be explicitly truthy, so an omitted endpoints block generates NO frontend NOTIFICATION_* actions. To get the type-safe actions you must set notification.endpoints.enabled: true explicitly (with verification enabled).

Send a notification to one or more users. Body: { userId | userIds, title, body?, entityName?, entityId?, type?, source?, channels? }. Delivers over the requested channels (defaults to defaultChannel, else portal); type defaults to 'custom'. Recipients are sent with Promise.allSettled so one failure doesn't swallow the rest — the response reports { sent, failed } (failed is the list of user ids that errored). Returns 401 without x-user-id, 403 when the caller isn't godmin or a sendRoles member, and 400 when neither userId nor userIds is supplied.

Send a transactional email to explicit recipients through the configured provider (Gmail or Azure). Body: { to (string | string[]), subject, html?, text?, replyTo? }. Same privileged gate as /send. Returns 503 when no email provider is configured or available, and 502 when the provider reports a delivery failure. On success returns { success: true, data: null }.

When a verification flow fires on_flow_started / on_step_reached / on_approved / on_rejected / on_flow_completed, the service loads the matching notification rules (filtered by node, and by a startsAt/expiresAt window), interpolates their title/body templates and sends to every resolved recipient on the rule's enabled channels.

A rule's recipients can be concrete users, a role (expanded to all its users), the current step's verifier, the entity's creator (the instance's startedBy), or every verifier in the flow — all de-duplicated into a final user-id set before sending.

A portal notification is a row in the notifications table (user_id, title, body, entity_name, entity_id, type, source, is_seen) — exactly what NOTIFICATION_LIST / UNSEEN_COUNT / MARK_SEEN read and what the NotificationBell renders.

An email notification looks up the recipient's address and hands a subject/html to the shared EmailService — so it inherits whichever provider (Gmail or Azure) the email block configures, and logs a warning and skips delivery (without failing the notify call) if email isn't available.

telegram posts the interpolated title/body to the Bot API sendMessage endpoint for the configured chatId; webhook POSTs a JSON payload (user_id, title, body, entity_name, entity_id, type, source, timestamp) to your URL with any configured headers. Both honor timeoutMs (default 10s) and log failures without breaking the notify call.

Paginated in-app notifications with optional limit, offset and type filter.

The unread count — drive the bell badge from this.

Mark a single notification as read.

Mark every notification as read at once.