Preferences & unsubscribe

// Server-side:
await notify.preferences.update({
  recipientId: user.id,
  notificationId: "comment_mentioned",
  channels: { email: false },
})

const prefs = await notify.preferences.list(user.id)

// Client-side (React):
import { usePreferences } from "@notifykitjs/react"

function Settings() {
  const { items, update, isEnabled } = usePreferences()

  return (
    <input
      type="checkbox"
      checked={isEnabled("comment_mentioned", "email")}
      onChange={(e) =>
        update({
          notificationId: "comment_mentioned",
          channels: { email: e.target.checked },
        })
      }
    />
  )
}

const meta = await client.notifications.list()
// [
//   { id: "comment_mentioned", channels: ["inbox","email"], category: "social" },
//   { id: "order_shipped", channels: ["email"], category: "billing" },
// ]

// In your notification definitions:
notification({ id: "comment_mentioned", category: "activity", ... })
notification({ id: "task_assigned",     category: "activity", ... })
notification({ id: "new_follower",      category: "social",   ... })
notification({ id: "post_liked",        category: "social",   ... })
notification({ id: "invoice_paid",      category: "billing",  ... })

const meta = await client.notifications.list()
const grouped = Object.groupBy(meta, n => n.category ?? "other")
// { activity: [...], social: [...], billing: [...] }

notification({
  id: "password_reset",
  payload: { resetUrl: "string" },
  channels: [email({ subject: "Reset password", body: "{{resetUrl}}" })],
  required: true, // always delivers regardless of preferences
})

createNotifyKit({
  // ...
  unsubscribe: {
    secret: process.env.NOTIFYKIT_SECRET!,
    baseUrl: "https://app.com/api/notifykit",
  },
})

// In your email template:
email({
  subject: "...",
  body: "...\n\nUnsubscribe: {{_unsubscribeUrl}}",
})

import { usePreferences } from "@notifykitjs/react"
import { useEffect, useState } from "react"

