@murumets-ee/notifications 0.12.0

package/dist/index.d.mts

@@ -0,0 +1,500 @@
+import { _ as RenderedEmail, a as NOTIFICATION_TOPICS, c as NotificationRealtimePayload, d as NotifyOptions, f as NotifyResult, g as RenderedContent, h as RenderArgs, i as DEFAULT_RECIPIENT_CAP, l as NotificationTopic, m as Recipients, n as ChannelDeliveryRecord, o as NotificationChannelId, p as RecipientContext, r as ChannelDeliveryState, s as NotificationPreferences, t as ChannelDefinition, u as NotificationType, v as RenderedInApp } from "./types-B8qKgKMj.mjs";
+import { clearNotificationTypeRegistry, defineNotificationType, getAllNotificationTypes, getNotificationType, registerNotificationType } from "./define.mjs";
+import { n as notificationPreferencesSettings, r as resolveEnabledChannels, t as notificationPreferencesSchema } from "./preferences-BCkY2j9L.mjs";
+import { JobDefinition } from "@murumets-ee/queue/client";
+import { z } from "zod";
+import * as _$_murumets_ee_db0 from "@murumets-ee/db";
+import * as _$drizzle_orm0 from "drizzle-orm";
+import { Logger } from "@murumets-ee/core";
+import * as _$drizzle_orm_postgres_js0 from "drizzle-orm/postgres-js";
+import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { MailMessage, MailProvider, SendResult } from "@murumets-ee/mail";
+import * as _$drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
+
+//#region src/channels/types.d.ts
+interface ChannelSendContext {
+  /** The notification row id this delivery is for. */
+  notificationId: string;
+  /** Whether this is a fresh row (`created`) or a group-collapse update. */
+  kind: 'created' | 'updated';
+  /** Type id (e.g. `ticketing.message.created`). */
+  typeId: string;
+  /** Recipient context (id + locale + verified email if any). */
+  recipient: RecipientContext;
+  /** Rendered content for ALL channels — channel picks its own slice. */
+  rendered: RenderedContent;
+  /**
+   * Total unread count for the recipient AFTER this notification — used
+   * in realtime payloads so connected tabs can update the badge in one
+   * round-trip without an extra fetch.
+   */
+  unreadCount: number;
+  /**
+   * Optional Drizzle transaction handle — present when the publisher
+   * called `notify(..., { tx })`. Channels that perform side-effects
+   * which must roll back with the publisher's tx (canonically, the
+   * email channel's `queue.enqueue`) MUST forward it. Channels with
+   * purely ephemeral side-effects (in-app realtime publish) ignore it.
+   *
+   * Documented in PLAN-OUTBOX Phase 5 / PR E (a.k.a. PLAN-NOTIFICATIONS PR F).
+   *
+   * Spelled `T | undefined` (not bare optional) because the publisher's
+   * tx is passed in as a destructured variable that may be undefined,
+   * and the repo enables `exactOptionalPropertyTypes` — bare optional
+   * would refuse the assignment.
+   */
+  tx?: PostgresJsDatabase | undefined;
+}
+interface NotificationChannel {
+  id: NotificationChannelId;
+  /**
+   * Perform the channel's delivery. Returning the delivery record lets
+   * the notify pipeline merge per-channel state into the row's `channels`
+   * array under a single TX-free UPDATE per notify call.
+   *
+   * Implementations MUST NOT throw — return a `failed` record with the
+   * reason in `detail` instead. A throw would leak into the publisher's
+   * call stack and break user-facing routes that fan out notifications
+   * non-critically (e.g. ticket reply succeeded, but notify() crashed).
+   */
+  send(ctx: ChannelSendContext): Promise<ChannelDeliveryRecord>;
+}
+//#endregion
+//#region src/channels/email.d.ts
+/**
+ * Payload schema for the `notifications:send-email` job.
+ *
+ * Deliberately minimal — only the row id + the recipient. Render content
+ * is re-derived from the row's `payload` + the type registry at handler
+ * run time, so a group-collapse update between enqueue and run is reflected
+ * in the sent email.
+ *
+ * `recipientUserId` is repeated alongside `notificationId` so the handler's
+ * row read can scope to `(id, recipientUserId)` without needing a second
+ * lookup — defense-in-depth against a misbehaving plugin queueing a job
+ * for a row owned by a different user.
+ */
+declare const sendEmailJobPayloadSchema: z.ZodObject<{
+  notificationId: z.ZodString;
+  recipientUserId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  notificationId: string;
+  recipientUserId: string;
+}, {
+  notificationId: string;
+  recipientUserId: string;
+}>;
+type SendEmailJobPayload = z.infer<typeof sendEmailJobPayloadSchema>;
+/**
+ * Queue job definition. Plugin wiring registers a handler against this
+ * definition at init time when the mail provider is available.
+ */
+declare const notificationsSendEmailJob: JobDefinition<SendEmailJobPayload>;
+/**
+ * Minimal subset of `QueueClient.enqueue` the email channel relies on.
+ * Defining it as a shape (instead of importing the whole class) lets tests
+ * inject a stub without spinning up the queue table.
+ *
+ * The third `options` argument is structurally-typed against the bits of
+ * `EnqueueOptions` this channel actually forwards — currently just `tx`
+ * for outbox-style atomic enqueue (PLAN-OUTBOX Phase 5 / PR E). The real
+ * `QueueClient.enqueue` accepts a wider `EnqueueOptions`, which is
+ * structurally assignable to this narrower shape.
+ */
+interface QueueEnqueueShape {
+  enqueue(job: JobDefinition<SendEmailJobPayload>, payload: SendEmailJobPayload, options?: {
+    tx?: PostgresJsDatabase | undefined;
+  }): Promise<string>;
+}
+interface EmailChannelConfig {
+  /** Queue client used to enqueue the send job. */
+  queue: QueueEnqueueShape;
+  /** Optional logger; child-logger from the plugin is preferred. */
+  logger?: Logger | undefined;
+}
+/**
+ * Build the `email` channel. Returns a `NotificationChannel` whose `send`
+ * enqueues a queue job — never blocks on mail I/O.
+ */
+declare function createEmailChannel(config: EmailChannelConfig): NotificationChannel;
+interface SendEmailHandlerConfig {
+  db: PostgresJsDatabase;
+  /** Mail provider — usually `getMailConfig().provider`. */
+  mail: MailProvider;
+  /** From-address. Plugin resolves this from `mail().defaultFrom` or its own opt. */
+  from: string;
+  /** Default locale fallback when the recipient has no per-user locale. */
+  defaultLocale?: string;
+  logger?: Logger | undefined;
+}
+/**
+ * Subset of `JobContext` the send-email handler reads. Declared structurally
+ * so we don't depend on a `JobHandler` import that the queue package doesn't
+ * re-export from any subpath today. Function-param contravariance lets a
+ * `(SendEmailJobContext) => Promise<void>` be assigned to the broader
+ * `JobHandler<SendEmailJobPayload>` shape `registerJob` expects.
+ */
+interface SendEmailJobContext {
+  payload: SendEmailJobPayload;
+  /** Number of attempts so far (incl. the current one). Surfaced in failure logs. */
+  attempts: number;
+}
+type SendEmailHandler = (job: SendEmailJobContext) => Promise<void>;
+/**
+ * Build the queue-handler closure. Plugin wiring calls
+ * `registerJob(notificationsSendEmailJob, createSendEmailHandler({...}))`.
+ *
+ * The closure is a thin adapter: it builds DB-backed deps and forwards to
+ * `runSendEmailJob(deps, ...)`, which is the testable orchestration core.
+ */
+declare function createSendEmailHandler(config: SendEmailHandlerConfig): SendEmailHandler;
+/**
+ * Subset of `notificationsTable.makeClient(...).findOne` return shape that
+ * `runSendEmailJob` reads. Re-declared structurally so tests don't need a
+ * real DB to construct one.
+ */
+interface NotificationRowSnapshot {
+  id: string;
+  type: string;
+  payload: Record<string, unknown>;
+  channels: ChannelDeliveryRecord[];
+}
+/**
+ * Recipient subset returned by `fetchRecipient`. Mirrors `RecipientContext`
+ * but spelled out so tests don't need to import the full type for stubs.
+ */
+interface SendEmailRecipient {
+  id: string;
+  name?: string | undefined;
+  email?: string | undefined;
+  locale: string;
+}
+/**
+ * Lower-level deps used by `runSendEmailJob`. The shipping
+ * `createSendEmailHandler` builds these from a `SendEmailHandlerConfig`;
+ * unit tests inject their own stubs to drive each branch without touching
+ * the DB or mail provider.
+ */
+interface SendEmailJobDeps {
+  fetchRow(id: string, recipientUserId: string): Promise<NotificationRowSnapshot | null>;
+  fetchRecipient(userId: string): Promise<SendEmailRecipient | null>;
+  lookupType(typeId: string): {
+    render: (args: {
+      payload: Record<string, unknown>;
+      recipient: SendEmailRecipient;
+      locale: string;
+    }) => {
+      email?: RenderedEmail | undefined;
+    };
+  } | undefined;
+  sendMail(message: MailMessage): Promise<SendResult>;
+  flipChannelState(id: string, recipientUserId: string, entry: ChannelDeliveryRecord): Promise<void>;
+  from: string;
+  logger?: Logger | undefined;
+}
+/**
+ * Run the send-email job logic against pluggable deps.
+ *
+ * Behaviour summary:
+ *   - Row missing → log + return (archived/deleted between enqueue and run).
+ *   - Type missing → log + return (deregistered between enqueue and run).
+ *   - Recipient missing or email unverified at run time → flip channel
+ *     state to `skipped_unverified`, return cleanly.
+ *   - Render produced no `email` slice → flip to `failed`, log, return
+ *     cleanly (no retry — render is deterministic).
+ *   - mail.send threw → flip to `failed` with detail, RE-THROW so the
+ *     queue retries until maxRetries.
+ *   - mail.send returned → flip to `delivered`.
+ */
+declare function runSendEmailJob(deps: SendEmailJobDeps, job: SendEmailJobContext): Promise<void>;
+//#endregion
+//#region src/channels/in-app.d.ts
+declare const inAppChannel: NotificationChannel;
+//#endregion
+//#region src/throttle.d.ts
+/**
+ * Per-channel in-memory throttle - sliding window per (userId, typeId, channel).
+ *
+ * v1 lives in process memory; multi-process slip is acceptable for the v1
+ * targets ("5 emails per 15 min per user"). PLAN-NOTIFICATIONS section 6 Q2
+ * calls out the trade-off and the upgrade path (Postgres-backed counter) if
+ * the slip ever shows up in production.
+ *
+ * Format `<count>/<window>` - window is `<n><s|m|h>` (e.g. `5/15m`).
+ *
+ * Over-cap returns `false` from `tryConsume`. The caller (notify pipeline)
+ * records a `throttled` ChannelDeliveryRecord on the row instead of
+ * enqueueing the channel work.
+ */
+interface ParsedThrottle {
+  /** Max events allowed inside the window. */
+  count: number;
+  /** Window length in milliseconds. */
+  windowMs: number;
+}
+declare function parseThrottle(spec: string): ParsedThrottle;
+/**
+ * Tracks per-(userId, typeId, channel) event timestamps in memory.
+ *
+ * Memory bound: each key keeps at most `count` timestamps; entries with
+ * no recent activity are evicted on the next consume call against that
+ * key. The unbounded growth concern is therefore the *number of distinct
+ * keys*, not per-key length. v2 may add a periodic sweeper if the key
+ * count ever shows up in heap profiles.
+ */
+declare class ThrottleStore {
+  private readonly events;
+  private readonly nowFn;
+  constructor(nowFn?: () => number);
+  /**
+   * @returns `true` if the event fits in the window (and is recorded);
+   * `false` if it would exceed the cap (no record made - caller should
+   * mark the delivery as `throttled` and skip the channel work).
+   */
+  tryConsume(key: string, spec: string): boolean;
+  /**
+   * Build a stable throttle key from the per-recipient identity tuple.
+   * Uses `:` as a separator - none of the components (better-auth
+   * user ids, dot-namespaced type ids, camelCase channel ids) ever
+   * contain `:`, so collisions are impossible.
+   */
+  static buildKey(userId: string, typeId: string, channel: string): string;
+  /** @internal - for tests. */
+  reset(): void;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Resolver for per-user preferences. Allows the plugin to wire up a
+ * read-through cache without forcing the client to depend on a specific
+ * settings client implementation.
+ */
+type PreferencesResolver = (userId: string) => Promise<NotificationPreferences>;
+interface NotificationClientConfig {
+  db: PostgresJsDatabase;
+  logger?: Logger;
+  /** Default locale fallback when a recipient has no per-user locale. */
+  defaultLocale?: string;
+  /** Recipient cap for `resolveUsers()`. Defaults to 1000. */
+  recipientCap?: number;
+  /** Channel implementations. Keyed by channel id. Defaults to `inApp` only. */
+  channels?: Record<string, NotificationChannel>;
+  /** Resolver for per-user preferences. Defaults to "always empty" → type defaults apply. */
+  preferencesResolver?: PreferencesResolver;
+  /** In-memory throttle store. Tests inject a deterministic clock. */
+  throttleStore?: ThrottleStore;
+}
+declare class NotificationClient {
+  private readonly db;
+  private readonly logger?;
+  private readonly defaultLocale;
+  private readonly recipientCap;
+  private readonly channels;
+  private readonly preferencesResolver;
+  private readonly throttleStore;
+  private readonly notificationsClient;
+  constructor(config: NotificationClientConfig);
+  /**
+   * Resolve the table client to use for notification row writes. Mirrors
+   * `QueueClient.resolveJobsClient` (PR A of PLAN-OUTBOX). When `tx` is
+   * provided, every INSERT/UPDATE on `toolkit_notifications` participates
+   * in the caller's transaction; otherwise the package's owned client is
+   * used. Recipient lookup against the auth `user` table is a SELECT and
+   * does not need tx-binding.
+   */
+  private resolveNotificationsClient;
+  /**
+   * Publish a notification to one or more recipients. See PLAN-NOTIFICATIONS §3.3.
+   *
+   * When `options.tx` is set, every row write and every email-channel
+   * queue enqueue participates in the caller's transaction — see the
+   * file-level comment for the full contract.
+   */
+  notify<TPayload extends Record<string, unknown>>(options: NotifyOptions<TPayload>): Promise<NotifyResult>;
+  /**
+   * Per-recipient: collapse-or-insert the row, then dispatch each surviving
+   * channel under the throttle gate, then persist channel delivery state.
+   *
+   * `notificationsClient` is the tx-resolved table client from `notify()` —
+   * passed in instead of read from `this.notificationsClient` so every
+   * row write inside this method participates in the caller's tx when set.
+   * `tx` is forwarded to channels (the email channel needs it to attach
+   * `queue.enqueue` to the same tx).
+   */
+  private persistAndDispatch;
+  /**
+   * Count of unread (readAt IS NULL) notifications for a user. Drives the
+   * realtime payload's `unreadCount` and the bell badge.
+   */
+  unreadCount(userId: string): Promise<number>;
+  /**
+   * Result of `markRead` — `mutated` distinguishes "we updated readAt now"
+   * from "row was already read, no-op" so the route can decide whether to
+   * fire a realtime event.
+   */
+  markRead(userId: string, notificationId: string): Promise<{
+    id: string;
+    type: string;
+    readAt: Date;
+    mutated: boolean;
+  } | null>;
+  /** Mark all unread notifications for a user as read. Returns the count affected. */
+  markAllRead(userId: string): Promise<number>;
+  /**
+   * Soft-archive a notification. Returns the archived row or null if not
+   * addressable. `mutated` is false on a second call (already archived).
+   */
+  archive(userId: string, notificationId: string): Promise<{
+    id: string;
+    type: string;
+    mutated: boolean;
+  } | null>;
+}
+declare function setActiveNotificationClient(client: NotificationClient | null): void;
+declare function getActiveNotificationClient(): NotificationClient | null;
+/**
+ * Free-function publisher — the canonical caller-facing API. Resolves the
+ * active client wired up by the `notifications()` plugin's init hook.
+ *
+ * @example
+ * ```ts
+ * import { notify } from '@murumets-ee/notifications'
+ *
+ * await notify({
+ *   type: TicketingMessageCreated,
+ *   recipients: { userIds: [agentId] },
+ *   payload: { ticketId, messageId, ticketSubject, authorName },
+ * })
+ * ```
+ */
+declare function notify<TPayload extends Record<string, unknown>>(options: NotifyOptions<TPayload>): Promise<NotifyResult>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Errors thrown by `@murumets-ee/notifications`.
+ *
+ * All extend `Error` so callers can `instanceof` discriminate. Names match
+ * the class so logger output reads cleanly.
+ */
+declare class RecipientRequiredError extends Error {
+  constructor();
+}
+declare class NotificationFanoutTooLargeError extends Error {
+  readonly attemptedSize: number;
+  readonly cap: number;
+  constructor(attemptedSize: number, cap: number);
+}
+declare class UnknownNotificationTypeError extends Error {
+  readonly typeId: string;
+  constructor(typeId: string);
+}
+declare class UnsupportedChannelError extends Error {
+  readonly typeId: string;
+  readonly channelId: string;
+  constructor(typeId: string, channelId: string);
+}
+//#endregion
+//#region src/notifications-table.d.ts
+declare const notificationsTable: {
+  table: _$drizzle_orm_pg_core0.PgTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+      [x: string]: _$drizzle_orm_pg_core0.PgColumn<{
+        name: string;
+        tableName: string;
+        dataType: _$drizzle_orm0.ColumnDataType;
+        columnType: string;
+        data: unknown;
+        driverParam: unknown;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: string[] | undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {}>;
+    };
+    dialect: "pg";
+  }>;
+  schema: _$_murumets_ee_db0.TableDefinition<{
+    readonly id: _$_murumets_ee_db0.ColumnFactory<string, "uuid", true, true>;
+    readonly recipientUserId: _$_murumets_ee_db0.ColumnFactory<string, "varchar", true, false>;
+    readonly type: _$_murumets_ee_db0.ColumnFactory<string, "varchar", true, false>;
+    readonly payload: _$_murumets_ee_db0.ColumnFactory<Record<string, unknown>, "jsonb", true, true>;
+    readonly channels: _$_murumets_ee_db0.ColumnFactory<ChannelDeliveryRecord[], "jsonb", true, true>;
+    readonly groupKey: _$_murumets_ee_db0.ColumnFactory<string, "varchar", false, false>;
+    readonly readAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", false, false>;
+    readonly archivedAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", false, false>;
+    readonly createdAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", true, true>;
+    readonly updatedAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", true, true>;
+  }>;
+  columnKinds: Readonly<Record<string, _$_murumets_ee_db0.ColumnKind>>;
+  primaryKeyColumns: readonly string[];
+  makeClient: (db: _$drizzle_orm_postgres_js0.PostgresJsDatabase) => _$_murumets_ee_db0.TableClient<{
+    readonly id: _$_murumets_ee_db0.ColumnFactory<string, "uuid", true, true>;
+    readonly recipientUserId: _$_murumets_ee_db0.ColumnFactory<string, "varchar", true, false>;
+    readonly type: _$_murumets_ee_db0.ColumnFactory<string, "varchar", true, false>;
+    readonly payload: _$_murumets_ee_db0.ColumnFactory<Record<string, unknown>, "jsonb", true, true>;
+    readonly channels: _$_murumets_ee_db0.ColumnFactory<ChannelDeliveryRecord[], "jsonb", true, true>;
+    readonly groupKey: _$_murumets_ee_db0.ColumnFactory<string, "varchar", false, false>;
+    readonly readAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", false, false>;
+    readonly archivedAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", false, false>;
+    readonly createdAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", true, true>;
+    readonly updatedAt: _$_murumets_ee_db0.ColumnFactory<Date, "timestamp", true, true>;
+  }, _$drizzle_orm_pg_core0.PgTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+      [x: string]: _$drizzle_orm_pg_core0.PgColumn<{
+        name: string;
+        tableName: string;
+        dataType: _$drizzle_orm0.ColumnDataType;
+        columnType: string;
+        data: unknown;
+        driverParam: unknown;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: string[] | undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {}>;
+    };
+    dialect: "pg";
+  }>>;
+};
+/** Backward-compatible re-export following the queue/jobs convention. */
+declare const toolkitNotifications: _$drizzle_orm_pg_core0.PgTableWithColumns<{
+  name: string;
+  schema: undefined;
+  columns: {
+    [x: string]: _$drizzle_orm_pg_core0.PgColumn<{
+      name: string;
+      tableName: string;
+      dataType: _$drizzle_orm0.ColumnDataType;
+      columnType: string;
+      data: unknown;
+      driverParam: unknown;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: string[] | undefined;
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {}>;
+  };
+  dialect: "pg";
+}>;
+//#endregion
+export { type ChannelDefinition, type ChannelDeliveryRecord, type ChannelDeliveryState, type ChannelSendContext, DEFAULT_RECIPIENT_CAP, type EmailChannelConfig, NOTIFICATION_TOPICS, type NotificationChannel, type NotificationChannelId, NotificationClient, type NotificationClientConfig, NotificationFanoutTooLargeError, type NotificationPreferences, type NotificationRealtimePayload, type NotificationRowSnapshot, type NotificationTopic, type NotificationType, type NotifyOptions, type NotifyResult, type PreferencesResolver, type QueueEnqueueShape, type RecipientContext, RecipientRequiredError, type Recipients, type RenderArgs, type RenderedContent, type RenderedEmail, type RenderedInApp, type SendEmailHandler, type SendEmailHandlerConfig, type SendEmailJobContext, type SendEmailJobDeps, type SendEmailJobPayload, type SendEmailRecipient, ThrottleStore, UnknownNotificationTypeError, UnsupportedChannelError, clearNotificationTypeRegistry, createEmailChannel, createSendEmailHandler, defineNotificationType, getActiveNotificationClient, getAllNotificationTypes, getNotificationType, inAppChannel, notificationPreferencesSchema, notificationPreferencesSettings, notificationsSendEmailJob, notificationsTable, notify, parseThrottle, registerNotificationType, resolveEnabledChannels, runSendEmailJob, sendEmailJobPayloadSchema, setActiveNotificationClient, toolkitNotifications };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/channels/types.ts","../src/channels/email.ts","../src/channels/in-app.ts","../src/throttle.ts","../src/client.ts","../src/errors.ts","../src/notifications-table.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import{a as e,i as t,n,o as r,t as i}from"./email-DgfO6gZR.mjs";import{n as a,t as o}from"./types-Dy_AGX6X.mjs";import{clearNotificationTypeRegistry as s,defineNotificationType as c,getAllNotificationTypes as l,getNotificationType as u,registerNotificationType as d}from"./define.mjs";import{a as f,c as p,i as m,o as h,r as g,s as _}from"./recipients-DDN8AJzX.mjs";import{a as v,c as y,i as b,l as x,n as S,o as C,r as w,s as T,t as E,u as D}from"./client-CtklhnNF.mjs";throw Error(`This module cannot be imported from a Client Component module. It should only be used from a Server Component.`);export{o as DEFAULT_RECIPIENT_CAP,a as NOTIFICATION_TOPICS,E as NotificationClient,g as NotificationFanoutTooLargeError,m as RecipientRequiredError,v as ThrottleStore,f as UnknownNotificationTypeError,h as UnsupportedChannelError,s as clearNotificationTypeRegistry,i as createEmailChannel,n as createSendEmailHandler,c as defineNotificationType,S as getActiveNotificationClient,l as getAllNotificationTypes,u as getNotificationType,D as inAppChannel,T as notificationPreferencesSchema,y as notificationPreferencesSettings,t as notificationsSendEmailJob,_ as notificationsTable,w as notify,C as parseThrottle,d as registerNotificationType,x as resolveEnabledChannels,e as runSendEmailJob,r as sendEmailJobPayloadSchema,b as setActiveNotificationClient,p as toolkitNotifications};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../node_modules/.pnpm/server-only@0.0.1/node_modules/server-only/index.js"],"sourcesContent":["throw new Error(\n  \"This module cannot be imported from a Client Component module. \" +\n    \"It should only be used from a Server Component.\"\n);\n"],"x_google_ignoreList":[0],"mappings":"udAAA,MAAU,MACR,iHAED"}

