mailisk 1.0.0

package/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "printWidth": 120
+}

package/LICENSE.md

@@ -0,0 +1,21 @@
+## MIT License
+
+Copyright (c) 2022 Mailisk https://mailisk.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Mailisk Node Client
+
+Mailisk is an end-to-end email testing platform. It allows you to receive emails with code and automate email tests.
+
+- Get a unique subdomain and unlimited email addresses for free.
+- Easily automate E2E password reset and account verification by catching emails.
+- Virtual SMTP support to test outbound email without 3rd party clients.
+
+## Get started
+
+For a more step-by-step walkthrough see the [NodeJS Guide](https://docs.mailisk.com/guides/nodejs.html).
+
+### Installation
+
+#### Install with npm
+
+```shell
+npm install --save-dev mailisk
+```
+
+#### Install with Yarn
+
+```shell
+yarn add mailisk --dev
+```
+
+### Usage
+
+After installing the library import it and set the [API Key](https://docs.mailisk.com/#getting-your-api-key)
+
+```js
+const { MailiskClient } = require("mailisk");
+
+// create client
+const mailisk = new MailiskClient({ apiKey: "YOUR_API_KEY" });
+
+// send email (using virtual SMTP)
+await client.sendVirtualEmail(namespace, {
+  from: "test@example.com",
+  to: `john@${namespace}.mailisk.net`,
+  subject: "Testing",
+  text: "This is a test.",
+});
+
+// receive email
+const result = await client.searchInbox(namespace);
+
+console.log(result);
+```
+
+### API Reference
+
+This library wraps the REST API endpoints. Find out more in the [API Reference](https://docs.mailisk.com/api-reference/).
+
+## Client functions
+
+### searchInbox(namespace, params?)
+
+The `searchInbox` function takes a namespace and call parameters.
+
+- It uses the `wait` property by default. This means the call won't timeout until a result is returned or 5 minutes pass. This is adjustable by passing the `timeout` paramter (it can also be disabled by passing `wait: false`).
+- It uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored. This can be overriden by passing the `from_timestamp` parameter (`from_timestmap: 0` will disable filtering by email age).
+
+#### Filter by destination address
+
+A common use case is filtering the returned emails by the destination address, this is done using the `to_addr_prefix` parameter.
+
+```js
+const { data: emails } = await mailisk.searchInbox(namespace, {
+  to_addr_prefix: "john@mynamespace.mailisk.net",
+});
+```
+
+For more parameter options see the [endpoint reference](https://docs.mailisk.com/api-reference/search-inbox.html#request-1).
+
+### sendVirtualEmail(namespace, params)
+
+Send an email using [Virtual SMTP](https://docs.mailisk.com/smtp.html). This will fetch the SMTP settings for the selected namespace and send an email. These emails can only be sent to an address that ends in `@{namespace}.mailisk.net`.
+
+```js
+const namespace = "mynamespace";
+
+await mailisk.sendVirtualEmail(namespace, {
+  from: "test@example.com",
+  to: `john@${namespace}.mailisk.net`,
+  subject: "This is a test",
+  text: "Testing",
+});
+```
+
+This does not call an API endpoint but rather uses nodemailer to send an email using SMTP.
+
+### listNamespaces()
+
+List all namespaces associated with the current API Key.
+
+```js
+const namespacesResponse = await mailisk.listNamespaces();
+
+// will be ['namespace1', 'namespace2']
+const namespaces = namespacesResponse.map((nr) => nr.namespace);
+```

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { AxiosRequestConfig } from 'axios';
+
+interface EmailAddress {
+    /** Email address */
+    address: string;
+    /** Display name, if one is specified */
+    name?: string;
+}
+interface Email {
+    /** Namespace scoped ID */
+    id: string;
+    /** Sender of email */
+    from: EmailAddress;
+    /** Recepients of email */
+    to: EmailAddress[];
+    /** Carbon-copied recipients for email message */
+    cc?: EmailAddress[];
+    /** Blind carbon-copied recipients for email message */
+    bcc?: EmailAddress[];
+    /** Subject of email */
+    subject?: string;
+    /** Email content that was sent in HTML format */
+    html?: string;
+    /** Email content that was sent in plain text format */
+    text?: string;
+    /** The datetime that this email was received */
+    received_date: Date;
+    /** The unix timestamp (s) that this email was received */
+    received_timestamp: number;
+    /** The unix timestamp (s) when this email will be deleted */
+    expires_timestamp: number;
+    /** The spam score as reported by SpamAssassin */
+    spam_score?: number;
+}
+interface SearchInboxParams {
+    /**
+     * The maximum number of emails that can be returned in this request, used alongside `offset` for pagination.
+     */
+    limit?: number;
+    /**
+     * The number of emails to skip/ignore, used alongside `limit` for pagination.
+     */
+    offset?: number;
+    /**
+     * Filter emails by starting unix timestamp in seconds.
+     */
+    from_timestamp?: number;
+    /**
+     * Filter emails by ending unix timestamp in seconds.
+     */
+    to_timestamp?: number;
+    /**
+     * Filter emails by 'to' address. Address must start with this.
+     *
+     * 'foo' would return 'foobar@namespace.mailisk.net' but not 'barfoo@namespace.mailisk.net'
+     */
+    to_addr_prefix?: string;
+    /**
+     * Will keep the request going till at least one email would be returned.
+     *
+     * Default is `true`
+     */
+    wait?: boolean;
+}
+interface SearchInboxResponse {
+    /**
+     * Total number of emails matching query.
+     */
+    total_count: number;
+    /**
+     * Parameters that were used for the query
+     */
+    options: SearchInboxParams;
+    /**
+     * Emails
+     */
+    data: Email[];
+}
+interface SmtpSettings {
+    data: {
+        host: string;
+        port: number;
+        username: string;
+        password: string;
+    };
+}
+interface ListNamespacesResponse {
+    data: [
+        {
+            id: string;
+            namespace: string;
+        }
+    ];
+}
+interface SendVirtualEmailParams {
+    /** Sender of email */
+    from: string;
+    /**
+     * Recepients of email
+     *
+     * Must match namespace. E.g. if using namespace 'mynamespace' `to` must be 'something@mynamespace.mailisk.net'.
+     */
+    to: string;
+    /** The subject of the e-mail */
+    subject: string;
+    /** The plaintext version of the message */
+    text?: string | undefined;
+    /** The HTML version of the message */
+    html?: string | undefined;
+}
+
+declare class MailiskClient {
+    constructor({ apiKey, baseUrl }: {
+        apiKey: string;
+        baseUrl?: string;
+    });
+    private readonly axiosInstance;
+    /**
+     * List all namespaces that belong to the current account (API key).
+     */
+    listNamespaces(): Promise<ListNamespacesResponse>;
+    /**
+     * Send an email using the Virtual SMTP.
+     *
+     * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net
+     *
+     * @example
+     * For example, sending a test email:
+     * ```typescript
+     * client.sendVirtualEmail(namespace, {
+     *   from: "test@example.com",
+     *   to: `john@${namespace}.mailisk.net`,
+     *   subject: "This is a test",
+     *   text: "Testing",
+     * });
+     * ```
+     */
+    sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void>;
+    /**
+     * Search inbox of a namespace.
+     *
+     * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.
+     * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.
+     *
+     * Both of these settings can be overriden by passing them in the `params` object.
+     *
+     * @example
+     * Get the latest emails in the namespace
+     * ```typescript
+     * const { data: emails } = await client.searchInbox(namespace);
+     * ```
+     *
+     * @example
+     * Get the latest emails for a specific email address
+     * ```typescript
+     * const { data: emails } = await client.searchInbox(namespace, {
+     *  to_addr_prefix: 'john@mynamespace.mailisk.net'
+     * });
+     * ```
+     */
+    searchInbox(namespace: string, params?: SearchInboxParams, config?: AxiosRequestConfig): Promise<SearchInboxResponse>;
+    /**
+     * Get the SMTP settings for a namespace.
+     */
+    getSmtpSettings(namespace: string): Promise<SmtpSettings>;
+}
+
+export { MailiskClient };

package/dist/index.js

@@ -0,0 +1,98 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  MailiskClient: () => MailiskClient
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/mailisk.ts
+var import_axios = __toESM(require("axios"));
+var import_nodemailer = __toESM(require("nodemailer"));
+var MailiskClient = class {
+  constructor({ apiKey, baseUrl }) {
+    this.axiosInstance = import_axios.default.create({
+      headers: {
+        "X-Api-Key": apiKey
+      },
+      baseURL: baseUrl || "https://api.mailisk.com/"
+    });
+  }
+  axiosInstance;
+  async listNamespaces() {
+    return (await this.axiosInstance.get("api/namespaces")).data;
+  }
+  async sendVirtualEmail(namespace, params) {
+    const smtpSettings = await this.getSmtpSettings(namespace);
+    const transport = import_nodemailer.default.createTransport({
+      host: smtpSettings.data.host,
+      port: smtpSettings.data.port,
+      secure: false,
+      auth: {
+        user: smtpSettings.data.username,
+        pass: smtpSettings.data.password
+      }
+    });
+    const { from, to, subject, text, html } = params;
+    await transport.sendMail({
+      from,
+      to,
+      subject,
+      text,
+      html
+    });
+    transport.close();
+  }
+  async searchInbox(namespace, params, config) {
+    let _params = { ...params };
+    if (!params?.from_timestamp) {
+      _params.from_timestamp = Math.floor(new Date().getTime() / 1e3) - 5;
+    }
+    if (params?.wait !== false) {
+      _params.wait = true;
+    }
+    let _config = { ...config };
+    if (_params.wait && !config?.timeout) {
+      _config.timeout = 1e3 * 60 * 5;
+    }
+    return (await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {
+      ...config,
+      params: _params
+    })).data;
+  }
+  async getSmtpSettings(namespace) {
+    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);
+    return result.data;
+  }
+};
+__name(MailiskClient, "MailiskClient");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MailiskClient
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/mailisk.ts"],"sourcesContent":["export * from \"./mailisk\";\n","import axios, { AxiosRequestConfig } from \"axios\";\nimport {\n  ListNamespacesResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SendVirtualEmailParams,\n  SmtpSettings,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl }: { apiKey: string; baseUrl?: string }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n    });\n  }\n\n  private readonly axiosInstance;\n\n  /**\n   * List all namespaces that belong to the current account (API key).\n   */\n  async listNamespaces(): Promise<ListNamespacesResponse> {\n    return (await this.axiosInstance.get(\"api/namespaces\")).data;\n  }\n\n  /**\n   * Send an email using the Virtual SMTP.\n   *\n   * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net\n   *\n   * @example\n   * For example, sending a test email:\n   * ```typescript\n   * client.sendVirtualEmail(namespace, {\n   *   from: \"test@example.com\",\n   *   to: `john@${namespace}.mailisk.net`,\n   *   subject: \"This is a test\",\n   *   text: \"Testing\",\n   * });\n   * ```\n   */\n  async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {\n    const smtpSettings = await this.getSmtpSettings(namespace);\n\n    // TODO: to should match namespace\n\n    const transport = nodemailer.createTransport({\n      host: smtpSettings.data.host,\n      port: smtpSettings.data.port,\n      secure: false,\n      auth: {\n        user: smtpSettings.data.username,\n        pass: smtpSettings.data.password,\n      },\n    });\n\n    const { from, to, subject, text, html } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n    });\n\n    transport.close();\n  }\n\n  /**\n   * Search inbox of a namespace.\n   *\n   * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.\n   * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.\n   *\n   * Both of these settings can be overriden by passing them in the `params` object.\n   *\n   * @example\n   * Get the latest emails in the namespace\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace);\n   * ```\n   *\n   * @example\n   * Get the latest emails for a specific email address\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace, {\n   *  to_addr_prefix: 'john@mynamespace.mailisk.net'\n   * });\n   * ```\n   */\n  async searchInbox(\n    namespace: string,\n    params?: SearchInboxParams,\n    config?: AxiosRequestConfig\n  ): Promise<SearchInboxResponse> {\n    let _params = { ...params };\n\n    // default from timestamp, 5 seconds before starting this request\n    if (!params?.from_timestamp) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 5;\n    }\n\n    // by default wait for email\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && !config?.timeout) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    return (\n      await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {\n        ...config,\n        params: _params,\n      })\n    ).data;\n  }\n\n  /**\n   * Get the SMTP settings for a namespace.\n   */\n  async getSmtpSettings(namespace: string): Promise<SmtpSettings> {\n    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);\n    return result.data;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAA0C;AAQ1C,wBAAuB;AAEhB,IAAM,gBAAN,MAAoB;AAAA,EACzB,YAAY,EAAE,QAAQ,QAAQ,GAAyC;AACrE,SAAK,gBAAgB,aAAAA,QAAM,OAAO;AAAA,MAChC,SAAS;AAAA,QACP,aAAa;AAAA,MACf;AAAA,MACA,SAAS,WAAW;AAAA,IACtB,CAAC;AAAA,EACH;AAAA,EAEiB;AAAA,EAKjB,MAAM,iBAAkD;AACtD,YAAQ,MAAM,KAAK,cAAc,IAAI,gBAAgB,GAAG;AAAA,EAC1D;AAAA,EAkBA,MAAM,iBAAiB,WAAmB,QAA+C;AACvF,UAAM,eAAe,MAAM,KAAK,gBAAgB,SAAS;AAIzD,UAAM,YAAY,kBAAAC,QAAW,gBAAgB;AAAA,MAC3C,MAAM,aAAa,KAAK;AAAA,MACxB,MAAM,aAAa,KAAK;AAAA,MACxB,QAAQ;AAAA,MACR,MAAM;AAAA,QACJ,MAAM,aAAa,KAAK;AAAA,QACxB,MAAM,aAAa,KAAK;AAAA,MAC1B;AAAA,IACF,CAAC;AAED,UAAM,EAAE,MAAM,IAAI,SAAS,MAAM,KAAK,IAAI;AAE1C,UAAM,UAAU,SAAS;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,cAAU,MAAM;AAAA,EAClB;AAAA,EAwBA,MAAM,YACJ,WACA,QACA,QAC8B;AAC9B,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,CAAC,QAAQ,gBAAgB;AAC3B,cAAQ,iBAAiB,KAAK,MAAM,IAAI,KAAK,EAAE,QAAQ,IAAI,GAAI,IAAI;AAAA,IACrE;AAGA,QAAI,QAAQ,SAAS,OAAO;AAC1B,cAAQ,OAAO;AAAA,IACjB;AAEA,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,QAAQ,CAAC,QAAQ,SAAS;AACpC,cAAQ,UAAU,MAAO,KAAK;AAAA,IAChC;AAEA,YACE,MAAM,KAAK,cAAc,IAAI,cAAc,mBAAmB;AAAA,MAC5D,GAAG;AAAA,MACH,QAAQ;AAAA,IACV,CAAC,GACD;AAAA,EACJ;AAAA,EAKA,MAAM,gBAAgB,WAA0C;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,YAAY,WAAW;AACnE,WAAO,OAAO;AAAA,EAChB;AACF;AA5Ha;","names":["axios","nodemailer"]}

package/dist/index.mjs

@@ -0,0 +1,67 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/mailisk.ts
+import axios from "axios";
+import nodemailer from "nodemailer";
+var MailiskClient = class {
+  constructor({ apiKey, baseUrl }) {
+    this.axiosInstance = axios.create({
+      headers: {
+        "X-Api-Key": apiKey
+      },
+      baseURL: baseUrl || "https://api.mailisk.com/"
+    });
+  }
+  axiosInstance;
+  async listNamespaces() {
+    return (await this.axiosInstance.get("api/namespaces")).data;
+  }
+  async sendVirtualEmail(namespace, params) {
+    const smtpSettings = await this.getSmtpSettings(namespace);
+    const transport = nodemailer.createTransport({
+      host: smtpSettings.data.host,
+      port: smtpSettings.data.port,
+      secure: false,
+      auth: {
+        user: smtpSettings.data.username,
+        pass: smtpSettings.data.password
+      }
+    });
+    const { from, to, subject, text, html } = params;
+    await transport.sendMail({
+      from,
+      to,
+      subject,
+      text,
+      html
+    });
+    transport.close();
+  }
+  async searchInbox(namespace, params, config) {
+    let _params = { ...params };
+    if (!params?.from_timestamp) {
+      _params.from_timestamp = Math.floor(new Date().getTime() / 1e3) - 5;
+    }
+    if (params?.wait !== false) {
+      _params.wait = true;
+    }
+    let _config = { ...config };
+    if (_params.wait && !config?.timeout) {
+      _config.timeout = 1e3 * 60 * 5;
+    }
+    return (await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {
+      ...config,
+      params: _params
+    })).data;
+  }
+  async getSmtpSettings(namespace) {
+    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);
+    return result.data;
+  }
+};
+__name(MailiskClient, "MailiskClient");
+export {
+  MailiskClient
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mailisk.ts"],"sourcesContent":["import axios, { AxiosRequestConfig } from \"axios\";\nimport {\n  ListNamespacesResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SendVirtualEmailParams,\n  SmtpSettings,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl }: { apiKey: string; baseUrl?: string }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n    });\n  }\n\n  private readonly axiosInstance;\n\n  /**\n   * List all namespaces that belong to the current account (API key).\n   */\n  async listNamespaces(): Promise<ListNamespacesResponse> {\n    return (await this.axiosInstance.get(\"api/namespaces\")).data;\n  }\n\n  /**\n   * Send an email using the Virtual SMTP.\n   *\n   * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net\n   *\n   * @example\n   * For example, sending a test email:\n   * ```typescript\n   * client.sendVirtualEmail(namespace, {\n   *   from: \"test@example.com\",\n   *   to: `john@${namespace}.mailisk.net`,\n   *   subject: \"This is a test\",\n   *   text: \"Testing\",\n   * });\n   * ```\n   */\n  async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {\n    const smtpSettings = await this.getSmtpSettings(namespace);\n\n    // TODO: to should match namespace\n\n    const transport = nodemailer.createTransport({\n      host: smtpSettings.data.host,\n      port: smtpSettings.data.port,\n      secure: false,\n      auth: {\n        user: smtpSettings.data.username,\n        pass: smtpSettings.data.password,\n      },\n    });\n\n    const { from, to, subject, text, html } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n    });\n\n    transport.close();\n  }\n\n  /**\n   * Search inbox of a namespace.\n   *\n   * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.\n   * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.\n   *\n   * Both of these settings can be overriden by passing them in the `params` object.\n   *\n   * @example\n   * Get the latest emails in the namespace\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace);\n   * ```\n   *\n   * @example\n   * Get the latest emails for a specific email address\n   * ```typescript\n   * const { data: emails } = await client.searchInbox(namespace, {\n   *  to_addr_prefix: 'john@mynamespace.mailisk.net'\n   * });\n   * ```\n   */\n  async searchInbox(\n    namespace: string,\n    params?: SearchInboxParams,\n    config?: AxiosRequestConfig\n  ): Promise<SearchInboxResponse> {\n    let _params = { ...params };\n\n    // default from timestamp, 5 seconds before starting this request\n    if (!params?.from_timestamp) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 5;\n    }\n\n    // by default wait for email\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && !config?.timeout) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    return (\n      await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {\n        ...config,\n        params: _params,\n      })\n    ).data;\n  }\n\n  /**\n   * Get the SMTP settings for a namespace.\n   */\n  async getSmtpSettings(namespace: string): Promise<SmtpSettings> {\n    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);\n    return result.data;\n  }\n}\n"],"mappings":";;;;AAAA,OAAO,WAAmC;AAQ1C,OAAO,gBAAgB;AAEhB,IAAM,gBAAN,MAAoB;AAAA,EACzB,YAAY,EAAE,QAAQ,QAAQ,GAAyC;AACrE,SAAK,gBAAgB,MAAM,OAAO;AAAA,MAChC,SAAS;AAAA,QACP,aAAa;AAAA,MACf;AAAA,MACA,SAAS,WAAW;AAAA,IACtB,CAAC;AAAA,EACH;AAAA,EAEiB;AAAA,EAKjB,MAAM,iBAAkD;AACtD,YAAQ,MAAM,KAAK,cAAc,IAAI,gBAAgB,GAAG;AAAA,EAC1D;AAAA,EAkBA,MAAM,iBAAiB,WAAmB,QAA+C;AACvF,UAAM,eAAe,MAAM,KAAK,gBAAgB,SAAS;AAIzD,UAAM,YAAY,WAAW,gBAAgB;AAAA,MAC3C,MAAM,aAAa,KAAK;AAAA,MACxB,MAAM,aAAa,KAAK;AAAA,MACxB,QAAQ;AAAA,MACR,MAAM;AAAA,QACJ,MAAM,aAAa,KAAK;AAAA,QACxB,MAAM,aAAa,KAAK;AAAA,MAC1B;AAAA,IACF,CAAC;AAED,UAAM,EAAE,MAAM,IAAI,SAAS,MAAM,KAAK,IAAI;AAE1C,UAAM,UAAU,SAAS;AAAA,MACvB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAED,cAAU,MAAM;AAAA,EAClB;AAAA,EAwBA,MAAM,YACJ,WACA,QACA,QAC8B;AAC9B,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,CAAC,QAAQ,gBAAgB;AAC3B,cAAQ,iBAAiB,KAAK,MAAM,IAAI,KAAK,EAAE,QAAQ,IAAI,GAAI,IAAI;AAAA,IACrE;AAGA,QAAI,QAAQ,SAAS,OAAO;AAC1B,cAAQ,OAAO;AAAA,IACjB;AAEA,QAAI,UAAU,EAAE,GAAG,OAAO;AAG1B,QAAI,QAAQ,QAAQ,CAAC,QAAQ,SAAS;AACpC,cAAQ,UAAU,MAAO,KAAK;AAAA,IAChC;AAEA,YACE,MAAM,KAAK,cAAc,IAAI,cAAc,mBAAmB;AAAA,MAC5D,GAAG;AAAA,MACH,QAAQ;AAAA,IACV,CAAC,GACD;AAAA,EACJ;AAAA,EAKA,MAAM,gBAAgB,WAA0C;AAC9D,UAAM,SAAS,MAAM,KAAK,cAAc,IAAI,YAAY,WAAW;AACnE,WAAO,OAAO;AAAA,EAChB;AACF;AA5Ha;","names":[]}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "mailisk",
+  "version": "1.0.0",
+  "description": "Mailisk library for NodeJS",
+  "keywords": [
+    "mailisk",
+    "email-automation",
+    "email-testing",
+    "email"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/nodemailer": "^6.4.6",
+    "tsup": "^6.2.3",
+    "typescript": "^4.8.4"
+  },
+  "dependencies": {
+    "axios": "^1.1.2",
+    "nodemailer": "^6.8.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./mailisk";

package/src/mailisk.interfaces.ts

@@ -0,0 +1,114 @@
+export interface EmailAddress {
+  /** Email address */
+  address: string;
+  /** Display name, if one is specified */
+  name?: string;
+}
+
+export interface Email {
+  /** Namespace scoped ID */
+  id: string;
+  /** Sender of email */
+  from: EmailAddress;
+  /** Recepients of email */
+  to: EmailAddress[];
+  /** Carbon-copied recipients for email message */
+  cc?: EmailAddress[];
+  /** Blind carbon-copied recipients for email message */
+  bcc?: EmailAddress[];
+  /** Subject of email */
+  subject?: string;
+  /** Email content that was sent in HTML format */
+  html?: string;
+  /** Email content that was sent in plain text format */
+  text?: string;
+  /** The datetime that this email was received */
+  received_date: Date;
+  /** The unix timestamp (s) that this email was received */
+  received_timestamp: number;
+  /** The unix timestamp (s) when this email will be deleted */
+  expires_timestamp: number;
+  /** The spam score as reported by SpamAssassin */
+  spam_score?: number;
+}
+
+export interface SearchInboxParams {
+  /**
+   * The maximum number of emails that can be returned in this request, used alongside `offset` for pagination.
+   */
+  limit?: number;
+  /**
+   * The number of emails to skip/ignore, used alongside `limit` for pagination.
+   */
+  offset?: number;
+  /**
+   * Filter emails by starting unix timestamp in seconds.
+   */
+  from_timestamp?: number;
+  /**
+   * Filter emails by ending unix timestamp in seconds.
+   */
+  to_timestamp?: number;
+  /**
+   * Filter emails by 'to' address. Address must start with this.
+   *
+   * 'foo' would return 'foobar@namespace.mailisk.net' but not 'barfoo@namespace.mailisk.net'
+   */
+  to_addr_prefix?: string;
+  /**
+   * Will keep the request going till at least one email would be returned.
+   *
+   * Default is `true`
+   */
+  wait?: boolean;
+}
+
+export interface SearchInboxResponse {
+  /**
+   * Total number of emails matching query.
+   */
+  total_count: number;
+  /**
+   * Parameters that were used for the query
+   */
+  options: SearchInboxParams;
+  /**
+   * Emails
+   */
+  data: Email[];
+}
+
+export interface SmtpSettings {
+  data: {
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+  };
+}
+
+export interface ListNamespacesResponse {
+  data: [
+    {
+      id: string;
+      namespace: string;
+    }
+  ];
+}
+
+export interface SendVirtualEmailParams {
+  /** Sender of email */
+  from: string;
+  /**
+   * Recepients of email
+   *
+   * Must match namespace. E.g. if using namespace 'mynamespace' `to` must be 'something@mynamespace.mailisk.net'.
+   */
+  to: string;
+  /** The subject of the e-mail */
+  subject: string;
+  /** The plaintext version of the message */
+  text?: string | undefined;
+  /** The HTML version of the message */
+  html?: string | undefined;
+}

package/src/mailisk.ts

@@ -0,0 +1,135 @@
+import axios, { AxiosRequestConfig } from "axios";
+import {
+  ListNamespacesResponse,
+  SearchInboxParams,
+  SearchInboxResponse,
+  SendVirtualEmailParams,
+  SmtpSettings,
+} from "./mailisk.interfaces";
+import nodemailer from "nodemailer";
+
+export class MailiskClient {
+  constructor({ apiKey, baseUrl }: { apiKey: string; baseUrl?: string }) {
+    this.axiosInstance = axios.create({
+      headers: {
+        "X-Api-Key": apiKey,
+      },
+      baseURL: baseUrl || "https://api.mailisk.com/",
+    });
+  }
+
+  private readonly axiosInstance;
+
+  /**
+   * List all namespaces that belong to the current account (API key).
+   */
+  async listNamespaces(): Promise<ListNamespacesResponse> {
+    return (await this.axiosInstance.get("api/namespaces")).data;
+  }
+
+  /**
+   * Send an email using the Virtual SMTP.
+   *
+   * These emails can only be sent to valid Mailisk namespaces, i.e. emails that end in @mynamespace.mailisk.net
+   *
+   * @example
+   * For example, sending a test email:
+   * ```typescript
+   * client.sendVirtualEmail(namespace, {
+   *   from: "test@example.com",
+   *   to: `john@${namespace}.mailisk.net`,
+   *   subject: "This is a test",
+   *   text: "Testing",
+   * });
+   * ```
+   */
+  async sendVirtualEmail(namespace: string, params: SendVirtualEmailParams): Promise<void> {
+    const smtpSettings = await this.getSmtpSettings(namespace);
+
+    // TODO: to should match namespace
+
+    const transport = nodemailer.createTransport({
+      host: smtpSettings.data.host,
+      port: smtpSettings.data.port,
+      secure: false,
+      auth: {
+        user: smtpSettings.data.username,
+        pass: smtpSettings.data.password,
+      },
+    });
+
+    const { from, to, subject, text, html } = params;
+
+    await transport.sendMail({
+      from,
+      to,
+      subject,
+      text,
+      html,
+    });
+
+    transport.close();
+  }
+
+  /**
+   * Search inbox of a namespace.
+   *
+   * By default, this calls the api using the `wait` flag. This means the call won't timeout until at least one email is received or 5 minutes pass.
+   * It also uses a default `from_timestamp` of **current timestamp - 5 seconds**. This means that older emails will be ignored.
+   *
+   * Both of these settings can be overriden by passing them in the `params` object.
+   *
+   * @example
+   * Get the latest emails in the namespace
+   * ```typescript
+   * const { data: emails } = await client.searchInbox(namespace);
+   * ```
+   *
+   * @example
+   * Get the latest emails for a specific email address
+   * ```typescript
+   * const { data: emails } = await client.searchInbox(namespace, {
+   *  to_addr_prefix: 'john@mynamespace.mailisk.net'
+   * });
+   * ```
+   */
+  async searchInbox(
+    namespace: string,
+    params?: SearchInboxParams,
+    config?: AxiosRequestConfig
+  ): Promise<SearchInboxResponse> {
+    let _params = { ...params };
+
+    // default from timestamp, 5 seconds before starting this request
+    if (!params?.from_timestamp) {
+      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 5;
+    }
+
+    // by default wait for email
+    if (params?.wait !== false) {
+      _params.wait = true;
+    }
+
+    let _config = { ...config };
+
+    // by default, wait 5 minutes for emails before timing out
+    if (_params.wait && !config?.timeout) {
+      _config.timeout = 1000 * 60 * 5;
+    }
+
+    return (
+      await this.axiosInstance.get(`api/emails/${namespace}/inbox`, {
+        ...config,
+        params: _params,
+      })
+    ).data;
+  }
+
+  /**
+   * Get the SMTP settings for a namespace.
+   */
+  async getSmtpSettings(namespace: string): Promise<SmtpSettings> {
+    const result = await this.axiosInstance.get(`api/smtp/${namespace}`);
+    return result.data;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2022" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+    "module": "commonjs" /* Specify what module code is generated. */,
+    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
+    "inlineSourceMap": true /* Include sourcemap files inside the emitted JavaScript. */,
+    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
+    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+    "strict": true /* Enable all strict type-checking options. */,
+    "skipLibCheck": true /* Skip type checking all .d.ts files. */
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsup.config.js

@@ -0,0 +1,19 @@
+module.exports = function defineConfig() {
+  return {
+    entry: ["src/index.ts"],
+    external: [],
+    noExternal: [],
+    platform: "node",
+    format: ["esm", "cjs"],
+    target: "es2022",
+    skipNodeModulesBundle: true,
+    clean: true,
+    shims: true,
+    minify: false,
+    splitting: false,
+    keepNames: true,
+    dts: true,
+    sourcemap: true,
+    esbuildPlugins: [],
+  };
+};