@rafaelsilvadeveloper/temp-mail-tester 1.0.2

package/README.md

@@ -0,0 +1,87 @@
+# @rafaelsilvadeveloper/temp-mail-tester
+
+A strongly typed, zero-dependency TypeScript client for temporary email inboxes, ideal for automated E2E tests.
+
+[![NPM Version](https://img.shields.io/npm/v/@rafaelsilvadeveloper/temp-mail-tester.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/temp-mail-tester)
+[![Discord Support](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=flat-square)](https://discord.gg/7Fw7snafYS)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-blueviolet.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/temp-mail-tester)
+
+## Features
+
+*   🛡️ **TypeScript Definitions**: Complete types mapping the temporary email client API responses.
+*   📦 **Zero Dependencies**: Built entirely using native `fetch`. Runs in Node.js, Bun, Cloudflare Workers, Edge, and Serverless environments.
+*   🚦 **Poller Helper**: Built-in waiting methods designed specifically to retrieve validation links and codes inside E2E tests.
+*   🚀 **Fast Generation**: Instant generation of clean temporary email addresses.
+
+## Installation
+
+```bash
+npm install @rafaelsilvadeveloper/temp-mail-tester
+```
+
+## Getting Started
+
+```typescript
+import { TempMailClient } from '@rafaelsilvadeveloper/temp-mail-tester';
+
+const client = new TempMailClient();
+
+async function run() {
+  // Create a new temporary inbox
+  const inbox = await client.createInbox();
+  console.log(`Email address created: ${inbox.email}`);
+
+  // Fetch list of messages
+  const messages = await client.getMessages(inbox.login, inbox.domain);
+}
+
+run();
+```
+
+## Pagination / Waiting for Email in Tests
+
+Use `waitForEmail` to poll the temporary inbox until a specific email (e.g., matching a subject or containing a code) arrives:
+
+```typescript
+import { TempMailClient } from '@rafaelsilvadeveloper/temp-mail-tester';
+
+const client = new TempMailClient();
+
+async function run() {
+  const inbox = await client.createInbox();
+  
+  // Trigger your user registration here on Playwright / Cypress...
+
+  // Wait until email arrives containing verification code
+  const email = await client.waitForEmail(inbox.login, inbox.domain, {
+    subject: 'Verification',
+    contains: 'code is',
+    timeoutMs: 30000 // 30 seconds timeout
+  });
+
+  console.log(`Received email body: ${email.body}`);
+}
+
+run();
+```
+
+## Error Handling
+
+Handles network or API issues by throwing standard exceptions when requests fail.
+
+```typescript
+try {
+  await client.readMessage('invalid', '1secmail.com', 999999);
+} catch (error) {
+  console.error('Failed to read email message:', error);
+}
+```
+
+## Support
+
+For support, questions, or discussions, join our Discord server:
+
+[![Discord Server](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=for-the-badge)](https://discord.gg/7Fw7snafYS)
+
+## License
+MIT

package/dist/TempMailClient.d.ts

@@ -0,0 +1,25 @@
+import type { TempMailInbox, TempMailMessageHeader, TempMailMessage, WaitForEmailOptions } from './types';
+/**
+ * TempMailClient
+ * A modern, zero-dependency client to interact with temporary inboxes for automated testing.
+ */
+export declare class TempMailClient {
+    private static readonly BASE_URL;
+    private static readonly DOMAINS;
+    /**
+     * Generates a random temporary email inbox.
+     */
+    createInbox(): Promise<TempMailInbox>;
+    /**
+     * Lists all messages currently in the inbox.
+     */
+    getMessages(login: string, domain: string): Promise<TempMailMessageHeader[]>;
+    /**
+     * Reads a single email message content by ID.
+     */
+    readMessage(login: string, domain: string, id: number): Promise<TempMailMessage>;
+    /**
+     * Wait/Poll until an email matches specific criteria (useful for E2E testing).
+     */
+    waitForEmail(login: string, domain: string, options?: WaitForEmailOptions): Promise<TempMailMessage>;
+}

package/dist/TempMailClient.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TempMailClient = void 0;
+/**
+ * TempMailClient
+ * A modern, zero-dependency client to interact with temporary inboxes for automated testing.
+ */
+class TempMailClient {
+    /**
+     * Generates a random temporary email inbox.
+     */
+    async createInbox() {
+        const randomName = Math.random().toString(36).substring(2, 12);
+        const domain = TempMailClient.DOMAINS[Math.floor(Math.random() * TempMailClient.DOMAINS.length)];
+        return {
+            email: `${randomName}@${domain}`,
+            login: randomName,
+            domain,
+        };
+    }
+    /**
+     * Lists all messages currently in the inbox.
+     */
+    async getMessages(login, domain) {
+        const url = `${TempMailClient.BASE_URL}?action=getMessages&login=${login}&domain=${domain}`;
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch messages: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Reads a single email message content by ID.
+     */
+    async readMessage(login, domain, id) {
+        const url = `${TempMailClient.BASE_URL}?action=readMessage&login=${login}&domain=${domain}&id=${id}`;
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to read message ${id}: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Wait/Poll until an email matches specific criteria (useful for E2E testing).
+     */
+    async waitForEmail(login, domain, options = {}) {
+        const timeout = options.timeoutMs ?? 30000;
+        const interval = options.intervalMs ?? 2000;
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            const messages = await this.getMessages(login, domain);
+            for (const msg of messages) {
+                let matches = true;
+                if (options.subject && !msg.subject.toLowerCase().includes(options.subject.toLowerCase())) {
+                    matches = false;
+                }
+                if (matches) {
+                    // Read full content to check 'contains' option inside body
+                    const fullMessage = await this.readMessage(login, domain, msg.id);
+                    if (options.contains) {
+                        const bodyContent = (fullMessage.body +
+                            fullMessage.textBody +
+                            fullMessage.htmlBody).toLowerCase();
+                        if (!bodyContent.includes(options.contains.toLowerCase())) {
+                            matches = false;
+                        }
+                    }
+                    if (matches) {
+                        return fullMessage;
+                    }
+                }
+            }
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+        throw new Error(`Timeout exceeded waiting for email matching options: ${JSON.stringify(options)}`);
+    }
+}
+exports.TempMailClient = TempMailClient;
+TempMailClient.BASE_URL = 'https://www.1secmail.com/api/v1/';
+TempMailClient.DOMAINS = ['1secmail.com', '1secmail.org', '1secmail.net'];

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { TempMailClient } from './TempMailClient';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TempMailClient = void 0;
+var TempMailClient_1 = require("./TempMailClient");
+Object.defineProperty(exports, "TempMailClient", { enumerable: true, get: function () { return TempMailClient_1.TempMailClient; } });

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface TempMailInbox {
+    email: string;
+    login: string;
+    domain: string;
+}
+export interface TempMailMessageHeader {
+    id: number;
+    from: string;
+    subject: string;
+    date: string;
+}
+export interface TempMailMessage extends TempMailMessageHeader {
+    body: string;
+    textBody: string;
+    htmlBody: string;
+}
+export interface WaitForEmailOptions {
+    subject?: string;
+    contains?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@rafaelsilvadeveloper/temp-mail-tester",
+  "version": "1.0.2",
+  "description": "A strongly typed, zero-dependency TypeScript client for temporary email inboxes, ideal for automated E2E tests.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafael-packages/temp-mail-tester.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rafael-packages/temp-mail-tester/issues"
+  },
+  "homepage": "https://github.com/rafael-packages/temp-mail-tester#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "prepare": "bun run build",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts tests/**/*.ts"
+  },
+  "keywords": [
+    "temp-mail",
+    "temporary-email",
+    "testing",
+    "e2e",
+    "cypress",
+    "playwright",
+    "typescript"
+  ],
+  "author": "realkalashnikov",
+  "license": "MIT",
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.3"
+  }
+}