package/dist/plugin.d.mts

@@ -0,0 +1,69 @@
+import { o as NotificationChannelId, u as NotificationType } from "./types-B8qKgKMj.mjs";
+import { r as resolveEnabledChannels } from "./preferences-BCkY2j9L.mjs";
+import { Plugin } from "@murumets-ee/core";
+
+//#region src/plugin.d.ts
+interface NotificationsPluginOptions {
+  /**
+   * Notification types contributed at the consumer level (i.e. defined in
+   * the app, not in a plugin). Plugin-contributed types are also collected
+   * via `Plugin.shared.notifications` and merged in at init time.
+   */
+  types?: NotificationType[];
+  /**
+   * Default locale for renders when the recipient has no per-user locale.
+   * Defaults to `'en'`.
+   */
+  defaultLocale?: string;
+  /**
+   * Maximum number of recipients a single `resolveUsers()` call may return.
+   * Defaults to 1000 — bounds the blast radius of a misbehaving permission
+   * resolver. See PLAN-NOTIFICATIONS §6 Q6.
+   */
+  recipientCap?: number;
+  /**
+   * Per-channel options. Currently only `email` is configurable.
+   *
+   * The email channel auto-enables when both `@murumets-ee/mail` (with a
+   * provider) and `@murumets-ee/queue` are initialised in the same app.
+   * Set `email.enabled: false` to opt out even when both are available
+   * (e.g. an environment that should only deliver in-app).
+   */
+  channels?: {
+    email?: {
+      /**
+       * Override the default opt-in. `true` forces email enabled (throws on
+       * init if mail is unavailable), `false` disables it explicitly,
+       * `undefined` (default) auto-enables when mail+queue are present.
+       */
+      enabled?: boolean;
+      /**
+       * From-address. Falls back to `mail().defaultFrom`. One of the two
+       * MUST be configured or the email channel skips registration with
+       * a warning.
+       */
+      from?: string;
+    };
+  };
+}
+declare function notifications(options?: NotificationsPluginOptions): Plugin;
+/**
+ * Cascade-loop guard for the queue terminal notifier.
+ *
+ * The notifications package owns `notifications:send-email` (and any
+ * future `notifications:*` jobs). If the mail provider is down, every
+ * send-email job dies after 3 retries. Without this guard each death
+ * would call `notify(QueueJobDead)` → enqueue one more send-email job
+ * per admin → each dies → geometric blow-up.
+ *
+ * The leading-edge alerter in `@murumets-ee/queue/alerter` still emails
+ * operators about send-email failures via its dedupe-window path, so
+ * the failure is still surfaced — just not via the bell drawer's
+ * per-admin path that would self-amplify.
+ *
+ * Exported for unit testing.
+ */
+declare function isQueueDeadEventNotifiable(jobType: string): boolean;
+//#endregion
+export { type NotificationChannelId, NotificationsPluginOptions, isQueueDeadEventNotifiable, notifications, resolveEnabledChannels };
+//# sourceMappingURL=plugin.d.mts.map

