Notifications API

This page lists everything buildContentNotifications accepts and how its notifications behave. For a guided setup, follow Notifications. Examples use newsroom.comment and newsroom.article from the newsroom plugin.

buildContentNotifications()Copy Anchor Link

import { buildContentNotifications } from "@vitnode/core/content/server";

export const commentNotifications = buildContentNotifications({
  content: commentContentType,
  root: articleContentType,
  rules: {
    replies: { id: "newsroom.comment_reply", preset: "threadReply" /* ... */ },
  },
});

Server-only, from @vitnode/core/content/server. Register the result in buildApiPlugin({ contentNotifications: [commentNotifications] }). Each rule becomes one notification type, registered with the plugin.

It throws ContentEngineError when an author field is not a to-one, shared field.user(), when threadReply is used without thread or without root, when two rules share an id, or when rules is empty. An invalid id or category throws NotificationRegistryError. At startup, an unregistered content type or a root that is not the thread.root target stops the app with a message naming the plugin.

Options shared by the presetsCopy Anchor Link

Stable idsCopy Anchor Link

id is stored with every notification event and every member's preference, so it must never change. The key in rules is not stored anywhere, so rename it freely. Two rules, in any plugin, cannot share an id.

threadReply presetCopy Anchor Link

New comments and replies in a thread. Runs on the record's first publication.

Author fields are typed: only to-one, shared field.user() names of each content type compile. content, parent and root in target are typed rows of their content types.

A member who is both the root's author and the parent's author gets one notification with the reply text. The record's author and whoever made it public, such as the moderator who approved it, never receive it. {actor} is the record's author, or "Someone" when the account is gone.

Without rootAuthorField the rule notifies replies only, so the root type needs no author. {title} reads the root's own row, so a localized title field gives an empty string. Leave {title} out of the texts or pass title.

moderationDecision presetCopy Anchor Link

Tells the submitter of a moderated create or edit what a moderator decided.

The recipient is the submission's authorId, which is the person who proposed the change, not necessarily the record's author. The moderator who decided is not named on the notification and is never notified about their own submission. Approving a create also runs the record's first-publication rules; approving an edit does not.

approvalPending presetCopy Anchor Link

Tells moderators that a new record or a proposed edit waits in the approval queue, and links to that submission at /modcp/approvals/{id}. The Forum plugin registers one for topics and one for comments:

pending: {
  id: "forum.topic_pending",
  preset: "approvalPending",
  messages: {
    label: "@vitnode/forum.notifications.topic_pending.label",
    description: "@vitnode/forum.notifications.topic_pending.description",
    pending: "@vitnode/forum.notifications.topic_pending.pending",
  },
},

The link is fixed, so there is no target, and the text carries no title or body: a moderator who loses access keeps nothing readable about the content. A typical message is "{kind, select, edit {An edit to a topic is waiting for approval in {container}} other {A new topic is waiting for approval in {container}}}".

Recipients are the moderators who could decide the submission: their can_approve for the content type, merged from their own entry and their roles, must cover the container the record is filed in, with the same container scopes the queue uses. Root roles and unrestricted moderator entries qualify everywhere. Being staff, or an administrator, is not enough. Permissions are read from the database when the notification is sent, not from the staff permission cache, and the submitter is never told about their own submission. At most 1000 permission holders are considered per submission; past that, the rest are skipped with a warning in the logs.

The preset only applies to content types whose container collection has publishing policies and whose publicWrite is on, because the queue lists nothing else.

Custom rulesCopy Anchor Link

A rule with type instead of preset publishes an existing notification type on a supported trigger:

import {
  contentNotificationAccess,
  contentNotificationRefs,
} from "@vitnode/core/content/server";
import { buildNotificationType } from "@vitnode/core/api/lib/notifications/registry";
import { z } from "zod";

const deskCommentNotification = buildNotificationType({
  id: "newsroom.desk_comment",
  version: 1,
  schema: z.object({
    contentId: z.string(),
    contentTypeId: z.string(),
    rootId: z.string().nullable(),
    target: z.string(),
  }),
  category: "content",
  label: "newsroom.notifications.desk_comment.label",
  defaults: { inApp: true, email: "none" },
  access: contentNotificationAccess({ content: commentContentType, policy: "content" }),
  present: ({ data, t }) => ({
    title: t("newsroom.notifications.desk_comment.title"),
    target: data.target,
  }),
});

