Channels

import { channel } from "@notifykitjs/core"

const inbox = channel.inbox()

inbox({
  title: "{{actorName}} mentioned you",
  body: "In {{postTitle}}",
  actionUrl: "{{postUrl}}",
})

const email = channel.email()

email({
  subject: "{{actorName}} mentioned you in {{postTitle}}",
  body: "Open {{postUrl}} to reply.\n\nUnsubscribe: {{_unsubscribeUrl}}",
})

const sms = channel.sms()

sms({
  body: "Your verification code is {{code}}",
})

const webhook = channel.webhook()

webhook({
  url: "https://hooks.slack.com/services/T.../B.../xxx",
  headers: { "Content-Type": "application/json" },
})

// What your endpoint receives:
{
  "event": "notification.delivered",
  "notificationId": "deploy_completed",
  "recipientId": "user_123",
  "payload": {
    "projectName": "api-gateway",
    "status": "succeeded",
    "sha": "abc123f"
  },
  "metadata": {
    "sentAt": "2026-06-27T14:30:00.000Z",
    "deliveryId": "del_abc123",
    "attempt": 1
  }
}

// Your webhook receiver (any framework)
import { createHmac, timingSafeEqual } from "node:crypto"

const WEBHOOK_SECRET = process.env.NOTIFYKIT_WEBHOOK_SECRET!

function verifySignature(rawBody: string, signatureHeader: string): boolean {
  const expected = createHmac("sha256", WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex")

  const received = signatureHeader.replace("sha256=", "")

  return timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex"),
  )
}

// Express / Node.js example:
app.post("/webhooks/notifykit", (req, res) => {
  const signature = req.headers["x-notifykit-signature"]
  if (!signature || !verifySignature(req.rawBody, signature)) {
    return res.status(401).json({ error: "Invalid signature" })
  }

  const { notificationId, payload, metadata } = req.body
  // Process the webhook...
  res.status(200).json({ received: true })
})

// Next.js Route Handler:
export async function POST(request: Request) {
  const rawBody = await request.text()
  const signature = request.headers.get("x-notifykit-signature")

  if (!signature || !verifySignature(rawBody, signature)) {
    return Response.json({ error: "Invalid signature" }, { status: 401 })
  }

  const body = JSON.parse(rawBody)
  // Process...
  return Response.json({ received: true })
}

// Slack: expects { text } or { blocks }
notification({
  id: "deploy_completed",
  payload: {
    projectName: "string",
    status: "string",
    sha: "string",
    actorName: "string",
  },
  channels: [
    inbox({ title: "Deploy {{status}}: {{projectName}}" }),
    webhook({
      url: "https://hooks.slack.com/services/T.../B.../xxx",
      render: (payload) => ({
        body: JSON.stringify({
          text: `Deploy *${payload.status}*: ${payload.projectName} (${payload.sha.slice(0, 7)})`,
          blocks: [
            {
              type: "section",
              text: {
                type: "mrkdwn",
                text: `*${payload.projectName}* deployed by ${payload.actorName}`,
              },
            },
            {
              type: "context",
              elements: [
                { type: "mrkdwn", text: `Status: ${payload.status} | SHA: \`${payload.sha.slice(0, 7)}\`` },
              ],
            },
          ],
        }),
      }),
    }),
  ],
})

// Discord: expects { content } or { embeds }
webhook({
  url: "https://discord.com/api/webhooks/123/abc",
  render: (payload) => ({
    body: JSON.stringify({
      content: `Deploy **${payload.status}**: ${payload.projectName}`,
      embeds: [{
        title: payload.projectName,
        description: `Deployed by ${payload.actorName}`,
        color: payload.status === "succeeded" ? 0x00ff00 : 0xff0000,
        fields: [
          { name: "SHA", value: `\`${payload.sha.slice(0, 7)}\``, inline: true },
          { name: "Status", value: payload.status, inline: true },
        ],
      }],
    }),
  }),
})

notification({
  id: "incident_alert",
  payload: {
    severity: "string",    // "low" | "medium" | "high" | "critical"
    title: "string",
    dashboardUrl: "string",
  },
  channels: [
    // Inbox: always fires
    inbox({
      title: "Incident: {{title}}",
      actionUrl: "{{dashboardUrl}}",
    }),

    // Email: fires for medium+ severity
    email({
      condition: (payload) => payload.severity !== "low",
      subject: "[{{severity}}] {{title}}",
      body: "View dashboard: {{dashboardUrl}}\n\nUnsubscribe: {{_unsubscribeUrl}}",
    }),

    // SMS: fires only for critical
    sms({
      condition: (payload) => payload.severity === "critical",
      body: "CRITICAL: {{title}} — check dashboard immediately",
    }),
  ],
})

