mailisk 2.2.4 → 2.4.0

package/README.md

@@ -5,6 +5,7 @@ Mailisk is an end-to-end email and SMS testing platform. It allows you to receiv
 - Get a unique subdomain and unlimited email addresses for free.
 - Easily automate E2E password reset and account verification by catching emails.
 - Receive SMS messages and automate SMS tests.
+- Generate TOTP authenticator codes and manage saved TOTP devices.
 - Virtual SMTP and SMS support to test without 3rd party clients.
 
 ## Get started
@@ -214,3 +215,105 @@ await mailisk.sendVirtualSms({
   body: "Test message",
 });
 ```
+
+## Client functions (TOTP)
+
+TOTP methods call the Mailisk API to generate codes and manage saved authenticator devices. The client does not generate TOTP codes locally.
+
+These endpoints require an organisation API key, prefixed with `sk_org_`.
+
+### `listTotpDevices(params?)`
+
+List active saved TOTP devices.
+
+```js
+const devices = await mailisk.listTotpDevices({
+  limit: 20,
+  offset: 0,
+  issuer: "GitHub",
+  username: "qa@example.com",
+});
+```
+
+### `createTotpDevice(params)`
+
+Create a saved TOTP device from a Base32 shared secret using default settings: 6 digits, 30 second period, and SHA1.
+
+```js
+const device = await mailisk.createTotpDevice({
+  name: "GitHub staging",
+  shared_secret: "JBSWY3DPEHPK3PXP",
+  expires_at: "2026-06-01T12:00:00.000Z",
+});
+```
+
+### `createCustomTotpDevice(params)`
+
+Create a saved TOTP device with custom settings.
+
+```js
+const device = await mailisk.createCustomTotpDevice({
+  name: "GitHub staging",
+  secret: "JBSWY3DPEHPK3PXP",
+  username: "qa@example.com",
+  issuer: "GitHub",
+  digits: 6,
+  period: 30,
+  algorithm: "SHA1",
+});
+```
+
+### `createTotpDeviceFromBase32SecretKey(params)`
+
+Create a saved TOTP device from a Base32 secret key.
+
+```js
+const device = await mailisk.createTotpDeviceFromBase32SecretKey({
+  base32_secret_key: "JBSWY3DPEHPK3PXP",
+  username: "qa@example.com",
+  issuer: "GitHub",
+});
+```
+
+### `createTotpDeviceFromOtpAuthUrl(params)`
+
+Create a saved TOTP device from an `otpauth://totp/...` URL.
+
+```js
+const device = await mailisk.createTotpDeviceFromOtpAuthUrl({
+  otp_auth_url: "otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub",
+});
+```
+
+### `getTotpOtpBySharedSecret(sharedSecret, params?)`
+
+Generate a TOTP code from a shared secret without saving a device.
+Pass `min_seconds_until_expire` to wait for the next TOTP period when the current code has fewer seconds left.
+
+```js
+const otp = await mailisk.getTotpOtpBySharedSecret("JBSWY3DPEHPK3PXP", {
+  min_seconds_until_expire: 10,
+});
+
+console.log(otp.code);
+console.log(otp.expires);
+```
+
+### `getTotpOtpByDeviceId(deviceId, params?)`
+
+Generate a TOTP code for a saved device.
+Pass `min_seconds_until_expire` to wait for the next TOTP period when the current code has fewer seconds left.
+
+```js
+const otp = await mailisk.getTotpOtpByDeviceId(device.id, {
+  min_seconds_until_expire: 10,
+});
+```
+
+### `deleteTotpDevice(deviceId)`
+
+Delete a saved TOTP device.
+
+```js
+await mailisk.deleteTotpDevice(device.id);
+```

package/dist/index.d.mts

