mailpit-api 1.5.3 → 1.6.0

package/README.md

@@ -61,6 +61,7 @@ export const test = base.extend<MyFixtures>({
     const mailpit = new MailpitClient("http://localhost:8025");
     await mailpit.deleteMessages();
     await use(mailpit);
+    mailpit.disconnect();
   },
 });
 
@@ -75,7 +76,10 @@ test("should receive welcome email after registration", async ({
   page,
   mailpit,
 }) => {
-  // Register
+  // Start waiting for the new email event before triggering the action
+  const emailPromise = mailpit.waitForEvent("new");
+
+  // Register a new user
   await page.goto("/register");
   await page.getByTestId("email").fill("test@example.test");
   await page.getByTestId("password").fill("password123");
@@ -84,12 +88,12 @@ test("should receive welcome email after registration", async ({
   // Wait for success message on page
   await expect(page.getByTestId("success-message")).toBeVisible();
 
-  // Get the welcome email
-  const message = await mailpit.getMessageSummary();
+  // Wait for the new email event (up to 5 seconds by default)
+  const event = await emailPromise;
 
-  expect(message.To[0].Address).toBe("test@example.test");
-  expect(message.From.Address).toBe("no-reply@your-app.test");
-  expect(message.Subject).toBe("Welcome to Our App");
-  expect(message.Text).toContain("Thank you for registering with our app!");
+  // Verify the email from the event data
+  expect(event.Data.To[0].Address).toBe("test@example.test");
+  expect(event.Data.From.Address).toBe("no-reply@your-app.test");
+  expect(event.Data.Subject).toBe("Welcome to Our App");
 });
 ```

package/dist/index.d.mts

@@ -177,38 +177,7 @@ interface MailpitMessageSummaryResponse {
 /** Response for the {@link MailpitClient.listMessages| listMessages()} API containing the summary of multiple messages. */
 interface MailpitMessagesSummaryResponse {
     /** Messages */
-    messages: {
-        /** The number of attachments */
-        Attachments: number;
-        /** BCC addresses */
-        Bcc: MailpitEmailAddressResponse[];
-        /** CC addresses */
-        Cc: MailpitEmailAddressResponse[];
-        /** Created time in ISO format: 1970-01-01T00:00:00.000Z */
-        Created: string;
-        /** Sender address */
-        From: MailpitEmailAddressResponse;
-        /** Database ID */
-        ID: string;
-        /** Message ID */
-        MessageID: string;
-        /** Read status */
-        Read: boolean;
-        /** Reply-To addresses */
-        ReplyTo: MailpitEmailAddressResponse[];
-        /** Message size in bytes (total) */
-        Size: number;
-        /** Message snippet includes up to 250 characters */
-        Snippet: string;
-        /** Email subject */
-        Subject: string;
-        /** Message tags */
-        Tags: string[];
-        /** To addresses */
-        To: MailpitEmailAddressResponse[];
-        /** Username used for authentication (if provided) with the SMTP or {@link MailpitClient.sendMessage| sendMessage} */
-        Username?: string;
-    }[];
+    messages: MailpitMessageListItem[];
     /** Total number of messages matching the current query */
     messages_count: number;
     /** Total number of unread messages matching current query */
@@ -224,6 +193,39 @@ interface MailpitMessagesSummaryResponse {
     /** @deprecated No longer documented upstream */
     count: number;
 }
+/** Represents a message item in a list or WebSocket event */
+interface MailpitMessageListItem {
+    /** The number of attachments */
+    Attachments: number;
+    /** BCC addresses */
+    Bcc: MailpitEmailAddressResponse[];
+    /** CC addresses */
+    Cc: MailpitEmailAddressResponse[];
+    /** Created time in ISO format: 1970-01-01T00:00:00.000Z */
+    Created: string;
+    /** Sender address */
+    From: MailpitEmailAddressResponse;
+    /** Database ID */
+    ID: string;
+    /** Message ID */
+    MessageID: string;
+    /** Read status */
+    Read: boolean;
+    /** Reply-To addresses */
+    ReplyTo: MailpitEmailAddressResponse[];
+    /** Message size in bytes (total) */
+    Size: number;
+    /** Message snippet includes up to 250 characters */
+    Snippet: string;
+    /** Email subject */
+    Subject: string;
+    /** Message tags */
+    Tags: string[];
+    /** To addresses */
+    To: MailpitEmailAddressResponse[];
+    /** Username used for authentication (if provided) with the SMTP or {@link MailpitClient.sendMessage| sendMessage} */
+    Username?: string;
+}
 /** Response for the {@link MailpitClient.getMessageHeaders | getMessageHeaders()} API containing message headers */
 interface MailpitMessageHeadersResponse {
     /** Message headers */
@@ -411,6 +413,91 @@ interface MailpitAttachmentDataResponse {
     /** The attachment MIME type */
     contentType: string;
 }
+/** Message summary data structure returned in "new" events */
+type MailpitMessageSummary = MailpitMessageListItem;
+/** Statistics data structure returned in "stats" events */
+interface MailpitStatsData {
+    /** Total number of messages in the database */
+    Total: number;
+    /** Total number of unread messages */
+    Unread: number;
+    /** Mailpit version */
+    Version: string;
+}
+/** Update data structure returned in "update" events */
+interface MailpitUpdateData {
+    /** Message database ID */
+    ID: string;
+    /** Read status (if changed) */
+    Read?: boolean;
+    /** Tags (if changed) */
+    Tags?: string[];
+}
+/** Delete data structure returned in "delete" events */
+interface MailpitDeleteData {
+    /** Message database ID */
+    ID: string;
+}
+/** Error data structure returned in "error" events */
+interface MailpitErrorData {
+    /** Error severity level */
+    Level: string;
+    /** Error type */
+    Type: string;
+    /** Client IP address */
+    IP: string;
+    /** Error message */
+    Message: string;
+}
+/** Event message containing a type and data payload */
+interface MailpitEvent<T = MailpitMessageSummary | MailpitStatsData | MailpitUpdateData | MailpitDeleteData | MailpitErrorData | null> {
+    /** Type of event being broadcast */
+    Type: string;
+    /** Event data payload */
+    Data: T;
+}
+/** Event for new messages */
+interface MailpitNewMessageEvent extends MailpitEvent<MailpitMessageSummary> {
+    Type: "new";
+}
+/** Event for statistics updates */
+interface MailpitStatsEvent extends MailpitEvent<MailpitStatsData> {
+    Type: "stats";
+}
+/** Event for message updates */
+interface MailpitUpdateEvent extends MailpitEvent<MailpitUpdateData> {
+    Type: "update";
+}
+/** Event for message deletion */
+interface MailpitDeleteEvent extends MailpitEvent<MailpitDeleteData> {
+    Type: "delete";
+}
+/** Event for database pruning (Data is null) */
+interface MailpitPruneEvent extends MailpitEvent<null> {
+    Type: "prune";
+}
+/** Event for truncating all messages (Data is null) */
+interface MailpitTruncateEvent extends MailpitEvent<null> {
+    Type: "truncate";
+}
+/** Event for client errors (SMTP/POP3 errors) */
+interface MailpitErrorEvent extends MailpitEvent<MailpitErrorData> {
+    Type: "error";
+}
+/** Maps event type strings to their corresponding event interfaces */
+interface MailpitEventMap {
+    new: MailpitNewMessageEvent;
+    stats: MailpitStatsEvent;
+    update: MailpitUpdateEvent;
+    delete: MailpitDeleteEvent;
+    prune: MailpitPruneEvent;
+    truncate: MailpitTruncateEvent;
+    error: MailpitErrorEvent;
+    /** Wildcard event type that matches all events */
+    "*": MailpitEvent;
+}
+/** Valid event types including specific event names and the wildcard "*" */
+type MailpitEventType = keyof MailpitEventMap;
 /**
  * Client for interacting with the {@link https://mailpit.axllent.org/docs/api-v1/ | Mailpit API}.
  * @example
@@ -422,6 +509,10 @@ interface MailpitAttachmentDataResponse {
  */
 declare class MailpitClient {
     private readonly axiosInstance;
+    private readonly baseURL;
+    private readonly wsURL;
+    private webSocket;
+    private eventListeners;
     /**
      * Creates an instance of {@link MailpitClient}.
      * @param baseURL - The base URL of the Mailpit API.
@@ -435,8 +526,8 @@ declare class MailpitClient {
      * @example Basic Auth
      * ```typescript
      * const mailpit = new MailpitClient("http://localhost:8025", {
-     *  username: "admin",
-     *  password: "supersecret",
+     *   username: "admin",
+     *   password: "supersecret"
      * });
      * ```
      */
@@ -781,6 +872,110 @@ declare class MailpitClient {
      * ```
      */
     renderMessageText(id?: string): Promise<string>;
+    /**
+     * @internal
+     * Connects to the WebSocket endpoint for receiving real-time events.
+     */
+    private connectWebSocket;
+    /**
+     * @internal
+     * Adds a listener to the event listeners map.
+     * @param eventType - The type of event to listen for
+     * @param listener - The listener function to add
+     */
+    private addListener;
+    /**
+     * @internal
+     * Removes a listener from the event listeners map.
+     * @param eventType - The type of event to remove the listener from
+     * @param listener - The listener function to remove
+     */
+    private removeListener;
+    /**
+     * @internal
+     * Dispatches a message to listeners of a specific event type.
+     * @param eventType - The event type to dispatch to
+     * @param message - The event message
+     */
+    private dispatchToListeners;
+    /**
+     * @internal
+     * Handles incoming WebSocket messages and dispatches them to registered listeners.
+     * @param message - The event message
+     */
+    private handleWebSocketMessage;
+    /**
+     * Disconnects from the real-time event stream.
+     * @example
+     * ```typescript
+     * mailpit.disconnect();
+     * ```
+     */
+    disconnect(): void;
+    /**
+     * Registers a listener for real-time events of a specific type.
+     * @remarks
+     * Automatically connects to the event stream if not already connected.
+     * @param eventType - The type of event to listen for.
+     * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+     * Use "*" to listen for all event types (Useful if processing all events uniformly (e.g., logging, debugging, metrics)).
+     * @param listener - The callback function to invoke when an event is received
+     * @returns A function to unregister the listener
+     * @example Listen for event type "new" messages (recommended)
+     * ```typescript
+     * const unsubscribe = mailpit.onEvent("new", (event) => {
+     *   // event.Data is typed as MailpitMessageSummary with full type safety
+     *   console.log("New message:", event.Data.Subject);
+     * });
+     *
+     * // Other code...
+     *
+     * // Unsubscribe listener when no longer needed
+     * unsubscribe();
+     * ```
+     * @example Listen for all events uniformly (for logging/debugging)
+     * ```typescript
+     * const unsubscribe = mailpit.onEvent("*", (event) => {
+     *   // Generic processing for all event types
+     *   console.log(`Event ${event.Type} received`);
+     * });
+     *
+     * // Other code...
+     *
+     * // Unsubscribe listener when no longer needed
+     * unsubscribe();
+     * ```
+     */
+    onEvent<T extends keyof MailpitEventMap>(eventType: T, listener: (event: MailpitEventMap[T]) => void): () => void;
+    /**
+     * Waits for the next event of a specific type.
+     * @remarks
+     * Automatically connects to the event stream if not already connected.
+     * Primarily intended for testing scenarios where you need to wait for a single specific event.
+     * The promise will reject if the timeout is reached before an event is received.
+     * @param eventType - The type of event to wait for.
+     * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+     * @param timeout - Timeout in milliseconds (default: 5000ms). Pass `Infinity` to disable timeout.
+     * @returns A promise that resolves with the event when received, or rejects on timeout
+     * @example Basic usage
+     * ```typescript
+     * // Create the promise before triggering the event
+     * const eventPromise = mailpit.waitForEvent("new");
+     *
+     * // Do something that triggers an email to send
+     * await mailpit.sendMessage({
+     *   From: { Email: "test@example.com" },
+     *   To: [{ Email: "recipient@example.com" }],
+     *   Subject: "Test",
+     * });
+     *
+     * // Wait for the event confirming the message was received
+     * const event = await eventPromise;
+     * // event.Data is fully typed as MailpitMessageSummary
+     * console.log("Message received:", event.Data.Subject);
+     * ```
+     */
+    waitForEvent<T extends Exclude<keyof MailpitEventMap, "*">>(eventType: T, timeout?: number): Promise<MailpitEventMap[T]>;
 }
 
-export { type MailpitAttachmentDataResponse, type MailpitAttachmentRequest, type MailpitAttachmentResponse, type MailpitChaosTrigger, type MailpitChaosTriggersRequest, type MailpitChaosTriggersResponse, MailpitClient, type MailpitConfigurationResponse, type MailpitDatabaseIDsRequest, type MailpitEmailAddressRequest, type MailpitEmailAddressResponse, type MailpitHTMLCheckResponse, type MailpitInfoResponse, type MailpitLinkCheckResponse, type MailpitMessageHeadersResponse, type MailpitMessageSummaryResponse, type MailpitMessagesSummaryResponse, type MailpitReadStatusRequest, type MailpitSearchMessagesRequest, type MailpitSearchRequest, type MailpitSendMessageConfirmationResponse, type MailpitSendRequest, type MailpitSetTagsRequest, type MailpitSpamAssassinResponse, type MailpitTimeZoneRequest };
+export { type MailpitAttachmentDataResponse, type MailpitAttachmentRequest, type MailpitAttachmentResponse, type MailpitChaosTrigger, type MailpitChaosTriggersRequest, type MailpitChaosTriggersResponse, MailpitClient, type MailpitConfigurationResponse, type MailpitDatabaseIDsRequest, type MailpitDeleteData, type MailpitDeleteEvent, type MailpitEmailAddressRequest, type MailpitEmailAddressResponse, type MailpitErrorData, type MailpitErrorEvent, type MailpitEvent, type MailpitEventMap, type MailpitEventType, type MailpitHTMLCheckResponse, type MailpitInfoResponse, type MailpitLinkCheckResponse, type MailpitMessageHeadersResponse, type MailpitMessageListItem, type MailpitMessageSummary, type MailpitMessageSummaryResponse, type MailpitMessagesSummaryResponse, type MailpitNewMessageEvent, type MailpitPruneEvent, type MailpitReadStatusRequest, type MailpitSearchMessagesRequest, type MailpitSearchRequest, type MailpitSendMessageConfirmationResponse, type MailpitSendRequest, type MailpitSetTagsRequest, type MailpitSpamAssassinResponse, type MailpitStatsData, type MailpitStatsEvent, type MailpitTimeZoneRequest, type MailpitTruncateEvent, type MailpitUpdateData, type MailpitUpdateEvent };

package/dist/index.d.ts

@@ -177,38 +177,7 @@ interface MailpitMessageSummaryResponse {
 /** Response for the {@link MailpitClient.listMessages| listMessages()} API containing the summary of multiple messages. */
 interface MailpitMessagesSummaryResponse {
     /** Messages */
-    messages: {
-        /** The number of attachments */
-        Attachments: number;
-        /** BCC addresses */
-        Bcc: MailpitEmailAddressResponse[];
-        /** CC addresses */
-        Cc: MailpitEmailAddressResponse[];
-        /** Created time in ISO format: 1970-01-01T00:00:00.000Z */
-        Created: string;
-        /** Sender address */
-        From: MailpitEmailAddressResponse;
-        /** Database ID */
-        ID: string;
-        /** Message ID */
-        MessageID: string;
-        /** Read status */
-        Read: boolean;
-        /** Reply-To addresses */
-        ReplyTo: MailpitEmailAddressResponse[];
-        /** Message size in bytes (total) */
-        Size: number;
-        /** Message snippet includes up to 250 characters */
-        Snippet: string;
-        /** Email subject */
-        Subject: string;
-        /** Message tags */
-        Tags: string[];
-        /** To addresses */
-        To: MailpitEmailAddressResponse[];
-        /** Username used for authentication (if provided) with the SMTP or {@link MailpitClient.sendMessage| sendMessage} */
-        Username?: string;
-    }[];
+    messages: MailpitMessageListItem[];
     /** Total number of messages matching the current query */
     messages_count: number;
     /** Total number of unread messages matching current query */
@@ -224,6 +193,39 @@ interface MailpitMessagesSummaryResponse {
     /** @deprecated No longer documented upstream */
     count: number;
 }
+/** Represents a message item in a list or WebSocket event */
+interface MailpitMessageListItem {
+    /** The number of attachments */
+    Attachments: number;
+    /** BCC addresses */
+    Bcc: MailpitEmailAddressResponse[];
+    /** CC addresses */
+    Cc: MailpitEmailAddressResponse[];
+    /** Created time in ISO format: 1970-01-01T00:00:00.000Z */
+    Created: string;
+    /** Sender address */
+    From: MailpitEmailAddressResponse;
+    /** Database ID */
+    ID: string;
+    /** Message ID */
+    MessageID: string;
+    /** Read status */
+    Read: boolean;
+    /** Reply-To addresses */
+    ReplyTo: MailpitEmailAddressResponse[];
+    /** Message size in bytes (total) */
+    Size: number;
+    /** Message snippet includes up to 250 characters */
+    Snippet: string;
+    /** Email subject */
+    Subject: string;
+    /** Message tags */
+    Tags: string[];
+    /** To addresses */
+    To: MailpitEmailAddressResponse[];
+    /** Username used for authentication (if provided) with the SMTP or {@link MailpitClient.sendMessage| sendMessage} */
+    Username?: string;
+}
 /** Response for the {@link MailpitClient.getMessageHeaders | getMessageHeaders()} API containing message headers */
 interface MailpitMessageHeadersResponse {
     /** Message headers */
@@ -411,6 +413,91 @@ interface MailpitAttachmentDataResponse {
     /** The attachment MIME type */
     contentType: string;
 }
+/** Message summary data structure returned in "new" events */
+type MailpitMessageSummary = MailpitMessageListItem;
+/** Statistics data structure returned in "stats" events */
+interface MailpitStatsData {
+    /** Total number of messages in the database */
+    Total: number;
+    /** Total number of unread messages */
+    Unread: number;
+    /** Mailpit version */
+    Version: string;
+}
+/** Update data structure returned in "update" events */
+interface MailpitUpdateData {
+    /** Message database ID */
+    ID: string;
+    /** Read status (if changed) */
+    Read?: boolean;
+    /** Tags (if changed) */
+    Tags?: string[];
+}
+/** Delete data structure returned in "delete" events */
+interface MailpitDeleteData {
+    /** Message database ID */
+    ID: string;
+}
+/** Error data structure returned in "error" events */
+interface MailpitErrorData {
+    /** Error severity level */
+    Level: string;
+    /** Error type */
+    Type: string;
+    /** Client IP address */
+    IP: string;
+    /** Error message */
+    Message: string;
+}
+/** Event message containing a type and data payload */
+interface MailpitEvent<T = MailpitMessageSummary | MailpitStatsData | MailpitUpdateData | MailpitDeleteData | MailpitErrorData | null> {
+    /** Type of event being broadcast */
+    Type: string;
+    /** Event data payload */
+    Data: T;
+}
+/** Event for new messages */
+interface MailpitNewMessageEvent extends MailpitEvent<MailpitMessageSummary> {
+    Type: "new";
+}
+/** Event for statistics updates */
+interface MailpitStatsEvent extends MailpitEvent<MailpitStatsData> {
+    Type: "stats";
+}
+/** Event for message updates */
+interface MailpitUpdateEvent extends MailpitEvent<MailpitUpdateData> {
+    Type: "update";
+}
+/** Event for message deletion */
+interface MailpitDeleteEvent extends MailpitEvent<MailpitDeleteData> {
+    Type: "delete";
+}
+/** Event for database pruning (Data is null) */
+interface MailpitPruneEvent extends MailpitEvent<null> {
+    Type: "prune";
+}
+/** Event for truncating all messages (Data is null) */
+interface MailpitTruncateEvent extends MailpitEvent<null> {
+    Type: "truncate";
+}
+/** Event for client errors (SMTP/POP3 errors) */
+interface MailpitErrorEvent extends MailpitEvent<MailpitErrorData> {
+    Type: "error";
+}
+/** Maps event type strings to their corresponding event interfaces */
+interface MailpitEventMap {
+    new: MailpitNewMessageEvent;
+    stats: MailpitStatsEvent;
+    update: MailpitUpdateEvent;
+    delete: MailpitDeleteEvent;
+    prune: MailpitPruneEvent;
+    truncate: MailpitTruncateEvent;
+    error: MailpitErrorEvent;
+    /** Wildcard event type that matches all events */
+    "*": MailpitEvent;
+}
+/** Valid event types including specific event names and the wildcard "*" */
+type MailpitEventType = keyof MailpitEventMap;
 /**
  * Client for interacting with the {@link https://mailpit.axllent.org/docs/api-v1/ | Mailpit API}.
  * @example
@@ -422,6 +509,10 @@ interface MailpitAttachmentDataResponse {
  */
 declare class MailpitClient {
     private readonly axiosInstance;
+    private readonly baseURL;
+    private readonly wsURL;
+    private webSocket;
+    private eventListeners;
     /**
      * Creates an instance of {@link MailpitClient}.
      * @param baseURL - The base URL of the Mailpit API.
@@ -435,8 +526,8 @@ declare class MailpitClient {
      * @example Basic Auth
      * ```typescript
      * const mailpit = new MailpitClient("http://localhost:8025", {
-     *  username: "admin",
-     *  password: "supersecret",
+     *   username: "admin",
+     *   password: "supersecret"
      * });
      * ```
      */
@@ -781,6 +872,110 @@ declare class MailpitClient {
      * ```
      */
     renderMessageText(id?: string): Promise<string>;
+    /**
+     * @internal
+     * Connects to the WebSocket endpoint for receiving real-time events.
+     */
+    private connectWebSocket;
+    /**
+     * @internal
+     * Adds a listener to the event listeners map.
+     * @param eventType - The type of event to listen for
+     * @param listener - The listener function to add
+     */
+    private addListener;
+    /**
+     * @internal
+     * Removes a listener from the event listeners map.
+     * @param eventType - The type of event to remove the listener from
+     * @param listener - The listener function to remove
+     */
+    private removeListener;
+    /**
+     * @internal
+     * Dispatches a message to listeners of a specific event type.
+     * @param eventType - The event type to dispatch to
+     * @param message - The event message
+     */
+    private dispatchToListeners;
+    /**
+     * @internal
+     * Handles incoming WebSocket messages and dispatches them to registered listeners.
+     * @param message - The event message
+     */
+    private handleWebSocketMessage;
+    /**
+     * Disconnects from the real-time event stream.
+     * @example
+     * ```typescript
+     * mailpit.disconnect();
+     * ```
+     */
+    disconnect(): void;
+    /**
+     * Registers a listener for real-time events of a specific type.
+     * @remarks
+     * Automatically connects to the event stream if not already connected.
+     * @param eventType - The type of event to listen for.
+     * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+     * Use "*" to listen for all event types (Useful if processing all events uniformly (e.g., logging, debugging, metrics)).
+     * @param listener - The callback function to invoke when an event is received
+     * @returns A function to unregister the listener
+     * @example Listen for event type "new" messages (recommended)
+     * ```typescript
+     * const unsubscribe = mailpit.onEvent("new", (event) => {
+     *   // event.Data is typed as MailpitMessageSummary with full type safety
+     *   console.log("New message:", event.Data.Subject);
+     * });
+     *
+     * // Other code...
+     *
+     * // Unsubscribe listener when no longer needed
+     * unsubscribe();
+     * ```
+     * @example Listen for all events uniformly (for logging/debugging)
+     * ```typescript
+     * const unsubscribe = mailpit.onEvent("*", (event) => {
+     *   // Generic processing for all event types
+     *   console.log(`Event ${event.Type} received`);
+     * });
+     *
+     * // Other code...
+     *
+     * // Unsubscribe listener when no longer needed
+     * unsubscribe();
+     * ```
+     */
+    onEvent<T extends keyof MailpitEventMap>(eventType: T, listener: (event: MailpitEventMap[T]) => void): () => void;
+    /**
+     * Waits for the next event of a specific type.
+     * @remarks
+     * Automatically connects to the event stream if not already connected.
+     * Primarily intended for testing scenarios where you need to wait for a single specific event.
+     * The promise will reject if the timeout is reached before an event is received.
+     * @param eventType - The type of event to wait for.
+     * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+     * @param timeout - Timeout in milliseconds (default: 5000ms). Pass `Infinity` to disable timeout.
+     * @returns A promise that resolves with the event when received, or rejects on timeout
+     * @example Basic usage
+     * ```typescript
+     * // Create the promise before triggering the event
+     * const eventPromise = mailpit.waitForEvent("new");
+     *
+     * // Do something that triggers an email to send
+     * await mailpit.sendMessage({
+     *   From: { Email: "test@example.com" },
+     *   To: [{ Email: "recipient@example.com" }],
+     *   Subject: "Test",
+     * });
+     *
+     * // Wait for the event confirming the message was received
+     * const event = await eventPromise;
+     * // event.Data is fully typed as MailpitMessageSummary
+     * console.log("Message received:", event.Data.Subject);
+     * ```
+     */
+    waitForEvent<T extends Exclude<keyof MailpitEventMap, "*">>(eventType: T, timeout?: number): Promise<MailpitEventMap[T]>;
 }
 
-export { type MailpitAttachmentDataResponse, type MailpitAttachmentRequest, type MailpitAttachmentResponse, type MailpitChaosTrigger, type MailpitChaosTriggersRequest, type MailpitChaosTriggersResponse, MailpitClient, type MailpitConfigurationResponse, type MailpitDatabaseIDsRequest, type MailpitEmailAddressRequest, type MailpitEmailAddressResponse, type MailpitHTMLCheckResponse, type MailpitInfoResponse, type MailpitLinkCheckResponse, type MailpitMessageHeadersResponse, type MailpitMessageSummaryResponse, type MailpitMessagesSummaryResponse, type MailpitReadStatusRequest, type MailpitSearchMessagesRequest, type MailpitSearchRequest, type MailpitSendMessageConfirmationResponse, type MailpitSendRequest, type MailpitSetTagsRequest, type MailpitSpamAssassinResponse, type MailpitTimeZoneRequest };
+export { type MailpitAttachmentDataResponse, type MailpitAttachmentRequest, type MailpitAttachmentResponse, type MailpitChaosTrigger, type MailpitChaosTriggersRequest, type MailpitChaosTriggersResponse, MailpitClient, type MailpitConfigurationResponse, type MailpitDatabaseIDsRequest, type MailpitDeleteData, type MailpitDeleteEvent, type MailpitEmailAddressRequest, type MailpitEmailAddressResponse, type MailpitErrorData, type MailpitErrorEvent, type MailpitEvent, type MailpitEventMap, type MailpitEventType, type MailpitHTMLCheckResponse, type MailpitInfoResponse, type MailpitLinkCheckResponse, type MailpitMessageHeadersResponse, type MailpitMessageListItem, type MailpitMessageSummary, type MailpitMessageSummaryResponse, type MailpitMessagesSummaryResponse, type MailpitNewMessageEvent, type MailpitPruneEvent, type MailpitReadStatusRequest, type MailpitSearchMessagesRequest, type MailpitSearchRequest, type MailpitSendMessageConfirmationResponse, type MailpitSendRequest, type MailpitSetTagsRequest, type MailpitSpamAssassinResponse, type MailpitStatsData, type MailpitStatsEvent, type MailpitTimeZoneRequest, type MailpitTruncateEvent, type MailpitUpdateData, type MailpitUpdateEvent };

package/dist/index.js

@@ -34,8 +34,14 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_axios = __toESM(require("axios"));
+var import_partysocket = require("partysocket");
+var import_ws = __toESM(require("ws"));
 var MailpitClient = class {
   axiosInstance;
+  baseURL;
+  wsURL;
+  webSocket = null;
+  eventListeners = /* @__PURE__ */ new Map();
   /**
    * Creates an instance of {@link MailpitClient}.
    * @param baseURL - The base URL of the Mailpit API.
@@ -49,12 +55,19 @@ var MailpitClient = class {
    * @example Basic Auth
    * ```typescript
    * const mailpit = new MailpitClient("http://localhost:8025", {
-   *  username: "admin",
-   *  password: "supersecret",
+   *   username: "admin",
+   *   password: "supersecret"
    * });
    * ```
    */
   constructor(baseURL, auth) {
+    if (!baseURL || !/^https?:\/\//.test(baseURL)) {
+      throw new Error(
+        "The value of the 'baseURL' parameter must start with http:// or https://"
+      );
+    }
+    this.baseURL = baseURL;
+    this.wsURL = `${baseURL.replace(/^http/, "ws")}/api/events`;
     this.axiosInstance = import_axios.default.create({
       baseURL,
       auth,
@@ -564,6 +577,198 @@ var MailpitClient = class {
       () => this.axiosInstance.get(`/view/${id}.txt`)
     );
   }
+  /**
+   * @internal
+   * Connects to the WebSocket endpoint for receiving real-time events.
+   */
+  connectWebSocket() {
+    if (this.webSocket && (this.webSocket.readyState === import_partysocket.WebSocket.OPEN || this.webSocket.readyState === import_partysocket.WebSocket.CONNECTING)) {
+      return;
+    }
+    const wsOptions = {};
+    if (this.axiosInstance.defaults.auth) {
+      wsOptions.headers = {
+        Authorization: `Basic ${Buffer.from(`${this.axiosInstance.defaults.auth.username}:${this.axiosInstance.defaults.auth.password}`).toString("base64")}`
+      };
+    }
+    class AuthenticatedWebSocket extends import_ws.default {
+      constructor(address, options) {
+        super(address, { ...wsOptions, ...options });
+      }
+    }
+    this.webSocket = new import_partysocket.WebSocket(this.wsURL, void 0, {
+      WebSocket: AuthenticatedWebSocket
+    });
+    this.webSocket.addEventListener("message", (event) => {
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      this.handleWebSocketMessage(message);
+    });
+  }
+  /**
+   * @internal
+   * Adds a listener to the event listeners map.
+   * @param eventType - The type of event to listen for
+   * @param listener - The listener function to add
+   */
+  addListener(eventType, listener) {
+    if (!this.eventListeners.has(eventType)) {
+      this.eventListeners.set(eventType, /* @__PURE__ */ new Set());
+    }
+    this.eventListeners.get(eventType)?.add(listener);
+  }
+  /**
+   * @internal
+   * Removes a listener from the event listeners map.
+   * @param eventType - The type of event to remove the listener from
+   * @param listener - The listener function to remove
+   */
+  removeListener(eventType, listener) {
+    const listeners = this.eventListeners.get(eventType);
+    if (listeners) {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.eventListeners.delete(eventType);
+      }
+    }
+  }
+  /**
+   * @internal
+   * Dispatches a message to listeners of a specific event type.
+   * @param eventType - The event type to dispatch to
+   * @param message - The event message
+   */
+  dispatchToListeners(eventType, message) {
+    const listeners = this.eventListeners.get(eventType);
+    if (listeners) {
+      listeners.forEach((listener) => {
+        listener(message);
+      });
+    }
+  }
+  /**
+   * @internal
+   * Handles incoming WebSocket messages and dispatches them to registered listeners.
+   * @param message - The event message
+   */
+  handleWebSocketMessage(message) {
+    this.dispatchToListeners(message.Type, message);
+    this.dispatchToListeners("*", message);
+  }
+  /**
+   * Disconnects from the real-time event stream.
+   * @example
+   * ```typescript
+   * mailpit.disconnect();
+   * ```
+   */
+  disconnect() {
+    if (this.webSocket) {
+      const ws = this.webSocket;
+      this.webSocket = null;
+      ws.close(1e3, "Client disconnect");
+    }
+  }
+  /**
+   * Registers a listener for real-time events of a specific type.
+   * @remarks
+   * Automatically connects to the event stream if not already connected.
+   * @param eventType - The type of event to listen for.
+   * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+   * Use "*" to listen for all event types (Useful if processing all events uniformly (e.g., logging, debugging, metrics)).
+   * @param listener - The callback function to invoke when an event is received
+   * @returns A function to unregister the listener
+   * @example Listen for event type "new" messages (recommended)
+   * ```typescript
+   * const unsubscribe = mailpit.onEvent("new", (event) => {
+   *   // event.Data is typed as MailpitMessageSummary with full type safety
+   *   console.log("New message:", event.Data.Subject);
+   * });
+   *
+   * // Other code...
+   *
+   * // Unsubscribe listener when no longer needed
+   * unsubscribe();
+   * ```
+   * @example Listen for all events uniformly (for logging/debugging)
+   * ```typescript
+   * const unsubscribe = mailpit.onEvent("*", (event) => {
+   *   // Generic processing for all event types
+   *   console.log(`Event ${event.Type} received`);
+   * });
+   *
+   * // Other code...
+   *
+   * // Unsubscribe listener when no longer needed
+   * unsubscribe();
+   * ```
+   */
+  onEvent(eventType, listener) {
+    if (!this.webSocket || this.webSocket.readyState === import_partysocket.WebSocket.CLOSED) {
+      this.connectWebSocket();
+    }
+    this.addListener(eventType, listener);
+    return () => {
+      this.removeListener(eventType, listener);
+    };
+  }
+  /**
+   * Waits for the next event of a specific type.
+   * @remarks
+   * Automatically connects to the event stream if not already connected.
+   * Primarily intended for testing scenarios where you need to wait for a single specific event.
+   * The promise will reject if the timeout is reached before an event is received.
+   * @param eventType - The type of event to wait for.
+   * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+   * @param timeout - Timeout in milliseconds (default: 5000ms). Pass `Infinity` to disable timeout.
+   * @returns A promise that resolves with the event when received, or rejects on timeout
+   * @example Basic usage
+   * ```typescript
+   * // Create the promise before triggering the event
+   * const eventPromise = mailpit.waitForEvent("new");
+   *
+   * // Do something that triggers an email to send
+   * await mailpit.sendMessage({
+   *   From: { Email: "test@example.com" },
+   *   To: [{ Email: "recipient@example.com" }],
+   *   Subject: "Test",
+   * });
+   *
+   * // Wait for the event confirming the message was received
+   * const event = await eventPromise;
+   * // event.Data is fully typed as MailpitMessageSummary
+   * console.log("Message received:", event.Data.Subject);
+   * ```
+   */
+  waitForEvent(eventType, timeout = 5e3) {
+    if (!this.webSocket || this.webSocket.readyState === import_partysocket.WebSocket.CLOSED) {
+      this.connectWebSocket();
+    }
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      const cleanup = () => {
+        if (timer) {
+          clearTimeout(timer);
+        }
+        this.removeListener(eventType, listener);
+      };
+      const listener = (event) => {
+        cleanup();
+        resolve(event);
+      };
+      this.addListener(eventType, listener);
+      if (isFinite(timeout)) {
+        timer = setTimeout(() => {
+          cleanup();
+          reject(new Error(`Timeout waiting for event of type "${eventType}"`));
+        }, timeout);
+      }
+    });
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -2,8 +2,14 @@
 import axios, {
   isAxiosError
 } from "axios";
+import { WebSocket as ReconnectingWebSocket } from "partysocket";
+import WS from "ws";
 var MailpitClient = class {
   axiosInstance;
+  baseURL;
+  wsURL;
+  webSocket = null;
+  eventListeners = /* @__PURE__ */ new Map();
   /**
    * Creates an instance of {@link MailpitClient}.
    * @param baseURL - The base URL of the Mailpit API.
@@ -17,12 +23,19 @@ var MailpitClient = class {
    * @example Basic Auth
    * ```typescript
    * const mailpit = new MailpitClient("http://localhost:8025", {
-   *  username: "admin",
-   *  password: "supersecret",
+   *   username: "admin",
+   *   password: "supersecret"
    * });
    * ```
    */
   constructor(baseURL, auth) {
+    if (!baseURL || !/^https?:\/\//.test(baseURL)) {
+      throw new Error(
+        "The value of the 'baseURL' parameter must start with http:// or https://"
+      );
+    }
+    this.baseURL = baseURL;
+    this.wsURL = `${baseURL.replace(/^http/, "ws")}/api/events`;
     this.axiosInstance = axios.create({
       baseURL,
       auth,
@@ -532,6 +545,198 @@ var MailpitClient = class {
       () => this.axiosInstance.get(`/view/${id}.txt`)
     );
   }
+  /**
+   * @internal
+   * Connects to the WebSocket endpoint for receiving real-time events.
+   */
+  connectWebSocket() {
+    if (this.webSocket && (this.webSocket.readyState === ReconnectingWebSocket.OPEN || this.webSocket.readyState === ReconnectingWebSocket.CONNECTING)) {
+      return;
+    }
+    const wsOptions = {};
+    if (this.axiosInstance.defaults.auth) {
+      wsOptions.headers = {
+        Authorization: `Basic ${Buffer.from(`${this.axiosInstance.defaults.auth.username}:${this.axiosInstance.defaults.auth.password}`).toString("base64")}`
+      };
+    }
+    class AuthenticatedWebSocket extends WS {
+      constructor(address, options) {
+        super(address, { ...wsOptions, ...options });
+      }
+    }
+    this.webSocket = new ReconnectingWebSocket(this.wsURL, void 0, {
+      WebSocket: AuthenticatedWebSocket
+    });
+    this.webSocket.addEventListener("message", (event) => {
+      let message;
+      try {
+        message = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      this.handleWebSocketMessage(message);
+    });
+  }
+  /**
+   * @internal
+   * Adds a listener to the event listeners map.
+   * @param eventType - The type of event to listen for
+   * @param listener - The listener function to add
+   */
+  addListener(eventType, listener) {
+    if (!this.eventListeners.has(eventType)) {
+      this.eventListeners.set(eventType, /* @__PURE__ */ new Set());
+    }
+    this.eventListeners.get(eventType)?.add(listener);
+  }
+  /**
+   * @internal
+   * Removes a listener from the event listeners map.
+   * @param eventType - The type of event to remove the listener from
+   * @param listener - The listener function to remove
+   */
+  removeListener(eventType, listener) {
+    const listeners = this.eventListeners.get(eventType);
+    if (listeners) {
+      listeners.delete(listener);
+      if (listeners.size === 0) {
+        this.eventListeners.delete(eventType);
+      }
+    }
+  }
+  /**
+   * @internal
+   * Dispatches a message to listeners of a specific event type.
+   * @param eventType - The event type to dispatch to
+   * @param message - The event message
+   */
+  dispatchToListeners(eventType, message) {
+    const listeners = this.eventListeners.get(eventType);
+    if (listeners) {
+      listeners.forEach((listener) => {
+        listener(message);
+      });
+    }
+  }
+  /**
+   * @internal
+   * Handles incoming WebSocket messages and dispatches them to registered listeners.
+   * @param message - The event message
+   */
+  handleWebSocketMessage(message) {
+    this.dispatchToListeners(message.Type, message);
+    this.dispatchToListeners("*", message);
+  }
+  /**
+   * Disconnects from the real-time event stream.
+   * @example
+   * ```typescript
+   * mailpit.disconnect();
+   * ```
+   */
+  disconnect() {
+    if (this.webSocket) {
+      const ws = this.webSocket;
+      this.webSocket = null;
+      ws.close(1e3, "Client disconnect");
+    }
+  }
+  /**
+   * Registers a listener for real-time events of a specific type.
+   * @remarks
+   * Automatically connects to the event stream if not already connected.
+   * @param eventType - The type of event to listen for.
+   * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+   * Use "*" to listen for all event types (Useful if processing all events uniformly (e.g., logging, debugging, metrics)).
+   * @param listener - The callback function to invoke when an event is received
+   * @returns A function to unregister the listener
+   * @example Listen for event type "new" messages (recommended)
+   * ```typescript
+   * const unsubscribe = mailpit.onEvent("new", (event) => {
+   *   // event.Data is typed as MailpitMessageSummary with full type safety
+   *   console.log("New message:", event.Data.Subject);
+   * });
+   *
+   * // Other code...
+   *
+   * // Unsubscribe listener when no longer needed
+   * unsubscribe();
+   * ```
+   * @example Listen for all events uniformly (for logging/debugging)
+   * ```typescript
+   * const unsubscribe = mailpit.onEvent("*", (event) => {
+   *   // Generic processing for all event types
+   *   console.log(`Event ${event.Type} received`);
+   * });
+   *
+   * // Other code...
+   *
+   * // Unsubscribe listener when no longer needed
+   * unsubscribe();
+   * ```
+   */
+  onEvent(eventType, listener) {
+    if (!this.webSocket || this.webSocket.readyState === ReconnectingWebSocket.CLOSED) {
+      this.connectWebSocket();
+    }
+    this.addListener(eventType, listener);
+    return () => {
+      this.removeListener(eventType, listener);
+    };
+  }
+  /**
+   * Waits for the next event of a specific type.
+   * @remarks
+   * Automatically connects to the event stream if not already connected.
+   * Primarily intended for testing scenarios where you need to wait for a single specific event.
+   * The promise will reject if the timeout is reached before an event is received.
+   * @param eventType - The type of event to wait for.
+   * Specific event types include: "new" (new messages), "stats", "update", "delete", "prune", "truncate", and "error".
+   * @param timeout - Timeout in milliseconds (default: 5000ms). Pass `Infinity` to disable timeout.
+   * @returns A promise that resolves with the event when received, or rejects on timeout
+   * @example Basic usage
+   * ```typescript
+   * // Create the promise before triggering the event
+   * const eventPromise = mailpit.waitForEvent("new");
+   *
+   * // Do something that triggers an email to send
+   * await mailpit.sendMessage({
+   *   From: { Email: "test@example.com" },
+   *   To: [{ Email: "recipient@example.com" }],
+   *   Subject: "Test",
+   * });
+   *
+   * // Wait for the event confirming the message was received
+   * const event = await eventPromise;
+   * // event.Data is fully typed as MailpitMessageSummary
+   * console.log("Message received:", event.Data.Subject);
+   * ```
+   */
+  waitForEvent(eventType, timeout = 5e3) {
+    if (!this.webSocket || this.webSocket.readyState === ReconnectingWebSocket.CLOSED) {
+      this.connectWebSocket();
+    }
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      const cleanup = () => {
+        if (timer) {
+          clearTimeout(timer);
+        }
+        this.removeListener(eventType, listener);
+      };
+      const listener = (event) => {
+        cleanup();
+        resolve(event);
+      };
+      this.addListener(eventType, listener);
+      if (isFinite(timeout)) {
+        timer = setTimeout(() => {
+          cleanup();
+          reject(new Error(`Timeout waiting for event of type "${eventType}"`));
+        }, timeout);
+      }
+    });
+  }
 };
 export {
   MailpitClient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailpit-api",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "A TypeScript client for interacting with Mailpit's REST API.",
   "repository": {
     "type": "git",
@@ -59,23 +59,26 @@
   "author": "Matthew Spahr",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.8.4"
+    "axios": "^1.12.1",
+    "partysocket": "^1.1.10",
+    "ws": "^8.18.3"
   },
   "devDependencies": {
-    "@eslint/js": "^9.30.0",
-    "@jest/globals": "^30.0.3",
-    "@types/node": "^22.15.34",
-    "dotenv": "^16.6.1",
-    "eslint": "^9.30.0",
-    "eslint-plugin-jest": "^29.0.1",
-    "jest": "^30.0.3",
-    "prettier": "^3.6.2",
-    "ts-jest": "^29.4.0",
-    "tsup": "^8.5.0",
-    "tsx": "^4.20.3",
-    "typedoc": "^0.28.7",
-    "typedoc-github-theme": "^0.3.0",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.35.1"
+    "@eslint/js": "^9.39.2",
+    "@jest/globals": "^30.2.0",
+    "@types/node": "^22.19.5",
+    "@types/ws": "^8.18.1",
+    "dotenv": "^17.2.3",
+    "eslint": "^9.39.2",
+    "eslint-plugin-jest": "^29.12.1",
+    "jest": "^30.2.0",
+    "prettier": "^3.7.4",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typedoc": "^0.28.15",
+    "typedoc-github-theme": "^0.3.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.52.0"
   }
 }