notif-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# notif-agent 🚀
+
+A lightweight, Pusher-like real-time notification client and server library powered by **Server-Sent Events (SSE)**.
+
+Enjoy the developer experience and channel pub/sub API of Pusher or WebSockets with zero external cloud dependencies, built-in reconnection, automatic heartbeats, and seamless HTTP/2 multiplexing.
+
+[![npm version](https://img.shields.io/npm/v/notif-agent.svg)](https://www.npmjs.com/package/notif-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+## ✨ Features
+
+- 🎯 **Pusher-Compatible API**: Familiar `subscribe(channel)`, `channel.bind(event)`, `server.trigger()`, and `connection.bind()` semantics.
+- ⚡ **Lightweight SSE Architecture**: Runs entirely over HTTP/HTTPS — no complex WebSocket proxies or port forwarding needed.
+- 🔒 **Full Authentication Support**:
+  - Connection-level auth (Bearer tokens, cookies, custom headers).
+  - Pusher-style dynamic channel authorization (`authEndpoint` for `private-*` channels).
+- 🔄 **Smart Reconnections**: Exponential backoff reconnection with state transitions (`connecting`, `connected`, `unavailable`, `disconnected`).
+- 💓 **Heartbeat Keep-Alive**: Prevents proxy timeouts (e.g. Nginx, Cloudflare) with automatic ping monitoring.
+- 🌐 **Universal Runtime Support**:
+  - **Server**: Node.js HTTP, Express, Fastify, Next.js App Router, Edge runtime, Cloudflare Workers, Hono.
+  - **Client**: Modern Browsers, React, Vue, Svelte, Node.js (v18+).
+- 📦 **Zero Dependencies**: Pure TypeScript, dual ESM & CommonJS builds with full type definitions.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install notif-agent
+# or
+yarn add notif-agent
+# or
+pnpm add notif-agent
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Server-side (Node.js / Express)
+
+```typescript
+import http from 'http';
+import { NotifServer } from 'notif-agent/server';
+
+const server = new NotifServer({
+  heartbeatInterval: 20000, // 20s heartbeat
+  debug: true,
+});
+
+const httpServer = http.createServer((req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+
+  // SSE Stream Endpoint
+  if (url.pathname === '/sse') {
+    server.handleRequest(req, res);
+    return;
+  }
+
+  // HTTP API to broadcast events
+  if (url.pathname === '/api/trigger' && req.method === 'POST') {
+    let body = '';
+    req.on('data', chunk => (body += chunk));
+    req.on('end', () => {
+      const { channel, event, data } = JSON.parse(body);
+      
+      // Trigger event to all subscribers of this channel (like Pusher)
+      server.trigger(channel, event, data);
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ success: true }));
+    });
+    return;
+  }
+});
+
+httpServer.listen(3000);
+```
+
+#### Next.js App Router (`app/api/sse/route.ts`)
+
+```typescript
+import { NotifServer } from 'notif-agent/server';
+
+const server = new NotifServer();
+
+export async function GET(request: Request) {
+  return server.createWebResponse(request);
+}
+```
+
+---
+
+### 2. Client-side (Browser / React / Vue)
+
+```typescript
+import NotifAgent from 'notif-agent';
+
+// Initialize client
+const agent = new NotifAgent('http://localhost:3000/sse', {
+  reconnectBaseDelay: 1000,
+  heartbeatTimeout: 30000,
+});
+
+// Monitor connection state
+agent.connection.bind('state_change', ({ current }) => {
+  console.log('Connection state:', current);
+});
+
+// Subscribe to a public channel
+const ordersChannel = agent.subscribe('orders');
+
+// Listen to specific events
+ordersChannel.bind('order:created', (order, metadata) => {
+  console.log('New Order received:', order);
+  console.log('Channel:', metadata.channel);
+});
+
+// Catch-all global listener
+agent.bind_global((eventName, data, metadata) => {
+  console.log('[Global]', eventName, data, metadata);
+});
+```
+
+---
+
+## 🔐 Authentication & Private Channels
+
+`notif-agent` supports both **Handshake Authentication** (Bearer tokens/Cookies) and **Pusher-Style Channel Authorization** (`authEndpoint`).
+
+### Option 1: Connection Handshake Auth (Bearer Token / Cookie)
+
+Pass dynamic headers or cookie credentials when connecting:
+
+```typescript
+const agent = new NotifAgent('http://localhost:3000/sse', {
+  headers: () => ({
+    Authorization: `Bearer ${localStorage.getItem('jwt_token')}`,
+  }),
+  withCredentials: true, // Send session cookies
+});
+```
+
+On the backend, authorize the user and restrict allowed channels:
+
+```typescript
+app.get('/sse', (req, res) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+  const user = verifyToken(token); // Authenticate
+
+  server.handleRequest(req, res, {
+    userId: user.id,
+    channels: ['public-news', `private-user.${user.id}`], // restrict client to these channels
+  });
+});
+```
+
+---
+
+### Option 2: Pusher-Style `authEndpoint` for `private-*` Channels
+
+Specify an `authEndpoint` on the client:
+
+```typescript
+const agent = new NotifAgent('/sse', {
+  authEndpoint: '/api/notif/auth',
+  auth: {
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  },
+});
+
+// When subscribing to a private channel:
+const privateChannel = agent.subscribe('private-orders.123');
+
+privateChannel.bind('subscription_succeeded', () => {
+  console.log('Authorized & subscribed to private channel!');
+});
+
+privateChannel.bind('subscription_error', (err) => {
+  console.error('Subscription failed:', err);
+});
+```
+
+On your backend, verify the user and call `server.subscribeClient()`:
+
+```typescript
+app.post('/api/notif/auth', (req, res) => {
+  const { clientId, channel } = req.body;
+  const user = authenticate(req);
+
+  // Authorize channel access
+  if (channel === `private-orders.${user.id}`) {
+    server.subscribeClient(clientId, channel);
+    return res.json({ success: true, channel });
+  }
+
+  return res.status(403).json({ error: 'Forbidden' });
+});
+```
+
+---
+
+## 📖 API Reference
+
+### `NotifAgent` (Client)
+
+| Method / Property | Description |
+|---|---|
+| `new NotifAgent(url, options?)` | Instantiate client and connect to SSE endpoint |
+| `agent.subscribe(channelName)` | Returns a [`Channel`](#channel) object |
+| `agent.unsubscribe(channelName)` | Unsubscribes and cleans up channel listeners |
+| `agent.channel(channelName)` | Returns active channel by name |
+| `agent.bind_global(callback)` | Catch-all listener for any incoming event |
+| `agent.unbind_global(callback?)` | Remove global listener(s) |
+| `agent.connect()` / `disconnect()` | Manual connection control |
+| `agent.clientId` / `agent.socket_id` | Unique connection ID assigned by server handshake |
+| `agent.connection.bind(state, cb)` | Listen to `'connecting'`, `'connected'`, `'unavailable'`, `'state_change'` |
+
+### `Channel` (Client)
+
+| Method | Description |
+|---|---|
+| `channel.bind(event, callback)` | Attach listener: `(data, metadata) => void` |
+| `channel.unbind(event?, callback?)` | Remove listener(s) |
+| `channel.bind_global(callback)` | Catch-all listener for events on this channel |
+| `channel.subscribed` | Boolean indicating subscription status |
+
+### `NotifServer` (Server)
+
+| Method | Description |
+|---|---|
+| `server.trigger(channel, event, data, options?)` | Broadcast event to channel(s) |
+| `server.broadcast(...)` | Alias for `trigger()` |
+| `server.sendToUser(userId, event, data)` | Deliver event to all sessions of a specific user |
+| `server.sendToClient(clientId, event, data)` | Deliver event directly to a specific client |
+| `server.subscribeClient(clientId, channel)` | Dynamically grant client access to a channel |
+| `server.unsubscribeClient(clientId, channel)`| Remove client from a channel |
+| `server.handleRequest(req, res, options?)` | Node.js / Express / Fastify request handler |
+| `server.createWebResponse(req, options?)` | Web API Standard Response stream (Next.js / Edge) |
+| `server.getClientCount()` | Total active SSE connections |
+| `server.getSubscribersCount(channel)` | Total subscribers listening to channel |
+
+---
+
+## 🧪 Running Tests
+
+```bash
+npm test
+```
+
+## 🛠️ Build
+
+```bash
+npm run build
+```
+
+---
+
+## 📄 License
+
+MIT © 2026

package/dist/index.d.mts

@@ -0,0 +1,298 @@
+/**
+ * Connection states matching the Pusher-like lifecycle.
+ */
+type ConnectionState = 'initialized' | 'connecting' | 'connected' | 'unavailable' | 'failed' | 'disconnected';
+interface StateChangePayload {
+    previous: ConnectionState;
+    current: ConnectionState;
+}
+interface EventMetadata {
+    channel?: string;
+    event: string;
+    id?: string;
+    timestamp?: number;
+}
+type EventCallback<T = any> = (data: T, metadata?: EventMetadata) => void;
+type GlobalEventCallback = (eventName: string, data: any, metadata?: EventMetadata) => void;
+type TransportType = 'auto' | 'eventsource' | 'fetch';
+interface NotifAgentOptions {
+    /**
+     * The SSE endpoint URL.
+     */
+    url?: string;
+    /**
+     * Custom HTTP headers (forces `fetch` transport if specified in browser).
+     * Can be an object or a sync/async function returning an object.
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Query parameters to append to the SSE URL.
+     */
+    queryParams?: Record<string, string | number | boolean>;
+    /**
+     * Whether to send cookies with cross-origin requests.
+     * Defaults to false.
+     */
+    withCredentials?: boolean;
+    /**
+     * SSE Transport mechanism.
+     * - 'auto': uses Fetch stream if custom headers or non-browser, otherwise EventSource if available.
+     * - 'eventsource': uses standard EventSource.
+     * - 'fetch': uses fetch API with ReadableStream.
+     * Defaults to 'auto'.
+     */
+    transport?: TransportType;
+    /**
+     * Initial delay in ms before reconnection attempts.
+     * Defaults to 1000ms.
+     */
+    reconnectBaseDelay?: number;
+    /**
+     * Maximum reconnect delay in ms.
+     * Defaults to 30000ms.
+     */
+    reconnectMaxDelay?: number;
+    /**
+     * Maximum number of reconnect attempts before transitioning to 'failed'.
+     * Defaults to Infinity.
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Heartbeat timeout in ms. If no data/ping is received within this period,
+     * the connection is presumed dead and reconnected.
+     * Defaults to 45000ms (45s).
+     */
+    heartbeatTimeout?: number;
+    /**
+     * Whether to automatically connect upon instantiation.
+     * Defaults to true.
+     */
+    autoConnect?: boolean;
+    /**
+     * Enable verbose console logging for debugging.
+     * Defaults to false.
+     */
+    debug?: boolean;
+    /**
+     * Endpoint URL for channel authorization (Pusher-compatible authEndpoint).
+     * Automatically invoked when subscribing to private or presence channels (e.g. `private-*`).
+     */
+    authEndpoint?: string;
+    /**
+     * Custom authentication headers and parameters sent to `authEndpoint`.
+     */
+    auth?: {
+        headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+        params?: Record<string, any>;
+    };
+}
+type ChannelSubscriptionState = 'unsubscribed' | 'subscribing' | 'subscribed' | 'error';
+interface SSEMessagePayload<T = any> {
+    channel?: string;
+    event: string;
+    data: T;
+    id?: string;
+    timestamp?: number;
+}
+
+declare class Channel {
+    readonly name: string;
+    state: ChannelSubscriptionState;
+    private emitter;
+    constructor(name: string);
+    /**
+     * Whether the channel is currently successfully subscribed.
+     */
+    get subscribed(): boolean;
+    /**
+     * Bind an event listener to this channel.
+     *
+     * Example:
+     * ```ts
+     * channel.bind('new-comment', (data) => {
+     *   console.log(data);
+     * });
+     * ```
+     */
+    bind<T = any>(event: string, callback: EventCallback<T>): this;
+    /**
+     * Unbind an event listener from this channel.
+     */
+    unbind<T = any>(event?: string, callback?: EventCallback<T>): this;
+    /**
+     * Bind a global listener to all events received on this channel.
+     *
+     * Example:
+     * ```ts
+     * channel.bind_global((eventName, data) => {
+     *   console.log(`Event ${eventName}:`, data);
+     * });
+     * ```
+     */
+    bind_global(callback: GlobalEventCallback): this;
+    /**
+     * Unbind a global listener from this channel.
+     */
+    unbind_global(callback?: GlobalEventCallback): this;
+    /**
+     * Internal method to dispatch an event onto this channel.
+     */
+    handleEvent<T = any>(event: string, data: T, metadata?: EventMetadata): void;
+    /**
+     * Internal method to update subscription status and fire Pusher-compatible subscription events.
+     */
+    setSubscribed(data?: any): void;
+    /**
+     * Internal method to set subscription error.
+     */
+    setSubscriptionError(error: any): void;
+    /**
+     * Internal method called when channel is unsubscribed.
+     */
+    setUnsubscribed(): void;
+}
+
+declare class ConnectionManager {
+    state: ConnectionState;
+    clientId: string | null;
+    /**
+     * Pusher-compatible alias for clientId.
+     */
+    get socket_id(): string | null;
+    private emitter;
+    private options;
+    private eventSource;
+    private abortController;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private isManuallyClosed;
+    constructor(url: string, options?: NotifAgentOptions);
+    bind<T = any>(event: string, callback: (data: T) => void): this;
+    unbind<T = any>(event?: string, callback?: (data: T) => void): this;
+    connect(): void;
+    disconnect(): void;
+    private transition;
+    private establishConnection;
+    private connectViaEventSource;
+    private connectViaFetch;
+    private processSSEFrame;
+    private parseAndDispatchMessage;
+    private handleConnectionSuccess;
+    private handleConnectionFailure;
+    private scheduleReconnect;
+    private resetHeartbeat;
+    private clearHeartbeat;
+    private clearTimers;
+    private closeActiveTransport;
+    private buildUrl;
+    private resolveHeaders;
+    private log;
+}
+
+declare class NotifAgent {
+    readonly connection: ConnectionManager;
+    private options;
+    private channels;
+    private globalEmitter;
+    /**
+     * Unique client connection ID provided by NotifServer handshake.
+     */
+    get clientId(): string | null;
+    /**
+     * Pusher-compatible alias for clientId.
+     */
+    get socket_id(): string | null;
+    constructor(urlOrOptions: string | NotifAgentOptions, maybeOptions?: NotifAgentOptions);
+    /**
+     * Subscribe to a channel.
+     *
+     * Example:
+     * ```ts
+     * const channel = agent.subscribe('orders');
+     * channel.bind('created', (order) => { ... });
+     * ```
+     */
+    subscribe(channelName: string): Channel;
+    /**
+     * Internal authorization helper for private/presence channels.
+     */
+    private authorizeChannel;
+    /**
+     * Unsubscribe from a channel.
+     */
+    unsubscribe(channelName: string): void;
+    /**
+     * Get an existing subscribed channel by name, if any.
+     */
+    channel(channelName: string): Channel | undefined;
+    /**
+     * Return all currently subscribed channels.
+     */
+    allChannels(): Channel[];
+    /**
+     * Bind to an event across all channels or global events.
+     *
+     * Example:
+     * ```ts
+     * agent.bind('system-alert', (data) => console.log(data));
+     * ```
+     */
+    bind<T = any>(event: string, callback: EventCallback<T>): this;
+    /**
+     * Unbind an event listener.
+     */
+    unbind<T = any>(event?: string, callback?: EventCallback<T>): this;
+    /**
+     * Bind to all events regardless of name.
+     */
+    bind_global(callback: GlobalEventCallback): this;
+    /**
+     * Unbind a global event listener.
+     */
+    unbind_global(callback?: GlobalEventCallback): this;
+    /**
+     * Connect to the SSE endpoint.
+     */
+    connect(): void;
+    /**
+     * Disconnect from the SSE endpoint.
+     */
+    disconnect(): void;
+    /**
+     * Route incoming SSE message to global emitters and specific channels.
+     */
+    private routeMessage;
+}
+
+declare class EventEmitter {
+    private listeners;
+    private globalListeners;
+    /**
+     * Bind a callback to a specific event name.
+     */
+    bind<T = any>(event: string, callback: EventCallback<T>): this;
+    /**
+     * Unbind a callback from a specific event name, or all callbacks if callback is omitted.
+     * If both event and callback are omitted, all listeners are removed.
+     */
+    unbind<T = any>(event?: string, callback?: EventCallback<T>): this;
+    /**
+     * Bind a callback to ALL incoming events on this emitter.
+     */
+    bind_global(callback: GlobalEventCallback): this;
+    /**
+     * Unbind a global callback, or all global callbacks if callback is omitted.
+     */
+    unbind_global(callback?: GlobalEventCallback): this;
+    /**
+     * Emit an event to registered listeners and global listeners.
+     */
+    emit<T = any>(event: string, data: T, metadata?: EventMetadata): void;
+    /**
+     * Clear all listeners.
+     */
+    clear(): void;
+}
+
+export { Channel, type ChannelSubscriptionState, ConnectionManager, type ConnectionState, type EventCallback, EventEmitter, type EventMetadata, type GlobalEventCallback, NotifAgent, type NotifAgentOptions, type SSEMessagePayload, type StateChangePayload, type TransportType, NotifAgent as default };