@mailhooks/sdk 2.3.0 → 2.4.0

package/dist/index.d.ts

@@ -152,8 +152,160 @@ declare class EmailsResource extends MailhooksClient {
     waitFor(options?: WaitForOptions): Promise<Email>;
 }
 
+/**
+ * Event types for real-time 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;
+}
+/**
+ * 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 {
+    /** 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 +506,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,157 @@ 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 {
+      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)}`;
+    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 +459,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.4.0",
   "description": "TypeScript SDK for Mailhooks API",
   "publishConfig": {
     "access": "public"