temp-disposable-email 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 1.1.0 (2024-11-28)
+
+
+### Features
+
+* account and authentication services with dotenv support ([d886b69](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/d886b69f54169b24654ea60de37985a522058ac8))
+* add GitHub Actions workflows for NPM publishing and release management ([4a4ac8f](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/4a4ac8f980604ef80b3ae6a542c70da233816390))
+* add Jest configuration and GitHub Actions workflow for CI, along with comprehensive tests for services and utilities ([e110b58](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/e110b583b60f2d9f5c4c048535ea1e266ff93ae4))
+* add TypeScript dependency to package.json and package-lock.json ([f709340](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/f709340ec77ad7900877c7c89ad36a4d654df73c))
+* add verification code extraction utility and update ignore files ([bd0f6a9](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/bd0f6a9a82f8569f40b1d8e3826610359e41076c))
+* enhance message service by exporting additional interfaces and updating options parameter ([a161235](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/a1612354648e611c43c449131569fc40b3ef508f))
+* implement message retrieval and deletion services with API integration ([d898bcf](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/d898bcf01de4ba8ed5da4bf8aa23e669dc84e5db))
+* update GitHub Actions release workflow to use GITHUB_TOKEN instead of PA_TOKEN ([7d0cce7](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/7d0cce7f462be80e8af81697138af5bad32c69e8))
+* update GitHub Actions workflow to support Node.js 18.x ([2f56cad](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/2f56cad1e705b25e7b7555c8dd289605046b7920))
+* update release workflow to trigger on master branch ([79bc990](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/79bc9909cc21a8e537886ae7cd77ed5a4f597d0a))
+* update release workflow to use PA_TOKEN for GitHub Actions ([d3e8883](https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/commit/d3e888365ed55813db309ea7fd547d32ad373cf6))
+
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pirasanthan Jesugeevegan
+
+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 @@
+# temp-disposable-email

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createInbox, deleteAccount } from './services/accountService';
+export { getRecentEmail, deleteMessage, MessageContent, GetEmailOptions, } from './services/messageService';
+export { getVerificationCode } from './utils/getVerificationCode';

package/dist/services/accountService.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Creates a new email inbox with a unique address.
+ *
+ * This function selects an available domain, generates an email
+ * address, and attempts to create an account on the Mail.tm service.
+ * If account creation is rate-limited, the function retries with a
+ * delay. Upon successful creation, it authenticates the account and
+ * stores the token and account ID for future API calls.
+ *
+ * @param {string} [username] - Optional username; a random one is generated if not provided.
+ * @returns {Promise<string>} The generated email address.
+ *
+ * @throws {Error} If no domains are available or account creation fails.
+ *
+ * @example
+ * const email = await createInbox("customUser");
+ * console.log(email); // Outputs: "customUser@mail.tm"
+ */
+export declare const createInbox: (username?: string) => Promise<string>;
+/**
+ * Deletes the account created during `createInbox`.
+ *
+ * This function removes the email account from the Mail.tm service
+ * and clears the stored authentication token and account ID.
+ * Subsequent API calls requiring authentication will fail until a
+ * new account is created.
+ *
+ * @returns {Promise<void>} Resolves when the account is successfully deleted.
+ *
+ * @throws {Error} If no account is authenticated or deletion fails.
+ *
+ * @example
+ * await deleteAccount();
+ * console.log("Account deleted successfully.");
+ */
+export declare const deleteAccount: () => Promise<void>;

package/dist/services/authService.d.ts

@@ -0,0 +1,2 @@
+export declare const authenticate: (email: string, password: string) => Promise<void>;
+export declare const getToken: () => string | null;

package/dist/services/messageService.d.ts

