API reference

import { createNotifyKit, memoryAdapter, setTimeoutQueue } from "@notifykitjs/core"

export const notify = createNotifyKit({
  notifications: [commentMentioned, orderShipped] as const,
  database: memoryAdapter(),
  providers: { email: resendProvider({ apiKey, from }) },
  queue: setTimeoutQueue(),
  retry: { maxAttempts: 5, delayMs: (n) => 1000 * 2 ** (n - 1) },
  unsubscribe: { secret: process.env.NOTIFYKIT_SECRET!, baseUrl },
  devMode: process.env.NODE_ENV !== "production",
})

const result = await notify.send({
  recipientId: string,
  notificationId: string,      // must match a registered definition
  payload: { ... },            // typed per notification
  tenantId?: string,
  organizationId?: string,     // alias for tenantId
  workspaceId?: string,
  idempotencyKey?: string,
  dedupeKey?: string,
  dedupeWindowMs?: number,
  dryRun?: boolean,
})

type SendResult = {
  notification: NotificationRecord | null
  inboxItems: InboxItem[]
  deliveries: DeliveryRecord[]
  skippedChannels: ChannelType[] // deprecated; use skipped[]
  skipped: SkippedDelivery[]
  deferredChannels: ChannelType[]
  digested: boolean
  rateLimited: boolean
  idempotent: boolean
}

const explanation = await notify.explain({
  recipientId: "user_123",
  notificationId: "comment_mentioned",
  payload: { actorName: "Rey", postUrl: "/posts/42" },
})

// Check why email didn't fire:
console.log(explanation.channels.email)
// → { outcome: "skipped", reason: "preferences_disabled" }

// Check the full preference trail:
console.log(explanation.preferences)
// → { global: { email: true }, recipient: { email: false }, resolved: { email: false } }

// Check pipeline stages:
console.log(explanation.wouldRateLimit)  // false
console.log(explanation.quietHours)      // { active: true, resumesAt: "2026-06-28T08:00:00Z" }

import { NotifyKitValidationError, NotifyKitNotFoundError } from "@notifykitjs/core"

try {
  const result = await notify.send({
    recipientId: userId,
    notificationId: "comment_mentioned",
    payload: data,
  })
  // result.deliveries may contain failed deliveries — those are NOT errors
  // They were attempted, retried, and captured in the result
} catch (err) {
  if (err instanceof NotifyKitValidationError) {
    // Payload was wrong — log which fields and fix upstream
    console.error("Bad payload:", err.fields)
  } else if (err instanceof NotifyKitNotFoundError) {
    // Recipient doesn't exist yet — create them and retry
    await notify.upsertRecipient({ id: userId, email: userEmail })
    await notify.send({ ... })
  } else {
    // Infrastructure error (DB down, connection refused)
    throw err
  }
}

// Create the recipient (idempotent — safe to call on every login)
await notify.upsertRecipient({
  id: user.id,
  email: user.email,
  name: user.name,
  tenantId: user.orgId,
})

// 2. Set their default preferences (optional — skip if you want all-on)
await notify.preferences.update({
  recipientId: user.id,
  notificationId: "marketing_digest",
  channels: { email: false },
  tenantId: user.orgId,
})

// 3. Send the welcome notification
const result = await notify.send({
  recipientId: user.id,
  notificationId: "welcome",
  payload: { name: user.name },
  tenantId: user.orgId,
})

const recipientId = user.id
const tenantId = user.orgId

// 1. Drain any in-flight sends so nothing new arrives mid-cleanup
await notify.drain()

// 2. Clear their inbox (iterate and delete)
const items = await notify.inbox.list(recipientId, { tenantId })
await Promise.all(
  items.map(item => notify.inbox.deleteForRecipient(item.id, recipientId, { tenantId }))
)

// 3. Opt them out of all channels to prevent future sends
//    (belt-and-suspenders — even if your app stops calling send() for this user,
//    scheduled digests or queued sends might still fire)
const metadata = notify.notificationMetadata
await Promise.all(
  metadata.map(n =>
    notify.preferences.update({
      recipientId,
      notificationId: n.id,
      channels: { email: false, sms: false, inbox: false, webhook: false },
      tenantId,
    })
  )
)