// In buildContentNotifications({ ..., rules }):
deskEditors: {
  type: deskCommentNotification,
  on: "firstPublication",
  // Your own query: the user ids that should hear about it.
  recipients: async ({ c, root }) => await findDeskEditorIds(c, root),
  data: context => ({
    ...contentNotificationRefs(context),
    target: `/news/${String(context.root?.slug)}#comment-${String(context.content.id)}`,
  }),
},

context holds content, parent and root (typed rows, reloaded when the notification is sent), decision (for moderationDecision: submissionId, status, kind, authorId, reviewerId, reason), actorId, trigger, contentTypeId and c. c is the background worker's context. The database works, but there is no signed-in user.

Give a custom type access: contentNotificationAccess({ content, policy }) and spread contentNotificationRefs(context) into its data, so core can check the record again later. Without it, only the type's own access (or none) applies.

Triggers and deduplicationCopy Anchor Link

Two different things decide whether something is sent twice:

• Retrying one operation never duplicates anything. Each publication carries a key built from the operation (first-publication:{contentTypeId}:{id}:{relation} or decision:{contentTypeId}:{submissionId} or approval:{contentTypeId}:{submissionId}), and core stores at most one event per type and key, enforced by a unique index. A worker that publishes and then crashes before finishing finds the same event on its retry.
• Separate operations notify again only when the trigger allows it:

VitNode recognises the first publication inside the publishing transaction, where the record's publishedAt is still NULL under the row lock. Once set, VitNode never rewrites it. That state lives on the record itself, not in anyone's inbox, so deleting a notification or the passing of time cannot make a comment notify again. Content published before the rules existed already has a publishedAt, so adding rules sends nothing for it, and no migration or backfill is needed.

AccessCopy Anchor Link

Core checks a notification type's access before delivering it, before every immediate or digest email and every time an inbox loads. Presets use contentNotificationAccess:

A notification that fails the check shows "This notification is no longer available", with no title, text or link, and its email is skipped. Content Engine reads are not role-based, so add access to buildContentNotifications when your plugin limits content to some members. An email that was already sent cannot be taken back.

Delivery and retriesCopy Anchor Link

1. The operation commits. In the same transaction VitNode stored an intent: a content-notifications task in core_queue holding only ids and the facts of the operation (who acted, which decision). A rolled-back operation leaves no intent. An existing transaction is joined, never committed early.
2. Right after the response, or on the next run of the queue cron, a worker claims the task (FOR UPDATE SKIP LOCKED, so two workers never take the same one), reloads the records and checks they are still public.
3. It resolves recipients, calls your callbacks and publishes every notification of the operation in one transaction.
4. Core fans out to inboxes and emails, checking access again.

A failure retries with backoff up to 5 attempts, then the task is marked failed with its error, visible with the other queue tasks. A rule or content type that is no longer registered is skipped with a warning in the logs, never retried forever. Nothing depends on a long-running process. Any request or the cron endpoint drives the queue.

CleanupCopy Anchor Link

Deleting a record stores a cleanup intent in the same transaction. Once it runs, the record's notifications leave every inbox, and so do notifications about records in its thread when the record was the root, including replies a database cascade removed. A grouped item loses only the deleted contributions and points at the newest one left; it disappears when none is left. Pending emails for those notifications are dropped.

A submission that stops waiting, because a moderator decided it, the author replaced it with a newer proposal or the record was deleted, stores a cleanup intent in the same transaction, and its approvalPending notifications leave the moderators' inboxes. Delivery that has not reached an inbox yet is stopped by the access check; in the rare case that delivery and cleanup cross, the item stays behind as "no longer available".

Hiding is not deleting. A hidden record's notifications are only unavailable until it is shown again. A delete that races with a notification being sent is safe either way, because the access check runs again at every step.

useRevealHashTarget()Copy Anchor Link

import { useRevealHashTarget } from "@vitnode/core/hooks/use-reveal-hash-target";

Brings the element named by the URL hash into view in a paginated list. Until the element exists it loads the next page; then it scrolls the element to the middle of the screen, keeps it there while late content settles and focuses it (give the element tabIndex={-1}).

It returns { status, targetId }, where status is "idle", "searching", "found" or "missing". Show a short notice for "missing" so a stale link is not silently ignored.

RelatedCopy Anchor Link

• Notifications: set up comment and reply notifications step by step.
• Limit access: how core uses access and remove().
• Queue and scale: how the core workers deliver.