mailpit-api 1.0.5 → 1.1.0

package/dist/mjs/src/index.js

@@ -0,0 +1,141 @@
+import axios, { isAxiosError, } from "axios";
+export class MailpitClient {
+    axiosInstance;
+    constructor(baseURL, auth) {
+        this.axiosInstance = axios.create({
+            baseURL,
+            auth,
+            validateStatus: function (status) {
+                return status === 200;
+            },
+        });
+    }
+    async handleRequest(request, options = { fullResponse: false }) {
+        try {
+            const response = await request();
+            return options.fullResponse ? response : response.data;
+        }
+        catch (error) {
+            if (isAxiosError(error)) {
+                const url = error.config?.url || "UNKNOWN URL";
+                const method = error.config?.method?.toUpperCase() || "UNKNOWN METHOD";
+                if (error.response) {
+                    // Server responded with a status other than 2xx
+                    throw new Error(`Mailpit API Error: ${error.response.status.toString()} ${error.response.statusText} at ${method} ${url}: ${JSON.stringify(error.response.data)}`);
+                }
+                else if (error.request) {
+                    // Request was made but no response was received
+                    throw new Error(`Mailpit API Error: No response received from server at ${method} ${url}`);
+                }
+                else {
+                    // Something happened in setting up the request
+                    throw new Error(`Mailpit API Error: ${error.toString()} at ${method} ${url}`);
+                }
+            }
+            else {
+                throw new Error(`Unexpected Error: ${error}`);
+            }
+        }
+    }
+    // Application
+    async getInfo() {
+        return await this.handleRequest(() => this.axiosInstance.get("/api/v1/info"));
+    }
+    async getConfiguration() {
+        return await this.handleRequest(() => this.axiosInstance.get("/api/v1/webui"));
+    }
+    // Message
+    async getMessageSummary(id = "latest") {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}`));
+    }
+    async getMessageHeaders(id = "latest") {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/headers`));
+    }
+    async getMessageAttachment(id, partID) {
+        const response = await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/part/${partID}`, { responseType: "arraybuffer" }), { fullResponse: true });
+        return {
+            data: response.data,
+            contentType: response.headers["content-type"],
+        };
+    }
+    async getMessageSource(id = "latest") {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/raw`));
+    }
+    async getAttachmentThumbnail(id, partID) {
+        const response = await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/part/${partID}/thumb`, {
+            responseType: "arraybuffer",
+        }), { fullResponse: true });
+        return {
+            data: response.data,
+            contentType: response.headers["content-type"],
+        };
+    }
+    async releaseMessage(id, releaseRequest) {
+        return await this.handleRequest(() => this.axiosInstance.post(`/api/v1/message/${id}/release`, releaseRequest));
+    }
+    async sendMessage(sendReqest) {
+        return await this.handleRequest(() => this.axiosInstance.post(`/api/v1/send`, sendReqest));
+    }
+    // Other
+    async htmlCheck(id = "latest") {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/html-check`));
+    }
+    async linkCheck(id = "latest", follow = "false") {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/link-check`, { params: { follow } }));
+    }
+    async spamAssassinCheck(id = "latest") {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/message/${id}/sa-check`));
+    }
+    // Messages
+    async listMessages(start = 0, limit = 50) {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/messages`, { params: { start, limit } }));
+    }
+    async setReadStatus(readStatus) {
+        return await this.handleRequest(() => this.axiosInstance.put(`/api/v1/messages`, readStatus));
+    }
+    async deleteMessages(deleteRequest) {
+        return await this.handleRequest(() => this.axiosInstance.delete(`/api/v1/messages`, {
+            data: deleteRequest,
+        }));
+    }
+    // See https://mailpit.axllent.org/docs/usage/search-filters/
+    async searchMessages(search) {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/search`, {
+            params: search,
+        }));
+    }
+    // See https://mailpit.axllent.org/docs/usage/search-filters/
+    async deleteMessagesBySearch(search) {
+        return await this.handleRequest(() => this.axiosInstance.delete(`/api/v1/search`, { params: search }));
+    }
+    // Tags
+    async getTags() {
+        return await this.handleRequest(() => this.axiosInstance.get(`/api/v1/tags`));
+    }
+    async setTags(request) {
+        return await this.handleRequest(() => this.axiosInstance.put(`/api/v1/tags`, request));
+    }
+    async renameTag(tag, newTagName) {
+        const encodedTag = encodeURI(tag);
+        return await this.handleRequest(() => this.axiosInstance.put(`/api/v1/tags/${encodedTag}`, {
+            Name: newTagName,
+        }));
+    }
+    async deleteTag(tag) {
+        const encodedTag = encodeURI(tag);
+        return await this.handleRequest(() => this.axiosInstance.delete(`/api/v1/tags/${encodedTag}`));
+    }
+    // Testing
+    async renderMessageHTML(id = "latest", embed) {
+        return await this.handleRequest(() => this.axiosInstance.get(`/view/${id}.html`, { params: { embed } }));
+    }
+    async renderMessageText(id = "latest") {
+        return await this.handleRequest(() => this.axiosInstance.get(`/view/${id}.txt`));
+    }
+    async getChaosTriggers() {
+        return await this.handleRequest(() => this.axiosInstance.get("/api/v1/chaos"));
+    }
+    async setChaosTriggers(triggers = {}) {
+        return await this.handleRequest(() => this.axiosInstance.put("/api/v1/chaos", triggers));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailpit-api",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "A NodeJS client library, written in TypeScript, to interact with the Mailpit API.",
   "repository": {
     "type": "git",
@@ -17,7 +17,8 @@
   "scripts": {
     "test": "echo \"TODO: Add tests\" && exit 0",
     "build": "rm -fr dist/* && tsc -p tsconfig.json && tsc -p tsconfig-cjs.json && ./fixup_type",
-    "pretty": "npx prettier . --write"
+    "pretty": "npx prettier . --write",
+    "lint": "npx eslint . --fix"
   },
   "keywords": [
     "mailpit-api",
@@ -33,19 +34,17 @@
   "author": "Matthew Spahr",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.7.8"
+    "axios": "^1.7.9"
   },
   "devDependencies": {
-    "@eslint/js": "^8.57.0",
+    "@eslint/js": "^8.57.1",
+    "@types/eslint__js": "^8.42.3",
     "@types/node": "^20.14.15",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.0",
-    "globals": "^15.13.0",
+    "eslint": "^9.20.1",
     "jest": "^29.7.0",
     "prettier": "3.4.2",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "typescript-eslint": "^7.18.0"
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.0"
   }
 }

package/src/index.ts

@@ -1,5 +1,34 @@
-import axios, { AxiosInstance } from "axios";
+import axios, {
+  type AxiosInstance,
+  type AxiosResponse,
+  isAxiosError,
+} from "axios";
+
+// Common types
+interface Address {
+  Address: string;
+  Name: string;
+}
+
+interface Email {
+  Email: string;
+  Name: string;
+}
 
+interface Attachment {
+  ContentID: string;
+  ContentType: string;
+  FileName: string;
+  PartID: string;
+  Size: number;
+}
+
+interface ChaosTrigger {
+  ErrorCode: number;
+  Probability: number;
+}
+
+// Responses and Requests
 export interface MailpitInfoResponse {
   Database: string;
   DatabaseSize: number;
@@ -34,49 +63,22 @@ export interface MailpitConfigurationResponse {
 }
 
 export interface MailpitMessageSummaryResponse {
-  Attachments: {
-    ContentID: string;
-    ContentType: string;
-    FileName: string;
-    PartID: string;
-    Size: number;
-  }[];
-  Bcc: {
-    Address: string;
-    Name: string;
-  }[];
-  Cc: {
-    Address: string;
-    Name: string;
-  }[];
+  Attachments: Attachment[];
+  Bcc: Address[];
+  Cc: Address[];
   Date: string;
-  From: {
-    Address: string;
-    Name: string;
-  };
+  From: Address;
   HTML: string;
   ID: string;
-  Inline: {
-    ContentID: string;
-    ContentType: string;
-    FileName: string;
-    PartID: string;
-    Size: number;
-  }[];
+  Inline: Attachment[];
   MessageID: string;
-  ReplyTo: {
-    Address: string;
-    Name: string;
-  }[];
+  ReplyTo: Address[];
   ReturnPath: string;
   Size: number;
   Subject: string;
   Tags: string[];
   Text: string;
-  To: {
-    Address: string;
-    Name: string;
-  }[];
+  To: Address[];
 }
 
 export interface MailpitMessagesSummaryResponse {
@@ -89,26 +91,11 @@ export interface MailpitMessagesSummaryResponse {
     ID: string;
     MessageID: string;
     Read: boolean;
-    Bcc: {
-      Address: string;
-      Name: string;
-    }[];
-    Cc: {
-      Address: string;
-      Name: string;
-    }[];
-    From: {
-      Address: string;
-      Name: string;
-    };
-    ReplyTo: {
-      Address: string;
-      Name: string;
-    }[];
-    To: {
-      Address: string;
-      Name: string;
-    }[];
+    Bcc: Address[];
+    Cc: Address[];
+    From: Address;
+    ReplyTo: Address[];
+    To: Address[];
   }[];
   messages_count: number;
   start: number;
@@ -127,29 +114,17 @@ export interface MailpitSendRequest {
     Filename: string;
   }[];
   Bcc: string[];
-  Cc: {
-    Email: string;
-    Name: string;
-  }[];
-  From: {
-    Email: string;
-    Name: string;
-  };
+  Cc: Email[];
+  From: Email;
   HTML: string;
   Headers: {
     [key: string]: string;
   };
-  ReplyTo: {
-    Email: string;
-    Name: string;
-  }[];
+  ReplyTo: Email[];
   Subject: string;
   Tags: string[];
   Text: string;
-  To: {
-    Email: string;
-    Name: string;
-  }[];
+  To: Email[];
 }
 
 export interface MailpitSendMessageConfirmationResponse {
@@ -241,12 +216,30 @@ export interface MailpitSetTagsRequest {
   Tags: string[];
 }
 
+export interface ChaosTriggersRequest {
+  Authentication?: ChaosTrigger;
+  Recipient?: ChaosTrigger;
+  Sender?: ChaosTrigger;
+}
+
+export interface ChaosTriggersResponse {
+  Authentication: ChaosTrigger;
+  Recipient?: ChaosTrigger;
+  Sender?: ChaosTrigger;
+}
+
+interface AttachmentResponse {
+  data: ArrayBuffer;
+  contentType: string;
+}
+
 export class MailpitClient {
   private axiosInstance: AxiosInstance;
 
-  constructor(baseURL: string) {
+  constructor(baseURL: string, auth?: { username: string; password: string }) {
     this.axiosInstance = axios.create({
-      baseURL: baseURL,
+      baseURL,
+      auth,
       validateStatus: function (status) {
         return status === 200;
       },
@@ -254,50 +247,64 @@ export class MailpitClient {
   }
 
   private async handleRequest<T>(
-    request: () => Promise<{ data: T }>,
-  ): Promise<T> {
+    request: () => Promise<AxiosResponse<T>>,
+    options: { fullResponse: true },
+  ): Promise<AxiosResponse<T>>;
+  private async handleRequest<T>(
+    request: () => Promise<AxiosResponse<T>>,
+    options?: { fullResponse?: false },
+  ): Promise<T>;
+  private async handleRequest<T>(
+    request: () => Promise<AxiosResponse<T>>,
+    options: { fullResponse?: boolean } = { fullResponse: false },
+  ): Promise<T | AxiosResponse<T>> {
     try {
       const response = await request();
-      return response.data;
-    } catch (error) {
-      if (axios.isAxiosError(error)) {
+      return options.fullResponse ? response : response.data;
+    } catch (error: unknown) {
+      if (isAxiosError(error)) {
+        const url = error.config?.url || "UNKNOWN URL";
+        const method = error.config?.method?.toUpperCase() || "UNKNOWN METHOD";
         if (error.response) {
           // Server responded with a status other than 2xx
           throw new Error(
-            `Mailpit API Error: ${error.response.status} ${error.response.statusText}: ${JSON.stringify(error.response.data)}`,
+            `Mailpit API Error: ${error.response.status.toString()} ${error.response.statusText} at ${method} ${url}: ${JSON.stringify(error.response.data)}`,
           );
         } else if (error.request) {
           // Request was made but no response was received
           throw new Error(
-            "Mailpit API Error: No response received from server.",
+            `Mailpit API Error: No response received from server at ${method} ${url}`,
           );
         } else {
           // Something happened in setting up the request
-          throw new Error(`Mailpit API Error: ${error.message}`);
+          throw new Error(
+            `Mailpit API Error: ${(error as Error).toString()} at ${method} ${url}`,
+          );
         }
       } else {
-        throw new Error("Unexpected Error: " + error);
+        throw new Error(`Unexpected Error: ${error as Error}`);
       }
     }
   }
 
-  // Message
+  // Application
   public async getInfo(): Promise<MailpitInfoResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitInfoResponse>("/api/v1/info"),
     );
   }
 
   public async getConfiguration(): Promise<MailpitConfigurationResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitConfigurationResponse>("/api/v1/webui"),
     );
   }
 
+  // Message
   public async getMessageSummary(
     id: string = "latest",
   ): Promise<MailpitMessageSummaryResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitMessageSummaryResponse>(
         `/api/v1/message/${id}`,
       ),
@@ -307,7 +314,7 @@ export class MailpitClient {
   public async getMessageHeaders(
     id: string = "latest",
   ): Promise<MailpitMessageHeadersResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitMessageHeadersResponse>(
         `/api/v1/message/${id}/headers`,
       ),
@@ -317,14 +324,23 @@ export class MailpitClient {
   public async getMessageAttachment(
     id: string,
     partID: string,
-  ): Promise<string> {
-    return this.handleRequest(() =>
-      this.axiosInstance.get<string>(`/api/v1/message/${id}/part/${partID}`),
+  ): Promise<AttachmentResponse> {
+    const response = await this.handleRequest(
+      () =>
+        this.axiosInstance.get<ArrayBuffer>(
+          `/api/v1/message/${id}/part/${partID}`,
+          { responseType: "arraybuffer" },
+        ),
+      { fullResponse: true },
     );
+    return {
+      data: response.data,
+      contentType: response.headers["content-type"] as string,
+    };
   }
 
   public async getMessageSource(id: string = "latest"): Promise<string> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<string>(`/api/v1/message/${id}/raw`),
     );
   }
@@ -332,19 +348,28 @@ export class MailpitClient {
   public async getAttachmentThumbnail(
     id: string,
     partID: string,
-  ): Promise<string> {
-    return this.handleRequest(() =>
-      this.axiosInstance.get<string>(
-        `/api/v1/message/${id}/part/${partID}/thumb`,
-      ),
+  ): Promise<AttachmentResponse> {
+    const response = await this.handleRequest(
+      () =>
+        this.axiosInstance.get<ArrayBuffer>(
+          `/api/v1/message/${id}/part/${partID}/thumb`,
+          {
+            responseType: "arraybuffer",
+          },
+        ),
+      { fullResponse: true },
     );
+    return {
+      data: response.data,
+      contentType: response.headers["content-type"] as string,
+    };
   }
 
   public async releaseMessage(
     id: string,
     releaseRequest: { To: string[] },
   ): Promise<string> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.post<string>(
         `/api/v1/message/${id}/release`,
         releaseRequest,
@@ -355,7 +380,7 @@ export class MailpitClient {
   public async sendMessage(
     sendReqest: MailpitSendRequest,
   ): Promise<MailpitSendMessageConfirmationResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.post<MailpitSendMessageConfirmationResponse>(
         `/api/v1/send`,
         sendReqest,
@@ -367,7 +392,7 @@ export class MailpitClient {
   public async htmlCheck(
     id: string = "latest",
   ): Promise<MailpitHTMLCheckResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitHTMLCheckResponse>(
         `/api/v1/message/${id}/html-check`,
       ),
@@ -378,7 +403,7 @@ export class MailpitClient {
     id: string = "latest",
     follow: "true" | "false" = "false",
   ): Promise<MailpitLinkCheckResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitLinkCheckResponse>(
         `/api/v1/message/${id}/link-check`,
         { params: { follow } },
@@ -389,7 +414,7 @@ export class MailpitClient {
   public async spamAssassinCheck(
     id: string = "latest",
   ): Promise<MailpitSpamAssassinResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitSpamAssassinResponse>(
         `/api/v1/message/${id}/sa-check`,
       ),
@@ -401,7 +426,7 @@ export class MailpitClient {
     start: number = 0,
     limit: number = 50,
   ): Promise<MailpitMessagesSummaryResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitMessagesSummaryResponse>(
         `/api/v1/messages`,
         { params: { start, limit } },
@@ -412,7 +437,7 @@ export class MailpitClient {
   public async setReadStatus(
     readStatus: MailpitReadStatusRequest,
   ): Promise<string> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.put<string>(`/api/v1/messages`, readStatus),
     );
   }
@@ -420,7 +445,7 @@ export class MailpitClient {
   public async deleteMessages(
     deleteRequest?: MailpitDeleteRequest,
   ): Promise<string> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.delete<string>(`/api/v1/messages`, {
         data: deleteRequest,
       }),
@@ -431,7 +456,7 @@ export class MailpitClient {
   public async searchMessages(
     search: MailpitSearchRequest,
   ): Promise<MailpitMessagesSummaryResponse> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<MailpitMessagesSummaryResponse>(`/api/v1/search`, {
         params: search,
       }),
@@ -442,27 +467,27 @@ export class MailpitClient {
   public async deleteMessagesBySearch(
     search: MailpitSearchDeleteRequest,
   ): Promise<string> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.delete<string>(`/api/v1/search`, { params: search }),
     );
   }
 
   // Tags
   public async getTags(): Promise<string[]> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<string[]>(`/api/v1/tags`),
     );
   }
 
   public async setTags(request: MailpitSetTagsRequest): Promise<string> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.put<string>(`/api/v1/tags`, request),
     );
   }
 
   public async renameTag(tag: string, newTagName: string): Promise<string> {
     const encodedTag = encodeURI(tag);
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.put<string>(`/api/v1/tags/${encodedTag}`, {
         Name: newTagName,
       }),
@@ -471,21 +496,38 @@ export class MailpitClient {
 
   public async deleteTag(tag: string): Promise<string> {
     const encodedTag = encodeURI(tag);
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.delete<string>(`/api/v1/tags/${encodedTag}`),
     );
   }
 
   // Testing
-  public async renderMessageHTML(id: string = "latest"): Promise<string> {
-    return this.handleRequest(() =>
-      this.axiosInstance.get<string>(`/view/${id}.html`),
+  public async renderMessageHTML(
+    id: string = "latest",
+    embed?: 1,
+  ): Promise<string> {
+    return await this.handleRequest(() =>
+      this.axiosInstance.get<string>(`/view/${id}.html`, { params: { embed } }),
     );
   }
 
   public async renderMessageText(id: string = "latest"): Promise<string> {
-    return this.handleRequest(() =>
+    return await this.handleRequest(() =>
       this.axiosInstance.get<string>(`/view/${id}.txt`),
     );
   }
+
+  public async getChaosTriggers(): Promise<ChaosTriggersResponse> {
+    return await this.handleRequest(() =>
+      this.axiosInstance.get<ChaosTriggersResponse>("/api/v1/chaos"),
+    );
+  }
+
+  public async setChaosTriggers(
+    triggers: ChaosTriggersRequest = {},
+  ): Promise<ChaosTriggersResponse> {
+    return await this.handleRequest(() =>
+      this.axiosInstance.put<ChaosTriggersResponse>("/api/v1/chaos", triggers),
+    );
+  }
 }

package/tsconfig-base.json

@@ -13,13 +13,13 @@
     "noFallthroughCasesInSwitch": true,
     "pretty": true,
     "resolveJsonModule": true,
-    "rootDir": "src",
+    "rootDir": ".",
     "skipLibCheck": true,
     "strict": true,
     "traceResolution": false,
     "types": ["node", "jest"]
   },
   "compileOnSave": false,
-  "exclude": ["node_modules", "dist"],
-  "include": ["src"]
+  "include": ["src", "eslint.config.mjs", "test"],
+  "exclude": ["node_modules", "dist"]
 }