@@ -0,0 +1,53 @@
+export interface MessageContent {
+    from: {
+        address: string;
+    };
+    to: {
+        address: string;
+    }[];
+    subject: string;
+    intro: string;
+    text: string;
+    html: string;
+}
+export interface GetEmailOptions {
+    maxWaitTime?: number;
+    waitInterval?: number;
+    logPolling?: boolean;
+    deleteAfterRead?: boolean;
+}
+/**
+ * Retrieves the latest message from the inbox.
+ *
+ * If messages are available, this function fetches the first one and
+ * returns its details. Polling options can be specified to wait for
+ * messages if the inbox is empty. Optionally, the message can be
+ * deleted after reading.
+ *
+ * @param {GetEmailOptions} [options] - Optional settings for polling and deletion.
+ * @returns {Promise<MessageContent | null>} The email content (sender, recipient, subject, text, HTML), or `null` if no messages are found.
+ *
+ * @throws {Error} If no messages are available within the polling timeout or authentication fails.
+ *
+ * @example
+ * const message = await getRecentEmail({ maxWaitTime: 5000, waitInterval: 1000, logPolling: true });
+ * console.log(message.subject); // Outputs: "Hello!"
+ */
+export declare const getRecentEmail: (options?: GetEmailOptions) => Promise<MessageContent | null>;
+/**
+ * Deletes a message by its unique ID from the Mail.tm inbox.
+ *
+ * This function requires a valid authentication token. If the
+ * token is not set, an error is thrown. The message is deleted
+ * using the Mail.tm API, and a success or failure message is logged.
+ *
+ * @param {string} messageId - The unique ID of the message to delete.
+ * @returns {Promise<void>} Resolves after the message is deleted.
+ *
+ * @throws {Error} If authentication is missing or the deletion fails.
+ *
+ * @example
+ * await deleteMessage("12345");
+ * console.log("Message deleted successfully.");
+ */
+export declare const deleteMessage: (messageId: string) => Promise<void>;

package/dist/utils/api.d.ts

@@ -0,0 +1,6 @@
+export declare const getAuthHeaders: () => {
+    accept: string;
+    Authorization: string;
+};
+export declare const fetchMessages: () => Promise<any[]>;
+export declare const fetchMessageContent: (messageId: string) => Promise<any>;

package/dist/utils/constant.d.ts

@@ -0,0 +1 @@
+export declare const BASE_URL: string | undefined;

package/dist/utils/delay.d.ts

@@ -0,0 +1 @@
+export declare const delay: (ms: number) => Promise<void>;

package/dist/utils/generateRandomName.d.ts

@@ -0,0 +1 @@
+export declare const generateRandomName: () => string;

package/dist/utils/getVerificationCode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extracts a verification code from the provided email content.
+ *
+ * This function scans the given text for a sequence of 5 or more
+ * consecutive digits and returns the first valid verification code.
+ * If no valid sequence is found, the function returns `null`.
+ *
+ * @param {string} text - The content of the email, typically the body.
+ * @returns {Promise<string | null>} The first verification code found, or `null` if no valid code exists.
+ *
+ * @example
+ * const emailContent = "Your code is 123456.";
+ * const verificationCode = await getVerificationCode(emailContent);
+ * console.log(verificationCode); // Output: "123456"
+ */
+export declare const getVerificationCode: (text: string) => Promise<string | null>;

