mailisk 2.2.4 → 2.3.0

package/dist/index.mjs

@@ -5,6 +5,9 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 import axios from "axios";
 import nodemailer from "nodemailer";
 var MailiskClient = class {
+  static {
+    __name(this, "MailiskClient");
+  }
   constructor({ apiKey, baseUrl, auth }) {
     this.axiosInstance = axios.create({
       headers: {
@@ -15,6 +18,15 @@ var MailiskClient = class {
     });
   }
   axiosInstance;
+  /**
+   * Search SMS messages sent to a phone number.
+   *
+   * @example
+   * Search for SMS messages sent to a phone number
+   * ```typescript
+   * const { data: smsMessages } = await client.searchSmsMessages("1234567890");
+   * ```
+   */
   async searchSmsMessages(phoneNumber, params, config) {
     let _params = { ...params };
     if (params?.from_date === void 0 || params?.from_date === null) {
@@ -40,15 +52,166 @@ var MailiskClient = class {
       params: requestParams
     })).data;
   }
+  /**
+   * List all SMS phone numbers associated with the current account.
+   *
+   * @example
+   * List all SMS phone numbers
+   * ```typescript
+   * const { data: smsNumbers } = await client.listSmsNumbers();
+   * ```
+   */
   async listSmsNumbers() {
     return (await this.axiosInstance.get("api/sms/numbers")).data;
   }
   async sendVirtualSms(params) {
     return (await this.axiosInstance.post("api/sms/virtual", params)).data;
   }
+  /**
+   * List saved TOTP devices.
+   *
+   * @example
+   * List saved TOTP devices for an issuer and username
+   * ```typescript
+   * const { items: devices } = await client.listTotpDevices({
+   *   issuer: "GitHub",
+   *   username: "qa@example.com",
+   * });
+   * ```
+   */
+  async listTotpDevices(params) {
+    const requestParams = {
+      ...params,
+      username: params?.username?.trim(),
+      issuer: params?.issuer?.trim()
+    };
+    return (await this.axiosInstance.get("api/devices", {
+      params: requestParams
+    })).data;
+  }
+  /**
+   * Create a saved TOTP device from a Base32 shared secret using default TOTP settings.
+   *
+   * @example
+   * Create a saved TOTP device from a shared secret
+   * ```typescript
+   * const device = await client.createTotpDevice({
+   *   name: "GitHub staging",
+   *   sharedSecret: "JBSWY3DPEHPK3PXP",
+   * });
+   * ```
+   */
+  async createTotpDevice(params) {
+    return (await this.axiosInstance.post("api/devices", params)).data;
+  }
+  /**
+   * Create a saved TOTP device with custom settings.
+   *
+   * @example
+   * Create a saved TOTP device with custom settings
+   * ```typescript
+   * const device = await client.createCustomTotpDevice({
+   *   name: "GitHub staging",
+   *   secret: "JBSWY3DPEHPK3PXP",
+   *   username: "qa@example.com",
+   *   issuer: "GitHub",
+   *   digits: 6,
+   *   period: 30,
+   *   algorithm: "SHA1",
+   * });
+   * ```
+   */
+  async createCustomTotpDevice(params) {
+    return (await this.axiosInstance.post("api/devices/custom", params)).data;
+  }
+  /**
+   * Create a saved TOTP device from a Base32 secret key.
+   *
+   * @example
+   * Create a saved TOTP device from a Base32 secret key
+   * ```typescript
+   * const device = await client.createTotpDeviceFromBase32SecretKey({
+   *   base32SecretKey: "JBSWY3DPEHPK3PXP",
+   *   username: "qa@example.com",
+   *   issuer: "GitHub",
+   * });
+   * ```
+   */
+  async createTotpDeviceFromBase32SecretKey(params) {
+    return (await this.axiosInstance.post("api/devices/base32-secret-key", params)).data;
+  }
+  /**
+   * Create a saved TOTP device from an otpauth://totp URL.
+   *
+   * @example
+   * Create a saved TOTP device from an otpauth URL
+   * ```typescript
+   * const device = await client.createTotpDeviceFromOtpAuthUrl({
+   *   otpAuthUrl: "otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub",
+   * });
+   * ```
+   */
+  async createTotpDeviceFromOtpAuthUrl(params) {
+    return (await this.axiosInstance.post("api/devices/otpauth-url", params)).data;
+  }
+  /**
+   * Generate a TOTP code from a shared secret without saving a device.
+   *
+   * @example
+   * Generate a TOTP code from a shared secret
+   * ```typescript
+   * const { code } = await client.getTotpOtpBySharedSecret("JBSWY3DPEHPK3PXP");
+   * ```
+   */
+  async getTotpOtpBySharedSecret(sharedSecret) {
+    return (await this.axiosInstance.post("api/devices/otp", { sharedSecret })).data;
+  }
+  /**
+   * Generate a TOTP code for a saved device.
+   *
+   * @example
+   * Generate a TOTP code for a saved device
+   * ```typescript
+   * const { code } = await client.getTotpOtpByDeviceId(device.id);
+   * ```
+   */
+  async getTotpOtpByDeviceId(deviceId) {
+    return (await this.axiosInstance.get(`api/devices/${deviceId}/otp`)).data;
+  }
+  /**
+   * Delete a saved TOTP device.
+   *
+   * @example
+   * Delete a saved TOTP device
+   * ```typescript
+   * await client.deleteTotpDevice(device.id);
+   * ```
+   */
+  async deleteTotpDevice(deviceId) {
+    await this.axiosInstance.delete(`api/devices/${deviceId}`);
+  }
+  /**
+   * List all namespaces that belong to the current account (API key).
+   */
   async listNamespaces() {
     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, params) {
     const smtpSettings = await this.getSmtpSettings(namespace);
     const transport = nodemailer.createTransport({
@@ -72,10 +235,42 @@ var MailiskClient = class {
     });
     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 - 15 minutes**. 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
+   * ```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'
+   * });
+   * ```
+   *
+   * @example
+   * Get the last 20 emails in the namespace
+   * ```typescript
+   * const { data: emails } = await mailisk.searchInbox(namespace, {
+   *   wait: false,
+   *   from_timestamp: 0,
+   *   limit: 20
+   * });
+   * ```
+   */
   async searchInbox(namespace, params, config) {
     let _params = { ...params };
     if (params?.from_timestamp === void 0 || params?.from_timestamp === null) {
-      _params.from_timestamp = Math.floor(new Date().getTime() / 1e3) - 15 * 60;
+      _params.from_timestamp = Math.floor((/* @__PURE__ */ new Date()).getTime() / 1e3) - 15 * 60;
     }
     if (params?.wait !== false) {
       _params.wait = true;
@@ -92,6 +287,9 @@ var MailiskClient = class {
       params: _params
     })).data;
   }
+  /**
+   * Get the SMTP settings for a namespace.
+   */
   async getSmtpSettings(namespace) {
     const result = await this.axiosInstance.get(`api/smtp/${namespace}`);
     return result.data;
@@ -100,13 +298,25 @@ var MailiskClient = class {
     const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);
     return result.data;
   }
+  /**
+   * Download an attachment from an attachment ID.
+   *
+   * @example
+   * Download an attachment from an email
+   * ```typescript
+   * const attachment = email.attachments[0];
+   * const attachmentBuffer = await client.downloadAttachment(attachment.id);
+   *
+   * // save to file
+   * fs.writeFileSync(attachment.filename, attachmentBuffer);
+   * ```
+   */
   async downloadAttachment(attachmentId) {
     const result = await this.getAttachment(attachmentId);
     const response = await axios.get(result.data.download_url, { responseType: "arraybuffer" });
     return Buffer.from(response.data);
   }
 };
-__name(MailiskClient, "MailiskClient");
 export {
   MailiskClient
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mailisk.ts"],"sourcesContent":["import axios, { AxiosBasicCredentials, AxiosInstance, AxiosRequestConfig } from \"axios\";\nimport {\n  GetAttachmentResponse,\n  ListNamespacesResponse,\n  ListSmsNumbersResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SearchSmsMessagesParams,\n  SearchSmsMessagesResponse,\n  SendVirtualEmailParams,\n  SendVirtualSmsParams,\n  SmtpSettings,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl, auth }: { apiKey: string; baseUrl?: string; auth?: AxiosBasicCredentials }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n      auth,\n    });\n  }\n\n  private readonly axiosInstance: AxiosInstance;\n\n  /**\n   * Search SMS messages sent to a phone number.\n   *\n   * @example\n   * Search for SMS messages sent to a phone number\n   * ```typescript\n   * const { data: smsMessages } = await client.searchSmsMessages(\"1234567890\");\n   * ```\n   */\n  async searchSmsMessages(\n    phoneNumber: string,\n    params?: SearchSmsMessagesParams,\n    config?: AxiosRequestConfig\n  ): Promise<SearchSmsMessagesResponse> {\n    let _params: SearchSmsMessagesParams = { ...params };\n\n    // default from timestamp, 15 minutes before starting this request\n    if (params?.from_date === undefined || params?.from_date === null) {\n      _params.from_date = new Date(Date.now() - 15 * 60 * 1000).toISOString();\n    }\n\n    // by default wait for sms\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    if (config?.maxRedirects === undefined) {\n      _config.maxRedirects = 99999;\n    }\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && config?.timeout === undefined) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    const requestParams = {\n      ..._params,\n      from_date: _params.from_date ?? undefined,\n      to_date: _params.to_date ?? undefined,\n    };\n\n    return (\n      await this.axiosInstance.get(`api/sms/${phoneNumber}/messages`, {\n        ..._config,\n        params: requestParams,\n      })\n    ).data;\n  }\n\n  /**\n   * List all SMS phone numbers associated with the current account.\n   *\n   * @example\n   * List all SMS phone numbers\n   * ```typescript\n   * const { data: smsNumbers } = await client.listSmsNumbers();\n   * ```\n   */\n  async listSmsNumbers(): Promise<ListSmsNumbersResponse> {\n    return (await this.axiosInstance.get(\"api/sms/numbers\")).data;\n  }\n\n  async sendVirtualSms(params: SendVirtualSmsParams): Promise<void> {\n    return (await this.axiosInstance.post(\"api/sms/virtual\", params)).data;\n  }\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    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, headers, attachments } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n      headers,\n      attachments,\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 - 15 minutes**. 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\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   * @example\n   * Get the last 20 emails in the namespace\n   * ```typescript\n   * const { data: emails } = await mailisk.searchInbox(namespace, {\n   *   wait: false,\n   *   from_timestamp: 0,\n   *   limit: 20\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, 15 minutes before starting this request\n    if (params?.from_timestamp === undefined || params?.from_timestamp === null) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 15 * 60;\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    if (config?.maxRedirects === undefined) {\n      _config.maxRedirects = 99999;\n    }\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && config?.timeout === undefined) {\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  async getAttachment(attachmentId: string): Promise<GetAttachmentResponse> {\n    const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);\n    return result.data;\n  }\n\n  /**\n   * Download an attachment from an attachment ID.\n   *\n   * @example\n   * Download an attachment from an email\n   * ```typescript\n   * const attachment = email.attachments[0];\n   * const attachmentBuffer = await client.downloadAttachment(attachment.id);\n   *\n   * // save to file\n   * fs.writeFileSync(attachment.filename, attachmentBuffer);\n   * ```\n   */\n  async downloadAttachment(attachmentId: string): Promise<Buffer> {\n    const result = await this.getAttachment(attachmentId);\n\n    const response = await axios.get(result.data.download_url, { responseType: \"arraybuffer\" });\n    return Buffer.from(response.data);\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/mailisk.ts"],"sourcesContent":["import axios, { AxiosBasicCredentials, AxiosInstance, AxiosRequestConfig } from \"axios\";\nimport {\n  CreateBase32SecretKeyTotpDeviceParams,\n  CreateCustomTotpDeviceParams,\n  CreateOtpAuthUrlTotpDeviceParams,\n  CreateTotpDeviceParams,\n  GetAttachmentResponse,\n  ListNamespacesResponse,\n  ListSmsNumbersResponse,\n  ListTotpDevicesParams,\n  ListTotpDevicesResponse,\n  SearchInboxParams,\n  SearchInboxResponse,\n  SearchSmsMessagesParams,\n  SearchSmsMessagesResponse,\n  SendVirtualEmailParams,\n  SendVirtualSmsParams,\n  SmtpSettings,\n  TotpDevice,\n  TotpOtpResponse,\n} from \"./mailisk.interfaces\";\nimport nodemailer from \"nodemailer\";\n\nexport class MailiskClient {\n  constructor({ apiKey, baseUrl, auth }: { apiKey: string; baseUrl?: string; auth?: AxiosBasicCredentials }) {\n    this.axiosInstance = axios.create({\n      headers: {\n        \"X-Api-Key\": apiKey,\n      },\n      baseURL: baseUrl || \"https://api.mailisk.com/\",\n      auth,\n    });\n  }\n\n  private readonly axiosInstance: AxiosInstance;\n\n  /**\n   * Search SMS messages sent to a phone number.\n   *\n   * @example\n   * Search for SMS messages sent to a phone number\n   * ```typescript\n   * const { data: smsMessages } = await client.searchSmsMessages(\"1234567890\");\n   * ```\n   */\n  async searchSmsMessages(\n    phoneNumber: string,\n    params?: SearchSmsMessagesParams,\n    config?: AxiosRequestConfig,\n  ): Promise<SearchSmsMessagesResponse> {\n    let _params: SearchSmsMessagesParams = { ...params };\n\n    // default from timestamp, 15 minutes before starting this request\n    if (params?.from_date === undefined || params?.from_date === null) {\n      _params.from_date = new Date(Date.now() - 15 * 60 * 1000).toISOString();\n    }\n\n    // by default wait for sms\n    if (params?.wait !== false) {\n      _params.wait = true;\n    }\n\n    let _config = { ...config };\n\n    if (config?.maxRedirects === undefined) {\n      _config.maxRedirects = 99999;\n    }\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && config?.timeout === undefined) {\n      _config.timeout = 1000 * 60 * 5;\n    }\n\n    const requestParams = {\n      ..._params,\n      from_date: _params.from_date ?? undefined,\n      to_date: _params.to_date ?? undefined,\n    };\n\n    return (\n      await this.axiosInstance.get(`api/sms/${phoneNumber}/messages`, {\n        ..._config,\n        params: requestParams,\n      })\n    ).data;\n  }\n\n  /**\n   * List all SMS phone numbers associated with the current account.\n   *\n   * @example\n   * List all SMS phone numbers\n   * ```typescript\n   * const { data: smsNumbers } = await client.listSmsNumbers();\n   * ```\n   */\n  async listSmsNumbers(): Promise<ListSmsNumbersResponse> {\n    return (await this.axiosInstance.get(\"api/sms/numbers\")).data;\n  }\n\n  async sendVirtualSms(params: SendVirtualSmsParams): Promise<void> {\n    return (await this.axiosInstance.post(\"api/sms/virtual\", params)).data;\n  }\n\n  /**\n   * List saved TOTP devices.\n   *\n   * @example\n   * List saved TOTP devices for an issuer and username\n   * ```typescript\n   * const { items: devices } = await client.listTotpDevices({\n   *   issuer: \"GitHub\",\n   *   username: \"qa@example.com\",\n   * });\n   * ```\n   */\n  async listTotpDevices(params?: ListTotpDevicesParams): Promise<ListTotpDevicesResponse> {\n    const requestParams: ListTotpDevicesParams = {\n      ...params,\n      username: params?.username?.trim(),\n      issuer: params?.issuer?.trim(),\n    };\n\n    return (\n      await this.axiosInstance.get(\"api/devices\", {\n        params: requestParams,\n      })\n    ).data;\n  }\n\n  /**\n   * Create a saved TOTP device from a Base32 shared secret using default TOTP settings.\n   *\n   * @example\n   * Create a saved TOTP device from a shared secret\n   * ```typescript\n   * const device = await client.createTotpDevice({\n   *   name: \"GitHub staging\",\n   *   sharedSecret: \"JBSWY3DPEHPK3PXP\",\n   * });\n   * ```\n   */\n  async createTotpDevice(params: CreateTotpDeviceParams): Promise<TotpDevice> {\n    return (await this.axiosInstance.post(\"api/devices\", params)).data;\n  }\n\n  /**\n   * Create a saved TOTP device with custom settings.\n   *\n   * @example\n   * Create a saved TOTP device with custom settings\n   * ```typescript\n   * const device = await client.createCustomTotpDevice({\n   *   name: \"GitHub staging\",\n   *   secret: \"JBSWY3DPEHPK3PXP\",\n   *   username: \"qa@example.com\",\n   *   issuer: \"GitHub\",\n   *   digits: 6,\n   *   period: 30,\n   *   algorithm: \"SHA1\",\n   * });\n   * ```\n   */\n  async createCustomTotpDevice(params: CreateCustomTotpDeviceParams): Promise<TotpDevice> {\n    return (await this.axiosInstance.post(\"api/devices/custom\", params)).data;\n  }\n\n  /**\n   * Create a saved TOTP device from a Base32 secret key.\n   *\n   * @example\n   * Create a saved TOTP device from a Base32 secret key\n   * ```typescript\n   * const device = await client.createTotpDeviceFromBase32SecretKey({\n   *   base32SecretKey: \"JBSWY3DPEHPK3PXP\",\n   *   username: \"qa@example.com\",\n   *   issuer: \"GitHub\",\n   * });\n   * ```\n   */\n  async createTotpDeviceFromBase32SecretKey(params: CreateBase32SecretKeyTotpDeviceParams): Promise<TotpDevice> {\n    return (await this.axiosInstance.post(\"api/devices/base32-secret-key\", params)).data;\n  }\n\n  /**\n   * Create a saved TOTP device from an otpauth://totp URL.\n   *\n   * @example\n   * Create a saved TOTP device from an otpauth URL\n   * ```typescript\n   * const device = await client.createTotpDeviceFromOtpAuthUrl({\n   *   otpAuthUrl: \"otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub\",\n   * });\n   * ```\n   */\n  async createTotpDeviceFromOtpAuthUrl(params: CreateOtpAuthUrlTotpDeviceParams): Promise<TotpDevice> {\n    return (await this.axiosInstance.post(\"api/devices/otpauth-url\", params)).data;\n  }\n\n  /**\n   * Generate a TOTP code from a shared secret without saving a device.\n   *\n   * @example\n   * Generate a TOTP code from a shared secret\n   * ```typescript\n   * const { code } = await client.getTotpOtpBySharedSecret(\"JBSWY3DPEHPK3PXP\");\n   * ```\n   */\n  async getTotpOtpBySharedSecret(sharedSecret: string): Promise<TotpOtpResponse> {\n    return (await this.axiosInstance.post(\"api/devices/otp\", { sharedSecret })).data;\n  }\n\n  /**\n   * Generate a TOTP code for a saved device.\n   *\n   * @example\n   * Generate a TOTP code for a saved device\n   * ```typescript\n   * const { code } = await client.getTotpOtpByDeviceId(device.id);\n   * ```\n   */\n  async getTotpOtpByDeviceId(deviceId: string): Promise<TotpOtpResponse> {\n    return (await this.axiosInstance.get(`api/devices/${deviceId}/otp`)).data;\n  }\n\n  /**\n   * Delete a saved TOTP device.\n   *\n   * @example\n   * Delete a saved TOTP device\n   * ```typescript\n   * await client.deleteTotpDevice(device.id);\n   * ```\n   */\n  async deleteTotpDevice(deviceId: string): Promise<void> {\n    await this.axiosInstance.delete(`api/devices/${deviceId}`);\n  }\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    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, headers, attachments } = params;\n\n    await transport.sendMail({\n      from,\n      to,\n      subject,\n      text,\n      html,\n      headers,\n      attachments,\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 - 15 minutes**. 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\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   * @example\n   * Get the last 20 emails in the namespace\n   * ```typescript\n   * const { data: emails } = await mailisk.searchInbox(namespace, {\n   *   wait: false,\n   *   from_timestamp: 0,\n   *   limit: 20\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, 15 minutes before starting this request\n    if (params?.from_timestamp === undefined || params?.from_timestamp === null) {\n      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 15 * 60;\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    if (config?.maxRedirects === undefined) {\n      _config.maxRedirects = 99999;\n    }\n\n    // by default, wait 5 minutes for emails before timing out\n    if (_params.wait && config?.timeout === undefined) {\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  async getAttachment(attachmentId: string): Promise<GetAttachmentResponse> {\n    const result = await this.axiosInstance.get(`api/attachments/${attachmentId}`);\n    return result.data;\n  }\n\n  /**\n   * Download an attachment from an attachment ID.\n   *\n   * @example\n   * Download an attachment from an email\n   * ```typescript\n   * const attachment = email.attachments[0];\n   * const attachmentBuffer = await client.downloadAttachment(attachment.id);\n   *\n   * // save to file\n   * fs.writeFileSync(attachment.filename, attachmentBuffer);\n   * ```\n   */\n  async downloadAttachment(attachmentId: string): Promise<Buffer> {\n    const result = await this.getAttachment(attachmentId);\n\n    const response = await axios.get(result.data.download_url, { responseType: \"arraybuffer\" });\n    return Buffer.from(response.data);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailisk",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "description": "Mailisk library for NodeJS",
   "keywords": [
     "mailisk",

package/src/index.ts

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

package/src/mailisk.interfaces.ts

@@ -241,3 +241,112 @@ export interface SendVirtualSmsParams {
   /** The body of the SMS message */
   body: string;
 }
+
+export type TotpAlgorithm = "SHA1" | "SHA256" | "SHA512";
+
+export type KnownTotpDeviceSource = "shared_secret" | "custom" | "base32_secret_key" | "otpauth_url";
+
+export type TotpDeviceSource = KnownTotpDeviceSource | (string & {});
+
+export interface TotpDevice {
+  id: string;
+  organisation_id: string;
+  name: string;
+  username?: string | null;
+  issuer?: string | null;
+  digits: number;
+  period: number;
+  algorithm: TotpAlgorithm;
+  source: TotpDeviceSource;
+  expiresAt?: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ListTotpDevicesParams {
+  /** The maximum number of saved TOTP devices returned (1-100), used alongside `offset` for pagination. */
+  limit?: number;
+  /** The number of saved TOTP devices to skip/ignore, used alongside `limit` for pagination. Must be >= 0. */
+  offset?: number;
+  /** Case-insensitive partial username match. Trimmed before sending. */
+  username?: string;
+  /** Case-insensitive partial issuer match. Trimmed before sending. */
+  issuer?: string;
+}
+
+export interface ListTotpDevicesResponse {
+  total_count: number;
+  options: ListTotpDevicesParams;
+  items: TotpDevice[];
+}
+
+export interface CreateTotpDeviceParams {
+  /** Base32 shared secret. Uses default TOTP settings. */
+  sharedSecret: string;
+  /** Optional saved-device display name. Max 120 characters. */
+  name?: string;
+  /** Future ISO timestamp after which the saved device expires. */
+  expiresAt?: string;
+}
+
+export interface CreateCustomTotpDeviceParams {
+  /** Base32 shared secret. */
+  secret: string;
+  /** Optional saved-device display name. Max 120 characters. */
+  name?: string;
+  /** Account label. Max 240 characters. */
+  username?: string;
+  /** Issuer/app label. Max 240 characters. */
+  issuer?: string;
+  /** Number of OTP digits. */
+  digits?: 6 | 8;
+  /** OTP period in seconds. Must be an integer from 10 to 300. */
+  period?: number;
+  /** Hashing algorithm. */
+  algorithm?: TotpAlgorithm;
+  /** Future ISO timestamp after which the saved device expires. */
+  expiresAt?: string;
+}
+
+export interface CreateBase32SecretKeyTotpDeviceParams {
+  /** Base32 shared secret key. */
+  base32SecretKey: string;
+  /** Optional saved-device display name. Max 120 characters. */
+  name?: string;
+  /** Account label. Max 240 characters. */
+  username?: string;
+  /** Issuer/app label. Max 240 characters. */
+  issuer?: string;
+  /** Number of OTP digits. */
+  digits?: 6 | 8;
+  /** OTP period in seconds. Must be an integer from 10 to 300. */
+  period?: number;
+  /** Hashing algorithm. */
+  algorithm?: TotpAlgorithm;
+  /** Future ISO timestamp after which the saved device expires. */
+  expiresAt?: string;
+}
+
+export interface CreateOtpAuthUrlTotpDeviceParams {
+  /** otpauth://totp URL with a secret query parameter. */
+  otpAuthUrl: string;
+  /** Optional saved-device display name. Max 120 characters. */
+  name?: string;
+  /** Account label, used when missing from the URL label. Max 240 characters. */
+  username?: string;
+  /** Issuer/app label, used when missing from the URL. Max 240 characters. */
+  issuer?: string;
+  /** Number of OTP digits, used when missing from the URL. */
+  digits?: 6 | 8;
+  /** OTP period in seconds, used when missing from the URL. Must be an integer from 10 to 300. */
+  period?: number;
+  /** Hashing algorithm, used when missing from the URL. */
+  algorithm?: TotpAlgorithm;
+  /** Future ISO timestamp after which the saved device expires. */
+  expiresAt?: string;
+}
+
+export interface TotpOtpResponse {
+  code: string;
+  expires: string;
+}

package/src/mailisk.ts

@@ -1,8 +1,14 @@
 import axios, { AxiosBasicCredentials, AxiosInstance, AxiosRequestConfig } from "axios";
 import {
+  CreateBase32SecretKeyTotpDeviceParams,
+  CreateCustomTotpDeviceParams,
+  CreateOtpAuthUrlTotpDeviceParams,
+  CreateTotpDeviceParams,
   GetAttachmentResponse,
   ListNamespacesResponse,
   ListSmsNumbersResponse,
+  ListTotpDevicesParams,
+  ListTotpDevicesResponse,
   SearchInboxParams,
   SearchInboxResponse,
   SearchSmsMessagesParams,
@@ -10,6 +16,8 @@ import {
   SendVirtualEmailParams,
   SendVirtualSmsParams,
   SmtpSettings,
+  TotpDevice,
+  TotpOtpResponse,
 } from "./mailisk.interfaces";
 import nodemailer from "nodemailer";
 
@@ -38,7 +46,7 @@ export class MailiskClient {
   async searchSmsMessages(
     phoneNumber: string,
     params?: SearchSmsMessagesParams,
-    config?: AxiosRequestConfig
+    config?: AxiosRequestConfig,
   ): Promise<SearchSmsMessagesResponse> {
     let _params: SearchSmsMessagesParams = { ...params };
 
@@ -94,6 +102,140 @@ export class MailiskClient {
     return (await this.axiosInstance.post("api/sms/virtual", params)).data;
   }
 
+  /**
+   * List saved TOTP devices.
+   *
+   * @example
+   * List saved TOTP devices for an issuer and username
+   * ```typescript
+   * const { items: devices } = await client.listTotpDevices({
+   *   issuer: "GitHub",
+   *   username: "qa@example.com",
+   * });
+   * ```
+   */
+  async listTotpDevices(params?: ListTotpDevicesParams): Promise<ListTotpDevicesResponse> {
+    const requestParams: ListTotpDevicesParams = {
+      ...params,
+      username: params?.username?.trim(),
+      issuer: params?.issuer?.trim(),
+    };
+
+    return (
+      await this.axiosInstance.get("api/devices", {
+        params: requestParams,
+      })
+    ).data;
+  }
+
+  /**
+   * Create a saved TOTP device from a Base32 shared secret using default TOTP settings.
+   *
+   * @example
+   * Create a saved TOTP device from a shared secret
+   * ```typescript
+   * const device = await client.createTotpDevice({
+   *   name: "GitHub staging",
+   *   sharedSecret: "JBSWY3DPEHPK3PXP",
+   * });
+   * ```
+   */
+  async createTotpDevice(params: CreateTotpDeviceParams): Promise<TotpDevice> {
+    return (await this.axiosInstance.post("api/devices", params)).data;
+  }
+
+  /**
+   * Create a saved TOTP device with custom settings.
+   *
+   * @example
+   * Create a saved TOTP device with custom settings
+   * ```typescript
+   * const device = await client.createCustomTotpDevice({
+   *   name: "GitHub staging",
+   *   secret: "JBSWY3DPEHPK3PXP",
+   *   username: "qa@example.com",
+   *   issuer: "GitHub",
+   *   digits: 6,
+   *   period: 30,
+   *   algorithm: "SHA1",
+   * });
+   * ```
+   */
+  async createCustomTotpDevice(params: CreateCustomTotpDeviceParams): Promise<TotpDevice> {
+    return (await this.axiosInstance.post("api/devices/custom", params)).data;
+  }
+
+  /**
+   * Create a saved TOTP device from a Base32 secret key.
+   *
+   * @example
+   * Create a saved TOTP device from a Base32 secret key
+   * ```typescript
+   * const device = await client.createTotpDeviceFromBase32SecretKey({
+   *   base32SecretKey: "JBSWY3DPEHPK3PXP",
+   *   username: "qa@example.com",
+   *   issuer: "GitHub",
+   * });
+   * ```
+   */
+  async createTotpDeviceFromBase32SecretKey(params: CreateBase32SecretKeyTotpDeviceParams): Promise<TotpDevice> {
+    return (await this.axiosInstance.post("api/devices/base32-secret-key", params)).data;
+  }
+
+  /**
+   * Create a saved TOTP device from an otpauth://totp URL.
+   *
+   * @example
+   * Create a saved TOTP device from an otpauth URL
+   * ```typescript
+   * const device = await client.createTotpDeviceFromOtpAuthUrl({
+   *   otpAuthUrl: "otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub",
+   * });
+   * ```
+   */
+  async createTotpDeviceFromOtpAuthUrl(params: CreateOtpAuthUrlTotpDeviceParams): Promise<TotpDevice> {
+    return (await this.axiosInstance.post("api/devices/otpauth-url", params)).data;
+  }
+
+  /**
+   * Generate a TOTP code from a shared secret without saving a device.
+   *
+   * @example
+   * Generate a TOTP code from a shared secret
+   * ```typescript
+   * const { code } = await client.getTotpOtpBySharedSecret("JBSWY3DPEHPK3PXP");
+   * ```
+   */
+  async getTotpOtpBySharedSecret(sharedSecret: string): Promise<TotpOtpResponse> {
+    return (await this.axiosInstance.post("api/devices/otp", { sharedSecret })).data;
+  }
+
+  /**
+   * Generate a TOTP code for a saved device.
+   *
+   * @example
+   * Generate a TOTP code for a saved device
+   * ```typescript
+   * const { code } = await client.getTotpOtpByDeviceId(device.id);
+   * ```
+   */
+  async getTotpOtpByDeviceId(deviceId: string): Promise<TotpOtpResponse> {
+    return (await this.axiosInstance.get(`api/devices/${deviceId}/otp`)).data;
+  }
+
+  /**
+   * Delete a saved TOTP device.
+   *
+   * @example
+   * Delete a saved TOTP device
+   * ```typescript
+   * await client.deleteTotpDevice(device.id);
+   * ```
+   */
+  async deleteTotpDevice(deviceId: string): Promise<void> {
+    await this.axiosInstance.delete(`api/devices/${deviceId}`);
+  }
+
   /**
    * List all namespaces that belong to the current account (API key).
    */
@@ -180,7 +322,7 @@ export class MailiskClient {
   async searchInbox(
     namespace: string,
     params?: SearchInboxParams,
-    config?: AxiosRequestConfig
+    config?: AxiosRequestConfig,
   ): Promise<SearchInboxResponse> {
     let _params = { ...params };
 

package/tests/mocks/axios-mocks.ts

@@ -106,3 +106,34 @@ export const mockSmsNumbersResponse = {
     },
   ],
 };
+
+export const mockTotpDevice = {
+  id: "9b1f6ec0-b90d-4bd8-8dd0-f6b2d5138273",
+  organisation_id: "7f0a9c32-66b2-4e25-a4cf-1f77db8f7f3b",
+  name: "GitHub staging",
+  username: "qa@example.com",
+  issuer: "GitHub",
+  digits: 6,
+  period: 30,
+  algorithm: "SHA1",
+  source: "custom",
+  expiresAt: null,
+  created_at: "2026-05-18T12:00:00.000Z",
+  updated_at: "2026-05-18T12:00:00.000Z",
+};
+
+export const mockTotpDevicesResponse = {
+  total_count: 1,
+  options: {
+    limit: 20,
+    offset: 0,
+    issuer: "GitHub",
+    username: "qa@example.com",
+  },
+  items: [mockTotpDevice],
+};
+
+export const mockTotpOtpResponse = {
+  code: "123456",
+  expires: "2026-05-18T12:00:30.000Z",
+};