// 4. Prune their timeline data (GDPR / data minimization)
await notify.pruneTimeline(new Date())  // prune all existing timeline events

const recipientId = "user_abc"

// 1. Find recent deliveries for this user
const deliveries = await notify.deliveries.list(recipientId)
const failed = deliveries.filter(d => d.status === "failed" || d.status === "skipped")

// 2. Check the timeline for the specific send
if (failed.length > 0) {
  const events = await notify.timeline(failed[0].notificationRecordId)
  // events show: created → channel_evaluated → delivery_attempted → failed (with error)
}

// 3. Dry-run the same send to see what would happen now
const explanation = await notify.explain({
  recipientId,
  notificationId: "comment_mentioned",
  payload: { actorName: "Test", postTitle: "Test", postUrl: "#" },
})
// explanation shows current preferences, quiet hours, provider state

async function getPreferencesPageData(recipientId: string, tenantId: string) {
  const [prefs, metadata] = await Promise.all([
    notify.preferences.list(recipientId, { tenantId }),
    notify.notificationMetadata,  // safe subset: id, description, category, channels
  ])

  // Group by category for the UI
  const grouped = Object.groupBy(metadata, m => m.category ?? "general")

  // Merge saved preferences with available notifications
  return Object.entries(grouped).map(([category, notifications]) => ({
    category,
    notifications: notifications!.map(n => ({
      id: n.id,
      description: n.description,
      channels: n.channels,
      preferences: prefs.find(p => p.notificationId === n.id)?.channels ?? {},
    })),
  }))
}

export async function handler(req: Request) {
  const result = await notify.send({ ... })

  // Flush deferred sends (quiet hours) and digests before shutdown
  await Promise.all([
    notify.flushScheduledSends(),
    notify.flushDigests(),
  ])

  // Wait for any in-flight queue jobs to complete
  await notify.drain()

  return Response.json(result)
}

// ─── Send ────────────────────────────────────────────────────────────
await notify.send({ recipientId, notificationId, payload })
await notify.send({ recipientId, notificationId, payload, tenantId, idempotencyKey, dedupeKey, dedupeWindowMs })
await notify.send({ recipientId, notificationId, payload, dryRun: true })  // → DeliveryExplanation
await notify.explain({ recipientId, notificationId, payload })             // same as dryRun: true

// ─── Recipients ──────────────────────────────────────────────────────
await notify.upsertRecipient({ id, email?, phone?, name?, tenantId?, quietHours? })

// ─── Inbox (server-side) ─────────────────────────────────────────────
await notify.inbox.list(recipientId, { tenantId }?, { archived }?, limit?)
await notify.inbox.unreadCount(recipientId, { tenantId }?)
await notify.inbox.markReadForRecipient(itemId, recipientId, { tenantId }?)
await notify.inbox.markAllRead(recipientId, { tenantId }?)
await notify.inbox.archiveForRecipient(itemId, recipientId, { tenantId }?)
await notify.inbox.unarchiveForRecipient(itemId, recipientId, { tenantId }?)
await notify.inbox.deleteForRecipient(itemId, recipientId, { tenantId }?)

// ─── Preferences ─────────────────────────────────────────────────────
await notify.preferences.list(recipientId, { tenantId }?)
await notify.preferences.get({ recipientId, notificationId, tenantId? })
await notify.preferences.update({ recipientId, notificationId, channels: { email: false }, tenantId? })
await notify.preferences.explain({ recipientId, notificationId, tenantId? })

// ─── Debugging ───────────────────────────────────────────────────────
await notify.timeline(notificationRecordId)
await notify.timeline(notificationRecordId, { deliveryId })
await notify.deliveries.list(recipientId?, { tenantId }?, limit?)
await notify.pruneTimeline(olderThan?)
notify.redactPayload(notificationId, payload)

// ─── Lifecycle ───────────────────────────────────────────────────────
await notify.drain()                 // wait for in-flight jobs
await notify.flushScheduledSends()   // fire deferred quiet-hours sends
await notify.flushDigests()          // flush expired digest buckets

// ─── Instance properties ─────────────────────────────────────────────
notify.definitions                   // NotificationDefinition[]
notify.notificationMetadata          // NotificationMeta[] (safe for client)