package/jest.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "temp-disposable-email",
+  "version": "1.1.0",
+  "description": "",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src --fix",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pirasanthan-jesugeevegan/temp-disposable-email.git"
+  },
+  "keywords": [
+    "temp-email",
+    "disposable-email",
+    "email",
+    "email-testing",
+    "automation",
+    "polling",
+    "cypress",
+    "playwright"
+  ],
+  "author": "Pirasanthan Jesugeevegan",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/pirasanthan-jesugeevegan/temp-disposable-email/issues"
+  },
+  "homepage": "https://github.com/pirasanthan-jesugeevegan/temp-disposable-email#readme",
+  "dependencies": {
+    "axios": "^1.7.8",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.0",
+    "axios-mock-adapter": "^2.1.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { createInbox, deleteAccount } from './services/accountService';
+export {
+  getRecentEmail,
+  deleteMessage,
+  MessageContent,
+  GetEmailOptions,
+} from './services/messageService';
+export { getVerificationCode } from './utils/getVerificationCode';

package/src/services/accountService.ts

@@ -0,0 +1,103 @@
+import axios from 'axios';
+import { authenticate, getToken } from './authService';
+import { generateRandomName } from '../utils/generateRandomName';
+import { delay } from '../utils/delay';
+import { BASE_URL } from '../utils/constant';
+
+let accountId: string | null = null;
+/**
+ * Creates a new email inbox with a unique address.
+ *
+ * This function selects an available domain, generates an email
+ * address, and attempts to create an account on the Mail.tm service.
+ * If account creation is rate-limited, the function retries with a
+ * delay. Upon successful creation, it authenticates the account and
+ * stores the token and account ID for future API calls.
+ *
+ * @param {string} [username] - Optional username; a random one is generated if not provided.
+ * @returns {Promise<string>} The generated email address.
+ *
+ * @throws {Error} If no domains are available or account creation fails.
+ *
+ * @example
+ * const email = await createInbox("customUser");
+ * console.log(email); // Outputs: "customUser@mail.tm"
+ */
+
+export const createInbox = async (username?: string): Promise<string> => {
+  const domainsResponse = await axios.get(`${BASE_URL}/domains`, {
+    headers: { accept: 'application/ld+json' },
+  });
+  const domains = domainsResponse.data['hydra:member'].map(
+    (domain: { domain: string }) => domain.domain
+  );
+  if (domains.length === 0) throw new Error('No available domains.');
+
+  const emailAddress = `${username || generateRandomName()}@${domains[0]}`;
+  const password = generateRandomName();
+
+  let attempts = 0;
+  const maxRetries = 5;
+
+  while (attempts < maxRetries) {
+    try {
+      const accountResponse = await axios.post(
+        `${BASE_URL}/accounts`,
+        { address: emailAddress, password },
+        {
+          headers: {
+            accept: 'application/json',
+            'Content-Type': 'application/json',
+          },
+        }
+      );
+      accountId = accountResponse.data.id;
+      await authenticate(emailAddress, password);
+      return emailAddress;
+    } catch (error: any) {
+      if (error.response?.status === 429) {
+        attempts++;
+        const retryAfter = error.response.headers['retry-after']
+          ? parseInt(error.response.headers['retry-after'])
+          : 5;
+        await delay(retryAfter * 1000);
+      } else {
+        throw error;
+      }
+    }
+  }
+  throw new Error('Failed to create account after multiple retries.');
+};
+
+/**
+ * Deletes the account created during `createInbox`.
+ *
+ * This function removes the email account from the Mail.tm service
+ * and clears the stored authentication token and account ID.
+ * Subsequent API calls requiring authentication will fail until a
+ * new account is created.
+ *
+ * @returns {Promise<void>} Resolves when the account is successfully deleted.
+ *
+ * @throws {Error} If no account is authenticated or deletion fails.
+ *
+ * @example
+ * await deleteAccount();
+ * console.log("Account deleted successfully.");
+ */
+export const deleteAccount = async (): Promise<void> => {
+  const token = getToken();
+  if (!token || !accountId) {
+    throw new Error(
+      'Account information missing. Create and authenticate an account first.'
+    );
+  }
+
+  await axios.delete(`${BASE_URL}/accounts/${accountId}`, {
+    headers: {
+      accept: '*/*',
+      Authorization: `Bearer ${token}`,
+    },
+  });
+  accountId = null;
+};

package/src/services/authService.ts

@@ -0,0 +1,23 @@
+import axios from 'axios';
+import { BASE_URL } from '../utils/constant';
+
+let token: string | null = null;
+
+export const authenticate = async (
+  email: string,
+  password: string
+): Promise<void> => {
+  const response = await axios.post(
+    `${BASE_URL}/token`,
+    { address: email, password },
+    {
+      headers: {
+        accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+    }
+  );
+  token = response.data.token;
+};
+
+export const getToken = (): string | null => token;

package/src/services/messageService.ts

@@ -0,0 +1,155 @@
+import axios from 'axios';
+import { getToken } from './authService';
+import { BASE_URL } from '../utils/constant';
+import { fetchMessageContent, fetchMessages } from '../utils/api';
+
+export interface MessageContent {
+  from: { address: string };
+  to: { address: string }[];
+  subject: string;
+  intro: string;
+  text: string;
+  html: string;
+}
+export interface GetEmailOptions {
+  maxWaitTime?: number;
+  waitInterval?: number;
+  logPolling?: boolean;
+  deleteAfterRead?: boolean;
+}
+
+/**
+ * Retrieves the latest message from the inbox.
+ *
+ * If messages are available, this function fetches the first one and
+ * returns its details. Polling options can be specified to wait for
+ * messages if the inbox is empty. Optionally, the message can be
+ * deleted after reading.
+ *
+ * @param {GetEmailOptions} [options] - Optional settings for polling and deletion.
+ * @returns {Promise<MessageContent | null>} The email content (sender, recipient, subject, text, HTML), or `null` if no messages are found.
+ *
+ * @throws {Error} If no messages are available within the polling timeout or authentication fails.
+ *
+ * @example
+ * const message = await getRecentEmail({ maxWaitTime: 5000, waitInterval: 1000, logPolling: true });
+ * console.log(message.subject); // Outputs: "Hello!"
+ */
+export const getRecentEmail = async (
+  options?: GetEmailOptions
+): Promise<MessageContent | null> => {
+  const token = getToken();
+  const {
+    maxWaitTime = 30000,
+    waitInterval = 2000,
+    logPolling = false,
+    deleteAfterRead = false,
+  } = options || {};
+  if (!token)
+    throw new Error('Authentication required. Call createInbox() first.');
+
+  if (!options) {
+    const messages = await fetchMessages();
+    if (messages.length === 0) throw new Error('No messages available');
+    const messageId = messages[0].id;
+    const { from, to, subject, intro, text, html } = await fetchMessageContent(
+      messageId
+    );
+    if (deleteAfterRead) {
+      await deleteMessage(messageId);
+    }
+    return {
+      from: from.address,
+      to: to[0].address,
+      subject,
+      intro,
+      text,
+      html,
+    };
+  }
+
+  const startTime = Date.now();
+
+  if (logPolling) {
+    console.log(
+      `Polling started with a timeout of ${
+        maxWaitTime / 1000
+      }sec and interval of ${waitInterval / 1000}sec.`
+    );
+  }
+  while (Date.now() - startTime < maxWaitTime) {
+    const messages = await fetchMessages();
+    if (messages.length > 0) {
+      if (logPolling) {
+        console.log(`Found ${messages.length} message(s), fetching details...`);
+      }
+      const messageId = messages[0].id;
+      if (logPolling) {
+        console.log(`Message retrieved: ${messageId}`);
+      }
+      const { from, to, subject, intro, text, html } =
+        await fetchMessageContent(messageId);
+
+      if (deleteAfterRead) {
+        await deleteMessage(messageId);
+      }
+      return {
+        from: from.address,
+        to: to[0].address,
+        subject,
+        intro,
+        text,
+        html,
+      };
+    }
+    await new Promise((resolve) => setTimeout(resolve, waitInterval));
+    if (logPolling) {
+      console.log(
+        `No messages found, waiting for ${waitInterval / 1000} seconds...`
+      );
+    }
+  }
+  if (logPolling) {
+    console.log(
+      `Waiting timeout of ${
+        maxWaitTime / 1000
+      } seconds reached. No messages found.`
+    );
+  }
+  throw new Error(
+    `No messages available within ${maxWaitTime / 1000} seconds timeout`
+  );
+};
+
+/**
+ * Deletes a message by its unique ID from the Mail.tm inbox.
+ *
+ * This function requires a valid authentication token. If the
+ * token is not set, an error is thrown. The message is deleted
+ * using the Mail.tm API, and a success or failure message is logged.
+ *
+ * @param {string} messageId - The unique ID of the message to delete.
+ * @returns {Promise<void>} Resolves after the message is deleted.
+ *
+ * @throws {Error} If authentication is missing or the deletion fails.
+ *
+ * @example
+ * await deleteMessage("12345");
+ * console.log("Message deleted successfully.");
+ */
+export const deleteMessage = async (messageId: string): Promise<void> => {
+  const token = getToken();
+  if (!token)
+    throw new Error('Authentication required. Call createInbox() first.');
+
+  try {
+    await axios.delete(`${BASE_URL}/messages/${messageId}`, {
+      headers: {
+        accept: '*/*',
+        Authorization: `Bearer ${token}`,
+      },
+    });
+  } catch (error) {
+    console.error(`Failed to delete message with ID ${messageId}: ${error}`);
+  }
+};

package/src/utils/api.ts

@@ -0,0 +1,40 @@
+import axios from 'axios';
+import { BASE_URL } from './constant';
+import { getToken } from '../services/authService';
+
+export const getAuthHeaders = () => {
+  const token = getToken();
+  if (!token) {
+    throw new Error('Authentication required. Token not found.');
+  }
+  return {
+    accept: 'application/json',
+    Authorization: `Bearer ${token}`,
+  };
+};
+
+export const fetchMessages = async (): Promise<any[]> => {
+  try {
+    const res = await axios.get(`${BASE_URL}/messages`, {
+      headers: getAuthHeaders(),
+    });
+    console.log(JSON.stringify(res.data));
+
+    return res.data;
+  } catch (error) {
+    console.error('Error fetching messages:', error);
+    throw new Error('Failed to fetch messages. Please try again later.');
+  }
+};
+
+export const fetchMessageContent = async (messageId: string): Promise<any> => {
+  try {
+    const res = await axios.get(`${BASE_URL}/messages/${messageId}`, {
+      headers: getAuthHeaders(),
+    });
+    return res.data;
+  } catch (error) {
+    console.error(`Error fetching message content for ID ${messageId}:`, error);
+    throw new Error('Failed to fetch message content. Please try again later.');
+  }
+};

package/src/utils/constant.ts

@@ -0,0 +1,4 @@
+import * as dotenv from 'dotenv';
+dotenv.config();
+
+export const BASE_URL = process.env.BASE_URL;

package/src/utils/delay.ts

@@ -0,0 +1,2 @@
+export const delay = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));

package/src/utils/generateRandomName.ts

@@ -0,0 +1,2 @@
+export const generateRandomName = (): string =>
+  Math.random().toString(36).substring(2, 15);

package/src/utils/getVerificationCode.ts

@@ -0,0 +1,27 @@
+/**
+ * Extracts a verification code from the provided email content.
+ *
+ * This function scans the given text for a sequence of 5 or more
+ * consecutive digits and returns the first valid verification code.
+ * If no valid sequence is found, the function returns `null`.
+ *
+ * @param {string} text - The content of the email, typically the body.
+ * @returns {Promise<string | null>} The first verification code found, or `null` if no valid code exists.
+ *
+ * @example
+ * const emailContent = "Your code is 123456.";
+ * const verificationCode = await getVerificationCode(emailContent);
+ * console.log(verificationCode); // Output: "123456"
+ */
+
+export const getVerificationCode = async (
+  text: string
+): Promise<string | null> => {
+  console.log('Extracting the verification code from the email content...');
+  const matches = text.match(/\b\d{5,}\b/);
+  if (matches) {
+    return matches[0];
+  }
+  console.warn('No verification code found in the provided email content.');
+  return null;
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES6",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "emitDeclarationOnly": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "tests"]
+}