// Dynamic webhook URL from payload:
notification({
  id: "deploy_completed",
  payload: {
    projectName: "string",
    status: "string",
    webhookUrl: "string",  // empty string if not configured
  },
  channels: [
    inbox({
      title: "Deploy {{status}}: {{projectName}}",
    }),
    webhook({
      condition: (payload) => !!payload.webhookUrl,
      url: "{{webhookUrl}}",   // dynamic — comes from payload
    }),
  ],
})

notification({
  id: "task_assigned",
  payload: {
    assignerName: "string",
    taskTitle: "string",
    taskUrl: "string",
    projectName: "string",
  },
  channels: [
    inbox({
      title: "{{assignerName}} assigned you a task",
      body: "{{taskTitle}} in {{projectName}}",
      actionUrl: "{{taskUrl}}",
    }),
    email({
      subject: "New task: {{taskTitle}}",
      body: "{{assignerName}} assigned you '{{taskTitle}}' in {{projectName}}.\n\nOpen it: {{taskUrl}}\n\nUnsubscribe: {{_unsubscribeUrl}}",
    }),
    webhook({
      url: "https://hooks.slack.com/services/T.../B.../xxx",
    }),
  ],
  // Pipeline options (all optional):
  required: false,              // user can opt out per channel
  defaultChannels: { inbox: true, email: true, webhook: true },
})

// Definition:
notification({
  id: "comment_mentioned",
  payload: { actorName: "string", postTitle: "string", postUrl: "string" },
  channels: [
    inbox({ title: "{{actorName}} mentioned you", body: "In {{postTitle}}", actionUrl: "{{postUrl}}" }),
    email({ subject: "{{actorName}} mentioned you in {{postTitle}}", body: "Open {{postUrl}}" }),
  ],
})

// Send:
await notify.send({
  recipientId: user.id,
  notificationId: "comment_mentioned",
  payload: { actorName: "Rey", postTitle: "Launch Plan", postUrl: "/posts/42" },
})
// → inbox title resolves to "Rey mentioned you"
// → email subject resolves to "Rey mentioned you in Launch Plan"

// Using built-in variables in an email:
email({
  subject: "Hi {{_recipient.name}}, {{actorName}} mentioned you",
  body: `Open {{postUrl}} to reply.

Unsubscribe: {{_unsubscribeUrl}}`,
})

notification({
  id: "order_shipped",
  payload: {
    orderNumber: "string",
    itemCount: "number",
    trackingUrl: "string",
    expedited: "boolean",
  },
  channels: [
    inbox({
      render: (payload) => ({
        title: `Order ${payload.orderNumber} shipped`,
        body: payload.expedited
          ? `${payload.itemCount} items — expedited shipping`
          : `${payload.itemCount} items on the way`,
        actionUrl: payload.trackingUrl,
      }),
    }),
    email({
      render: (payload) => ({
        subject: `Your order ${payload.orderNumber} has shipped`,
        body: [
          `Hi! Your order with ${payload.itemCount} item${payload.itemCount > 1 ? "s" : ""} is on the way.`,
          payload.expedited ? "Expedited delivery — arriving in 1-2 days." : "",
          `Track your package: ${payload.trackingUrl}`,
          "",
          `Unsubscribe: {{_unsubscribeUrl}}`,
        ].filter(Boolean).join("\n"),
      }),
    }),
  ],
})

import { renderEmailHtml } from "@/lib/email-templates"

notification({
  id: "weekly_digest",
  payload: {
    recipientName: "string",
    highlights: "string",
    unreadCount: "number",
    weekOf: "string",
  },
  channels: [
    email({
      render: (payload) => ({
        subject: `Your weekly digest — ${payload.weekOf}`,
        body: renderEmailHtml({
          heading: `Hey ${payload.recipientName}, here's your week`,
          sections: [
            { title: "Highlights", content: payload.highlights },
            { title: "Unread", content: `${payload.unreadCount} notifications waiting` },
          ],
          footer: { unsubscribeUrl: "{{_unsubscribeUrl}}" },
        }),
        html: true,
      }),
    }),
  ],
})

