notifkit 0.1.12 → 0.1.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
**You shouldn't have to build a notification system.**
|
|
6
6
|
|
|
7
|
-
Self-hosted notification infrastructure for product notifications. One API call handles email, SMS,
|
|
7
|
+
Self-hosted notification infrastructure for product notifications. One API call handles push, email, SMS, chat, and webhooks, with preferences, quiet hours, retries, fallback, scheduling, workflows, an admin dashboard, and delivery logs built in.
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/notifkit) [](https://www.npmjs.com/package/notifkit) [](https://github.com/devkitshq/notifkit/actions/workflows/ci.yml) [](https://www.typescriptlang.org/) [](https://nodejs.org) [](./LICENSE)
|
|
10
10
|
|
|
@@ -12,23 +12,9 @@ Self-hosted notification infrastructure for product notifications. One API call
|
|
|
12
12
|
|
|
13
13
|
</div>
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Like Knock or Courier, except it runs on the PostgreSQL and Redis you already have, your workflows live in your code, and there is no per-message bill.
|
|
16
16
|
|
|
17
17
|
```ts
|
|
18
|
-
await sendEmail({
|
|
19
|
-
to: user.email,
|
|
20
|
-
subject: "Order Shipped",
|
|
21
|
-
...
|
|
22
|
-
});
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
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.
|
|
26
|
-
|
|
27
|
-
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.
|
|
28
|
-
|
|
29
|
-
```ts
|
|
30
|
-
import { notifkit } from "notifkit";
|
|
31
|
-
|
|
32
18
|
await notifkit.notify({
|
|
33
19
|
user: "usr_123",
|
|
34
20
|
template: "order-shipped",
|
|
@@ -39,303 +25,67 @@ await notifkit.notify({
|
|
|
39
25
|
|
|
40
26
|
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.
|
|
41
27
|
|
|
42
|
-
##
|
|
43
|
-
|
|
44
|
-
notifkit is an orchestration engine and a typed SDK.
|
|
45
|
-
|
|
46
|
-
```mermaid
|
|
47
|
-
flowchart TD
|
|
48
|
-
App["Your Application / AI Agent / Browser<br/>Typed SDK · REST API · MCP Server · Admin Dashboard"]
|
|
49
|
-
|
|
50
|
-
App -->|"HTTP POST /v1/notify"| API
|
|
51
|
-
App -->|"HTTP GET /admin"| API
|
|
52
|
-
|
|
53
|
-
API["Notifkit API Server<br/>Schema Validation · Auth · Multi-Tenancy<br/>Admin SPA · Priority Queue Ingestion"]
|
|
54
|
-
|
|
55
|
-
API --> PG
|
|
56
|
-
API --> REDIS
|
|
57
|
-
|
|
58
|
-
PG[("PostgreSQL — Storage<br/>Users · Preferences<br/>Templates · Workflows<br/>Delivery Logs · DLQ")]
|
|
59
|
-
REDIS[("Redis — Streams / ZSET<br/>Priority Queues<br/>Scheduled Sends<br/>Sliding Rate Limits")]
|
|
60
|
-
|
|
61
|
-
subgraph WORKERS["Background Workers Pipeline"]
|
|
62
|
-
direction LR
|
|
63
|
-
ENRICH["Enricher<br/>(Resolve)"] --> ENGINE["Engine<br/>(Quiet Hours)"] --> DELIVER["Delivery<br/>(Rate Limits / CB)"]
|
|
64
|
-
ENGINE --> SCHED["Scheduler<br/>(sendAt / QH)"]
|
|
65
|
-
SCHED --> DELIVER
|
|
66
|
-
end
|
|
67
|
-
REDIS -->|"consume"| ENRICH
|
|
68
|
-
ENRICH -.->|"read / write state"| PG
|
|
69
|
-
DELIVER -.->|"delivery logs"| PG
|
|
70
|
-
DELIVER -->|"Dispatch"| PROVIDERS
|
|
28
|
+
## Why notifkit
|
|
71
29
|
|
|
72
|
-
|
|
30
|
+
- **Doesn't lose messages.** Redis Streams consumer groups, 24-hour idempotency, retries, circuit breakers and a replayable dead-letter queue. [Chaos-tested](./tests/chaos): workers killed with `SIGKILL` mid-stream, Redis and PostgreSQL restarted under load, Redis wiped, and 100k messages with flat memory.
|
|
31
|
+
- **Runs on a small box.** 200 notifications/sec sustained on 2 vCPUs, over a 15-minute soak with provider failures, retries and webhooks. [Method and numbers →](https://notifkit.dev/articles/notifications-on-a-25-dollar-server.html)
|
|
32
|
+
- **Runs in production.** About 260K notifications a day (8M a month) of email, push and OTPs at our own company.
|
|
33
|
+
- **Your stack, your data.** PostgreSQL and Redis you already run, provider accounts you already have, and nothing that bills per send. Trust me it will save you $$$
|
|
34
|
+
- **Workflows in code.** Multi-step sequences that wait days, block on events and survive restarts, written in TypeScript and kept in git.
|
|
73
35
|
|
|
74
|
-
|
|
75
|
-
classDef store stroke:#0ea5e9,stroke-width:2px
|
|
76
|
-
classDef work stroke:#22c55e,stroke-width:2px
|
|
77
|
-
class App,API,PROVIDERS entry
|
|
78
|
-
class PG,REDIS store
|
|
79
|
-
class ENRICH,ENGINE,DELIVER,SCHED work
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
`NotifkitServer` runs the HTTP REST API router (`/v1/notify`, `/health`, `/metrics`), the built-in admin dashboard (`/admin`), 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.
|
|
83
|
-
|
|
84
|
-
### Topologies
|
|
85
|
-
|
|
86
|
-
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.
|
|
36
|
+
## Quickstart
|
|
87
37
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
### 1. Install
|
|
38
|
+
You need Node 22+ and Docker running. In development notifkit starts throwaway PostgreSQL and Redis containers for you.
|
|
91
39
|
|
|
92
40
|
```bash
|
|
93
|
-
npm
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
The `@testcontainers/*` packages start throwaway PostgreSQL and Redis containers for local development when `DATABASE_URL` and `REDIS_URL` are not set.
|
|
98
|
-
|
|
99
|
-
> [!WARNING]
|
|
100
|
-
> In production, point notifkit at real PostgreSQL and Redis instances via `DATABASE_URL` and `REDIS_URL`, and run with `NODE_ENV=production`.
|
|
101
|
-
|
|
102
|
-
### 2. Run the engine
|
|
103
|
-
|
|
104
|
-
`server.ts` starts the API and the worker pipelines. In development it auto-starts those containers, so Docker is the only prerequisite.
|
|
105
|
-
|
|
106
|
-
```ts
|
|
107
|
-
import { NotifkitServer } from "notifkit";
|
|
108
|
-
import { ResendTransport } from "@notifkit/provider-resend";
|
|
109
|
-
|
|
110
|
-
const server = new NotifkitServer({
|
|
111
|
-
services: ["all"],
|
|
112
|
-
port: 3000,
|
|
113
|
-
databaseUrl: process.env.DATABASE_URL,
|
|
114
|
-
redisUrl: process.env.REDIS_URL,
|
|
115
|
-
adminUser: {
|
|
116
|
-
email: "admin@example.com",
|
|
117
|
-
password: "supersecretpassword123",
|
|
118
|
-
},
|
|
119
|
-
providers: [
|
|
120
|
-
new ResendTransport({
|
|
121
|
-
apiKey: process.env.RESEND_API_KEY!,
|
|
122
|
-
from: "notifications@yourdomain.com",
|
|
123
|
-
}),
|
|
124
|
-
],
|
|
125
|
-
});
|
|
126
|
-
|
|
127
|
-
await server.start();
|
|
128
|
-
console.log("notifkit listening on http://localhost:3000");
|
|
41
|
+
npm create notifkit@latest my-app # or: npx notifkit create my-app
|
|
42
|
+
cd my-app
|
|
43
|
+
npm run dev # leave it running
|
|
129
44
|
```
|
|
130
45
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
`adminUser` (or `ADMIN_EMAIL` and `ADMIN_PASSWORD` in the environment) seeds your initial dashboard login credentials in PostgreSQL on startup.
|
|
134
|
-
|
|
135
|
-
`ADMIN_API_KEY` is the root credential that mints project API keys. In production, use a long random string (`openssl rand -hex 32`). Locally, any string works:
|
|
136
|
-
|
|
137
|
-
```bash
|
|
138
|
-
ADMIN_API_KEY=supersecretkey RESEND_API_KEY=re_xxx npx tsx server.ts
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
### 3. Create a project and its API key
|
|
142
|
-
|
|
143
|
-
Every `/v1/*` route requires a project API key, and only the admin credential can mint one. You can create projects via the CLI helper or in the admin dashboard under **Projects & API Keys** (`/admin/projects`):
|
|
46
|
+
In a second terminal:
|
|
144
47
|
|
|
145
48
|
```bash
|
|
146
|
-
|
|
49
|
+
npm run setup # create a project, save its API key to .env
|
|
50
|
+
npm run send # send a test notification
|
|
147
51
|
```
|
|
148
52
|
|
|
149
|
-
|
|
150
|
-
Project "my-app" created. Save the API key now — it is not recoverable.
|
|
53
|
+
The default provider prints notifications to the server terminal, so you need no provider account to try it. Pass `--provider resend`, `twilio` or `fcm` to start with a real one. See [create-notifkit](./packages/create-notifkit) for the options.
|
|
151
54
|
|
|
152
|
-
|
|
153
|
-
NOTIFKIT_API_KEY=nk_live_f57c57b76d795cef89e2dbf6b6f352a36…
|
|
154
|
-
```
|
|
55
|
+
To add notifkit to an app you already have, or to see what each generated file does, follow the [full quickstart](https://notifkit.dev/docs/quickstart.html). For production, see [Deployment](https://notifkit.dev/docs/deployment.html).
|
|
155
56
|
|
|
156
|
-
|
|
57
|
+
## How it compares
|
|
157
58
|
|
|
158
|
-
|
|
59
|
+
| | notifkit | Novu |
|
|
60
|
+
| :--------------- | :-------------------------- | :--------------------------------------------- |
|
|
61
|
+
| Self-hosted | Yes | Yes |
|
|
62
|
+
| Storage | PostgreSQL + Redis | MongoDB + Redis |
|
|
63
|
+
| Workflows | TypeScript in your codebase | Code via a bridge endpoint, or a visual editor |
|
|
64
|
+
| Channel fallback | Built in: `fallback: true` | Built from workflow step conditions |
|
|
65
|
+
| In-app inbox UI | No | Yes |
|
|
66
|
+
| Admin dashboard | Yes | Yes |
|
|
67
|
+
| MCP server | Yes | Yes |
|
|
68
|
+
| License | MIT, no paid edition | MIT core, commercial enterprise modules |
|
|
159
69
|
|
|
160
|
-
|
|
70
|
+
**Knock and Courier** are hosted SaaS. Both have a free tier of about 10k notifications a month; past that, Knock's Starter plan is $250/month for 50k plus $5 per extra 1,000, and Courier bills per send. notifkit costs whatever your Postgres and Redis cost. _(Pricing checked October 2026. See their pricing pages for current numbers.)_
|
|
161
71
|
|
|
162
|
-
|
|
163
|
-
// client.ts
|
|
164
|
-
import { NotifkitClient } from "notifkit";
|
|
72
|
+
If you need an in-app inbox or 75 provider adapters today, Novu is the more complete choice. Choose notifkit if you want reliability features like provider fallback without a commercial license, a small codebase you can read, and published failure testing.
|
|
165
73
|
|
|
166
|
-
|
|
167
|
-
baseUrl: "http://localhost:3000",
|
|
168
|
-
apiKey: process.env.NOTIFKIT_API_KEY!,
|
|
169
|
-
});
|
|
74
|
+
Longer comparisons: [Novu](https://notifkit.dev/docs/vs/novu.html) · [Knock](https://notifkit.dev/docs/vs/knock.html) · [Courier](https://notifkit.dev/docs/vs/courier.html)
|
|
170
75
|
|
|
171
|
-
|
|
172
|
-
await notifkit.syncTemplates({
|
|
173
|
-
templates: [
|
|
174
|
-
{
|
|
175
|
-
id: "order-shipped",
|
|
176
|
-
channel: "email",
|
|
177
|
-
content: { subject: "Order #{{orderId}} Shipped", text: "Your order is on the way!" },
|
|
178
|
-
},
|
|
179
|
-
],
|
|
180
|
-
});
|
|
181
|
-
|
|
182
|
-
// 2. Register a user (supports id + contacts array or object)
|
|
183
|
-
await notifkit.addUser("usr_123", [{ channel: "email", target: "alex@acme.com" }]);
|
|
76
|
+
## What it handles
|
|
184
77
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
```bash
|
|
197
|
-
NOTIFKIT_API_KEY=nk_live_xxx npx tsx client.ts
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
### 5. Or call the REST API directly
|
|
201
|
-
|
|
202
|
-
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):
|
|
203
|
-
|
|
204
|
-
```bash
|
|
205
|
-
curl -X POST http://localhost:3000/v1/notify \
|
|
206
|
-
-H "Content-Type: application/json" \
|
|
207
|
-
-H "Authorization: Bearer $NOTIFKIT_API_KEY" \
|
|
208
|
-
-d '{
|
|
209
|
-
"user": "usr_123",
|
|
210
|
-
"template": "order-shipped",
|
|
211
|
-
"channels": ["email"],
|
|
212
|
-
"data": { "orderId": "9481" }
|
|
213
|
-
}'
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
### Development vs. production
|
|
217
|
-
|
|
218
|
-
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 with the bundled CLI before starting the server:
|
|
219
|
-
|
|
220
|
-
```bash
|
|
221
|
-
DATABASE_URL=postgres://user:pass@host:5432/db npx notifkit-migrate
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
`notifkit-migrate` reads `DATABASE_URL` and `DB_SCHEMA` (from the environment or `.env`), applies any pending migrations into that schema, and exits non-zero if anything fails, so it can gate a deploy. It is safe to run on every deploy. Do not point `drizzle-kit` at `node_modules/notifkit/drizzle` directly: that ignores `DB_SCHEMA` and always creates the tables in `public`. In the default `public` schema both use the same journal (`drizzle.__drizzle_migrations`), so an install migrated with `drizzle-kit` so far can switch to `notifkit-migrate` as is.
|
|
225
|
-
|
|
226
|
-
### Installing into a custom PostgreSQL schema
|
|
227
|
-
|
|
228
|
-
By default notifkit creates its tables and enum types in `public`. To share a database with an application that already owns `public`, set `DB_SCHEMA` (or `dbOptions.schema` on `NotifkitServer`):
|
|
229
|
-
|
|
230
|
-
```bash
|
|
231
|
-
DB_SCHEMA=notifications
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
Migrations (`notifkit-migrate`, or `autoMigrate` on start-up) then create the schema if it is missing and put every notifkit object into it, and every connection notifkit opens resolves queries against that schema only. After migrating, notifkit checks that every one of its tables exists in that schema and fails with the names of any that do not. The migration journal is kept in the same schema (`notifications.__drizzle_migrations`), so two installs in one database never share it. Pass `runMigrations(db, { schema, migrationsSchema, migrationsTable })` to run migrations yourself.
|
|
235
|
-
|
|
236
|
-
The schema is set as the `search_path` startup parameter. If a connection pooler in front of PostgreSQL rejects that parameter (PgBouncer does unless `search_path` is listed in `track_extra_parameters` or `ignore_startup_parameters`), set it on the role instead: `ALTER ROLE <role> SET search_path = notifications`.
|
|
237
|
-
|
|
238
|
-
> [!WARNING]
|
|
239
|
-
> **Do not set `DB_SCHEMA` on an install that already runs in `public`.** Nothing is moved for you: notifkit creates a fresh, empty set of tables in the new schema and stops looking at `public`. The application then looks empty: admin logins and every project API key stop working, and users, templates and history are gone from its point of view (the data is still in `public`, just no longer read).
|
|
240
|
-
>
|
|
241
|
-
> To move an existing install, stop notifkit and move **every** notifkit table and enum type, plus the migration journal, into the new schema yourself **before** running `notifkit-migrate` with the new `DB_SCHEMA`, for example:
|
|
242
|
-
>
|
|
243
|
-
> ```sql
|
|
244
|
-
> BEGIN;
|
|
245
|
-
> CREATE SCHEMA notifications;
|
|
246
|
-
> ALTER TABLE public.projects SET SCHEMA notifications; -- repeat for every table in notifkitTableNames()
|
|
247
|
-
> ALTER TYPE public.channel SET SCHEMA notifications; -- and for api_key_role, workflow_status
|
|
248
|
-
> ALTER TABLE drizzle.__drizzle_migrations SET SCHEMA notifications;
|
|
249
|
-
> COMMIT;
|
|
250
|
-
> ```
|
|
251
|
-
>
|
|
252
|
-
> Then `notifkit-migrate` finds the journal, applies nothing it has already applied, and confirms that every table is in place.
|
|
253
|
-
|
|
254
|
-
## Running in production
|
|
255
|
-
|
|
256
|
-
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.
|
|
257
|
-
|
|
258
|
-
### Reliability and resilience
|
|
259
|
-
|
|
260
|
-
Every component is tested against failure using real testcontainers:
|
|
261
|
-
|
|
262
|
-
- **Crash recovery**: Worker processes killed with `SIGKILL` mid-stream lose zero messages. Redis Streams consumer groups (PEL) auto-reclaim and replay in-flight work.
|
|
263
|
-
- **Connection resilience**: Disconnections from PostgreSQL or Redis trigger automatic backpressure and reconnects without dropping state.
|
|
264
|
-
- **High throughput & concurrency**: 10,000+ notification bursts with sliding-window rate limiters, flat memory profiles, and 24-hour idempotency deduplication.
|
|
265
|
-
|
|
266
|
-
## Scope
|
|
267
|
-
|
|
268
|
-
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.
|
|
269
|
-
|
|
270
|
-
First-party providers cover Resend, Firebase Cloud Messaging, Slack, Twilio, Telegram, Discord, and WhatsApp. Anything else is a `Transport` class with a `send()` method.
|
|
271
|
-
|
|
272
|
-
## Agent-operable
|
|
273
|
-
|
|
274
|
-
https://github.com/user-attachments/assets/4dff98bb-37d3-44b4-bf46-9607c1cd89b5
|
|
275
|
-
|
|
276
|
-
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:
|
|
277
|
-
|
|
278
|
-
```bash
|
|
279
|
-
npx -y @notifkit/mcp
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
### Ask your agent
|
|
283
|
-
|
|
284
|
-
```text
|
|
285
|
-
You: Why didn't usr_9182 receive their password reset?
|
|
286
|
-
|
|
287
|
-
Agent: The notification was suppressed because usr_9182's email
|
|
288
|
-
address has a hard-bounce suppression from yesterday.
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
Your application and your AI agents use the same notification infrastructure. Through MCP an agent can:
|
|
292
|
-
|
|
293
|
-
- Send one-off notifications or campaigns to users, lists, and segments (`send_notification`, `send_campaign`)
|
|
294
|
-
- Diagnose delivery issues by inspecting message histories, provider responses, and quiet hours (`get_delivery_logs`, `get_notification`)
|
|
295
|
-
- Schedule future sends and cancel pending notifications (`list_scheduled`, `cancel_notification`)
|
|
296
|
-
- Check delivery, open, click, bounce, and complaint metrics (`list_campaigns`, `get_campaign_stats`)
|
|
297
|
-
- List, preview, and update templates with sample data (`list_templates`, `preview_template`, `upsert_template`)
|
|
298
|
-
- Look up users, contacts, preferences, and segment membership (`list_users`, `get_user_preferences`, `update_user_preferences`)
|
|
299
|
-
- Trigger workflows and inspect workflow runs (`create_workflow`, `trigger_workflow`, `get_workflow_run`)
|
|
300
|
-
- Manage bounce suppressions, check system queues, and replay dead-letter messages (`list_suppressions`, `get_dead_letters`, `replay_dead_letter`)
|
|
301
|
-
|
|
302
|
-
### The same task, with and without an agent
|
|
303
|
-
|
|
304
|
-
| Without an agent | With the notifkit MCP server |
|
|
305
|
-
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
306
|
-
| 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. |
|
|
307
|
-
|
|
308
|
-
[MCP documentation](https://notifkit.dev/docs/mcp.html)
|
|
309
|
-
|
|
310
|
-
## AI-assisted migration
|
|
311
|
-
|
|
312
|
-
Already have notification code scattered across your application? Point your coding agent at:
|
|
313
|
-
|
|
314
|
-
```text
|
|
315
|
-
https://notifkit.dev/llms-full.txt
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
It can read notifkit's API from there, find ad-hoc notification code in your repository, and refactor it into notifkit calls.
|
|
319
|
-
|
|
320
|
-
## Feature matrix
|
|
321
|
-
|
|
322
|
-
| Feature | Capabilities |
|
|
323
|
-
| :------------------ | :--------------------------------------------------------------------------------------- |
|
|
324
|
-
| **Channels** | `email`, `sms`, `push`, `webhook`, `telegram`, `discord`, `whatsapp`, `slack`, `console` |
|
|
325
|
-
| **Admin Dashboard** | Built-in SPA at `/admin` for live feeds, DLQ triage, queue metrics, workflows, templates |
|
|
326
|
-
| **Targeting** | A user, a list of users, a segment, or a topic |
|
|
327
|
-
| **Priorities** | `low`, `normal`, `high`, `critical`, on separate stream lanes |
|
|
328
|
-
| **Scheduling** | Future sends with `sendAt`, quiet-hours deferral, cancellation |
|
|
329
|
-
| **Preferences** | Per-user channel and topic opt-outs, quiet hours, contact-level overrides |
|
|
330
|
-
| **Workflows** | Multi-step sequences with `wait`, `waitForEvent`, and `notify` steps |
|
|
331
|
-
| **Reliability** | Redis Streams, 24h idempotency, retries, DLQ, provider circuit breakers |
|
|
332
|
-
| **Templates** | `{{var}}` interpolation with destination-aware escaping |
|
|
333
|
-
| **AI** | Optional LLM augmentation before render via the Vercel AI SDK |
|
|
334
|
-
| **Multi-tenancy** | Projects with isolated keys, data, and rate limits |
|
|
335
|
-
| **Consent** | RFC 8058 one-click unsubscribe; complaints and hard bounces suppress automatically |
|
|
336
|
-
| **Reporting** | Campaign labels with delivery and engagement totals |
|
|
337
|
-
| **Agent operation** | MCP server for sending, triage, campaigns, templates, workflows, and system operations |
|
|
338
|
-
| **Observability** | Prometheus `/metrics`, `/health`, `/live`, `/ready`, and queryable delivery logs |
|
|
78
|
+
| The question | What notifkit does |
|
|
79
|
+
| :------------------------------------------ | :------------------------------------------------------------------ |
|
|
80
|
+
| "What happens when a provider goes down?" | Circuit breakers, exponential backoff, DLQ replay |
|
|
81
|
+
| "What if a worker dies mid-send?" | Consumer groups reclaim and replay in-flight messages |
|
|
82
|
+
| "Will a retried request send twice?" | Same `X-Idempotency-Key` within 24 hours is delivered once |
|
|
83
|
+
| "What if push fails?" | Falls back to the next channel you listed: SMS, then email |
|
|
84
|
+
| "What if the user is asleep?" | Quiet hours in the user's timezone; the send waits for the window |
|
|
85
|
+
| "What about OTPs during a marketing blast?" | `critical` runs on its own lane and skips quiet hours |
|
|
86
|
+
| "What if they unsubscribed?" | RFC 8058 one-click unsubscribe; bounces and complaints suppress too |
|
|
87
|
+
| "Can several apps share one deployment?" | Projects, each with its own API keys, data and rate limit |
|
|
88
|
+
| "Can my Python or Go service use it?" | Yes. It is a REST API; the TypeScript SDK is optional |
|
|
339
89
|
|
|
340
90
|
## Providers
|
|
341
91
|
|
|
@@ -343,12 +93,12 @@ Bring your own provider accounts. First-party packages:
|
|
|
343
93
|
|
|
344
94
|
- [`@notifkit/provider-resend`](./packages/provider-resend): transactional email via Resend
|
|
345
95
|
- [`@notifkit/provider-fcm`](./packages/provider-fcm): push notifications via Firebase Cloud Messaging
|
|
346
|
-
- [`@notifkit/provider-slack`](./packages/provider-slack): Slack messages via Incoming Webhooks or the Web API
|
|
347
96
|
- [`@notifkit/provider-twilio`](./packages/provider-twilio): SMS via Twilio, with signature-verified delivery status callbacks
|
|
97
|
+
- [`@notifkit/provider-slack`](./packages/provider-slack): Slack messages via Incoming Webhooks or the Web API
|
|
348
98
|
- [`@notifkit/provider-telegram`](./packages/provider-telegram): messages via a Telegram bot
|
|
349
99
|
- [`@notifkit/provider-discord`](./packages/provider-discord): messages via a Discord webhook
|
|
350
100
|
- [`@notifkit/provider-whatsapp`](./packages/provider-whatsapp): messages via Meta's WhatsApp Cloud API
|
|
351
|
-
- [`@notifkit/provider-console`](./packages/provider-console):
|
|
101
|
+
- [`@notifkit/provider-console`](./packages/provider-console): prints instead of sending, for development and tests
|
|
352
102
|
|
|
353
103
|
For anything else, implement a `Transport`:
|
|
354
104
|
|
|
@@ -361,58 +111,34 @@ class MyTransport implements Transport {
|
|
|
361
111
|
}
|
|
362
112
|
```
|
|
363
113
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
## Admin dashboard
|
|
367
|
-
|
|
368
|
-
notifkit includes a web console served directly at `/admin` for operational management:
|
|
369
|
-
|
|
370
|
-
- **Live activity feed & logs**: Real-time SSE stream for worker transitions, delivery histories, and error diagnostics.
|
|
371
|
-
- **Queue analytics & DLQ triage**: Redis Streams lane gauges (`low`, `normal`, `high`, `critical`), message replay, and dead-letter queue management.
|
|
372
|
-
- **Workflows & template studio**: Visual multi-step sequence viewer (`wait`, `waitForEvent`, `notify`) with execution step tracing and live template previews.
|
|
373
|
-
- **Users, projects & API keys**: Manage recipient preferences, quiet hours, projects, and scoped API keys (`admin` or `read_only`).
|
|
114
|
+
## Run it from your AI agent
|
|
374
115
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
Once the server is running, visit `http://localhost:3000/admin` and sign in with the admin credentials you configured.
|
|
378
|
-
|
|
379
|
-
You can also create or update admin users at any time via the CLI:
|
|
116
|
+
Connect the notifkit MCP server to Claude Code, Cursor, or any MCP client:
|
|
380
117
|
|
|
381
118
|
```bash
|
|
382
|
-
|
|
119
|
+
claude mcp add notifkit \
|
|
120
|
+
--env NOTIFKIT_URL=http://localhost:3000 \
|
|
121
|
+
--env NOTIFKIT_API_KEY=nk_live_... \
|
|
122
|
+
-- npx -y @notifkit/mcp
|
|
383
123
|
```
|
|
384
124
|
|
|
385
|
-
|
|
125
|
+
Then ask things like "why didn't usr_9182 get their password reset?" or "how did yesterday's spring-sale campaign do?". [MCP docs →](https://notifkit.dev/docs/mcp.html)
|
|
386
126
|
|
|
387
|
-
|
|
127
|
+
Already have notification code scattered across your app? Point your coding agent at `https://notifkit.dev/llms-full.txt` and ask it to refactor that code into notifkit calls.
|
|
388
128
|
|
|
389
|
-
##
|
|
129
|
+
## Admin dashboard
|
|
390
130
|
|
|
391
|
-
|
|
131
|
+
Templates, workflows, and routing live in your code. The dashboard at `/admin` is an optional ops console: a live activity feed, delivery logs, queue depth per priority lane, workflow runs step by step, dead-letter replay, scheduled-send cancellation, and project and API key management.
|
|
392
132
|
|
|
393
|
-
|
|
394
|
-
| :----------------------------------------------------------------------------- | :------------------------------------------------------- |
|
|
395
|
-
| [Quickstart](https://notifkit.dev/docs/quickstart.html) | Install to first delivered notification |
|
|
396
|
-
| [How it works](https://notifkit.dev/docs/concepts.html) | Core concepts and the notification pipeline |
|
|
397
|
-
| [Channels & fallback](https://notifkit.dev/docs/guides/routing.html) | Multicast, ordered fallback, and custom transports |
|
|
398
|
-
| [Preferences & quiet hours](https://notifkit.dev/docs/guides/preferences.html) | Preference, consent, and timing rules |
|
|
399
|
-
| [Templates & AI](https://notifkit.dev/docs/guides/templates.html) | Interpolation, escaping, and per-channel content |
|
|
400
|
-
| [Segments & scheduling](https://notifkit.dev/docs/guides/segments.html) | Fan-out, priority lanes, `sendAt`, and idempotency |
|
|
401
|
-
| [Workflows](https://notifkit.dev/docs/guides/workflows.html) | Multi-step sequences, recurring sends, and digests |
|
|
402
|
-
| [Examples](https://notifkit.dev/docs/examples.html) | Runnable projects |
|
|
403
|
-
| [Architecture](https://notifkit.dev/docs/architecture.html) | Streams, delivery guarantees, topologies, and data model |
|
|
404
|
-
| [Deployment](https://notifkit.dev/docs/deployment.html) | Docker, Compose, and production topologies |
|
|
405
|
-
| [Operations](https://notifkit.dev/docs/operations.html) | Health, metrics, DLQ, key rotation, and shutdown |
|
|
406
|
-
| [Reference](https://notifkit.dev/docs/reference.html) | API, payloads, and SDK methods |
|
|
407
|
-
| [MCP server](https://notifkit.dev/docs/mcp.html) | Operate notifkit from an AI agent |
|
|
133
|
+
To sign in, set `ADMIN_EMAIL` and `ADMIN_PASSWORD` before starting the server, then open `http://localhost:3000/admin`.
|
|
408
134
|
|
|
409
|
-
##
|
|
135
|
+
## Documentation
|
|
410
136
|
|
|
411
|
-
|
|
137
|
+
Everything lives at **[notifkit.dev/docs](https://notifkit.dev/docs/)**: [concepts](https://notifkit.dev/docs/concepts.html), [routing and fallback](https://notifkit.dev/docs/guides/routing.html), [preferences](https://notifkit.dev/docs/guides/preferences.html), [workflows](https://notifkit.dev/docs/guides/workflows.html), [architecture](https://notifkit.dev/docs/architecture.html), [operations](https://notifkit.dev/docs/operations.html) and the [API reference](https://notifkit.dev/docs/reference.html).
|
|
412
138
|
|
|
413
139
|
## Contributing
|
|
414
140
|
|
|
415
|
-
Issues and pull requests are welcome.
|
|
141
|
+
Issues and pull requests are welcome.
|
|
416
142
|
|
|
417
143
|
```bash
|
|
418
144
|
npm install
|
|
@@ -423,10 +149,8 @@ npm test
|
|
|
423
149
|
|
|
424
150
|
The test suite starts its own PostgreSQL and Redis containers, so Docker is the only thing you need running.
|
|
425
151
|
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
Questions, bugs, or ideas: [contact.devkitshq@gmail.com](mailto:contact.devkitshq@gmail.com), or open an issue.
|
|
152
|
+
Questions, bugs, or ideas: [contact.devkitshq@gmail.com](mailto:contact.devkitshq@gmail.com), or open an issue. If notifkit saved you from building notification plumbing, a [star](https://github.com/devkitshq/notifkit) helps other developers find it.
|
|
429
153
|
|
|
430
154
|
## License
|
|
431
155
|
|
|
432
|
-
MIT.
|
|
156
|
+
MIT. Use it for anything, including commercially. Every feature is in this repository: there is no paid edition and no hosted tier.
|