@mailhooks/sdk 2.4.0 → 2.5.0

package/README.md

@@ -161,6 +161,124 @@ const email = await mailhooks.emails.waitFor({
 - Efficiently tracks checked emails to avoid duplicates
 - Throws error on timeout or max retries exceeded
 
+## Push Notifications (SSE)
+
+Get instant push notifications when emails arrive using Server-Sent Events. This is ideal for serverless environments, client-side apps, firewalled networks, or local development where webhooks aren't practical.
+
+### Basic Usage
+
+```typescript
+import { Mailhooks } from '@mailhooks/sdk';
+
+const mailhooks = new Mailhooks({ apiKey: 'mh_xxx' });
+
+const subscription = mailhooks.realtime.subscribe({
+  onEmailReceived: (email) => {
+    console.log('New email:', email.subject);
+    console.log('From:', email.from);
+  },
+  onConnected: (payload) => {
+    console.log('Connected!', payload.connectionId);
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  },
+});
+
+// Later, disconnect when done
+subscription.disconnect();
+```
+
+### Distributed Mode (Worker Load Balancing)
+
+When running multiple workers, use distributed mode so only ONE worker receives each notification:
+
+```typescript
+// Each worker connects with the same API key
+// Only ONE worker receives each notification (random selection)
+const subscription = mailhooks.realtime.subscribe({
+  mode: 'distributed',
+  onEmailReceived: async (email) => {
+    // Process email - only one worker will receive this
+    await processEmail(email.id);
+  },
+});
+```
+
+### Full Event Handling
+
+```typescript
+const subscription = mailhooks.realtime.subscribe({
+  mode: 'broadcast', // or 'distributed'
+  onConnected: (payload) => {
+    console.log(`Connected: ${payload.connectionId}`);
+    console.log(`Mode: ${payload.mode}`);
+  },
+  onEmailReceived: (email) => {
+    console.log(`From: ${email.from}`);
+    console.log(`Subject: ${email.subject}`);
+    console.log(`Has attachments: ${email.hasAttachments}`);
+  },
+  onEmailUpdated: (update) => {
+    console.log(`Email ${update.id} updated:`, update.changes);
+  },
+  onHeartbeat: () => {
+    // Sent every 30 seconds to keep connection alive
+  },
+  onError: (error) => {
+    console.error('Connection error:', error);
+  },
+  onDisconnect: () => {
+    console.log('Disconnected');
+  },
+  autoReconnect: true,  // Automatically reconnect on disconnect (default: true)
+  reconnectDelay: 5000, // Delay between reconnect attempts in ms (default: 5000)
+});
+```
+
+### Node.js Usage
+
+In Node.js, you need to install the `eventsource` package:
+
+```bash
+npm install eventsource
+```
+
+Then make EventSource available globally before importing the SDK:
+
+```typescript
+import EventSource from 'eventsource';
+(global as any).EventSource = EventSource;
+
+import { Mailhooks } from '@mailhooks/sdk';
+// Use as normal
+```
+
+### Check Connection Limits
+
+```typescript
+const access = await mailhooks.realtime.checkAccess();
+console.log('Has access:', access.hasAccess);
+console.log('Max connections:', access.maxConnections); // -1 = unlimited
+console.log('Current connections:', access.currentConnections);
+```
+
+### Event Types
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `connected` | `{ tenantId, connectedAt, mode, connectionId }` | Connection established |
+| `email.received` | `{ id, from, to, subject, hasAttachments, ... }` | New email arrived |
+| `email.updated` | `{ id, changes: { read?: boolean } }` | Email was updated |
+| `heartbeat` | `{ timestamp }` | Keep-alive ping (every 30s) |
+
+### Connection Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `broadcast` | All connected clients receive every event | Dashboards, monitoring |
+| `distributed` | One random client per API key receives each event | Worker pools, load balancing |
+
 ## Types
 
 The SDK includes comprehensive TypeScript types:

package/dist/index.d.ts

@@ -153,7 +153,13 @@ declare class EmailsResource extends MailhooksClient {
 }
 
 /**
- * Event types for real-time notifications
+ * Connection mode for SSE subscriptions
+ * - broadcast: All connected clients receive every event (default)
+ * - distributed: Only ONE client per API key group receives each event (load balancing)
+ */
+type ConnectionMode = 'broadcast' | 'distributed';
+/**
+ * Event types for push notifications
  */
 declare enum RealtimeEventType {
     EMAIL_RECEIVED = "email.received",
@@ -190,6 +196,8 @@ interface EmailUpdatedPayload {
 interface ConnectedPayload {
     tenantId: string;
     connectedAt: string;
+    mode?: ConnectionMode;
+    connectionId?: string;
 }
 /**
  * Heartbeat event payload
@@ -220,6 +228,12 @@ interface RealtimeCallbacks {
  * Subscription options
  */
 interface SubscribeOptions extends RealtimeCallbacks {
+    /**
+     * Connection mode (default: 'broadcast')
+     * - broadcast: All connected clients receive every event
+     * - distributed: Only ONE client per API key group receives each event (load balancing for workers)
+     */
+    mode?: ConnectionMode;
     /** Auto-reconnect on disconnect (default: true) */
     autoReconnect?: boolean;
     /** Reconnect delay in milliseconds (default: 5000) */

package/dist/index.js

@@ -305,6 +305,7 @@ var RealtimeResource = class {
    */
   subscribe(options = {}) {
     const {
+      mode = "broadcast",
       onEmailReceived,
       onEmailUpdated,
       onConnected,
@@ -328,7 +329,7 @@ var RealtimeResource = class {
       );
     }
     const baseUrl = this.config.baseUrl ?? "https://mailhooks.dev/api";
-    const url = `${baseUrl}/v1/realtime/events?token=${encodeURIComponent(this.config.apiKey)}`;
+    const url = `${baseUrl}/v1/realtime/events?token=${encodeURIComponent(this.config.apiKey)}&mode=${mode}`;
     const connect = () => {
       this.eventSource = new EventSource(url);
       this.eventSource.onmessage = (event) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailhooks/sdk",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "TypeScript SDK for Mailhooks API",
   "publishConfig": {
     "access": "public"