Explain & dry run

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

console.log(explanation)

const explanation = await notify.send({
  recipientId: user.id,
  notificationId: "comment_mentioned",
  payload: { actorName: "Rey", postTitle: "Launch Plan", postUrl: "/posts/42" },
  dryRun: true,
})

{
  // Pipeline-level decisions (checked first)
  wouldRateLimit: false,       // under threshold
  wouldDeduplicate: false,     // no matching dedup key
  wouldDigest: false,          // no digest configured
  wouldReplayIdempotent: false,// no matching idempotency key

  // Payload validation
  payloadValidation: { valid: true, errors: [] },

  // Notification metadata
  required: false,             // preferences apply

  // Rate limit state
  rateLimit: { current: 7, max: 30, windowMs: 3600000 },

  // Quiet hours state
  quietHours: { active: false, start: "22:00", end: "08:00", timezone: "America/New_York" },

  // Per-channel resolution
  channels: {
    inbox: {
      outcome: "deliver",      // ✓ will fire
      allowed: true,
      resolvedBy: "app_default",
      trail: [{ layer: "app_default", value: true }],
    },
    email: {
      outcome: "disabled",     // ✗ user opted out
      allowed: false,
      resolvedBy: "user_notification",
      trail: [
        { layer: "app_default", value: true },
        { layer: "notification_default", value: undefined },
        { layer: "tenant_setting", value: undefined },
        { layer: "user_notification", value: false },  // ← blocked here
      ],
    },
  },
}

// explanation.channels[0].trail:
[
  { layer: "app_default", value: true },
  { layer: "notification_default", value: undefined },
  { layer: "tenant_setting", value: undefined },
  { layer: "user_notification", value: false },  // ← user disabled it
]
// resolvedBy: "user_notification"
// allowed: false

const prefExplanation = await notify.preferences.explain({
  recipientId: user.id,
  notificationId: "comment_mentioned",
})

// Returns PreferenceExplanation with channels, resolution trails,
// required status, classification, and category info.

const e = await notify.explain({
  recipientId: "user_456",
  notificationId: "comment_mentioned",
  payload: { actorName: "Rey", postTitle: "Q4 Plan", postUrl: "/posts/99" },
})

// Shortcut: find all blocked channels
const blocked = Object.entries(e.channels)
  .filter(([, ch]) => ch.outcome !== "deliver")
  .map(([name, ch]) => `${name}: ${ch.outcome} (by ${ch.resolvedBy ?? "system"})`)

console.log(blocked.length ? blocked : "All channels would deliver")

import { notify } from "@/lib/notifykit"
import { requireAdmin } from "@/lib/auth"

export async function GET(request: Request) {
  await requireAdmin(request)
  const url = new URL(request.url)
  const recipientId = url.searchParams.get("user")!
  const notificationId = url.searchParams.get("notification")!

  const explanation = await notify.explain({
    recipientId,
    notificationId,
    payload: getTestPayload(notificationId), // default test values
  })

  // Translate to support-friendly format
  const diagnosis = {
    wouldDeliver: Object.values(explanation.channels)
      .some(ch => ch.outcome === "deliver"),
    blockers: Object.entries(explanation.channels)
      .filter(([, ch]) => ch.outcome !== "deliver")
      .map(([name, ch]) => ({
        channel: name,
        reason: friendlyReason(ch.outcome, ch.resolvedBy),
      })),
    quietHours: explanation.quietHours?.active
      ? `Active until ${explanation.quietHours.resumesAt}`
      : "Not active",
    rateLimited: explanation.wouldRateLimit
      ? `${explanation.rateLimit.current}/${explanation.rateLimit.max} in window`
      : "Under limit",
  }

  return Response.json(diagnosis)
}

function friendlyReason(outcome: string, layer?: string): string {
  const reasons: Record<string, string> = {
    disabled: `User opted out (set by: ${layer ?? "unknown"})`,
    unavailable: "No email/phone on file for this user",
    delayed: "Held by quiet hours — will deliver when window ends",
    rate_limited: "Too many sends in window — dropped",
    deduplicated: "Already sent recently — skipped as duplicate",
    digested: "Batched into a digest — will arrive with next flush",
  }
  return reasons[outcome] ?? outcome
}

import { describe, it, expect, beforeAll } from "vitest"
import { createNotifyKit, memoryAdapter, fakeEmailProvider } from "@notifykitjs/core"
import { commentMentioned } from "./notifications"

const notify = createNotifyKit({
  notifications: [commentMentioned] as const,
  database: memoryAdapter(),
  providers: { email: fakeEmailProvider() },
})

describe("notification routing", () => {
  beforeAll(async () => {
    await notify.upsertRecipient({ id: "user_1", email: "a@test.com" })
    await notify.upsertRecipient({ id: "user_2" }) // no email
  })

  it("delivers to inbox and email when recipient has both", 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")
    expect(e.wouldRateLimit).toBe(false)
    expect(e.wouldDeduplicate).toBe(false)
  })

  it("skips email when recipient has no address", async () => {
    const e = await notify.explain({
      recipientId: "user_2",
      notificationId: "comment_mentioned",
      payload: { actorName: "Rey", postUrl: "/p/1" },
    })

    expect(e.channels.inbox.outcome).toBe("deliver")
    expect(e.channels.email.outcome).toBe("unavailable")
  })

  it("respects preference opt-out", 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.email.resolvedBy).toBe("user_notification")
  })

  it("reports rate limit status without consuming budget", async () => {
    // Send 30 times to hit the rate limit
    for (let i = 0; i < 30; i++) {
      await notify.send({
        recipientId: "user_1",
        notificationId: "comment_mentioned",
        payload: { actorName: `User ${i}`, postUrl: "/p/1" },
      })
    }

    // explain() reports the limit WITHOUT counting against it
    const e = await notify.explain({
      recipientId: "user_1",
      notificationId: "comment_mentioned",
      payload: { actorName: "Next", postUrl: "/p/1" },
    })

    expect(e.wouldRateLimit).toBe(true)
    expect(e.rateLimit.current).toBe(30)
    expect(e.rateLimit.max).toBe(30)
  })
})

it("tenant default overrides app default", async () => {
  // Setup: tenant "free_org" has email off by default
  const e = await notify.explain({
    recipientId: "free_user",
    notificationId: "comment_mentioned",
    payload: { actorName: "Rey", postUrl: "/p/1" },
  })

  // Verify the trail shows which layer won
  const emailTrail = e.channels.email.trail
  const tenantLayer = emailTrail.find(t => t.layer === "tenant_setting")

  expect(tenantLayer?.value).toBe(false)
  expect(e.channels.email.resolvedBy).toBe("tenant_setting")
  expect(e.channels.email.outcome).toBe("disabled")
})

it("user preference overrides tenant default", async () => {
  // User explicitly opted back in despite tenant default
  await notify.preferences.update({
    recipientId: "free_user",
    notificationId: "comment_mentioned",
    channels: { email: true },
  })

  const e = await notify.explain({
    recipientId: "free_user",
    notificationId: "comment_mentioned",
    payload: { actorName: "Rey", postUrl: "/p/1" },
  })

  // User preference wins over tenant default
  expect(e.channels.email.resolvedBy).toBe("user_notification")
  expect(e.channels.email.outcome).toBe("deliver")
})