import { t } from "@/lib/i18n"

notification({
  id: "comment_mentioned",
  payload: {
    actorName: "string",
    postTitle: "string",
    postUrl: "string",
    locale: "string",
  },
  channels: [
    inbox({
      render: (payload) => ({
        title: t(payload.locale, "mention.title", { actor: payload.actorName }),
        body: t(payload.locale, "mention.body", { post: payload.postTitle }),
        actionUrl: payload.postUrl,
      }),
    }),
    email({
      render: (payload) => ({
        subject: t(payload.locale, "mention.email_subject", {
          actor: payload.actorName,
          post: payload.postTitle,
        }),
        body: t(payload.locale, "mention.email_body", {
          actor: payload.actorName,
          url: payload.postUrl,
        }),
      }),
    }),
  ],
})

// notifications/order-shipped.ts
export const orderShippedInbox = (payload) => ({
  title: `Order ${payload.orderNumber} shipped`,
  body: payload.itemCount === 1
    ? "1 item on the way"
    : `${payload.itemCount} items on the way`,
  actionUrl: payload.trackingUrl,
})

// notifications/order-shipped.test.ts
import { orderShippedInbox } from "./order-shipped"

test("singular item text", () => {
  const result = orderShippedInbox({
    orderNumber: "ABC-123",
    itemCount: 1,
    trackingUrl: "/track/abc",
    expedited: false,
  })
  expect(result.body).toBe("1 item on the way")
})

test("plural item text", () => {
  const result = orderShippedInbox({
    orderNumber: "ABC-123",
    itemCount: 5,
    trackingUrl: "/track/abc",
    expedited: false,
  })
  expect(result.body).toBe("5 items on the way")
})

import { notify } from "./notifykit"

test("comment_mentioned resolves all template variables", async () => {
  const result = await notify.explain({
    recipientId: "user_test",
    notificationId: "comment_mentioned",
    payload: { actorName: "Rey", postTitle: "Launch Plan", postUrl: "/posts/42" },
  })

  // Verify no unresolved {{variables}} remain
  const inboxChannel = result.channels.find(c => c.name === "inbox")
  expect(inboxChannel.rendered.title).toBe("Rey mentioned you")
  expect(inboxChannel.rendered.title).not.toMatch(/\{\{/)

  // Verify channel was not skipped
  expect(inboxChannel.status).toBe("would_deliver")
})

// notifykit.config.ts
import { createNotifyKit } from "@notifykitjs/core"
import { memoryAdapter } from "@notifykitjs/core"

export const notify = createNotifyKit({
  database: memoryAdapter(),
  devMode: process.env.NODE_ENV !== "production",
  // In dev mode:
  // - Email renders to console (subject + body)
  // - SMS renders to console (body)
  // - Webhook logs the full payload without POSTing
  // - Inbox writes to the in-memory DB as normal
})

// Console when devMode is enabled:
// ┌─────────────────────────────────────────────────
// │ 📧 EMAIL → user_123
// │ Subject: Rey mentioned you in Launch Plan
// │ Body: Open /posts/42 to reply.
// │
// │ Unsubscribe: http://localhost:3000/unsubscribe?token=dev_xxx
// └─────────────────────────────────────────────────
// ┌─────────────────────────────────────────────────
// │ 📥 INBOX → user_123
// │ Title: Rey mentioned you
// │ Body: In Launch Plan
// │ Action: /posts/42
// └─────────────────────────────────────────────────

const result = await notify.send({
  recipientId: user.id,
  notificationId: "comment_mentioned",
  payload: { actorName: "Rey", postTitle: "Launch", postUrl: "/posts/1" },
})

// Was anything skipped?
for (const skip of result.skipped) {
  console.log(`Channel ${skip.channel} skipped: ${skip.reason}`)
  // → "Channel email skipped: missing_destination"
  // → "Channel sms skipped: preference_opt_out"
}

// Did any delivery fail after retries?
const failures = result.deliveries.filter(d => d.status === "failed")
for (const fail of failures) {
  console.log(`${fail.channel} failed: ${fail.error}`)
  // → "email failed: 550 mailbox not found"
}

// Was it deferred by quiet hours?
if (result.deferredChannels.length > 0) {
  console.log(`Deferred: ${result.deferredChannels.join(", ")}`)
  // → "Deferred: email, sms"
}