payload-notifications 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# payload-notifications
+
+Multi-channel notification infrastructure for Payload CMS with document subscriptions and live messages.
+
+[![npm version](https://img.shields.io/npm/v/payload-notifications)](https://www.npmjs.com/package/payload-notifications)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Overview
+
+Payload has no built-in way to notify users about events. This plugin provides a server-side `notify()` / `subscribe()` / `getSubscribers()` API that you wire into your own hooks, endpoints, and workflows. A single `notify()` call can store an in-app notification, send an email, and fire an external callback -- each channel independent and optional. Everything is user-scoped with strict access control.
+
+**Features**
+
+- **Multi-channel delivery** -- in-app, email, and external callbacks from a single `notify()` call. Per-user preferences control which channels are active.
+- **Document subscriptions** -- users follow collections or globals. `getSubscribers()` returns follower IDs for fan-out. Supports auto-subscribe (e.g. on first comment) and manual follows.
+- **Live messages** -- template tokens (`t.actor`, `t.document('title')`, `t.meta('key')`) that resolve against fresh data at read time. Renamed users and updated titles are reflected in existing notifications.
+- **External callback** -- `onNotify` hook for pushing to Slack, webhooks, queues, or anything else.
+- **Admin bell component** -- optional popover UI with unread badge, mark-read, unsubscribe, and delete actions.
+
+## Installation
+
+```sh
+pnpm add payload-notifications
+```
+
+## Usage
+
+```ts
+// payload.config.ts
+import { buildConfig } from "payload";
+import { notificationsPlugin } from "payload-notifications";
+
+export default buildConfig({
+  // ...
+  plugins: [
+    notificationsPlugin({
+      email: {
+        generateSubject: ({ notification }) =>
+          `Notification: ${notification.event}`,
+        generateHTML: ({ notification, recipient }) =>
+          `<p>Hi ${recipient.displayName}, ${notification.message}</p>`,
+      },
+    }),
+  ],
+});
+```
+
+### Sending notifications
+
+```ts
+import { notify } from "payload-notifications";
+
+await notify(req, {
+  recipient: user.id,
+  event: "comment.created",
+  actor: commenter.id,
+  message: "Someone replied to your post",
+  documentReference: { entity: "collection", slug: "posts", id: post.id },
+});
+```
+
+### Subscriptions and fan-out
+
+```ts
+import {
+  subscribe,
+  getSubscribers,
+  notify,
+  createLiveMessage,
+} from "payload-notifications";
+
+const docRef = { entity: "collection", slug: "posts", id: post.id } as const;
+
+await subscribe(req, { userId: commenter.id, documentReference: docRef });
+
+const subscribers = await getSubscribers(req, docRef);
+for (const recipientId of subscribers) {
+  await notify(req, {
+    recipient: recipientId,
+    event: "comment.created",
+    actor: commenter.id,
+    message: createLiveMessage(
+      (t) => t`${t.actor} commented on "${t.document("title")}"`,
+    ),
+    documentReference: docRef,
+  });
+}
+```
+
+### Live messages
+
+Static strings go stale when users rename themselves or documents get updated. Live messages store tokens that resolve against fresh data at read time:
+
+```ts
+import { notify, createLiveMessage } from "payload-notifications";
+
+await notify(req, {
+  recipient: user.id,
+  event: "post.updated",
+  actor: editor.id,
+  message: createLiveMessage(
+    (t) => t`${t.actor} edited "${t.document("title")}"`,
+  ),
+  documentReference: { entity: "collection", slug: "posts", id: post.id },
+});
+```
+
+- `t.actor` -- actor's display name (from `admin.useAsTitle` on the user collection)
+- `t.document(field)` -- a field from the referenced document
+- `t.meta(key)` -- a key from the notification's `meta` object
+
+### Options
+
+| Option              | Type                      | Default           | Description                                                         |
+| ------------------- | ------------------------- | ----------------- | ------------------------------------------------------------------- |
+| `email`             | `NotificationEmailConfig` | --                | `generateSubject` and `generateHTML` functions. Omit to skip email. |
+| `onNotify`          | `NotifactionCallback`     | --                | Callback for every notification (Slack, webhooks, queues, etc).     |
+| `notificationsSlug` | `string`                  | `"notifications"` | Slug for the notifications collection.                              |
+| `subscriptionsSlug` | `string`                  | `"subscriptions"` | Slug for the subscriptions collection.                              |
+| `pollInterval`      | `number`                  | `30`              | Poll interval in seconds for the admin bell component.              |
+
+### API
+
+All functions are server-side and require a `PayloadRequest`:
+
+| Export                          | Description                                                    |
+| ------------------------------- | -------------------------------------------------------------- |
+| `notify(req, input)`            | Deliver a notification. Respects per-user channel preferences. |
+| `subscribe(req, opts)`          | Subscribe a user to a document. Deduplicates automatically.    |
+| `unsubscribe(req, userId, ref)` | Remove a subscription.                                         |
+| `getSubscribers(req, ref)`      | Return all user IDs subscribed to a document.                  |
+| `createLiveMessage(fn)`         | Build a serializable message template with dynamic tokens.     |
+
+## Contributing
+
+This plugin lives in the [payload-plugins](https://github.com/davincicoding-org/payload-plugins) monorepo.
+
+### Development
+
+```sh
+pnpm install
+
+# watch this plugin for changes
+pnpm --filter payload-notifications dev
+
+# run the Payload dev app (in a second terminal)
+pnpm --filter sandbox dev
+```
+
+The `sandbox/` directory is a Next.js + Payload app that imports plugins via `workspace:*` -- use it to test changes locally.
+
+### Code quality
+
+- **Formatting & linting** -- handled by [Biome](https://biomejs.dev/), enforced on commit via husky + lint-staged.
+- **Commits** -- must follow [Conventional Commits](https://www.conventionalcommits.org/) with a valid scope (e.g. `fix(payload-notifications): ...`).
+- **Changesets** -- please include a [changeset](https://github.com/changesets/changesets) in your PR by running `pnpm release`.
+
+### Issues & PRs
+
+Bug reports and feature requests are welcome -- [open an issue](https://github.com/davincicoding-org/payload-plugins/issues).
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,11 @@
+import { type DocumentID, type DocumentReference } from './internals/index.js';
+import type { PayloadRequest, TypeWithID } from 'payload';
+import type { NotifyInput } from './types';
+export declare function notify<Actor extends DocumentID | null>(req: PayloadRequest, input: NotifyInput<Actor>): Promise<void>;
+export declare function subscribe(req: PayloadRequest, { userId, documentReference, }: {
+    userId: string | number;
+    documentReference: DocumentReference;
+}): Promise<void>;
+export declare function unsubscribe(req: PayloadRequest, userId: string | number, documentReference: DocumentReference): Promise<void>;
+export declare function getSubscribers(req: PayloadRequest, documentReference: DocumentReference): Promise<TypeWithID['id'][]>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,iBAAiB,EAEvB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAS,MAAM,SAAS,CAAC;AAKjE,OAAO,KAAK,EAEV,WAAW,EAGZ,MAAM,SAAS,CAAC;AAEjB,wBAAsB,MAAM,CAAC,KAAK,SAAS,UAAU,GAAG,IAAI,EAC1D,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,GACxB,OAAO,CAAC,IAAI,CAAC,CAyEf;AAED,wBAAsB,SAAS,CAC7B,GAAG,EAAE,cAAc,EACnB,EACE,MAAM,EACN,iBAAiB,GAClB,EAAE;IACD,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,iBAAiB,EAAE,iBAAiB,CAAC;CACtC,GACA,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,wBAAsB,WAAW,CAC/B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,iBAAiB,EAAE,iBAAiB,GACnC,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,cAAc,EACnB,iBAAiB,EAAE,iBAAiB,GACnC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAgB7B"}

package/dist/api.js

@@ -0,0 +1,144 @@
+import { fetchDocumentByReference } from './internals/index.js';
+import { getPluginContext } from './context';
+import { sendNotificationEmail } from './email';
+import { resolveUser, toStoredReference } from './helpers';
+import { resolveMessageAtReadTime, toMessage } from './message';
+export async function notify(req, input) {
+    const ctx = getPluginContext(req.payload.config);
+    if (!req.payload.config.admin?.user) return;
+    // Resolve actor display name if provided
+    const actor = input.actor ? await resolveUser(req.payload, input.actor) : null;
+    // Fetch the referenced document if provided
+    const document = input.documentReference ? await fetchDocumentByReference(req.payload, input.documentReference) : undefined;
+    // Build message context from resolved data
+    const messageContext = {
+        actor: actor,
+        document: document,
+        meta: input.meta
+    };
+    // Convert message to stored format and resolve a plain string for email/callback
+    const serializedMessage = toMessage(input.message, messageContext);
+    const resolvedMessageString = resolveMessageAtReadTime(serializedMessage, messageContext);
+    const recipient = await resolveUser(req.payload, input.recipient);
+    const notificationDoc = await req.payload.create({
+        collection: ctx.collectionSlugs.notifications,
+        data: {
+            recipient: input.recipient,
+            event: input.event,
+            actor: input.actor,
+            message: serializedMessage,
+            url: input.url,
+            meta: input.meta,
+            documentReference: input.documentReference ? toStoredReference(input.documentReference) : undefined
+        },
+        req
+    });
+    if (ctx.email && recipient.notificationPreferences?.emailEnabled) {
+        await sendNotificationEmail(req, {
+            emailConfig: ctx.email,
+            notification: {
+                message: resolvedMessageString,
+                event: input.event
+            },
+            recipient,
+            notificationId: notificationDoc.id,
+            documentReference: input.documentReference
+        });
+    }
+    if (ctx.onNotify) {
+        try {
+            await ctx.onNotify({
+                req,
+                notification: {
+                    message: resolvedMessageString,
+                    event: input.event
+                },
+                recipient
+            });
+        } catch (err) {
+            console.error('[payload-notifications] onNotify callback failed:', err);
+        }
+    }
+}
+export async function subscribe(req, { userId, documentReference }) {
+    const ctx = getPluginContext(req.payload.config);
+    const ref = toStoredReference(documentReference);
+    const existing = await req.payload.find({
+        collection: ctx.collectionSlugs.subscriptions,
+        where: {
+            and: [
+                {
+                    user: {
+                        equals: userId
+                    }
+                },
+                ...documentReferenceWhere(ref)
+            ]
+        },
+        limit: 1
+    });
+    if (existing.totalDocs > 0) return;
+    await req.payload.create({
+        collection: ctx.collectionSlugs.subscriptions,
+        data: {
+            user: userId,
+            documentReference: ref
+        },
+        req
+    });
+}
+export async function unsubscribe(req, userId, documentReference) {
+    const ctx = getPluginContext(req.payload.config);
+    const ref = toStoredReference(documentReference);
+    await req.payload.delete({
+        collection: ctx.collectionSlugs.subscriptions,
+        where: {
+            and: [
+                {
+                    user: {
+                        equals: userId
+                    }
+                },
+                ...documentReferenceWhere(ref)
+            ]
+        },
+        req
+    });
+}
+export async function getSubscribers(req, documentReference) {
+    const ctx = getPluginContext(req.payload.config);
+    const ref = toStoredReference(documentReference);
+    const results = await req.payload.find({
+        collection: ctx.collectionSlugs.subscriptions,
+        where: {
+            and: documentReferenceWhere(ref)
+        },
+        limit: 0,
+        depth: 0
+    });
+    return results.docs.map(({ user })=>typeof user === 'object' ? user.id : user);
+}
+/** Build the where clause to match a stored document reference. */ function documentReferenceWhere(ref) {
+    const conditions = [
+        {
+            'documentReference.entity': {
+                equals: ref.entity
+            }
+        },
+        {
+            'documentReference.slug': {
+                equals: ref.slug
+            }
+        }
+    ];
+    if (ref.documentId) {
+        conditions.push({
+            'documentReference.documentId': {
+                equals: ref.documentId
+            }
+        });
+    }
+    return conditions;
+}
+
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api.ts"],"sourcesContent":["import {\n  type DocumentID,\n  type DocumentReference,\n  fetchDocumentByReference,\n} from '@repo/common';\nimport type { PayloadRequest, TypeWithID, Where } from 'payload';\nimport { getPluginContext } from './context';\nimport { sendNotificationEmail } from './email';\nimport { resolveUser, toStoredReference } from './helpers';\nimport { resolveMessageAtReadTime, toMessage } from './message';\nimport type {\n  MessageContext,\n  NotifyInput,\n  ResolvedActor,\n  StoredDocumentReference,\n} from './types';\n\nexport async function notify<Actor extends DocumentID | null>(\n  req: PayloadRequest,\n  input: NotifyInput<Actor>,\n): Promise<void> {\n  const ctx = getPluginContext(req.payload.config);\n  if (!req.payload.config.admin?.user) return;\n\n  // Resolve actor display name if provided\n  const actor = input.actor\n    ? await resolveUser(req.payload, input.actor)\n    : null;\n\n  // Fetch the referenced document if provided\n  const document = input.documentReference\n    ? await fetchDocumentByReference(req.payload, input.documentReference)\n    : undefined;\n\n  // Build message context from resolved data\n  const messageContext: MessageContext<Actor> = {\n    actor: actor as Actor extends DocumentID ? ResolvedActor : null,\n    document: document as Record<string, unknown> | undefined,\n    meta: input.meta,\n  };\n\n  // Convert message to stored format and resolve a plain string for email/callback\n  const serializedMessage = toMessage(input.message, messageContext);\n  const resolvedMessageString = resolveMessageAtReadTime(\n    serializedMessage,\n    messageContext,\n  );\n\n  const recipient = await resolveUser(req.payload, input.recipient);\n\n  const notificationDoc = await req.payload.create({\n    collection: ctx.collectionSlugs.notifications as 'notifications',\n    data: {\n      recipient: input.recipient as string,\n      event: input.event,\n      actor: input.actor as string,\n      message: serializedMessage,\n      url: input.url,\n      meta: input.meta,\n      documentReference: input.documentReference\n        ? toStoredReference(input.documentReference)\n        : undefined,\n    },\n    req,\n  });\n\n  if (ctx.email && recipient.notificationPreferences?.emailEnabled) {\n    await sendNotificationEmail(req, {\n      emailConfig: ctx.email,\n      notification: {\n        message: resolvedMessageString,\n        event: input.event,\n      },\n      recipient,\n      notificationId: notificationDoc.id,\n      documentReference: input.documentReference,\n    });\n  }\n\n  if (ctx.onNotify) {\n    try {\n      await ctx.onNotify({\n        req,\n        notification: {\n          message: resolvedMessageString,\n          event: input.event,\n        },\n        recipient,\n      });\n    } catch (err) {\n      console.error('[payload-notifications] onNotify callback failed:', err);\n    }\n  }\n}\n\nexport async function subscribe(\n  req: PayloadRequest,\n  {\n    userId,\n    documentReference,\n  }: {\n    userId: string | number;\n    documentReference: DocumentReference;\n  },\n): Promise<void> {\n  const ctx = getPluginContext(req.payload.config);\n  const ref = toStoredReference(documentReference);\n\n  const existing = await req.payload.find({\n    collection: ctx.collectionSlugs.subscriptions as 'subscriptions',\n    where: {\n      and: [{ user: { equals: userId } }, ...documentReferenceWhere(ref)],\n    },\n    limit: 1,\n  });\n\n  if (existing.totalDocs > 0) return;\n\n  await req.payload.create({\n    collection: ctx.collectionSlugs.subscriptions as 'subscriptions',\n    data: {\n      user: userId as string,\n      documentReference: ref,\n    },\n    req,\n  });\n}\n\nexport async function unsubscribe(\n  req: PayloadRequest,\n  userId: string | number,\n  documentReference: DocumentReference,\n): Promise<void> {\n  const ctx = getPluginContext(req.payload.config);\n  const ref = toStoredReference(documentReference);\n\n  await req.payload.delete({\n    collection: ctx.collectionSlugs.subscriptions as 'subscriptions',\n    where: {\n      and: [{ user: { equals: userId } }, ...documentReferenceWhere(ref)],\n    },\n    req,\n  });\n}\n\nexport async function getSubscribers(\n  req: PayloadRequest,\n  documentReference: DocumentReference,\n): Promise<TypeWithID['id'][]> {\n  const ctx = getPluginContext(req.payload.config);\n  const ref = toStoredReference(documentReference);\n\n  const results = await req.payload.find({\n    collection: ctx.collectionSlugs.subscriptions as 'subscriptions',\n    where: {\n      and: documentReferenceWhere(ref),\n    },\n    limit: 0,\n    depth: 0,\n  });\n\n  return results.docs.map(({ user }) =>\n    typeof user === 'object' ? user.id : user,\n  );\n}\n\n/** Build the where clause to match a stored document reference. */\nfunction documentReferenceWhere(ref: StoredDocumentReference): Where[] {\n  const conditions: Where[] = [\n    { 'documentReference.entity': { equals: ref.entity } },\n    { 'documentReference.slug': { equals: ref.slug } },\n  ];\n  if (ref.documentId) {\n    conditions.push({\n      'documentReference.documentId': { equals: ref.documentId },\n    });\n  }\n  return conditions;\n}\n"],"names":["fetchDocumentByReference","getPluginContext","sendNotificationEmail","resolveUser","toStoredReference","resolveMessageAtReadTime","toMessage","notify","req","input","ctx","payload","config","admin","user","actor","document","documentReference","undefined","messageContext","meta","serializedMessage","message","resolvedMessageString","recipient","notificationDoc","create","collection","collectionSlugs","notifications","data","event","url","email","notificationPreferences","emailEnabled","emailConfig","notification","notificationId","id","onNotify","err","console","error","subscribe","userId","ref","existing","find","subscriptions","where","and","equals","documentReferenceWhere","limit","totalDocs","unsubscribe","delete","getSubscribers","results","depth","docs","map","conditions","entity","slug","documentId","push"],"mappings":"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"}

package/dist/components/NotificationBell.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedPluginOptions } from '../types';
+export type NotificationBellProps = ResolvedPluginOptions<'pollInterval'>;
+export declare function NotificationBell({ pollInterval }: NotificationBellProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=NotificationBell.d.ts.map

package/dist/components/NotificationBell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationBell.d.ts","sourceRoot":"","sources":["../../src/components/NotificationBell.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAA2B,MAAM,SAAS,CAAC;AAU9E,MAAM,MAAM,qBAAqB,GAAG,qBAAqB,CAAC,cAAc,CAAC,CAAC;AAE1E,wBAAgB,gBAAgB,CAAC,EAAE,YAAY,EAAE,EAAE,qBAAqB,2CA+IvE"}

package/dist/components/NotificationBell.js

@@ -0,0 +1,318 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Collapsible } from '@base-ui/react/collapsible';
+import { Popover } from '@base-ui/react/popover';
+import { Button, useAuth, useConfig } from '@payloadcms/ui';
+import { IconAdjustments, IconBell } from '@tabler/icons-react';
+import { useCallback, useEffect, useReducer, useRef, useState } from 'react';
+import { toDocumentReference } from '../helpers';
+import { ENDPOINTS } from '../procedures';
+import styles from './NotificationBell.module.css';
+import { NotificationItem } from './NotificationItem';
+import { INITIAL_STATE, notificationReducer } from './notification-reducer';
+export function NotificationBell({ pollInterval }) {
+    const { config: { routes: { api: apiRoute } } } = useConfig();
+    const { user } = useAuth();
+    const [mounted, setMounted] = useState(false);
+    useEffect(()=>setMounted(true), []);
+    const [state, dispatch] = useReducer(notificationReducer, INITIAL_STATE);
+    useUnreadPolling(apiRoute, pollInterval, state, dispatch, mounted);
+    const { loadMore, isLoadingRead } = useReadNotifications(apiRoute, state, dispatch);
+    const { markRead, markAllRead, deleteNotification } = useNotificationActions(apiRoute, dispatch);
+    const { prefs, togglePref, unsubscribe } = useNotificationPreferences(apiRoute, user);
+    const bellIcon = /*#__PURE__*/ _jsxs("div", {
+        className: styles.bellIcon,
+        children: [
+            /*#__PURE__*/ _jsx(IconBell, {
+                size: 20,
+                strokeWidth: 1.5
+            }),
+            state.unread.length > 0 && /*#__PURE__*/ _jsx("span", {
+                className: styles.indicator,
+                children: state.unread.length
+            })
+        ]
+    });
+    // Render a static bell during SSR to avoid hydration mismatch from
+    // Base UI's Popover portal and floating-ui context.
+    if (!mounted) {
+        return /*#__PURE__*/ _jsx(Button, {
+            buttonStyle: "tab",
+            children: bellIcon
+        });
+    }
+    return /*#__PURE__*/ _jsxs(Popover.Root, {
+        children: [
+            /*#__PURE__*/ _jsx(Popover.Trigger, {
+                render: /*#__PURE__*/ _jsx(Button, {
+                    buttonStyle: "tab"
+                }),
+                children: bellIcon
+            }),
+            /*#__PURE__*/ _jsx(Popover.Portal, {
+                children: /*#__PURE__*/ _jsx(Popover.Positioner, {
+                    align: "start",
+                    sideOffset: 8,
+                    children: /*#__PURE__*/ _jsxs(Popover.Popup, {
+                        className: styles.popoverPopup,
+                        children: [
+                            /*#__PURE__*/ _jsx(Popover.Arrow, {
+                                className: styles.popoverArrow,
+                                children: /*#__PURE__*/ _jsx("svg", {
+                                    fill: "none",
+                                    height: "10",
+                                    viewBox: "0 0 20 10",
+                                    width: "20",
+                                    children: /*#__PURE__*/ _jsx("path", {
+                                        d: "M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z"
+                                    })
+                                })
+                            }),
+                            /*#__PURE__*/ _jsxs(Popover.Viewport, {
+                                className: styles.popoverViewport,
+                                children: [
+                                    /*#__PURE__*/ _jsx(Collapsible.Root, {
+                                        children: /*#__PURE__*/ _jsxs("div", {
+                                            className: styles.panelTop,
+                                            children: [
+                                                /*#__PURE__*/ _jsxs("div", {
+                                                    className: styles.header,
+                                                    children: [
+                                                        /*#__PURE__*/ _jsx("h3", {
+                                                            className: styles.title,
+                                                            children: "Notifications"
+                                                        }),
+                                                        /*#__PURE__*/ _jsx(Collapsible.Trigger, {
+                                                            "aria-label": "Notification settings",
+                                                            className: styles.headerAction,
+                                                            type: "button",
+                                                            children: /*#__PURE__*/ _jsx(IconAdjustments, {
+                                                                size: 18,
+                                                                strokeWidth: 1.5
+                                                            })
+                                                        })
+                                                    ]
+                                                }),
+                                                /*#__PURE__*/ _jsx(Collapsible.Panel, {
+                                                    className: styles.prefsPanel,
+                                                    children: /*#__PURE__*/ _jsxs("label", {
+                                                        className: styles.prefRow,
+                                                        children: [
+                                                            /*#__PURE__*/ _jsx("input", {
+                                                                checked: prefs?.emailEnabled ?? true,
+                                                                onChange: ()=>togglePref('emailEnabled'),
+                                                                type: "checkbox"
+                                                            }),
+                                                            "Email notifications"
+                                                        ]
+                                                    })
+                                                })
+                                            ]
+                                        })
+                                    }),
+                                    /*#__PURE__*/ _jsxs("div", {
+                                        className: styles.sections,
+                                        children: [
+                                            state.unread.length === 0 && !state.isReadLoaded && /*#__PURE__*/ _jsx("p", {
+                                                className: styles.empty,
+                                                children: "No notifications"
+                                            }),
+                                            state.unread.map((n)=>/*#__PURE__*/ _jsx(NotificationItem, {
+                                                    apiRoute: apiRoute,
+                                                    notification: n,
+                                                    onDelete: deleteNotification,
+                                                    onMarkRead: markRead,
+                                                    onUnsubscribe: unsubscribe
+                                                }, n.id)),
+                                            !state.isReadLoaded && state.hasMore && /*#__PURE__*/ _jsx("button", {
+                                                className: styles.showOlder,
+                                                onClick: loadMore,
+                                                type: "button",
+                                                children: "Show older"
+                                            }),
+                                            state.isReadLoaded && state.read.length === 0 && state.unread.length === 0 && /*#__PURE__*/ _jsx("p", {
+                                                className: styles.empty,
+                                                children: "No notifications"
+                                            }),
+                                            state.read.map((n)=>/*#__PURE__*/ _jsx(NotificationItem, {
+                                                    apiRoute: apiRoute,
+                                                    notification: n,
+                                                    onDelete: deleteNotification,
+                                                    onMarkRead: markRead,
+                                                    onUnsubscribe: unsubscribe
+                                                }, n.id)),
+                                            state.isReadLoaded && state.hasMoreRead && /*#__PURE__*/ _jsx("button", {
+                                                className: styles.showOlder,
+                                                disabled: isLoadingRead,
+                                                onClick: loadMore,
+                                                type: "button",
+                                                children: isLoadingRead ? 'Loading...' : 'Show more'
+                                            })
+                                        ]
+                                    })
+                                ]
+                            })
+                        ]
+                    })
+                })
+            })
+        ]
+    });
+}
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+/** Polls unread notifications with `since`-based diffing. */ function useUnreadPolling(apiRoute, pollInterval, state, dispatch, enabled) {
+    const timestampRef = useRef(state.pollTimestamp);
+    timestampRef.current = state.pollTimestamp;
+    const poll = useCallback(async ()=>{
+        try {
+            const since = timestampRef.current ?? undefined;
+            const { docs, timestamp, hasMore } = await ENDPOINTS.unread.call(apiRoute, {
+                since
+            });
+            if (!timestampRef.current) {
+                dispatch({
+                    type: 'SET_UNREAD',
+                    docs,
+                    timestamp,
+                    hasMore: hasMore ?? false
+                });
+            } else {
+                dispatch({
+                    type: 'PREPEND_UNREAD',
+                    docs,
+                    timestamp
+                });
+            }
+        } catch  {
+        // Poll will retry on next interval
+        }
+    }, [
+        apiRoute,
+        dispatch
+    ]);
+    useEffect(()=>{
+        if (!enabled) return;
+        let interval = null;
+        const start = ()=>{
+            poll();
+            interval = setInterval(poll, pollInterval * 1000);
+        };
+        const stop = ()=>{
+            if (interval) clearInterval(interval);
+            interval = null;
+        };
+        const onVisibilityChange = ()=>{
+            if (document.hidden) stop();
+            else start();
+        };
+        start();
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return ()=>{
+            stop();
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [
+        poll,
+        pollInterval,
+        enabled
+    ]);
+}
+/** On-demand paginated loading of read notifications. */ function useReadNotifications(apiRoute, state, dispatch) {
+    const [isLoadingRead, setIsLoadingRead] = useState(false);
+    const nextPage = state.readPage + 1;
+    const loadMore = useCallback(async ()=>{
+        setIsLoadingRead(true);
+        try {
+            const { docs, hasNextPage } = await ENDPOINTS.read.call(apiRoute, {
+                page: nextPage,
+                limit: 10
+            });
+            dispatch({
+                type: 'APPEND_READ',
+                docs,
+                hasNextPage
+            });
+        } finally{
+            setIsLoadingRead(false);
+        }
+    }, [
+        apiRoute,
+        nextPage,
+        dispatch
+    ]);
+    return {
+        loadMore,
+        isLoadingRead
+    };
+}
+/** Optimistic mutations dispatched to the reducer. */ function useNotificationActions(apiRoute, dispatch) {
+    const markRead = useCallback(async (id)=>{
+        dispatch({
+            type: 'MARK_READ',
+            id,
+            readAt: new Date().toISOString()
+        });
+        await ENDPOINTS.markRead.call(apiRoute, {
+            id
+        });
+    }, [
+        apiRoute,
+        dispatch
+    ]);
+    const markAllRead = useCallback(async ()=>{
+        dispatch({
+            type: 'MARK_ALL_READ'
+        });
+        await ENDPOINTS.markAllRead.call(apiRoute);
+    }, [
+        apiRoute,
+        dispatch
+    ]);
+    const deleteNotification = useCallback(async (id)=>{
+        dispatch({
+            type: 'DELETE_NOTIFICATION',
+            id
+        });
+        await ENDPOINTS.deleteNotification.call(apiRoute, {
+            id
+        });
+    }, [
+        apiRoute,
+        dispatch
+    ]);
+    return {
+        markRead,
+        markAllRead,
+        deleteNotification
+    };
+}
+/** Reads and toggles user-level notification preferences. */ function useNotificationPreferences(apiRoute, user) {
+    const prefs = user?.notificationPreferences;
+    const togglePref = useCallback(async (field)=>{
+        if (!user) return;
+        const current = prefs?.[field] ?? true;
+        await ENDPOINTS.updatePreferences.call(apiRoute, {
+            [field]: !current
+        });
+    }, [
+        apiRoute,
+        user,
+        prefs
+    ]);
+    const unsubscribe = useCallback(async (ref)=>{
+        await ENDPOINTS.unsubscribe.call(apiRoute, {
+            documentReference: toDocumentReference(ref)
+        });
+    }, [
+        apiRoute
+    ]);
+    return {
+        prefs,
+        togglePref,
+        unsubscribe
+    };
+}
+
+//# sourceMappingURL=NotificationBell.js.map