@mailhooks/sdk 2.3.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

@@ -152,8 +152,174 @@ declare class EmailsResource extends MailhooksClient {
     waitFor(options?: WaitForOptions): Promise<Email>;
 }
 
+/**
+ * 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",
+    EMAIL_UPDATED = "email.updated",
+    HEARTBEAT = "heartbeat",
+    CONNECTED = "connected"
+}
+/**
+ * Email received event payload
+ */
+interface EmailReceivedPayload {
+    id: string;
+    from: string;
+    to: string[];
+    subject: string;
+    domainId?: string;
+    domain?: string;
+    createdAt: string;
+    hasAttachments: boolean;
+    attachmentCount: number;
+}
+/**
+ * Email updated event payload
+ */
+interface EmailUpdatedPayload {
+    id: string;
+    changes: {
+        read?: boolean;
+    };
+}
+/**
+ * Connected event payload
+ */
+interface ConnectedPayload {
+    tenantId: string;
+    connectedAt: string;
+    mode?: ConnectionMode;
+    connectionId?: string;
+}
+/**
+ * Heartbeat event payload
+ */
+interface HeartbeatPayload {
+    timestamp: string;
+}
+/**
+ * Base realtime event structure
+ */
+interface RealtimeEvent<T = unknown> {
+    type: RealtimeEventType;
+    timestamp: string;
+    data: T;
+}
+/**
+ * Callback handlers for realtime events
+ */
+interface RealtimeCallbacks {
+    onEmailReceived?: (payload: EmailReceivedPayload) => void;
+    onEmailUpdated?: (payload: EmailUpdatedPayload) => void;
+    onConnected?: (payload: ConnectedPayload) => void;
+    onHeartbeat?: (payload: HeartbeatPayload) => void;
+    onError?: (error: Error) => void;
+    onDisconnect?: () => void;
+}
+/**
+ * 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) */
+    reconnectDelay?: number;
+}
+/**
+ * Subscription handle returned from subscribe()
+ */
+interface RealtimeSubscription {
+    /** Disconnect from the SSE stream */
+    disconnect: () => void;
+    /** Whether currently connected */
+    isConnected: () => boolean;
+}
+/**
+ * Realtime resource for subscribing to email notifications via SSE
+ *
+ * @example
+ * ```typescript
+ * const mailhooks = new Mailhooks({ apiKey: 'your-api-key' });
+ *
+ * // Subscribe to real-time notifications
+ * const subscription = mailhooks.realtime.subscribe({
+ *   onEmailReceived: (email) => {
+ *     console.log('New email:', email.subject);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Connection error:', error);
+ *   },
+ * });
+ *
+ * // Later, disconnect
+ * subscription.disconnect();
+ * ```
+ */
+declare class RealtimeResource {
+    private config;
+    private eventSource;
+    private reconnectTimeout;
+    constructor(config: MailhooksConfig);
+    /**
+     * Check if the plan allows real-time notifications and get connection quota
+     *
+     * @returns Promise resolving to access status and connection limits
+     */
+    checkAccess(): Promise<{
+        hasAccess: boolean;
+        maxConnections: number;
+        currentConnections: number;
+    }>;
+    /**
+     * Subscribe to real-time email notifications via Server-Sent Events (SSE)
+     *
+     * Note: This method requires the EventSource API, which is available in browsers
+     * and can be polyfilled in Node.js using packages like 'eventsource'.
+     *
+     * @param options Subscription options and callbacks
+     * @returns Subscription handle with disconnect method
+     *
+     * @example
+     * ```typescript
+     * const subscription = mailhooks.realtime.subscribe({
+     *   onEmailReceived: (email) => {
+     *     console.log('New email from:', email.from);
+     *     console.log('Subject:', email.subject);
+     *   },
+     *   onConnected: () => {
+     *     console.log('Connected to real-time notifications');
+     *   },
+     *   onError: (error) => {
+     *     console.error('Error:', error);
+     *   },
+     *   autoReconnect: true,
+     *   reconnectDelay: 5000,
+     * });
+     *
+     * // Disconnect when done
+     * subscription.disconnect();
+     * ```
+     */
+    subscribe(options?: SubscribeOptions): RealtimeSubscription;
+}
+
 declare class Mailhooks {
     emails: EmailsResource;
+    realtime: RealtimeResource;
     constructor(config: MailhooksConfig);
     /**
      * Create a new Mailhooks SDK instance
@@ -354,4 +520,4 @@ interface ParsedEmail {
  */
 declare function parseEml(eml: Buffer | string): Promise<ParsedEmail>;
 
-export { type Attachment, type DownloadResponse, type Email, type EmailContent, type EmailFilter, type EmailListParams, type EmailSort, EmailsResource, type EmailsResponse, Mailhooks, type MailhooksConfig, type PaginationResponse, type ParsedEmail, type StorageConfigSummary, type WaitForOptions, type WebhookPayload, constructSignature, Mailhooks as default, parseEml, parseWebhookPayload, verifyWebhookSignature };
+export { type Attachment, type ConnectedPayload, type DownloadResponse, type Email, type EmailContent, type EmailFilter, type EmailListParams, type EmailReceivedPayload, type EmailSort, type EmailUpdatedPayload, EmailsResource, type EmailsResponse, type HeartbeatPayload, Mailhooks, type MailhooksConfig, type PaginationResponse, type ParsedEmail, type RealtimeCallbacks, type RealtimeEvent, RealtimeEventType, RealtimeResource, type RealtimeSubscription, type StorageConfigSummary, type SubscribeOptions, type WaitForOptions, type WebhookPayload, constructSignature, Mailhooks as default, parseEml, parseWebhookPayload, verifyWebhookSignature };

package/dist/index.js

@@ -242,10 +242,158 @@ var EmailsResource = class extends MailhooksClient {
   }
 };
 
