@digimuza/system-core 0.2.0-rc.2 → 0.3.0-rc.1

package/src/notifications/api.ts

@@ -0,0 +1,477 @@
+// Notifications (DIG-74): the per-transaction notifier, `notify` for modules,
+// and the Convex functions of `defineNotifications`.
+//
+// Access: notifications are the user's own data, guarded like the profile
+// (`getMyProfile`): a human session plus `profile:own:read` (reads) or
+// `profile:own:update` (changes). Every active user holds both through the
+// protected, implicit Profile role, so no catalog migration is needed; API keys
+// get FORBIDDEN (human-only permissions); suspended users get FORBIDDEN.
+import { internalActionGeneric, internalMutationGeneric, makeFunctionReference, mutationGeneric, queryGeneric } from "convex/server"
+import { v } from "convex/values"
+import { isModuleEnabled, isSuperActor, requireHuman, usersWithPermission, type Actor, type UserActor } from "../core/access.js"
+import { recordAudit } from "../core/audit.js"
+import type { Catalog, NotificationTypeDefinition } from "../core/catalog.js"
+import type { SystemContext } from "../core/context.js"
+import { notFound, validation, type SystemError } from "../core/errors.js"
+import type { Notifier, NotifyRequest, NotificationParams } from "../core/notify.js"
+import { P } from "../core/system-modules.js"
+import { toConvexError, type ConvexNotificationsHook, type ConvexSystem, type DbCtx } from "../convex/functions.js"
+import {
+  NOTIFICATION_MARK_ALL_BATCH,
+  NOTIFICATION_PARAMS_MAX,
+  NOTIFICATION_UNREAD_CAP,
+  NOTIFICATIONS_AUDIT,
+  NOTIFY_MAX_RECIPIENTS,
+  type DeliverNotificationEmail,
+  type EmailStatus,
+  type NotificationEmailJob as EmailJob,
+  type NotificationId,
+  type NotificationPreferenceView,
+  type NotificationView,
+  type RenderNotificationEmail,
+} from "./contract.js"
+
+const DEFAULT_LOCALE = "lt"
+const SAFE_HREF = /^\/(?!\/)[^\s\\]*$/
+
+// --- Rows & loosely typed db (the app schema contains `notificationTables`) -------------------
+
+interface NotificationDoc {
+  _id: NotificationId
+  _creationTime: number
+  userId: string
+  type: string
+  params: NotificationParams
+  href?: string
+  inApp: boolean
+  readAt?: number
+  createdAt: number
+  emailStatus: EmailStatus
+  operationId: string
+}
+
+interface PreferenceDoc {
+  _id: string
+  userId: string
+  type: string
+  inApp: boolean
+  email: boolean
+  updatedAt: number
+}
+
+type Docs = { notifications: NotificationDoc; notificationPreferences: PreferenceDoc }
+type Table = keyof Docs
+type IndexQ = { eq(field: string, value: unknown): IndexQ }
+interface Ordered<D> {
+  take(n: number): Promise<D[]>
+  unique(): Promise<D | null>
+  paginate(o: { cursor: string | null; numItems: number }): Promise<{ page: D[]; continueCursor: string; isDone: boolean }>
+}
+interface Query<D> extends Ordered<D> {
+  order(o: "asc" | "desc"): Ordered<D>
+}
+interface Db {
+  query<T extends Table>(t: T): { withIndex(i: string, f: (q: IndexQ) => unknown): Query<Docs[T]> }
+  get<T extends Table>(t: T, id: string): Promise<Docs[T] | null>
+  insert<T extends Table>(t: T, doc: Omit<Docs[T], "_id" | "_creationTime">): Promise<Docs[T]["_id"]>
+  patch<T extends Table>(t: T, id: string, doc: Partial<Omit<Docs[T], "_id" | "_creationTime">>): Promise<void>
+}
+type Scheduler = { runAfter(ms: number, ref: unknown, args: Record<string, unknown>): Promise<unknown> }
+const db = (ctx: { db: unknown }) => ctx.db as Db
+
+// --- Install (the system hook) -----------------------------------------------------------------
+
+export interface NotificationsHookOptions {
+  /** Convex module path (relative to convex/) of the notifications functions. Default "notifications". */
+  functionsModule?: string
+  /**
+   * Whether emails can be sent at all. Set `false` when the app has no
+   * `deliverEmail`: rows then go straight to `skipped` without scheduling an action.
+   * Default true (the action marks `skipped` if an adapter is missing).
+   */
+  email?: boolean
+  /** App-local notification types on top of those declared in module manifests. */
+  types?: readonly NotificationTypeDefinition[]
+  /** Locale for users without a profile locale. Default "lt". */
+  defaultLocale?: string
+}
+
+/** Created by `notificationsHook`; pass it to `defineConvexSystem({ notifications })`. */
+export class NotificationsInstall implements ConvexNotificationsHook {
+  readonly functionsModule: string
+  readonly email: boolean
+  readonly defaultLocale: string
+  private readonly extraTypes: readonly NotificationTypeDefinition[]
+  private readonly cache = new WeakMap<Catalog, ReadonlyMap<string, NotificationTypeDefinition>>()
+
+  constructor(options: NotificationsHookOptions = {}) {
+    this.functionsModule = options.functionsModule ?? "notifications"
+    this.email = options.email ?? true
+    this.defaultLocale = options.defaultLocale ?? DEFAULT_LOCALE
+    this.extraTypes = options.types ?? []
+  }
+
+  /** All notification types of the system: module manifests + `types`. Throws on unknown modules or collisions. */
+  typesOf(catalog: Catalog): ReadonlyMap<string, NotificationTypeDefinition> {
+    let map = this.cache.get(catalog)
+    if (map) return map
+    const out = new Map(catalog.notificationTypes)
+    for (const t of this.extraTypes) {
+      if (!catalog.modules.has(t.moduleId)) throw new Error(`notificationsHook: type ${t.id} belongs to unknown module ${t.moduleId}`)
+      if (out.has(t.id)) throw new Error(`notificationsHook: duplicate notification type ${t.id}`)
+      out.set(t.id, t)
+    }
+    map = out
+    this.cache.set(catalog, map)
+    return map
+  }
+
+  deliverRef() {
+    return makeFunctionReference<"action">(`${this.functionsModule}:_deliverNotificationEmail`)
+  }
+
+  bind(ctx: DbCtx, sys: SystemContext): Notifier {
+    return new BoundNotifier(this, ctx, sys)
+  }
+}
+
+class BoundNotifier implements Notifier {
+  constructor(
+    readonly install: NotificationsInstall,
+    private readonly ctx: DbCtx,
+    private readonly sys: SystemContext,
+  ) {}
+
+  notify(request: NotifyRequest): Promise<number> {
+    return send(this.ctx, this.sys, this.install, request)
+  }
+}
+
+/**
+ * The system hook that installs notifications:
+ *
+ *   defineConvexSystem({ modules, notifications: notificationsHook() })
+ *
+ * Every mutation's SystemContext then carries a notifier, so core services
+ * (role assignment) and modules (finance) notify through `notifyIfInstalled`.
+ */
+export function notificationsHook(options: NotificationsHookOptions = {}): NotificationsInstall {
+  return new NotificationsInstall(options)
+}
+
+// --- Sending -----------------------------------------------------------------------------------
+
+const isPlainObject = (x: unknown): x is Record<string, unknown> => Object.prototype.toString.call(x) === "[object Object]"
+
+function fail(sys: SystemContext, e: SystemError): never {
+  e.operationId ??= sys.operationId
+  throw e
+}
+
+/** The acting human (an agent acts for its owner). */
+const actingUserId = (actor: NotifyRequest["actor"]) => (!actor || actor === "system" ? null : actor.kind === "user" ? actor.userId : actor.ownerId)
+
+async function recipients(sys: SystemContext, request: NotifyRequest): Promise<string[]> {
+  const to = request.to
+  if ("userIds" in to) {
+    const ids = [...new Set(to.userIds)]
+    if (ids.length > NOTIFY_MAX_RECIPIENTS) fail(sys, validation("too_many_recipients", ["to"]))
+    const out: string[] = []
+    for (const id of ids) {
+      const user = await sys.store.get("users", id)
+      if (user?.status === "active") out.push(id)
+    }
+    return out
+  }
+  if (!sys.def.catalog.permissions.has(to.permission)) fail(sys, validation("unknown_permission", ["to"]))
+  const exclude = request.includeActor ? null : actingUserId(request.actor)
+  const { userIds, truncated } = await usersWithPermission(sys, to.permission, NOTIFY_MAX_RECIPIENTS + 1)
+  const out = userIds.filter((id) => id !== exclude).slice(0, NOTIFY_MAX_RECIPIENTS)
+  if (truncated || userIds.filter((id) => id !== exclude).length > NOTIFY_MAX_RECIPIENTS) {
+    sys.logger.warn("notify_recipients_capped", { type: request.type, max: NOTIFY_MAX_RECIPIENTS })
+  }
+  return out
+}
+
+async function preference(ctx: { db: unknown }, userId: string, type: string): Promise<PreferenceDoc | null> {
+  return db(ctx)
+    .query("notificationPreferences")
+    .withIndex("by_user_type", (q) => q.eq("userId", userId).eq("type", type))
+    .unique()
+}
+
+/**
+ * Validates, resolves recipients, applies each recipient's preferences, inserts
+ * rows and schedules emails. Returns the number of recipients notified.
+ */
+async function send(ctx: { db: unknown; scheduler?: unknown }, sys: SystemContext, install: NotificationsInstall, request: NotifyRequest): Promise<number> {
+  const type = install.typesOf(sys.def.catalog).get(request.type)
+  if (!type) fail(sys, validation("unknown_notification_type", ["type"]))
+  if (!isPlainObject(request.params)) fail(sys, validation("invalid_params", ["params"]))
+  let json: string
+  try {
+    json = JSON.stringify(request.params)
+  } catch {
+    fail(sys, validation("invalid_params", ["params"]))
+  }
+  if (json.length > NOTIFICATION_PARAMS_MAX) fail(sys, validation("params_too_large", ["params"]))
+  const params = JSON.parse(json) as NotificationParams
+  if (request.href !== undefined && (request.href.length > 500 || !SAFE_HREF.test(request.href))) fail(sys, validation("invalid_href", ["href"]))
+  const writer = db(ctx) as Partial<Db>
+  if (typeof writer.insert !== "function") throw new Error("notify must run inside a mutation")
+
+  let userIds = await recipients(sys, request)
+  // A disabled module's notifications reach only those who can still use it (an effective Super).
+  if (!isModuleEnabled(sys, await sys.store.get("modules", type.moduleId))) {
+    const supers: string[] = []
+    for (const id of userIds) if (await isSuperActor(sys, { kind: "user", userId: id })) supers.push(id)
+    userIds = supers
+  }
+
+  const scheduler = (ctx as { scheduler?: Scheduler }).scheduler
+  const now = sys.now()
+  let count = 0
+  for (const userId of userIds) {
+    const pref = await preference(ctx, userId, type.id)
+    const inApp = pref?.inApp ?? type.defaultChannels.inApp
+    const email = pref?.email ?? type.defaultChannels.email
+    if (!inApp && !email) continue
+    const emailStatus: EmailStatus = !email ? "none" : install.email && scheduler ? "pending" : "skipped"
+    const row: Omit<NotificationDoc, "_id" | "_creationTime"> = { userId, type: type.id, params, inApp, createdAt: now, emailStatus, operationId: sys.operationId }
+    if (request.href !== undefined) row.href = request.href
+    const id = await db(ctx).insert("notifications", row)
+    if (emailStatus === "pending") await scheduler!.runAfter(0, install.deliverRef(), { notificationId: id })
+    count++
+  }
+  sys.logger.info("notifications_sent", { type: type.id, count })
+  return count
+}
+
+/**
+ * Sends a notification from any mutation of a module:
+ *
+ *   await notify(ctx, sys, { to: { permission: "crm:lead:assign" }, type: "crm.lead_assigned", params: { name }, href: "/app/crm", actor })
+ *
+ * `to.permission` → active users holding it now (via `decide`; module state and
+ * role view apply), without the acting user unless `includeActor`. At most
+ * NOTIFY_MAX_RECIPIENTS. Each recipient's preferences apply; emails are scheduled
+ * only for those with email on. Returns the count; 0 when notifications are not
+ * installed. Throws VALIDATION for an unknown type, bad params or href.
+ * (Core services and package modules use the swallowing `notifyIfInstalled`.)
+ */
+export async function notify(ctx: { db: unknown; scheduler?: unknown }, sys: SystemContext, request: NotifyRequest): Promise<number> {
+  const notifier = sys.notifier
+  if (!(notifier instanceof BoundNotifier)) return 0
+  return send(ctx, sys, notifier.install, request)
+}
+
+// --- Public functions ----------------------------------------------------------------------------
+
+export interface NotificationsOptions {
+  /** Renders subject and text from type + params in the recipient's locale. */
+  renderEmail?: RenderNotificationEmail
+  /** Sends the email. Without it (or without `renderEmail`) email stays `skipped`. */
+  deliverEmail?: DeliverNotificationEmail
+}
+
+const PAGE_DEFAULT = 20
+const PAGE_MAX = 100
+const actorArgs = { apiKey: v.optional(v.string()), operationId: v.optional(v.string()) }
+
+/**
+ * The notifications Convex functions, bound to the app's system (which must have
+ * `notifications: notificationsHook()`):
+ *
+ *   // convex/notifications.ts
+ *   export const { listNotifications, …, _deliverNotificationEmail, _claimNotificationEmail, _recordNotificationEmail } =
+ *     defineNotifications(system, { renderEmail, deliverEmail }).functions
+ */
+export function defineNotifications(system: ConvexSystem, options: NotificationsOptions = {}) {
+  const install = system.notifications
+  if (!(install instanceof NotificationsInstall)) {
+    throw new Error("defineNotifications: install the hook first: defineConvexSystem({ notifications: notificationsHook() })")
+  }
+  const types = install.typesOf(system.definition.catalog)
+  const ref = <T extends "query" | "mutation">(name: string) => makeFunctionReference<T>(`${install.functionsModule}:${name}`)
+  const canEmail = !!options.renderEmail && !!options.deliverEmail
+
+  /** Own data, like the profile: human session + profile:own:read / profile:own:update. */
+  async function guard(ctx: DbCtx, a: { apiKey?: string | undefined; operationId?: string | undefined }, permission: string): Promise<{ sys: SystemContext; actor: UserActor }> {
+    const { sys, actor } = await system.requirePermission(ctx, permission, { apiKey: a.apiKey, operationId: a.operationId })
+    try {
+      return { sys, actor: requireHuman(sys, actor) }
+    } catch (e) {
+      throw toConvexError(e, sys.operationId)
+    }
+  }
+
+  const moduleOf = (type: string) => types.get(type)?.moduleId ?? type.split(".", 1)[0]!
+
+  const view = (n: NotificationDoc): NotificationView => ({
+    id: n._id,
+    type: n.type,
+    moduleId: moduleOf(n.type),
+    params: n.params,
+    href: n.href ?? null,
+    readAt: n.readAt ?? null,
+    createdAt: n.createdAt,
+    emailStatus: n.emailStatus,
+  })
+
+  /** Types whose module the actor can use now (an effective Super sees disabled modules too). */
+  async function visibleTypes(sys: SystemContext, actor: Actor): Promise<NotificationTypeDefinition[]> {
+    const isSuper = await isSuperActor(sys, actor)
+    const out: NotificationTypeDefinition[] = []
+    for (const t of types.values()) {
+      if (isSuper || isModuleEnabled(sys, await sys.store.get("modules", t.moduleId))) out.push(t)
+    }
+    return out.sort((a, b) => a.moduleId.localeCompare(b.moduleId) || a.id.localeCompare(b.id))
+  }
+
+  const prefView = (t: NotificationTypeDefinition, pref: PreferenceDoc | null): NotificationPreferenceView => ({
+    type: t.id,
+    moduleId: t.moduleId,
+    description: t.description ?? null,
+    params: [...(t.params ?? [])],
+    defaultChannels: { inApp: t.defaultChannels.inApp, email: t.defaultChannels.email },
+    inApp: pref?.inApp ?? t.defaultChannels.inApp,
+    email: pref?.email ?? t.defaultChannels.email,
+    customized: !!pref,
+  })
+
+  const unread = (ctx: { db: unknown }, userId: string) =>
+    db(ctx)
+      .query("notifications")
+      .withIndex("by_user_unread", (q) => q.eq("userId", userId).eq("inApp", true).eq("readAt", undefined))
+
+  const functions = {
+    // --- Public ------------------------------------------------------------------------------
+
+    listNotifications: queryGeneric({
+      args: { ...actorArgs, cursor: v.optional(v.union(v.string(), v.null())), limit: v.optional(v.number()), unreadOnly: v.optional(v.boolean()) },
+      handler: async (ctx, a): Promise<{ items: NotificationView[]; cursor: string | null; done: boolean }> => {
+        const { actor } = await guard(ctx, a, P.profileRead)
+        const numItems = Math.min(Math.max(1, Math.floor(a.limit ?? PAGE_DEFAULT)), PAGE_MAX)
+        const q = a.unreadOnly ? unread(ctx, actor.userId) : db(ctx).query("notifications").withIndex("by_user", (q) => q.eq("userId", actor.userId).eq("inApp", true))
+        const res = await q.order("desc").paginate({ cursor: a.cursor ?? null, numItems })
+        return { items: res.page.map(view), cursor: res.isDone ? null : res.continueCursor, done: res.isDone }
+      },
+    }),
+
+    unreadNotificationCount: queryGeneric({
+      args: { ...actorArgs },
+      handler: async (ctx, a): Promise<number> => {
+        const { actor } = await guard(ctx, a, P.profileRead)
+        return (await unread(ctx, actor.userId).take(NOTIFICATION_UNREAD_CAP)).length
+      },
+    }),
+
+    markNotificationRead: mutationGeneric({
+      args: { ...actorArgs, notificationId: v.id("notifications") },
+      handler: async (ctx, a): Promise<{ read: boolean }> => {
+        const { sys, actor } = await guard(ctx, a, P.profileUpdate)
+        const row = await db(ctx).get("notifications", a.notificationId)
+        // Someone else's notification and a missing one look the same.
+        if (!row || row.userId !== actor.userId) throw toConvexError(notFound("notification_not_found"), sys.operationId)
+        if (row.readAt !== undefined) return { read: false }
+        await db(ctx).patch("notifications", row._id, { readAt: sys.now() })
+        return { read: true }
+      },
+    }),
+
+    markAllNotificationsRead: mutationGeneric({
+      args: { ...actorArgs },
+      handler: async (ctx, a): Promise<{ marked: number; done: boolean }> => {
+        const { sys, actor } = await guard(ctx, a, P.profileUpdate)
+        const rows = await unread(ctx, actor.userId).take(NOTIFICATION_MARK_ALL_BATCH + 1)
+        const batch = rows.slice(0, NOTIFICATION_MARK_ALL_BATCH)
+        const now = sys.now()
+        for (const r of batch) await db(ctx).patch("notifications", r._id, { readAt: now })
+        return { marked: batch.length, done: rows.length <= NOTIFICATION_MARK_ALL_BATCH }
+      },
+    }),
+
+    getNotificationPreferences: queryGeneric({
+      args: { ...actorArgs },
+      handler: async (ctx, a): Promise<NotificationPreferenceView[]> => {
+        const { sys, actor } = await guard(ctx, a, P.profileRead)
+        const out: NotificationPreferenceView[] = []
+        for (const t of await visibleTypes(sys, actor)) out.push(prefView(t, await preference(ctx, actor.userId, t.id)))
+        return out
+      },
+    }),
+
+    setNotificationPreference: mutationGeneric({
+      args: { ...actorArgs, type: v.string(), inApp: v.boolean(), email: v.boolean() },
+      handler: async (ctx, a): Promise<NotificationPreferenceView> => {
+        const { sys, actor } = await guard(ctx, a, P.profileUpdate)
+        const type = (await visibleTypes(sys, actor)).find((t) => t.id === a.type)
+        if (!type) throw toConvexError(validation("unknown_notification_type", ["type"]), sys.operationId)
+        const existing = await preference(ctx, actor.userId, type.id)
+        const now = sys.now()
+        if (existing) await db(ctx).patch("notificationPreferences", existing._id, { inApp: a.inApp, email: a.email, updatedAt: now })
+        else await db(ctx).insert("notificationPreferences", { userId: actor.userId, type: type.id, inApp: a.inApp, email: a.email, updatedAt: now })
+        await recordAudit(sys, actor, {
+          action: NOTIFICATIONS_AUDIT.preferenceUpdate,
+          targetType: "notification_type",
+          targetId: type.id,
+          changes: { inApp: a.inApp, email: a.email },
+        })
+        return prefView(type, { _id: existing?._id ?? "", userId: actor.userId, type: type.id, inApp: a.inApp, email: a.email, updatedAt: now })
+      },
+    }),
+
+    // --- Internal (email delivery) -------------------------------------------------------------
+
+    /** Scheduled by `notify` for each row with email `pending`. Never throws. */
+    _deliverNotificationEmail: internalActionGeneric({
+      args: { notificationId: v.id("notifications") },
+      handler: async (ctx, a): Promise<EmailStatus> => {
+        const job = (await ctx.runMutation(ref<"mutation">("_claimNotificationEmail"), { notificationId: a.notificationId })) as EmailJob | null
+        if (!job) return "skipped"
+        let ok = false
+        try {
+          const email = await options.renderEmail!(job.type, job.params, job.locale, { href: job.href, notificationId: a.notificationId })
+          if (!email || typeof email.subject !== "string" || typeof email.text !== "string") throw new Error("renderEmail returned no subject/text")
+          const res = await options.deliverEmail!({ to: job.to, subject: email.subject, text: email.text, type: job.type, notificationId: a.notificationId, operationId: job.operationId })
+          ok = res !== false
+        } catch (error) {
+          // The adapter's error may contain the address: log only its name.
+          system.definition.logger.warn("notification_email_failed", { notificationId: a.notificationId, type: job.type, errorName: error instanceof Error ? error.name : "unknown" })
+        }
+        await ctx.runMutation(ref<"mutation">("_recordNotificationEmail"), { notificationId: a.notificationId, ok })
+        return ok ? "sent" : "failed"
+      },
+    }),
+
+    /** → the email job, or null (and `skipped`) when there is nothing to send. */
+    _claimNotificationEmail: internalMutationGeneric({
+      args: { notificationId: v.id("notifications") },
+      handler: async (ctx, a): Promise<EmailJob | null> => {
+        const row = await db(ctx).get("notifications", a.notificationId)
+        if (!row || row.emailStatus !== "pending") return null
+        const { sys } = await system.context(ctx, { operationId: row.operationId })
+        const user = await sys.store.get("users", row.userId)
+        if (!canEmail || !types.has(row.type) || !user || user.status !== "active" || !user.emailVerified) {
+          await db(ctx).patch("notifications", row._id, { emailStatus: "skipped" })
+          return null
+        }
+        return { to: user.email, locale: user.locale ?? install.defaultLocale, type: row.type, params: row.params, href: row.href ?? null, operationId: row.operationId }
+      },
+    }),
+
+    _recordNotificationEmail: internalMutationGeneric({
+      args: { notificationId: v.id("notifications"), ok: v.boolean() },
+      handler: async (ctx, a): Promise<null> => {
+        const row = await db(ctx).get("notifications", a.notificationId)
+        if (row?.emailStatus === "pending") await db(ctx).patch("notifications", row._id, { emailStatus: a.ok ? "sent" : "failed" })
+        return null
+      },
+    }),
+  }
+
+  return { functions, types }
+}
+
+
+export type NotificationsSystem = ReturnType<typeof defineNotifications>

