notifkit 0.1.3 → 0.1.5

package/README.md

@@ -4,17 +4,15 @@
 
 **You shouldn't have to build a notification system.**
 
-Self-hosted notification infrastructure for product notifications. One API call handles email, SMS, push, and webhooks — with preferences, quiet hours, retries, fallback, scheduling, workflows, and delivery logs built in.
+Self-hosted notification infrastructure for product notifications. One API call handles email, SMS, push, and webhooks, with preferences, quiet hours, retries, fallback, scheduling, workflows, and delivery logs built in.
 
-[![npm version](https://img.shields.io/npm/v/notifkit.svg?style=flat-square&color=6366f1)](https://www.npmjs.com/package/notifkit) [![npm downloads](https://img.shields.io/npm/dm/notifkit.svg?style=flat-square&color=6366f1)](https://www.npmjs.com/package/notifkit) [![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen.svg?style=flat-square)](https://github.com/devkitshq/notifkit) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-339933.svg?style=flat-square)](https://nodejs.org) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](./LICENSE)
+[![npm version](https://img.shields.io/npm/v/notifkit.svg?style=flat-square&color=6366f1)](https://www.npmjs.com/package/notifkit) [![npm downloads](https://img.shields.io/npm/dm/notifkit.svg?style=flat-square&color=6366f1)](https://www.npmjs.com/package/notifkit) [![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/devkitshq/notifkit/badges/coverage.json&style=flat-square)](https://github.com/devkitshq/notifkit/actions/workflows/ci.yml) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-339933.svg?style=flat-square)](https://nodejs.org) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](./LICENSE)
 
 [Documentation](https://notifkit.dev/docs/) · [Quickstart](https://notifkit.dev/docs/quickstart.html) · [Examples](https://notifkit.dev/docs/examples.html) · [notifkit.dev](https://notifkit.dev)
 
 </div>
 
----
-
-### The first notification is easy
+### Sending one notification is easy
 
 ```ts
 await sendEmail({
@@ -24,13 +22,9 @@ await sendEmail({
 });
 ```
 
-### Then reality hits
-
-Users opt out. People are asleep. Push tokens die. Providers throw 503s. Some channels fail and need fallback. You need timezone-aware quiet hours, future scheduling, deduplication, multi-channel templates, delivery logs, unsubscribe handling, multi-step workflows, and a dead-letter queue nobody wants to maintain.
+Sending them reliably is the hard part. Users opt out. People are asleep. Push tokens die. Providers throw 503s. Channels fail and need fallback. Somewhere along the way you need timezone-aware quiet hours, future scheduling, deduplication, multi-channel templates, delivery logs, unsubscribe handling, multi-step workflows, and a dead-letter queue nobody wants to maintain.
 
-**notifkit is that machinery, already built.**
-
-Your app makes one typed call. notifkit handles the rest — **who gets it, which channel to use, when to send it, whether they're allowed to receive it, and what happens when delivery fails.**
+notifkit is that machinery. Your app makes one typed call, and notifkit decides who gets the notification, which channel to use, when to send it, whether the user is allowed to receive it, and what to do when delivery fails.
 
 ```ts
 import { notifkit } from "notifkit";
@@ -43,15 +37,11 @@ await notifkit.notify({
 });
 ```
 
-> **Push first. If it fails, email.**
->
-> Preferences, consent, quiet hours, retries, deduplication, throttling, template rendering, and delivery tracking happen behind that single call.
-
----
+That call tries push, then email if push fails. Preferences, consent, quiet hours, retries, deduplication, throttling, template rendering, and delivery tracking all happen behind it.
 
-## What actually runs
+## How it runs
 
-notifkit is both an **orchestration engine** and a **typed SDK**.
+notifkit is an orchestration engine and a typed SDK.
 
 ```mermaid
 flowchart TD
@@ -79,7 +69,7 @@ flowchart TD
     DELIVER -.->|"delivery logs"| PG
     DELIVER -->|"Dispatch"| PROVIDERS
 
-    PROVIDERS["Provider Transports<br/>Email: Resend, SES, Postmark · Push: Firebase (FCM)<br/>SMS: Twilio, MessageBird · Webhooks: Custom HTTP"]
+    PROVIDERS["Provider Transports<br/>Email: Resend · Push: Firebase (FCM) · SMS: Twilio<br/>Chat: Slack, Telegram, Discord, WhatsApp<br/>Webhooks: Custom HTTP"]
 
     classDef entry stroke:#6366f1,stroke-width:2px
     classDef store stroke:#0ea5e9,stroke-width:2px
@@ -89,107 +79,90 @@ flowchart TD
     class ENRICH,ENGINE,DELIVER,SCHED work
 ```
 
-- **`NotifkitServer`**: Runs the HTTP REST API router (`/v1/notify`, `/health`, `/metrics`) and the background worker pipelines (enricher, decision engine, scheduler, delivery).
-- **`NotifkitClient`**: The lightweight client your application uses to trigger notifications, sync templates, and manage users over HTTP.
+`NotifkitServer` runs the HTTP REST API router (`/v1/notify`, `/health`, `/metrics`) and the background worker pipelines: enricher, decision engine, scheduler, and delivery. `NotifkitClient` is the lightweight client your application uses to trigger notifications, sync templates, and manage users over HTTP.
 
 ### Topologies
 
-- **Single Process (Monolith)**: Run the API and all workers in the same Node.js process (`services: ["all"]`). Perfect for small-to-medium apps, side projects, and staging.
-- **Distributed Services**: Run stateless API servers (`services: ["api"]`) behind a load balancer and scale worker pools (`services: ["enricher", "engine", "delivery", "scheduler"]`) horizontally across Redis Streams consumer groups.
-
----
-
-## Battle-tested for production
-
-> **Battle-tested in production:** notifkit powers production notification pipelines handling **thousands of emails, push notifications, and OTPs every day.**
->
-> It is the infrastructure we built because we needed it ourselves — rather than spending months reinventing distributed notification plumbing or paying SaaS tolls per alert.
+In a single process, the API and all workers run in the same Node.js process (`services: ["all"]`), which works for small and medium apps, side projects, and staging. Distributed, you run stateless API servers (`services: ["api"]`) behind a load balancer and scale worker pools (`services: ["enricher", "engine", "delivery", "scheduler"]`) horizontally across Redis Streams consumer groups.
 
-**Your servers. Your providers. Your data. Zero notification SaaS markups.**
-
-### Reliability & Chaos Engineering
-
-Because notification delivery is mission-critical, every pipeline component is tested against extreme failure conditions:
+## Quickstart
 
-```mermaid
-flowchart LR
-    S1["Redis Streams"] -->|"Kill Worker (SIGKILL)"| M1["Auto-Claim and Replay"] --> O1["Zero Lost Messages"]
-    S2["Connection Loss"] -->|"Drop DB / Redis"| M2["Auto-Reconnect / Retry"] --> O2["In-Flight State Intact"]
-    S3["10k+ Messages"] -->|"Burst"| M3["Concurrency and Limits"] --> O3["Flat Memory, No Leaks"]
+### 1. Install
 
-    classDef fault stroke:#ef4444,stroke-width:2px
-    classDef guard stroke:#6366f1,stroke-width:2px
-    classDef result stroke:#22c55e,stroke-width:2px
-    class S1,S2,S3 fault
-    class M1,M2,M3 guard
-    class O1,O2,O3 result
+```bash
+npm install notifkit @notifkit/provider-resend
+npm install -D tsx @testcontainers/postgresql @testcontainers/redis
 ```
 
-- **Chaos Monkey Testing (`tests/chaos/crash.test.ts`)**: Background worker processes are randomly terminated with `SIGKILL` during active, high-throughput message streaming. Consumer group Pending Entries List (PEL) re-claims guarantee **zero lost messages** and seamless failover.
-- **Infrastructure Recovery Testing (`tests/chaos/recovery.test.ts`)**: PostgreSQL and Redis connections are forcefully severed and restored under live traffic. Verifies automatic client reconnection, worker backpressure, and durable state resumption.
-- **High-Throughput Load Testing (`tests/chaos/load.test.ts`)**: Stressed with bursts of **10,000+ notifications** across parallel worker pools, verifying queue drain velocity, sliding-window rate limiters, and flat memory profiles without leaks.
-- **Race Conditions & Concurrency (`tests/race-conditions.test.ts`, `tests/idempotency.test.ts`)**: Hardened against concurrent duplicate dispatches, overlapping quiet-hour boundary evaluations, atomic user updates, and 24-hour idempotency key deduplication.
-- **100% Real Ephemeral Containers**: Unit, integration, and chaos test suites execute against real PostgreSQL and Redis containers via [Testcontainers](https://testcontainers.com), eliminating mocks for core storage and streaming primitives.
+The two `@testcontainers/*` packages are what notifkit uses to start throwaway PostgreSQL and Redis containers in development. They are imported lazily, only when the server is given neither a `databaseUrl`/`redisUrl` option nor a `DATABASE_URL`/`REDIS_URL` environment variable, so `devDependencies` is the right place for them.
 
----
+> [!WARNING]
+> Those containers are for local development only. They are thrown away when the process exits, taking every user, template, delivery log, and queued notification with them. Before you deploy, point notifkit at a real PostgreSQL and Redis — set `DATABASE_URL` and `REDIS_URL` (or pass `databaseUrl` and `redisUrl`) and run with `NODE_ENV=production`, which refuses to start a container and fails loudly if either is missing.
 
-## What you get
+### 2. Run the engine
 
-| The problem you don't want to build                      | How notifkit solves it                                               |
-| :------------------------------------------------------- | :------------------------------------------------------------------- |
-| **“Should this user receive it?”**                       | User preferences, topic opt-outs, and consent gates                  |
-| **“Is this a bad time to send?”**                        | Timezone-aware quiet hours that defer non-urgent sends               |
-| **“What if push fails?”**                                | Automatic ordered multi-channel fallback (`push` → `email` → `sms`)  |
-| **“What if my worker crashes?”**                         | Redis Streams consumer groups, retries, and durable idempotency      |
-| **“What if an event fires twice?”**                      | 24-hour deduplication via idempotency keys                           |
-| **“Can I send this later?”**                             | Priority scheduling with `sendAt` and cancellation before dispatch   |
-| **“Can I send this 3 days after signup?”**               | Stateful multi-step workflows with `wait` and `waitForEvent`         |
-| **“How do I know what happened?”**                       | Queryable delivery logs, Prometheus metrics, and campaign reporting  |
-| **“What happens when a provider goes down?”**            | Circuit breakers, exponential backoff, and DLQ replay                |
-| **“What about bounces and spam complaints?”**            | RFC 8058 one-click unsubscribe and automatic hard-bounce suppression |
-| **“What if I don't want another SaaS holding my data?”** | 100% self-hosted on your PostgreSQL and Redis                        |
+`server.ts` starts the API and the worker pipelines. In development it auto-starts those containers, so Docker is the only prerequisite.
 
-> **The idea is simple:** You decide what to say. **notifkit handles getting it there reliably.**
+```ts
+// server.ts
+import { NotifkitServer } from "notifkit";
+import { ResendTransport } from "@notifkit/provider-resend";
 
----
+const server = new NotifkitServer({
+  services: ["all"], // API + enricher + engine + scheduler + delivery
+  port: 3000,
+  providers: [
+    new ResendTransport({
+      apiKey: process.env.RESEND_API_KEY!,
+      from: "notifications@yourdomain.com",
+    }),
+  ],
+});
 
-## What notifkit is — and what it isn't
+await server.start();
+console.log("notifkit listening on http://localhost:3000");
+```
 
-**What it is:** the durable notification infrastructure layer running directly inside your own stack.
+`ADMIN_API_KEY` is the root credential. It is read from the environment, it is what mints project API keys in the next step, and without it the project-management routes answer `403`. Any string works locally:
 
-**What it isn't:** a marketing automation suite.
+```bash
+ADMIN_API_KEY=supersecretkey RESEND_API_KEY=re_xxx npx tsx server.ts
+```
 
-notifkit is not Customer.io, OneSignal, or SendGrid. You bring your own provider accounts — your keys, your billing, your deliverability.
+> [!WARNING]
+> `supersecretkey` is a local placeholder. In production this one value can mint keys for every project, so use a long random string kept in your secret store — `openssl rand -hex 32` is enough.
 
-First-party providers ship for Resend and Firebase Cloud Messaging. Anything else is a simple `Transport` class with a `send()` method.
+### 3. Create a project and its API key
 
----
+Every `/v1/*` route requires a project API key, and only the admin credential can mint one, so this is the single bootstrap step between a running server and your first notification:
 
-## Quickstart
+```bash
+ADMIN_API_KEY=supersecretkey npx notifkit-create-project "my-app"
+```
 
-### 1. Install
+```
+Project "my-app" created. Save the API key now — it is not recoverable.
 
-```bash
-npm install notifkit @notifkit/provider-resend
+NOTIFKIT_PROJECT_ID=1ce67fa1-b4a9-4985-8046-ef6018912b2a
+NOTIFKIT_API_KEY=nk_live_f57c57b76d795cef89e2dbf6b6f352a36…
 ```
 
-### 2. Run the engine and dispatch your first notification
+The server stores only a SHA-256 hash of the key, so the `nk_live_…` value is printed once and never again — put it in your app's `.env` now. Point the script at another host with `NOTIFKIT_URL`, and mint further keys later with `POST /v1/projects/:id/keys` (`role: "read_only"` there gets you a key that can read but not send).
+
+### 4. Dispatch your first notification
+
+`client.ts` is your application code. It talks to the server over HTTP: register a template, register a user, and send.
 
 ```ts
-import { NotifkitServer, NotifkitClient } from "notifkit";
-import { ResendTransport } from "@notifkit/provider-resend";
+// client.ts
+import { NotifkitClient } from "notifkit";
 
-// 1. Start the server (runs API + workers; auto-starts Postgres & Redis in dev)
-const server = new NotifkitServer({
-  services: ["all"],
-  port: 3000,
-  providers: [new ResendTransport({ apiKey: process.env.RESEND_API_KEY! })],
+const notifkit = new NotifkitClient({
+  baseUrl: "http://localhost:3000",
+  apiKey: process.env.NOTIFKIT_API_KEY!,
 });
-await server.start();
-
-// 2. Instantiate client and register a template
-const notifkit = new NotifkitClient({ baseUrl: "http://localhost:3000" });
 
+// 1. Register a template
 await notifkit.syncTemplates({
   templates: [
     {
@@ -200,9 +173,10 @@ await notifkit.syncTemplates({
   ],
 });
 
-// 3. Register user and dispatch
+// 2. Register a user
 await notifkit.addUser({ id: "usr_123", email: "alex@acme.com" });
 
+// 3. Dispatch
 await notifkit.notify({
   user: "usr_123",
   template: "order-shipped",
@@ -211,13 +185,20 @@ await notifkit.notify({
 });
 ```
 
-### 3. Or call directly via REST API
+With the server still running in the first terminal, run the client in a second one:
 
-You don't need the Node.js SDK — notifkit exposes a standard HTTP REST API, so you can dispatch notifications and manage resources from any language (cURL, Python, Go, etc.):
+```bash
+NOTIFKIT_API_KEY=nk_live_xxx npx tsx client.ts
+```
+
+### 5. Or call the REST API directly
+
+The Node.js SDK is optional. notifkit exposes a standard HTTP REST API, so you can dispatch notifications and manage resources from any language (cURL, Python, Go, and so on). The same project API key goes in the `Authorization` header (an `x-api-key` header works too):
 
 ```bash
 curl -X POST http://localhost:3000/v1/notify \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $NOTIFKIT_API_KEY" \
   -d '{
     "user": "usr_123",
     "template": "order-shipped",
@@ -226,18 +207,81 @@ curl -X POST http://localhost:3000/v1/notify \
   }'
 ```
 
-### Development vs. Production
+### Development vs. production
+
+Locally, Docker is the only prerequisite: in development notifkit starts throwaway PostgreSQL and Redis containers for you. In production you need Node 22+, PostgreSQL, and Redis, and you run migrations by pointing `drizzle-kit` at `node_modules/notifkit/drizzle`.
+
+## Running in production
+
+notifkit runs in production at my own company, delivering 100K+ notifications a day across email, push, and OTPs. I built it because I needed it and didn't want to spend months rebuilding distributed notification plumbing or pay a SaaS per alert. It runs on your servers, with your provider accounts and your data.
 
-- **Local Development**: Docker is the only prerequisite. In development, notifkit starts throwaway PostgreSQL and Redis containers automatically.
-- **Production**: Node 22+, PostgreSQL, Redis. Run migrations by pointing `drizzle-kit` at `node_modules/notifkit/drizzle`.
+### Reliability and failure testing
+
+Every component of the pipeline is tested against failure:
+
+```mermaid
+flowchart LR
+    S1["Redis Streams"] -->|"Kill Worker (SIGKILL)"| M1["Auto-Claim and Replay"] --> O1["Zero Lost Messages"]
+    S2["Connection Loss"] -->|"Drop DB / Redis"| M2["Auto-Reconnect / Retry"] --> O2["In-Flight State Intact"]
+    S3["10k+ Messages"] -->|"Burst"| M3["Concurrency and Limits"] --> O3["Flat Memory, No Leaks"]
+
+    classDef fault stroke:#ef4444,stroke-width:2px
+    classDef guard stroke:#6366f1,stroke-width:2px
+    classDef result stroke:#22c55e,stroke-width:2px
+    class S1,S2,S3 fault
+    class M1,M2,M3 guard
+    class O1,O2,O3 result
+```
+
+- Crash testing (`tests/chaos/crash.test.ts`): background worker processes are killed with `SIGKILL` during high-throughput message streaming. Consumer group Pending Entries List (PEL) re-claims mean no messages are lost and another worker takes over.
+- Infrastructure recovery (`tests/chaos/recovery.test.ts`): PostgreSQL and Redis connections are severed and restored under live traffic, verifying client reconnection, worker backpressure, and durable state resumption.
+- Load testing (`tests/chaos/load.test.ts`): bursts of 10,000+ notifications across parallel worker pools, checking queue drain speed, sliding-window rate limiters, and memory use over time.
+- Race conditions and concurrency (`tests/race-conditions.test.ts`, `tests/idempotency.test.ts`): concurrent duplicate dispatches, overlapping quiet-hour boundary evaluations, atomic user updates, and 24-hour idempotency key deduplication.
+- Real containers, no mocks: unit, integration, and chaos suites all run against real PostgreSQL and Redis containers via [Testcontainers](https://testcontainers.com).
+
+## What you get
 
----
+| The problem you don't want to build                  | How notifkit solves it                                               |
+| :--------------------------------------------------- | :------------------------------------------------------------------- |
+| "Should this user receive it?"                       | User preferences, topic opt-outs, and consent gates                  |
+| "Is this a bad time to send?"                        | Timezone-aware quiet hours that defer non-urgent sends               |
+| "What if push fails?"                                | Ordered multi-channel fallback (`push`, then `email`, then `sms`)    |
+| "What if my worker crashes?"                         | Redis Streams consumer groups, retries, and durable idempotency      |
+| "What if an event fires twice?"                      | 24-hour deduplication via idempotency keys                           |
+| "Can I send this later?"                             | Priority scheduling with `sendAt` and cancellation before dispatch   |
+| "Can I send this 3 days after signup?"               | Stateful multi-step workflows with `wait` and `waitForEvent`         |
+| "How do I know what happened?"                       | Queryable delivery logs, Prometheus metrics, and campaign reporting  |
+| "What happens when a provider goes down?"            | Circuit breakers, exponential backoff, and DLQ replay                |
+| "What about bounces and spam complaints?"            | RFC 8058 one-click unsubscribe and automatic hard-bounce suppression |
+| "What if I don't want another SaaS holding my data?" | Fully self-hosted on your PostgreSQL and Redis                       |
+
+You decide what to say. notifkit gets it there.
+
+## Scope
+
+notifkit is the durable notification layer that runs inside your own stack. It is not a marketing automation suite, and it does not replace Customer.io, OneSignal, or SendGrid. You bring your own provider accounts and pay them directly.
+
+First-party providers cover Resend, Firebase Cloud Messaging, Slack, Twilio, Telegram, Discord, and WhatsApp. Anything else is a `Transport` class with a `send()` method.
+
+### How this compares to Novu
+
+Novu is the established open-source project in this space, and if you want a notification platform with a dashboard, a visual workflow editor, and a drop-in in-app inbox component, use Novu. It is more mature, has a much larger community, and solves a broader problem.
+
+notifkit is a narrower, more embeddable take on the same layer:
+
+- **A library first, a platform second.** notifkit is an npm package you can run inside your existing Node process. Novu self-hosts as a set of services (API, worker, WebSocket server, dashboard SPA) that you deploy and operate alongside your app.
+- **Postgres, not MongoDB.** notifkit stores state in PostgreSQL with Drizzle migrations and queues in Redis Streams. If Postgres is already your database, there is no new datastore to run.
+- **Workflows as code.** Multi-step sequences are typed TypeScript, versioned in your repo, rather than built in a visual editor.
+- **MIT, all of it.** There is no open-core split. Novu is MIT at the core with enterprise features under a commercial license; notifkit has no feature held back from the self-hosted build.
+- **MCP as a first-class interface.** Agents operate the same infrastructure your app uses, including triage and delivery-log inspection.
+
+What notifkit does not have: an in-app notification center or inbox component, a web dashboard for non-engineers, digest aggregation, or Novu's provider catalog. If you need those, Novu is the better fit.
 
 ## Agent-operable
 
-**notifkit isn't just an API your application can call — your AI agent can operate it directly.**
+https://github.com/user-attachments/assets/4dff98bb-37d3-44b4-bf46-9607c1cd89b5
 
-Connect the notifkit MCP server ([`@notifkit/mcp`](./packages/mcp)) to Claude Code, Cursor, Claude Desktop, Gemini, or any MCP-compatible agent:
+An AI agent can operate notifkit directly. Connect the notifkit MCP server ([`@notifkit/mcp`](./packages/mcp)) to Claude Code, Cursor, Claude Desktop, Gemini, or any MCP-compatible agent:
 
 ```bash
 npx -y @notifkit/mcp
@@ -252,48 +296,42 @@ Agent: The notification was suppressed because usr_9182's email
        address has a hard-bounce suppression from yesterday.
 ```
 
-Your application and your AI agents use the **same notification infrastructure**:
+Your application and your AI agents use the same notification infrastructure. Through MCP an agent can:
 
-- **Send & dispatch** — Send one-off notifications or campaigns to users, lists, and segments (`send_notification`, `send_campaign`)
-- **Investigate & triage** — Diagnose delivery issues by inspecting message histories, provider responses, and quiet hours (`get_delivery_logs`, `get_notification`)
-- **Schedule & cancel** — Schedule future sends and cancel pending notifications (`list_scheduled`, `cancel_notification`)
-- **Campaign analytics** — Check delivery, open, click, bounce, and complaint metrics (`list_campaigns`, `get_campaign_stats`)
-- **Template management** — List, preview, and update templates with sample data (`list_templates`, `preview_template`, `upsert_template`)
-- **Users & preferences** — Look up users, contacts, preferences, and segment membership (`list_users`, `get_user_preferences`, `update_user_preferences`)
-- **Workflow operations** — Trigger workflows and inspect workflow runs (`create_workflow`, `trigger_workflow`, `get_workflow_run`)
-- **Suppressions & health** — Manage bounce suppressions, check system queues, and replay dead-letter messages (`list_suppressions`, `get_dead_letters`, `replay_dead_letter`)
+- Send one-off notifications or campaigns to users, lists, and segments (`send_notification`, `send_campaign`)
+- Diagnose delivery issues by inspecting message histories, provider responses, and quiet hours (`get_delivery_logs`, `get_notification`)
+- Schedule future sends and cancel pending notifications (`list_scheduled`, `cancel_notification`)
+- Check delivery, open, click, bounce, and complaint metrics (`list_campaigns`, `get_campaign_stats`)
+- List, preview, and update templates with sample data (`list_templates`, `preview_template`, `upsert_template`)
+- Look up users, contacts, preferences, and segment membership (`list_users`, `get_user_preferences`, `update_user_preferences`)
+- Trigger workflows and inspect workflow runs (`create_workflow`, `trigger_workflow`, `get_workflow_run`)
+- Manage bounce suppressions, check system queues, and replay dead-letter messages (`list_suppressions`, `get_dead_letters`, `replay_dead_letter`)
 
-### From “write a script” to “just ask”
+### The same task, with and without an agent
 
-| Without an agent                                                                                                                                                              | With NotifKit MCP                                                                                                                                                                                                                                                                                                                                                   |
-| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Jump into the DB to find contact info → open Twilio/Resend or write a throwaway script → format the payload → check their timezone manually → fire it off → hope it delivered | **You:** _“Send an urgent update to alex@acme.com that his package was lost in transit and support is rushing a replacement — text him if push doesn't deliver.”_<br><br>**Agent:** Looks up `alex@acme.com` → renders template → dispatches push with SMS fallback → bypasses quiet hours for urgent delivery → tracks delivery status → confirms it hit his phone |
+| Without an agent                                                                                                                                                               | With the notifkit MCP server                                                                                                                                                                                                                                                                                                                                                      |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Query the database for contact info, open Twilio or Resend or write a throwaway script, format the payload, check the user's timezone by hand, send it, and hope it delivered. | **You:** _"Send an urgent update to alex@acme.com that his package was lost in transit and support is rushing a replacement. Text him if push doesn't deliver."_<br><br>**Agent:** Looks up `alex@acme.com`, renders the template, dispatches push with SMS fallback, bypasses quiet hours because the send is urgent, tracks delivery status, and confirms it reached his phone. |
 
-[Set up MCP](https://notifkit.dev/docs/mcp.html) · [MCP documentation](https://notifkit.dev/docs/mcp.html)
-
----
+[MCP documentation](https://notifkit.dev/docs/mcp.html)
 
 ## AI-assisted migration
 
-Already have notification code scattered across your application?
-
-Point your coding agent at:
+Already have notification code scattered across your application? Point your coding agent at:
 
 ```text
 https://notifkit.dev/llms-full.txt
 ```
 
-It can understand notifkit's API and help identify ad-hoc notification code in your repository and refactor it into durable notifkit calls.
-
----
+It can read notifkit's API from there, find ad-hoc notification code in your repository, and refactor it into notifkit calls.
 
 ## Feature matrix
 
 |                     |                                                                                        |
 | :------------------ | :------------------------------------------------------------------------------------- |
-| **Channels**        | `email`, `sms`, `push`, `webhook`                                                      |
+| **Channels**        | `email`, `sms`, `push`, `webhook`, `telegram`, `discord`, `whatsapp`, `slack`          |
 | **Targeting**       | A user, a list of users, a segment, or a topic                                         |
-| **Priorities**      | `low`, `normal`, `high`, `critical` — separate stream lanes                            |
+| **Priorities**      | `low`, `normal`, `high`, `critical`, on separate stream lanes                          |
 | **Scheduling**      | Future sends with `sendAt`, quiet-hours deferral, cancellation                         |
 | **Preferences**     | Per-user channel and topic opt-outs, quiet hours, contact-level overrides              |
 | **Workflows**       | Multi-step sequences with `wait`, `waitForEvent`, and `notify` steps                   |
@@ -306,31 +344,30 @@ It can understand notifkit's API and help identify ad-hoc notification code in y
 | **Agent operation** | MCP server for sending, triage, campaigns, templates, workflows, and system operations |
 | **Observability**   | Prometheus `/metrics`, `/health`, `/live`, `/ready`, and queryable delivery logs       |
 
----
-
 ## Providers
 
-Bring your own provider accounts.
-
-First-party packages:
+Bring your own provider accounts. First-party packages:
 
-- [`@notifkit/provider-resend`](./packages/provider-resend) — transactional email via Resend
-- [`@notifkit/provider-fcm`](./packages/provider-fcm) — push notifications via Firebase Cloud Messaging
+- [`@notifkit/provider-resend`](./packages/provider-resend): transactional email via Resend
+- [`@notifkit/provider-fcm`](./packages/provider-fcm): push notifications via Firebase Cloud Messaging
+- [`@notifkit/provider-slack`](./packages/provider-slack): Slack messages via Incoming Webhooks or the Web API
+- [`@notifkit/provider-twilio`](./packages/provider-twilio): SMS via Twilio, with signature-verified delivery status callbacks
+- [`@notifkit/provider-telegram`](./packages/provider-telegram): messages via a Telegram bot
+- [`@notifkit/provider-discord`](./packages/provider-discord): messages via a Discord webhook
+- [`@notifkit/provider-whatsapp`](./packages/provider-whatsapp): messages via Meta's WhatsApp Cloud API
 
-For anything else, implement a simple `Transport`:
+For anything else, implement a `Transport`:
 
 ```ts
 class MyTransport implements Transport {
   async send(message) {
-    // Send through Twilio, SES, Postmark, APNs,
+    // Send through SES, Postmark, APNs,
     // SendGrid, a custom webhook, or anything else.
   }
 }
 ```
 
-**Your keys. Your billing. Your deliverability.**
-
----
+The keys, the billing, and the deliverability stay yours.
 
 ## Documentation
 
@@ -352,27 +389,13 @@ Everything lives at [**notifkit.dev/docs**](https://notifkit.dev/docs/).
 | [Reference](https://notifkit.dev/docs/reference.html)                          | API, payloads, and SDK methods                           |
 | [MCP server](https://notifkit.dev/docs/mcp.html)                               | Operate notifkit from an AI agent                        |
 
----
-
 ## Why build this?
 
-Because notification infrastructure looks simple until you're responsible for it.
-
-You can spend months building queues, retries, provider adapters, preference systems, quiet-hour logic, workflows, suppression handling, and operational tooling.
-
-Or you can use the infrastructure we built for ourselves.
-
-**notifkit exists so your team can spend its time building the product — not another notification platform.**
-
----
-
-## Star the repo ⭐
-
-If notifkit saves you a month or two you were about to spend building this yourself, **[give it a star on GitHub](https://github.com/devkitshq/notifkit)** — it's the cheapest way to help other people find it.
+Notification infrastructure looks simple until you're responsible for it. Queues, retries, provider adapters, preference systems, quiet-hour logic, workflows, suppression handling, and operational tooling take months to build well. notifkit is what I built instead, and it's what I run.
 
 ## Contributing
 
-Issues and pull requests are welcome.
+Issues and pull requests are welcome. Stars help other people find the project.
 
 ```bash
 npm install
@@ -382,6 +405,10 @@ npm test
 
 The test suite starts its own PostgreSQL and Redis containers, so Docker is the only thing you need running.
 
+## Contact
+
+Questions, bugs, or ideas: [contact.devkitshq@gmail.com](mailto:contact.devkitshq@gmail.com), or open an issue.
+
 ## License
 
 MIT. Do what you like with it, including commercially. See [LICENSE](./LICENSE).