@@ -0,0 +1,544 @@
+import { AxiosBasicCredentials, AxiosRequestConfig } from 'axios';
+import { Attachment } from 'nodemailer/lib/mailer';
+
+interface EmailAddress {
+    /** Email address */
+    address: string;
+    /** Display name, if one is specified */
+    name?: string;
+}
+interface EmailAttachment {
+    /** Unique identifier for the attachment */
+    id: string;
+    /** Filename of the attachment */
+    filename: string;
+    /** Content type of the attachment */
+    content_type: string;
+    /** Size in bytes of the attachment */
+    size: number;
+}
+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;
+    /** The headers of the email */
+    headers?: Record<string, string>;
+    /** The attachments of the email */
+    attachments?: EmailAttachment[];
+}
+interface SmsMessage {
+    /** Unique identifier for the message */
+    id: string;
+    /** Unique identifier for the SMS phone number */
+    sms_phone_number_id: string;
+    /** Body of the message */
+    body: string;
+    /** From number of the message */
+    from_number: string;
+    /** To number of the message */
+    to_number: string;
+    /** Provider message ID */
+    provider_message_id?: string;
+    /** Date and time the message was created */
+    created_at: string;
+    /** Direction of the message */
+    direction: "inbound" | "outbound";
+}
+interface SmsNumber {
+    /** Unique identifier for the SMS number */
+    id: string;
+    /** Unique identifier for the organisation */
+    organisation_id: string;
+    /** Status of the SMS number */
+    status: "requested" | "active" | "disabled";
+    /** Country of the SMS number */
+    country: string;
+    /** SMS Phone number */
+    phone_number?: string;
+    /** Date and time the SMS number was created */
+    created_at: string;
+    /** Date and time the SMS number was updated */
+    updated_at: string;
+}
+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 for 'foobar@namespace.mailisk.net' but not 'barfoo@namespace.mailisk.net'
+     */
+    to_addr_prefix?: string;
+    /**
+     * Filter emails by 'from' address. Address must include this.
+     *
+     * '@foo' would return for 'a@foo.com', 'b@foo.net'
+     */
+    from_addr_includes?: string;
+    /**
+     * Filter emails by subject. This is case insensitive. Subject must include this.
+     *
+     * 'password' would return for 'Password reset', 'Reset password notification' but not 'Reset'
+     */
+    subject_includes?: 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 GetAttachmentResponse {
+    data: {
+        id: string;
+        filename: string;
+        content_type: string;
+        size: number;
+        expires_at: string | null;
+        download_url: string;
+    };
+}
+interface ListNamespacesResponse {
+    total_count: number;
+    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;
+    /** Custom headers for the email */
+    headers?: Record<string, string>;
+    /** Attachments to the email */
+    attachments?: Attachment[];
+}
+interface SearchSmsMessagesParams {
+    /**
+     * The maximum number of SMS messages returned (1-100), used alongside `offset` for pagination.
+     */
+    limit?: number;
+    /**
+     * The number of SMS messages to skip/ignore, used alongside `limit` for pagination.
+     */
+    offset?: number;
+    /**
+     * Filter messages by body contents (case insensitive).
+     */
+    body?: string;
+    /**
+     * Filter messages by sender phone number prefix.
+     */
+    from_number?: string;
+    /**
+     * Filter messages created on or after this date.
+     * Provide an ISO 8601 timestamp string.
+     */
+    from_date?: string;
+    /**
+     * Filter messages created on or before this date.
+     * Provide an ISO 8601 timestamp string.
+     */
+    to_date?: string;
+    /**
+     * When true, keep the request open until at least one SMS is returned.
+     */
+    wait?: boolean;
+}
+interface SearchSmsMessagesResponse {
+    total_count: number;
+    options: SearchSmsMessagesParams;
+    data: SmsMessage[];
+}
+interface ListSmsNumbersResponse {
+    total_count: number;
+    data: SmsNumber[];
+}
+interface SendVirtualSmsParams {
+    /** The phone number to send the SMS from */
+    from_number: string;
+    /** The phone number to send the SMS to */
+    to_number: string;
+    /** The body of the SMS message */
+    body: string;
+}
+type TotpAlgorithm = "SHA1" | "SHA256" | "SHA512";
+type KnownTotpDeviceSource = "shared_secret" | "custom" | "base32_secret_key" | "otpauth_url";
+type TotpDeviceSource = KnownTotpDeviceSource | (string & {});
+interface TotpDevice {
+    id: string;
+    organisation_id: string;
+    name: string;
+    username?: string | null;
+    issuer?: string | null;
+    digits: number;
+    period: number;
+    algorithm: TotpAlgorithm;
+    source: TotpDeviceSource;
+    expires_at?: string | null;
+    created_at: string;
+    updated_at: string;
+}
+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;
+}
+interface ListTotpDevicesResponse {
+    total_count: number;
+    options: ListTotpDevicesParams;
+    items: TotpDevice[];
+}
+interface CreateTotpDeviceParams {
+    /** Base32 shared secret. Uses default TOTP settings. */
+    shared_secret: string;
+    /** Optional saved-device display name. Max 120 characters. */
+    name?: string;
+    /** Future ISO timestamp after which the saved device expires. */
+    expires_at?: string;
+}
+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. */
+    expires_at?: string;
+}
+interface CreateBase32SecretKeyTotpDeviceParams {
+    /** Base32 shared secret key. */
+    base32_secret_key: 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. */
+    expires_at?: string;
+}
+interface CreateOtpAuthUrlTotpDeviceParams {
+    /** otpauth://totp URL with a secret query parameter. */
+    otp_auth_url: 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. */
+    expires_at?: string;
+}
+interface GetTotpOtpParams {
+    /** Minimum number of seconds the returned OTP should remain valid. Must be >= 0 and less than the TOTP period. */
+    min_seconds_until_expire?: number;
+}
+interface TotpOtpResponse {
+    code: string;
+    expires: string;
+}
+
+declare class MailiskClient {
+    constructor({ apiKey, baseUrl, auth }: {
+        apiKey: string;
+        baseUrl?: string;
+        auth?: AxiosBasicCredentials;
+    });
+    private readonly 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");
+     * ```
+     */
+    searchSmsMessages(phoneNumber: string, params?: SearchSmsMessagesParams, config?: AxiosRequestConfig): Promise<SearchSmsMessagesResponse>;
+    /**
+     * List all SMS phone numbers associated with the current account.
+     *
+     * @example
+     * List all SMS phone numbers
+     * ```typescript
+     * const { data: smsNumbers } = await client.listSmsNumbers();
+     * ```
+     */
+    listSmsNumbers(): Promise<ListSmsNumbersResponse>;
+    sendVirtualSms(params: SendVirtualSmsParams): Promise<void>;
+    /**
+     * 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",
+     * });
+     * ```
+     */
+    listTotpDevices(params?: ListTotpDevicesParams): Promise<ListTotpDevicesResponse>;
+    /**
+     * 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",
+     *   shared_secret: "JBSWY3DPEHPK3PXP",
+     * });
+     * ```
+     */
+    createTotpDevice(params: CreateTotpDeviceParams): Promise<TotpDevice>;
+    /**
+     * 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",
+     * });
+     * ```
+     */
+    createCustomTotpDevice(params: CreateCustomTotpDeviceParams): Promise<TotpDevice>;
+    /**
+     * 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({
+     *   base32_secret_key: "JBSWY3DPEHPK3PXP",
+     *   username: "qa@example.com",
+     *   issuer: "GitHub",
+     * });
+     * ```
+     */
+    createTotpDeviceFromBase32SecretKey(params: CreateBase32SecretKeyTotpDeviceParams): Promise<TotpDevice>;
+    /**
+     * 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({
+     *   otp_auth_url: "otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub",
+     * });
+     * ```
+     */
+    createTotpDeviceFromOtpAuthUrl(params: CreateOtpAuthUrlTotpDeviceParams): Promise<TotpDevice>;
+    /**
+     * 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", {
+     *   min_seconds_until_expire: 10,
+     * });
+     * ```
+     */
+    getTotpOtpBySharedSecret(sharedSecret: string, params?: GetTotpOtpParams): Promise<TotpOtpResponse>;
+    /**
+     * 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, {
+     *   min_seconds_until_expire: 10,
+     * });
+     * ```
+     */
+    getTotpOtpByDeviceId(deviceId: string, params?: GetTotpOtpParams): Promise<TotpOtpResponse>;
+    /**
+     * Delete a saved TOTP device.
+     *
+     * @example
+     * Delete a saved TOTP device
+     * ```typescript
+     * await client.deleteTotpDevice(device.id);
+     * ```
+     */
+    deleteTotpDevice(deviceId: string): Promise<void>;
+    /**
+     * 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 - 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
+     * });
+     * ```
+     */
+    searchInbox(namespace: string, params?: SearchInboxParams, config?: AxiosRequestConfig): Promise<SearchInboxResponse>;
+    /**
+     * Get the SMTP settings for a namespace.
+     */
+    getSmtpSettings(namespace: string): Promise<SmtpSettings>;
+    getAttachment(attachmentId: string): Promise<GetAttachmentResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    downloadAttachment(attachmentId: string): Promise<Buffer>;
+}
+
+export { type CreateBase32SecretKeyTotpDeviceParams, type CreateCustomTotpDeviceParams, type CreateOtpAuthUrlTotpDeviceParams, type CreateTotpDeviceParams, type Email, type EmailAddress, type EmailAttachment, type GetAttachmentResponse, type GetTotpOtpParams, type KnownTotpDeviceSource, type ListNamespacesResponse, type ListSmsNumbersResponse, type ListTotpDevicesParams, type ListTotpDevicesResponse, MailiskClient, type SearchInboxParams, type SearchInboxResponse, type SearchSmsMessagesParams, type SearchSmsMessagesResponse, type SendVirtualEmailParams, type SendVirtualSmsParams, type SmsMessage, type SmsNumber, type SmtpSettings, type TotpAlgorithm, type TotpDevice, type TotpDeviceSource, type TotpOtpResponse };