+// src/realtime.ts
+var RealtimeEventType = /* @__PURE__ */ ((RealtimeEventType2) => {
+  RealtimeEventType2["EMAIL_RECEIVED"] = "email.received";
+  RealtimeEventType2["EMAIL_UPDATED"] = "email.updated";
+  RealtimeEventType2["HEARTBEAT"] = "heartbeat";
+  RealtimeEventType2["CONNECTED"] = "connected";
+  return RealtimeEventType2;
+})(RealtimeEventType || {});
+var RealtimeResource = class {
+  constructor(config) {
+    this.eventSource = null;
+    this.reconnectTimeout = null;
+    this.config = config;
+  }
+  /**
+   * Check if the plan allows real-time notifications and get connection quota
+   *
+   * @returns Promise resolving to access status and connection limits
+   */
+  async checkAccess() {
+    const baseUrl = this.config.baseUrl ?? "https://mailhooks.dev/api";
+    const response = await fetch(`${baseUrl}/v1/realtime/plan-access`, {
+      headers: {
+        "x-api-key": this.config.apiKey
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to check plan access: ${response.statusText}`);
+    }
+    return response.json();
+  }
+  /**
+   * Subscribe to real-time email notifications via Server-Sent Events (SSE)
+   *
+   * Note: This method requires the EventSource API, which is available in browsers
+   * and can be polyfilled in Node.js using packages like 'eventsource'.
+   *
+   * @param options Subscription options and callbacks
+   * @returns Subscription handle with disconnect method
+   *
+   * @example
+   * ```typescript
+   * const subscription = mailhooks.realtime.subscribe({
+   *   onEmailReceived: (email) => {
+   *     console.log('New email from:', email.from);
+   *     console.log('Subject:', email.subject);
+   *   },
+   *   onConnected: () => {
+   *     console.log('Connected to real-time notifications');
+   *   },
+   *   onError: (error) => {
+   *     console.error('Error:', error);
+   *   },
+   *   autoReconnect: true,
+   *   reconnectDelay: 5000,
+   * });
+   *
+   * // Disconnect when done
+   * subscription.disconnect();
+   * ```
+   */
+  subscribe(options = {}) {
+    const {
+      mode = "broadcast",
+      onEmailReceived,
+      onEmailUpdated,
+      onConnected,
+      onHeartbeat,
+      onError,
+      onDisconnect,
+      autoReconnect = true,
+      reconnectDelay = 5e3
+    } = options;
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        'EventSource is not available. In Node.js, install and import the "eventsource" package.'
+      );
+    }
+    const baseUrl = this.config.baseUrl ?? "https://mailhooks.dev/api";
+    const url = `${baseUrl}/v1/realtime/events?token=${encodeURIComponent(this.config.apiKey)}&mode=${mode}`;
+    const connect = () => {
+      this.eventSource = new EventSource(url);
+      this.eventSource.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          switch (data.type) {
+            case "connected" /* CONNECTED */:
+              onConnected?.(data.data);
+              break;
+            case "email.received" /* EMAIL_RECEIVED */:
+              onEmailReceived?.(data.data);
+              break;
+            case "email.updated" /* EMAIL_UPDATED */:
+              onEmailUpdated?.(data.data);
+              break;
+            case "heartbeat" /* HEARTBEAT */:
+              onHeartbeat?.(data.data);
+              break;
+          }
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          onError?.(new Error(`Failed to parse event: ${message}`));
+        }
+      };
+      this.eventSource.onerror = (event) => {
+        onError?.(new Error("SSE connection error"));
+        this.eventSource?.close();
+        this.eventSource = null;
+        onDisconnect?.();
+        if (autoReconnect) {
+          if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+          }
+          this.reconnectTimeout = setTimeout(() => {
+            connect();
+          }, reconnectDelay);
+        }
+      };
+    };
+    connect();
+    return {
+      disconnect: () => {
+        if (this.reconnectTimeout) {
+          clearTimeout(this.reconnectTimeout);
+          this.reconnectTimeout = null;
+        }
+        if (this.eventSource) {
+          this.eventSource.close();
+          this.eventSource = null;
+          onDisconnect?.();
+        }
+      },
+      isConnected: () => {
+        return this.eventSource?.readyState === EventSource.OPEN;
+      }
+    };
+  }
+};
+
 // src/mailhooks.ts
 var Mailhooks = class _Mailhooks {
   constructor(config) {
     this.emails = new EmailsResource(config);
+    this.realtime = new RealtimeResource(config);
   }
   /**
    * Create a new Mailhooks SDK instance
@@ -312,4 +460,4 @@ async function parseEml(eml) {
 // src/index.ts
 var index_default = Mailhooks;
 
-export { EmailsResource, Mailhooks, constructSignature, index_default as default, parseEml, parseWebhookPayload, verifyWebhookSignature };
+export { EmailsResource, Mailhooks, RealtimeEventType, RealtimeResource, constructSignature, index_default as default, parseEml, parseWebhookPayload, verifyWebhookSignature };

package/package.json

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