function NotificationSettings() {
  const { isEnabled, update } = usePreferences()
  const [notifications, setNotifications] = useState([])

  useEffect(() => {
    fetch("/api/notifykit/notifications")
      .then(r => r.json())
      .then(body => setNotifications(body.data))
  }, [])

  return (
    <table>
      <thead>
        <tr><th>Notification</th><th>Inbox</th><th>Email</th></tr>
      </thead>
      <tbody>
        {notifications.map(n => (
          <tr key={n.id}>
            <td>{n.description || n.id}</td>
            {n.channels.map(ch => (
              <td key={ch}>
                <input
                  type="checkbox"
                  checked={isEnabled(n.id, ch)}
                  disabled={n.required}
                  onChange={e => update({
                    notificationId: n.id,
                    channels: { [ch]: e.target.checked },
                  })}
                />
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  )
}

// Set a global channel preference (disables email for everything):
await notify.preferences.update({
  recipientId: user.id,
  notificationId: "*",       // wildcard = applies to all notifications
  channels: { email: false },
})

// Per-notification preferences still exist but are masked:
// User had email ON for "comment_mentioned" — global OFF wins.

// Typical settings page layout:
//
// ┌─ Email ─────────────────────────────────────┐
// │ [x] Receive email notifications (global)    │
// │                                             │
// │  Activity                                   │
// │    [ ] Comments         ← user disabled     │
// │    [x] Task assigned                        │
// │                                             │
// │  Social                                     │
// │    [x] New followers                        │
// │    [x] Post reactions                       │
// └─────────────────────────────────────────────┘

function SettingsPage() {
  const { isEnabled, update } = usePreferences()

  // Global toggle
  const emailGlobalOn = isEnabled("*", "email")

  return (
    <>
      <label>
        <input
          type="checkbox"
          checked={emailGlobalOn}
          onChange={(e) => update({
            notificationId: "*",
            channels: { email: e.target.checked },
          })}
        />
        Receive email notifications
      </label>

      {/* Per-notification toggles (visually dimmed when global is off) */}
      <fieldset disabled={!emailGlobalOn}>
        {notifications.map(n => (
          <label key={n.id}>
            <input
              type="checkbox"
              checked={isEnabled(n.id, "email")}
              onChange={(e) => update({
                notificationId: n.id,
                channels: { email: e.target.checked },
              })}
            />
            {n.description}
          </label>
        ))}
      </fieldset>
    </>
  )
}

import { describe, it, expect, beforeEach } from "vitest"
import { createNotifyKit, memoryAdapter, fakeEmailProvider, notification, channel } from "@notifykitjs/core"

const inbox = channel.inbox()
const email = channel.email()

const commentMentioned = notification({
  id: "comment_mentioned",
  category: "activity",
  payload: { actorName: "string", postUrl: "string" },
  channels: [
    inbox({ title: "{{actorName}} mentioned you" }),
    email({ subject: "{{actorName}} mentioned you", body: "Open {{postUrl}}" }),
  ],
})

const passwordReset = notification({
  id: "password_reset",
  payload: { resetUrl: "string" },
  channels: [email({ subject: "Reset password", body: "{{resetUrl}}" })],
  required: true,
})

function createTestNotify(opts = {}) {
  return createNotifyKit({
    notifications: [commentMentioned, passwordReset] as const,
    database: memoryAdapter(),
    providers: { email: fakeEmailProvider() },
    ...opts,
  })
}

describe("preference resolution", () => {
  let notify: ReturnType<typeof createTestNotify>

  beforeEach(async () => {
    notify = createTestNotify()
    await notify.upsertRecipient({ id: "user_1", email: "a@test.com" })
  })

  it("delivers all channels by default (no preferences set)", async () => {
    const e = await notify.explain({
      recipientId: "user_1",
      notificationId: "comment_mentioned",
      payload: { actorName: "Rey", postUrl: "/p/1" },
    })
    expect(e.channels.inbox.outcome).toBe("deliver")
    expect(e.channels.email.outcome).toBe("deliver")
  })

  it("user opt-out disables a single channel", async () => {
    await notify.preferences.update({
      recipientId: "user_1",
      notificationId: "comment_mentioned",
      channels: { email: false },
    })

    const e = await notify.explain({
      recipientId: "user_1",
      notificationId: "comment_mentioned",
      payload: { actorName: "Rey", postUrl: "/p/1" },
    })
    expect(e.channels.email.outcome).toBe("disabled")
    expect(e.channels.inbox.outcome).toBe("deliver") // unaffected
  })

  it("required notifications ignore user opt-out", async () => {
    await notify.preferences.update({
      recipientId: "user_1",
      notificationId: "password_reset",
      channels: { email: false },
    })

    const e = await notify.explain({
      recipientId: "user_1",
      notificationId: "password_reset",
      payload: { resetUrl: "/reset/abc" },
    })
    expect(e.channels.email.outcome).toBe("deliver") // required overrides
  })

  it("global OFF disables email for all non-required notifications", async () => {
    await notify.preferences.update({
      recipientId: "user_1",
      notificationId: "*",
      channels: { email: false },
    })

    const mention = await notify.explain({
      recipientId: "user_1",
      notificationId: "comment_mentioned",
      payload: { actorName: "Rey", postUrl: "/p/1" },
    })
    expect(mention.channels.email.outcome).toBe("disabled")

    const reset = await notify.explain({
      recipientId: "user_1",
      notificationId: "password_reset",
      payload: { resetUrl: "/reset/abc" },
    })
    expect(reset.channels.email.outcome).toBe("deliver") // required wins
  })

  it("per-notification ON overrides global OFF", async () => {
    // Global: email off
    await notify.preferences.update({
      recipientId: "user_1",
      notificationId: "*",
      channels: { email: false },
    })
    // Exception: this specific notification stays on
    await notify.preferences.update({
      recipientId: "user_1",
      notificationId: "comment_mentioned",
      channels: { email: true },
    })

    const e = await notify.explain({
      recipientId: "user_1",
      notificationId: "comment_mentioned",
      payload: { actorName: "Rey", postUrl: "/p/1" },
    })
    expect(e.channels.email.outcome).toBe("deliver")
  })
})

const trail = await notify.preferences.explain({
  recipientId: "user_1",
  notificationId: "comment_mentioned",
})

// trail.email → {
//   outcome: "disabled",
//   resolvedBy: "user_notification",   ← which layer decided
//   trail: [
//     { layer: "app_default",          value: true },
//     { layer: "notification_default", value: true },
//     { layer: "tenant_setting",       value: null },   ← no tenant override
//     { layer: "user_global",          value: null },   ← no global pref
//     { layer: "user_notification",    value: false },  ← ✓ this one won
//   ]
// }