notifkit 0.1.2 → 0.1.4

package/README.md

@@ -6,7 +6,7 @@
 
 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)
 
@@ -53,50 +53,40 @@ await notifkit.notify({
 
 notifkit is both an **orchestration engine** and a **typed SDK**.
 
-```text
-  ┌──────────────────────────────────────────────────────────┐
-  │               Your Application / AI Agent                │
-  │           (Typed SDK / REST API / MCP Server)            │
-  └────────────────────────────┬─────────────────────────────┘
-                               │ HTTP POST /v1/notify
-                               ▼
-  ┌──────────────────────────────────────────────────────────┐
-  │                   Notifkit API Server                    │
-  │       • Schema Validation   • Auth & Multi-Tenancy       │
-  │       • Idempotency Gate    • Priority Queue Ingestion   │
-  └──────────────┬────────────────────────────┬──────────────┘
-                 │                            │
-                 ▼                            ▼
-  ┌─────────────────────────────┐  ┌─────────────────────────┐
-  │    PostgreSQL (Storage)     │  │  Redis (Streams & ZSET) │
-  │  • Users & Preferences      │  │  • Priority Queues      │
-  │  • Templates & Workflows    │  │  • Scheduled Sends      │
-  │  • Delivery Logs & DLQ      │  │  • Sliding Rate Limits  │
-  └──────────────▲──────────────┘  └──────────┬──────────────┘
-                 │                            │
-                 │   ┌────────────────────────┘
-                 │   ▼
-  ┌──────────────────────────────────────────────────────────┐
-  │               Background Workers Pipeline                │
-  │                                                          │
-  │  ┌───────────┐    ┌─────────────┐    ┌────────────────┐  │
-  │  │ Enricher  │───►│   Engine    │───►│    Delivery    │  │
-  │  │ (Resolve) │    │(Quiet Hours)│    │(Rate Limits/CB)│  │
-  │  └───────────┘    └──────┬──────┘    └───────┬────────┘  │
-  │                          │                   │           │
-  │                   ┌──────▼──────┐            │           │
-  │                   │  Scheduler  │────────────┘           │
-  │                   │ (sendAt/QH) │                        │
-  │                   └─────────────┘                        │
-  └──────────────────────────────────┬───────────────────────┘
-                                     │ Dispatch
-                                     ▼
-  ┌──────────────────────────────────────────────────────────┐
-  │                   Provider Transports                    │
-  │                                                          │
-  │  Email: Resend, SES, Postmark    Push: Firebase (FCM)    │
-  │  SMS: Twilio, MessageBird        Webhooks: Custom HTTP   │
-  └──────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+    App["Your Application / AI Agent<br/>Typed SDK · REST API · MCP Server"]
+
+    App -->|"HTTP POST /v1/notify"| API
+
+    API["Notifkit API Server<br/>Schema Validation · Auth · Multi-Tenancy<br/>Idempotency Gate · Priority Queue Ingestion"]
+
+    API --> PG
+    API --> REDIS
+
+    PG[("PostgreSQL — Storage<br/>Users · Preferences<br/>Templates · Workflows<br/>Delivery Logs · DLQ")]
+    REDIS[("Redis — Streams / ZSET<br/>Priority Queues<br/>Scheduled Sends<br/>Sliding Rate Limits")]
+
+    subgraph WORKERS["Background Workers Pipeline"]
+        direction LR
+        ENRICH["Enricher<br/>(Resolve)"] --> ENGINE["Engine<br/>(Quiet Hours)"] --> DELIVER["Delivery<br/>(Rate Limits / CB)"]
+        ENGINE --> SCHED["Scheduler<br/>(sendAt / QH)"]
+        SCHED --> DELIVER
+    end
+
+    REDIS -->|"consume"| ENRICH
+    ENRICH -.->|"read / write state"| PG
+    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"]
+
+    classDef entry stroke:#6366f1,stroke-width:2px
+    classDef store stroke:#0ea5e9,stroke-width:2px
+    classDef work stroke:#22c55e,stroke-width:2px
+    class App,API,PROVIDERS entry
+    class PG,REDIS store
+    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).
@@ -109,67 +99,61 @@ notifkit is both an **orchestration engine** and a **typed SDK**.
 
 ---
 
-## Battle-tested for production
+## Agent-operable
 
-> **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.
+https://github.com/user-attachments/assets/4dff98bb-37d3-44b4-bf46-9607c1cd89b5
 
-**Your servers. Your providers. Your data. Zero notification SaaS markups.**
+[▶️ Watch the AI demo](assets/ai_demo.mp4) - this is link to raw video file
 
-### Reliability & Chaos Engineering
+**notifkit isn't just an API your application can call — your AI agent can operate it directly.**
 
-Because notification delivery is mission-critical, every pipeline component is tested against extreme failure conditions:
+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
+```
+
+### Ask your agent
 
 ```text
- ┌────────────────┐     Kill Worker     ┌────────────────────────┐
- │ Redis Streams  │ ──( SIGKILL )────►  │ Auto-Claim & Replay    │ ──► Zero Lost Messages
- └────────────────┘                     └────────────────────────┘
- ┌────────────────┐     Drop DB/Redis   ┌────────────────────────┐
- │ Connection Loss│ ──( Disconnect )──► │ Auto-Reconnect / Retry │ ──► In-Flight State Intact
- └────────────────┘                     └────────────────────────┘
- ┌────────────────┐     High Load       ┌────────────────────────┐
- │ 10k+ Messages  │ ──( Burst )───────► │ Concurrency & Limits   │ ──► Flat Memory, No Leaks
- └────────────────┘                     └────────────────────────┘
+You: Why didn't usr_9182 receive their password reset?
+
+Agent: The notification was suppressed because usr_9182's email
+       address has a hard-bounce suppression from yesterday.
 ```
 
-- **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.
+Your application and your AI agents use the **same notification infrastructure**:
 
----
+- **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`)
 
-## What you get
+### From “write a script” to “just ask”
 
-| 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                        |
+| 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 |
 
-> **The idea is simple:** You decide what to say. **notifkit handles getting it there reliably.**
+[Set up MCP](https://notifkit.dev/docs/mcp.html) · [MCP documentation](https://notifkit.dev/docs/mcp.html)
 
 ---
 
-## What notifkit is — and what it isn't
+## AI-assisted migration
 
-**What it is:** the durable notification infrastructure layer running directly inside your own stack.
+Already have notification code scattered across your application?
 
-**What it isn't:** a marketing automation suite.
+Point your coding agent at:
 
-notifkit is not Customer.io, OneSignal, or SendGrid. You bring your own provider accounts — your keys, your billing, your deliverability.
+```text
+https://notifkit.dev/llms-full.txt
+```
 
-First-party providers ship for Resend and Firebase Cloud Messaging. Anything else is a simple `Transport` class with a `send()` method.
+It can understand notifkit's API and help identify ad-hoc notification code in your repository and refactor it into durable notifkit calls.
 
 ---
 
@@ -241,57 +225,69 @@ curl -X POST http://localhost:3000/v1/notify \
 
 ---
 
-## Agent-operable
-
-**notifkit isn't just an API your application can call — your AI agent can operate it directly.**
+## Battle-tested for production
 
-Connect the notifkit MCP server ([`@notifkit/mcp`](./packages/mcp)) to Claude Code, Cursor, Claude Desktop, Gemini, or any MCP-compatible agent:
+> **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.
 
-```bash
-npx -y @notifkit/mcp
-```
+**Your servers. Your providers. Your data. Zero notification SaaS markups.**
 
-### Ask your agent
+### Reliability & Chaos Engineering
 
-```text
-You: Why didn't usr_9182 receive their password reset?
+Because notification delivery is mission-critical, every pipeline component is tested against extreme failure conditions:
 
-Agent: The notification was suppressed because usr_9182's email
-       address has a hard-bounce suppression from yesterday.
+```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
 ```
 
-Your application and your AI agents use the **same notification infrastructure**:
+- **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.
 
-- **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`)
+---
 
-### From “write a script” to “just ask”
+## What you get
 
-| 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 |
+| 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                        |
 
-[Set up MCP](https://notifkit.dev/docs/mcp.html) · [MCP documentation](https://notifkit.dev/docs/mcp.html)
+> **The idea is simple:** You decide what to say. **notifkit handles getting it there reliably.**
 
 ---
 
-## AI-assisted migration
+## What notifkit is — and what it isn't
 
-Already have notification code scattered across your application?
+**What it is:** the durable notification infrastructure layer running directly inside your own stack.
 
-Point your coding agent at:
+**What it isn't:** a marketing automation suite.
 
-```text
-https://notifkit.dev/llms-full.txt
-```
+notifkit is not Customer.io, OneSignal, or SendGrid. You bring your own provider accounts — your keys, your billing, your deliverability.
 
-It can understand notifkit's API and help identify ad-hoc notification code in your repository and refactor it into durable notifkit calls.
+First-party providers ship for Resend and Firebase Cloud Messaging. Anything else is a simple `Transport` class with a `send()` method.
 
 ---
 
@@ -299,7 +295,7 @@ It can understand notifkit's API and help identify ad-hoc notification code in y
 
 |                     |                                                                                        |
 | :------------------ | :------------------------------------------------------------------------------------- |
-| **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                            |
 | **Scheduling**      | Future sends with `sendAt`, quiet-hours deferral, cancellation                         |
@@ -324,13 +320,18 @@ 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-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`:
 
 ```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.
   }
 }
@@ -390,6 +391,13 @@ 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 — mail me. I run this on my own company, which delivers a lot of notifications daily (100K+/day).
+
+- **Email:** [contact.devkitshq@gmail.com](mailto:contact.devkitshq@gmail.com)
+- **Book a 30-min call:** [calendly.com/contact-devkitshq/30min](https://calendly.com/contact-devkitshq/30min)
+
 ## License
 
 MIT. Do what you like with it, including commercially. See [LICENSE](./LICENSE).