better-inbox 0.0.1 → 0.1.0

package/README.md

@@ -1,5 +1,133 @@
 # better-inbox
 
-In-app inbox and notification-center components backed by your own database. Part of the [better-notify](https://www.npmjs.com/package/better-notify) project.
+In-app notifications for [better-auth](https://better-auth.com) apps. One plugin, one migration, one component — notifications live in **your** database, addressed to **your** users.
 
-**Not released yet.** This name is reserved for active development.
+```
+npm install better-inbox
+```
+
+- **A better-auth plugin, not a platform.** No services to deploy, no dashboard SaaS. The `notification` table lives in your own database via better-auth's adapter (drizzle, prisma, kysely — whatever you already use).
+- **Addressed to users, not email addresses.** `notify({ userId })` uses your better-auth user ids. Delete a user, their notifications cascade.
+- **Organization-aware.** Notify a whole org — optionally filtered by role — via the better-auth organization plugin: `notify({ organizationId, roles: ["owner", "admin"] })`.
+- **One React component.** `<InboxButton />` gives you the bell, unread badge, and inbox panel, styled with shadcn CSS variables (works with any shadcn theme, zero runtime dependencies, no shadcn required).
+
+> Community plugin — not affiliated with the better-auth team.
+
+## Quickstart
+
+**1. Add the plugin** to your better-auth config:
+
+```ts
+// lib/auth.ts
+import { betterAuth } from "better-auth";
+import { inbox } from "better-inbox";
+
+export const auth = betterAuth({
+  // ...your existing config
+  plugins: [inbox()],
+});
+```
+
+**2. Migrate.** The plugin declares the `notification` table; your existing better-auth workflow creates it:
+
+```
+npx @better-auth/cli migrate --config lib/auth.ts   # or: generate, for drizzle/prisma
+```
+
+(Point `--config` at your better-auth config if the CLI doesn't auto-detect it.)
+
+**3. Add the client plugin:**
+
+```ts
+// lib/auth-client.ts
+import { createAuthClient } from "better-auth/react";
+import { inboxClient } from "better-inbox/client";
+
+export const authClient = createAuthClient({
+  plugins: [inboxClient()],
+});
+```
+
+**4. Drop in the component** (any client component, e.g. your navbar):
+
+```tsx
+"use client";
+import { InboxButton } from "better-inbox/react";
+import { useRouter } from "next/navigation";
+import { authClient } from "@/lib/auth-client";
+
+export function Navbar() {
+  const router = useRouter();
+  return <InboxButton client={authClient} onNavigate={(href) => router.push(href)} />;
+}
+```
+
+**5. Send notifications** from any server code — a server action, a webhook handler, a cron job:
+
+```ts
+await auth.api.notify({
+  body: {
+    userId: comment.authorId,
+    type: "comment.reply",
+    title: `${user.name} replied to your comment`,
+    href: `/posts/${post.id}#comment-${comment.id}`,
+  },
+});
+```
+
+`notify` is server-only: callable through `auth.api`, never exposed as an HTTP route.
+
+## Notify a whole organization
+
+With the better-auth [organization plugin](https://better-auth.com/docs/plugins/organization) enabled, address an org instead of a user. One notification is created per member (fan-out on write), each stamped with `organizationId`:
+
+```ts
+// Stripe webhook: payment failed → tell the org's admins
+await auth.api.notify({
+  body: {
+    organizationId: subscription.metadata.orgId,
+    roles: ["owner", "admin"], // optional — omit to notify every member
+    type: "billing.payment_failed",
+    title: "Payment failed — update your card",
+    href: "/settings/billing",
+  },
+});
+```
+
+Fan-out is capped at 1,000 members by default (`inbox({ maxFanout })` to change). Over the cap, `notify` throws instead of hammering your database.
+
+## API
+
+### Server (`better-inbox`)
+
+| Endpoint | Access | Description |
+|----------|--------|-------------|
+| `auth.api.notify({ body })` | server-only | Create notification(s). Exactly one of `userId` / `organizationId`; optional `roles`, `body`, `href`, `data` (JSON) |
+| `auth.api.listNotifications({ query })` | session | `{ filter?: "unread"\|"all", limit? (≤100), offset?, organizationId? }` → `{ notifications, hasMore }` |
+| `auth.api.markRead({ body: { id } })` | session | Marks one of the caller's notifications read |
+| `auth.api.markAllRead({ body })` | session | Optional `{ organizationId }` scope |
+| `auth.api.unreadCount({ query })` | session | → `{ count }` |
+
+Every session endpoint is scoped to the caller — users can only ever see and mutate their own notifications.
+
+### React (`better-inbox/react`)
+
+- `<InboxButton client={authClient} />` — bell + badge + panel. Props: `onNavigate`, `renderItem`, `pollInterval` (default 30s; unread count only, full refresh on window focus and panel open), `organizationId`, `className`.
+- `useInbox(client, options)` — build your own UI: `{ notifications, unreadCount, isLoading, hasMore, loadMore, markRead, markAllRead, refresh }`.
+- `<InboxPanel inbox={useInbox(...)} />` — the panel without the bell.
+
+## Performance note
+
+Add an index for the list query once you have real traffic — plugin schemas can't declare indexes, so it's one manual line, e.g. drizzle:
+
+```ts
+index("notification_user_created_idx").on(table.userId, table.createdAt)
+```
+
+## What this is not (yet)
+
+Email/push channels, preferences, digests, realtime websockets — out of scope for v0.1 by design. Polling + focus refetch covers the badge honestly. If you need multi-channel delivery pipelines, look at [Novu](https://novu.co) or [betternotify](https://github.com/better-notify/better-notify); better-inbox is the thin, DB-owned layer for the in-app half.
+
+## License
+
+MIT

package/dist/client.cjs

@@ -0,0 +1,41 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  inboxClient: () => inboxClient
+});
+module.exports = __toCommonJS(client_exports);
+var inboxClient = () => {
+  return {
+    id: "inbox",
+    $InferServerPlugin: {},
+    pathMethods: {
+      "/inbox/list": "GET",
+      "/inbox/unread-count": "GET",
+      "/inbox/mark-read": "POST",
+      "/inbox/mark-all-read": "POST"
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  inboxClient
+});

package/dist/client.d.cts

@@ -0,0 +1,19 @@
+import { inbox } from './index.cjs';
+export { Notification } from './index.cjs';
+import 'better-auth';
+import 'better-call';
+import 'zod/v4/core';
+import 'zod';
+
+declare const inboxClient: () => {
+    id: "inbox";
+    $InferServerPlugin: ReturnType<typeof inbox>;
+    pathMethods: {
+        "/inbox/list": "GET";
+        "/inbox/unread-count": "GET";
+        "/inbox/mark-read": "POST";
+        "/inbox/mark-all-read": "POST";
+    };
+};
+
+export { inboxClient };

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { inbox } from './index.js';
+export { Notification } from './index.js';
+import 'better-auth';
+import 'better-call';
+import 'zod/v4/core';
+import 'zod';
+
+declare const inboxClient: () => {
+    id: "inbox";
+    $InferServerPlugin: ReturnType<typeof inbox>;
+    pathMethods: {
+        "/inbox/list": "GET";
+        "/inbox/unread-count": "GET";
+        "/inbox/mark-read": "POST";
+        "/inbox/mark-all-read": "POST";
+    };
+};
+
+export { inboxClient };

package/dist/client.js

@@ -0,0 +1,16 @@
+// src/client.ts
+var inboxClient = () => {
+  return {
+    id: "inbox",
+    $InferServerPlugin: {},
+    pathMethods: {
+      "/inbox/list": "GET",
+      "/inbox/unread-count": "GET",
+      "/inbox/mark-read": "POST",
+      "/inbox/mark-all-read": "POST"
+    }
+  };
+};
+export {
+  inboxClient
+};

package/dist/index.cjs

@@ -0,0 +1,299 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  INBOX_ERROR_CODES: () => INBOX_ERROR_CODES,
+  inbox: () => inbox
+});
+module.exports = __toCommonJS(src_exports);
+var import_db = require("better-auth/db");
+
+// src/error-codes.ts
+var import_better_auth = require("better-auth");
+var INBOX_ERROR_CODES = (0, import_better_auth.defineErrorCodes)({
+  NOTIFICATION_NOT_FOUND: "Notification not found",
+  USER_OR_ORGANIZATION_REQUIRED: "Provide exactly one of userId or organizationId",
+  ORGANIZATION_PLUGIN_REQUIRED: "organizationId requires the organization plugin",
+  ORGANIZATION_HAS_NO_MEMBERS: "Organization has no matching members",
+  FAN_OUT_LIMIT_EXCEEDED: "Organization member count exceeds maxFanout"
+});
+
+// src/routes.ts
+var import_api = require("better-auth/api");
+var z = __toESM(require("zod"), 1);
+var notifyBodySchema = z.object({
+  userId: z.string().optional(),
+  organizationId: z.string().optional(),
+  roles: z.array(z.string()).optional(),
+  type: z.string(),
+  title: z.string(),
+  body: z.string().optional(),
+  href: z.string().optional(),
+  data: z.record(z.string(), z.unknown()).optional()
+}).refine((body) => !!body.userId !== !!body.organizationId, {
+  message: INBOX_ERROR_CODES.USER_OR_ORGANIZATION_REQUIRED.message
+});
+var notify = (options) => import_api.createAuthEndpoint.serverOnly(
+  {
+    method: "POST",
+    body: notifyBodySchema
+  },
+  async (ctx) => {
+    const { userId, organizationId, roles, ...payload } = ctx.body;
+    const createFor = (targetUserId) => ctx.context.adapter.create({
+      model: "notification",
+      data: {
+        userId: targetUserId,
+        ...organizationId ? { organizationId } : {},
+        ...payload,
+        read: false,
+        createdAt: /* @__PURE__ */ new Date()
+      }
+    });
+    if (!organizationId) {
+      const notification = await createFor(userId);
+      return { count: 1, notifications: [notification] };
+    }
+    const hasOrgPlugin = ctx.context.options.plugins?.some(
+      (plugin) => plugin.id === "organization"
+    );
+    if (!hasOrgPlugin) {
+      throw import_api.APIError.from(
+        "BAD_REQUEST",
+        INBOX_ERROR_CODES.ORGANIZATION_PLUGIN_REQUIRED
+      );
+    }
+    const members = await ctx.context.adapter.findMany({
+      model: "member",
+      where: [{ field: "organizationId", value: organizationId }],
+      limit: options.maxFanout + 1
+    });
+    if (members.length > options.maxFanout) {
+      throw import_api.APIError.from(
+        "BAD_REQUEST",
+        INBOX_ERROR_CODES.FAN_OUT_LIMIT_EXCEEDED
+      );
+    }
+    const targets = roles?.length ? members.filter(
+      (member) => member.role.split(",").some((role) => roles.includes(role))
+    ) : members;
+    if (targets.length === 0) {
+      throw import_api.APIError.from(
+        "BAD_REQUEST",
+        INBOX_ERROR_CODES.ORGANIZATION_HAS_NO_MEMBERS
+      );
+    }
+    const notifications = [];
+    for (const member of targets) {
+      notifications.push(await createFor(member.userId));
+    }
+    return { count: notifications.length, notifications };
+  }
+);
+var listQuerySchema = z.object({
+  filter: z.enum(["unread", "all"]).optional(),
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+  offset: z.coerce.number().int().min(0).optional(),
+  organizationId: z.string().optional()
+}).optional();
+var listNotifications = () => (0, import_api.createAuthEndpoint)(
+  "/inbox/list",
+  {
+    method: "GET",
+    query: listQuerySchema,
+    use: [import_api.sessionMiddleware]
+  },
+  async (ctx) => {
+    const { filter = "all", limit = 20, offset = 0, organizationId } = ctx.query ?? {};
+    const where = [
+      { field: "userId", value: ctx.context.session.user.id }
+    ];
+    if (filter === "unread") {
+      where.push({ field: "read", value: false });
+    }
+    if (organizationId) {
+      where.push({ field: "organizationId", value: organizationId });
+    }
+    const rows = await ctx.context.adapter.findMany({
+      model: "notification",
+      where,
+      limit: limit + 1,
+      offset,
+      sortBy: { field: "createdAt", direction: "desc" }
+    });
+    return {
+      notifications: rows.slice(0, limit),
+      hasMore: rows.length > limit
+    };
+  }
+);
+var markRead = () => (0, import_api.createAuthEndpoint)(
+  "/inbox/mark-read",
+  {
+    method: "POST",
+    body: z.object({ id: z.string() }),
+    use: [import_api.sessionMiddleware]
+  },
+  async (ctx) => {
+    const updated = await ctx.context.adapter.update({
+      model: "notification",
+      where: [
+        { field: "id", value: ctx.body.id },
+        { field: "userId", value: ctx.context.session.user.id }
+      ],
+      update: { read: true }
+    });
+    if (!updated) {
+      throw import_api.APIError.from(
+        "NOT_FOUND",
+        INBOX_ERROR_CODES.NOTIFICATION_NOT_FOUND
+      );
+    }
+    return { notification: updated };
+  }
+);
+var markAllRead = () => (0, import_api.createAuthEndpoint)(
+  "/inbox/mark-all-read",
+  {
+    method: "POST",
+    body: z.object({ organizationId: z.string().optional() }),
+    use: [import_api.sessionMiddleware]
+  },
+  async (ctx) => {
+    const where = [
+      { field: "userId", value: ctx.context.session.user.id },
+      { field: "read", value: false }
+    ];
+    if (ctx.body.organizationId) {
+      where.push({ field: "organizationId", value: ctx.body.organizationId });
+    }
+    const count = await ctx.context.adapter.updateMany({
+      model: "notification",
+      where,
+      update: { read: true }
+    });
+    return { count };
+  }
+);
+var unreadCount = () => (0, import_api.createAuthEndpoint)(
+  "/inbox/unread-count",
+  {
+    method: "GET",
+    query: z.object({ organizationId: z.string().optional() }).optional(),
+    use: [import_api.sessionMiddleware]
+  },
+  async (ctx) => {
+    const where = [
+      { field: "userId", value: ctx.context.session.user.id },
+      { field: "read", value: false }
+    ];
+    if (ctx.query?.organizationId) {
+      where.push({
+        field: "organizationId",
+        value: ctx.query.organizationId
+      });
+    }
+    const count = await ctx.context.adapter.count({
+      model: "notification",
+      where
+    });
+    return { count };
+  }
+);
+
+// src/schema.ts
+var schema = {
+  notification: {
+    fields: {
+      userId: {
+        type: "string",
+        required: true,
+        references: { model: "user", field: "id" }
+      },
+      organizationId: {
+        type: "string",
+        required: false
+      },
+      type: {
+        type: "string",
+        required: true
+      },
+      title: {
+        type: "string",
+        required: true
+      },
+      body: {
+        type: "string",
+        required: false
+      },
+      href: {
+        type: "string",
+        required: false
+      },
+      data: {
+        type: "json",
+        required: false
+      },
+      read: {
+        type: "boolean",
+        required: true,
+        defaultValue: false
+      },
+      createdAt: {
+        type: "date",
+        required: true
+      }
+    }
+  }
+};
+
+// src/index.ts
+var inbox = (options = {}) => {
+  const opts = { maxFanout: options.maxFanout ?? 1e3 };
+  return {
+    id: "inbox",
+    schema: (0, import_db.mergeSchema)(schema, options.schema),
+    endpoints: {
+      notify: notify(opts),
+      listNotifications: listNotifications(),
+      markRead: markRead(),
+      markAllRead: markAllRead(),
+      unreadCount: unreadCount()
+    },
+    $ERROR_CODES: INBOX_ERROR_CODES,
+    options
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  INBOX_ERROR_CODES,
+  inbox
+});