package/src/notifications/contract.ts

@@ -0,0 +1,142 @@
+// Shared contract of `@digimuza/system-core/notifications` (DIG-74): tables,
+// views, adapters and function names. No server-only imports: safe in Convex's
+// default runtime and in the browser (types).
+import { defineTable } from "convex/server"
+import { v, type GenericId, type Infer } from "convex/values"
+import type { NotificationParams } from "../core/notify.js"
+
+export const emailStatus = v.union(v.literal("none"), v.literal("pending"), v.literal("sent"), v.literal("failed"), v.literal("skipped"))
+
+/** Spread into the app schema next to `systemTables`. */
+export const notificationTables = {
+  notifications: defineTable({
+    /** system-core user key of the recipient. Only they can see it. */
+    userId: v.string(),
+    /** Notification type id, e.g. `finance.invoice_awaiting_approval`. */
+    type: v.string(),
+    /** JSON params; the app renders the text (LT/EN) from them. */
+    params: v.any(),
+    /** App-relative link. */
+    href: v.optional(v.string()),
+    /** False for email-only rows (the user turned the in-app channel off): never listed. */
+    inApp: v.boolean(),
+    readAt: v.optional(v.number()),
+    createdAt: v.number(),
+    /** none: email off · pending: scheduled · sent · failed · skipped: no adapter, no verified address. */
+    emailStatus,
+    /** Operation that caused it (the business mutation's). */
+    operationId: v.string(),
+  })
+    .index("by_user", ["userId", "inApp", "createdAt"])
+    .index("by_user_unread", ["userId", "inApp", "readAt"]),
+
+  notificationPreferences: defineTable({
+    userId: v.string(),
+    type: v.string(),
+    inApp: v.boolean(),
+    email: v.boolean(),
+    updatedAt: v.number(),
+  }).index("by_user_type", ["userId", "type"]),
+}
+
+export type EmailStatus = Infer<typeof emailStatus>
+export type NotificationId = GenericId<"notifications">
+
+// --- Views returned by public functions ---------------------------------------------------
+
+export interface NotificationView {
+  id: NotificationId
+  type: string
+  /** Owning module of the type (`finance`, `roles`, …). */
+  moduleId: string
+  params: NotificationParams
+  href: string | null
+  readAt: number | null
+  createdAt: number
+  emailStatus: EmailStatus
+}
+
+export interface NotificationPreferenceView {
+  type: string
+  moduleId: string
+  /** Fallback text; the app translates by `type`. */
+  description: string | null
+  /** Param names the type carries. */
+  params: string[]
+  defaultChannels: { inApp: boolean; email: boolean }
+  /** Effective channels (the user's preference, else the defaults). */
+  inApp: boolean
+  email: boolean
+  /** The user has set a preference for this type. */
+  customized: boolean
+}
+
+// --- Email adapters (app side, like `inviteDelivery`) ---------------------------------------
+
+export interface RenderedEmail {
+  subject: string
+  text: string
+}
+
+/**
+ * Renders a notification email in the recipient's locale (profile locale, else
+ * the default, `lt`). Build absolute links from `href` with the app's SITE_URL.
+ */
+export type RenderNotificationEmail = (
+  type: string,
+  params: NotificationParams,
+  locale: string,
+  context: { href: string | null; notificationId: string },
+) => RenderedEmail | Promise<RenderedEmail>
+
+export interface NotificationEmailMessage {
+  /** Verified address of the recipient. Never logged by core. */
+  to: string
+  subject: string
+  text: string
+  type: string
+  notificationId: string
+  /** Stable per notification: use it as an idempotency key with the provider. */
+  operationId: string
+}
+
+/** Sends one email. Throw (or return false) on failure: the row becomes `failed`. */
+// biome-ignore lint/suspicious/noConfusingVoidType: adapters may return nothing on success
+export type DeliverNotificationEmail = (message: NotificationEmailMessage) => Promise<void | boolean>
+
+/** What `_claimNotificationEmail` hands the delivery action. */
+export interface NotificationEmailJob {
+  to: string
+  locale: string
+  type: string
+  params: NotificationParams
+  href: string | null
+  operationId: string
+}
+
+// --- Limits & function names ---------------------------------------------------------------
+
+/** Most recipients of one `notify` call. Explicit `userIds` above it are VALIDATION. */
+export const NOTIFY_MAX_RECIPIENTS = 100
+/** `unreadNotificationCount` stops counting here (show "99+"). */
+export const NOTIFICATION_UNREAD_CAP = 100
+/** Rows one `markAllNotificationsRead` call marks; call again while `done` is false. */
+export const NOTIFICATION_MARK_ALL_BATCH = 200
+/** Serialized params size limit (characters of JSON). */
+export const NOTIFICATION_PARAMS_MAX = 4000
+
+/** Public functions in `functionsModule` (default convex/notifications.ts). */
+export const NOTIFICATIONS_PUBLIC_FUNCTIONS = [
+  "listNotifications", // ({ cursor?, limit?, unreadOnly? }) → { items: NotificationView[], cursor, done }
+  "unreadNotificationCount", // () → number (≤ NOTIFICATION_UNREAD_CAP)
+  "markNotificationRead", // ({ notificationId }) → { read } (NOT_FOUND unless own)
+  "markAllNotificationsRead", // () → { marked, done }
+  "getNotificationPreferences", // () → NotificationPreferenceView[]
+  "setNotificationPreference", // ({ type, inApp, email }) → NotificationPreferenceView
+] as const
+
+/** Internal functions in `functionsModule` (email delivery). */
+export const NOTIFICATIONS_INTERNAL_FUNCTIONS = ["_deliverNotificationEmail", "_claimNotificationEmail", "_recordNotificationEmail"] as const
+
+/** Audit action of a preference change. */
+export const NOTIFICATIONS_AUDIT = { preferenceUpdate: "profile.notification_preference.update" } as const

package/src/notifications/index.ts

@@ -0,0 +1,8 @@
+// `@digimuza/system-core/notifications` (DIG-74): in-app + email notifications,
+// a shared primitive every module uses. Core stores type + JSON params; the app
+// renders LT/EN text (UI and email) from them.
+export * from "./contract.js"
+export { defineNotifications, notificationsHook, notify, NotificationsInstall, type NotificationsHookOptions, type NotificationsOptions, type NotificationsSystem } from "./api.js"
+export { defineNotificationType, NOTIFICATION_TYPE_ID, type NotificationTypeDefinition } from "../core/catalog.js"
+export { notifyIfInstalled, type Notifier, type NotifyRequest, type NotifyTarget, type NotificationParams } from "../core/notify.js"
+export { CORE_NOTIFICATION_TYPES } from "../core/system-modules.js"