package/dist/plugin.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.mts","names":[],"sources":["../src/plugin.ts"],"mappings":";;;;;UAoCiB,0BAAA;EA4C8D;;AAuQ/E;;;EA7SE,KAAA,GAAQ,gBAAA;EA6SgD;;;;EAxSxD,aAAA;;;;;;EAMA,YAAA;;;;;;;;;EASA,QAAA;IACE,KAAA;;;;;;MAME,OAAA;;;;;;MAMA,IAAA;IAAA;EAAA;AAAA;AAAA,iBAKU,aAAA,CAAc,OAAA,GAAS,0BAAA,GAAkC,MAAA;;;;;;;;;;;;;;;;;iBAuQzD,0BAAA,CAA2B,OAAA"}

package/dist/plugin.mjs

@@ -0,0 +1,2 @@
+import"./types-Dy_AGX6X.mjs";import{registerNotificationType as e}from"./define.mjs";import{c as t}from"./recipients-DDN8AJzX.mjs";import{c as n,i as r,l as i,r as a,t as o,u as s}from"./client-CtklhnNF.mjs";import{notificationsRoutes as c}from"./admin.mjs";import{schemaRegistry as l}from"@murumets-ee/db";import{user as u}from"@murumets-ee/auth/schema";import{eq as d}from"drizzle-orm";async function f(e){return(await e.select({id:u.id}).from(u).where(d(u.role,`admin`))).map(e=>e.id)}function p(i={}){let a=i.types??[];return{name:`@murumets-ee/notifications`,server:{tables:{toolkitNotifications:t},routes:[c()],init:async c=>{l.has(`toolkit_notifications`)||l.register(`toolkit_notifications`,t);for(let t of a)e(t);for(let t of c.plugins.all()){if(t.name===`@murumets-ee/notifications`)continue;let n=t.shared?.notifications;if(n)for(let t of n)e(t)}let u=async e=>{let{createSettingsClient:t}=await import(`@murumets-ee/settings`);return await t(n,{app:c,scopeId:e}).get(`prefs`)??{}},d={inApp:s},f=i.channels?.email;f?.enabled!==!1&&await h({app:c,channels:d,forced:f?.enabled===!0,from:f?.from,defaultLocale:i.defaultLocale??`en`}),r(new o({db:c.db.readWrite,logger:c.logger.child({pkg:`notifications`}),defaultLocale:i.defaultLocale??`en`,recipientCap:i.recipientCap??1e3,preferencesResolver:u,channels:d})),await _({app:c}),c.logger.info({types:Array.from(new Set(a.map(e=>e.id))),channels:Object.keys(d)},`Notifications plugin initialized`)}},shared:{settings:[n],notifications:a}}}const m=/^[^\s@]+@[^\s@]+\.[^\s@]+$|<[^\s@]+@[^\s@]+\.[^\s@]+>/;async function h(e){let{app:t,channels:n,forced:r,from:i,defaultLocale:a}=e,o;try{o=await import(`@murumets-ee/mail/plugin`)}catch(e){let n=`notifications: @murumets-ee/mail not available — email channel disabled (in-app still works)`;if(r)throw Error(`${n} (cause: ${e.message})`);t.logger.warn({err:e},n);return}let s;try{s=o.getMailConfig()}catch(e){let n=`notifications: mail() plugin not in plugins array — email channel disabled (in-app still works)`;if(r)throw Error(`${n} (cause: ${e.message})`);t.logger.warn({err:e},n);return}if(!s.provider){let e=`notifications: mail provider not configured — email channel disabled (in-app still works)`;if(r)throw Error(e);t.logger.warn(e);return}let c=i||s.defaultFrom;if(!c){let e=`notifications: no from-address — set channels.email.from or mail().defaultFrom (email channel disabled)`;if(r)throw Error(e);t.logger.warn(e);return}if(!m.test(c)){let e=`notifications: from-address "${c}" is not a valid email — email channel disabled`;if(r)throw Error(e);t.logger.warn(e);return}let l;try{l=await import(`@murumets-ee/queue/client`)}catch(e){let n=`notifications: @murumets-ee/queue not available — email channel disabled (in-app still works)`;if(r)throw Error(`${n} (cause: ${e.message})`);t.logger.warn({err:e},n);return}if(!t.plugins.all().some(e=>e.name===`@murumets-ee/queue`)){let e=`notifications: queue() plugin not in plugins array — email channel disabled (in-app still works)`;if(r)throw Error(e);t.logger.warn(e);return}let{createEmailChannel:u,createSendEmailHandler:d,notificationsSendEmailJob:f}=await import(`./email-DgfO6gZR.mjs`).then(e=>e.r),p=t.logger.child({pkg:`notifications`,channel:`email`});n.email=u({queue:new l.QueueClient({db:t.db.readWrite,logger:p}),logger:p}),l.registerJob(f,d({db:t.db.readWrite,mail:s.provider,from:c,defaultLocale:a,logger:p})),t.logger.info({from:c},`Notifications email channel enabled`)}function g(e){return!e.startsWith(`notifications:`)}async function _(e){let{app:t}=e;if(!t.plugins.all().some(e=>e.name===`@murumets-ee/queue`))return;let n;try{n=await import(`@murumets-ee/queue/client`)}catch(e){t.logger.warn({err:e},`notifications: @murumets-ee/queue not available — queue terminal notifier disabled`);return}let r;try{r=await import(`@murumets-ee/queue/notifications`)}catch(e){t.logger.warn({err:e},`notifications: @murumets-ee/queue/notifications subpath not available — queue terminal notifier disabled`);return}let{QueueJobDead:i,buildQueueJobDeadPayload:o}=r,s=t.db.readWrite,c=t.logger.child({pkg:`notifications`,wiring:`queue-notifier`});n.setActiveQueueNotifier({onJobDead:async e=>{if(g(e.jobType))try{await a({type:i,recipients:{resolveUsers:()=>f(s)},payload:o({jobId:e.jobId,jobType:e.jobType,attempts:e.attempts,error:e.error,failedAt:e.failedAt})})}catch(t){c.warn({err:t,jobId:e.jobId,jobType:e.jobType},`queue.job.dead notify() failed`)}}}),t.logger.info(`Notifications queue terminal notifier wired (queue.job.dead → admins)`)}export{g as isQueueDeadEventNotifiable,p as notifications,i as resolveEnabledChannels};
+//# sourceMappingURL=plugin.mjs.map