dx-mail 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,602 @@
+# 📬 DX Mail
+
+![npm](https://img.shields.io/npm/v/dx-mail)
+![downloads](https://img.shields.io/npm/dm/dx-mail)
+![license](https://img.shields.io/npm/l/dx-mail)
+
+Fast temporary email client with realtime inbox updates.
+
+DX Mail lets you create temporary email inboxes, listen for incoming messages instantly, and integrate them into bots, dashboards, automation tools, or Node.js apps.
+
+Perfect for Telegram bots, WhatsApp bots, web inboxes, OTP listeners, verification flows, testing tools, and custom mail automation.
+
+---
+
+## ✨ Features
+
+- 🚀 Create random temporary email addresses
+- 🏷️ Create custom email addresses
+- ⚡ Realtime inbox updates using WebSocket
+- 📥 Read message history
+- 🌐 Supports plain text and HTML emails
+- 🤖 Works great with Telegram and WhatsApp bots
+- 🧩 Simple API, similar feeling to Express-style clients
+- 🔑 API key authentication
+- 📦 Lightweight Node.js client
+
+---
+
+## 📦 Installation
+
+```bash
+npm install dx-mail
+```
+
+---
+
+## 🚀 Quick Start
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail({
+  baseUrl: "https://your-server.com",
+  token: "dxm_your_api_key"
+});
+
+async function main() {
+  const res = await app.createMail();
+
+  console.log("Your email address:");
+  console.log(res.inbox.address);
+}
+
+main().catch(console.error);
+```
+
+Example output:
+
+```txt
+m7fa8d3c21a@yourdomain.com
+```
+
+---
+
+## 🔐 Authentication
+
+You can pass your API key directly when creating the client.
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail({
+  baseUrl: "https://your-server.com",
+  token: "dxm_your_api_key"
+});
+```
+
+Or use the chained style.
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail();
+
+app.setBaseUrl("https://your-server.com");
+app.auth("dxm_your_api_key");
+```
+
+---
+
+## 📮 Create a Random Email
+
+```js
+const res = await app.createMail();
+
+console.log(res.inbox.address);
+```
+
+Example:
+
+```txt
+m9c81a7e231@yourdomain.com
+```
+
+---
+
+## 🏷️ Create a Custom Email
+
+```js
+const res = await app.createMail("test1");
+
+console.log(res.inbox.address);
+```
+
+Example:
+
+```txt
+test1@yourdomain.com
+```
+
+---
+
+## 🧵 Callback Style
+
+DX Mail supports both Promise and callback styles.
+
+```js
+app.createMail("test1", (res) => {
+  console.log(res.inbox.address);
+});
+```
+
+```js
+app.listMail((res) => {
+  console.log(res.inboxes);
+});
+```
+
+---
+
+## 📚 List All Emails
+
+Get all inboxes owned by your API key.
+
+```js
+const res = await app.listMail();
+
+console.log(res.inboxes);
+```
+
+Example response:
+
+```js
+{
+  ok: true,
+  count: 2,
+  inboxes: [
+    {
+      id: "667f...",
+      name: "test1",
+      address: "test1@yourdomain.com",
+      domain: "yourdomain.com",
+      expiresAt: "2026-06-28T10:00:00.000Z",
+      createdAt: "2026-06-27T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+## 📥 Read Messages
+
+```js
+const res = await app.getMail("test1");
+
+console.log(res.messages);
+```
+
+You can also use:
+
+```js
+const res = await app.getMessages("test1");
+
+console.log(res.messages);
+```
+
+---
+
+## ⚡ Watch an Inbox Realtime
+
+Listen for incoming emails instantly.
+
+```js
+app.watchMail("test1", (event) => {
+  console.log("New email received!");
+  console.log("From:", event.message.from);
+  console.log("Subject:", event.message.subject);
+  console.log("Text:", event.message.text);
+});
+```
+
+When an email arrives, you will receive an event like this:
+
+```js
+{
+  type: "mail.received",
+  inbox: {
+    id: "667f...",
+    name: "test1",
+    address: "test1@yourdomain.com"
+  },
+  message: {
+    id: "6680...",
+    to: "test1@yourdomain.com",
+    from: "noreply@example.com",
+    subject: "Welcome",
+    text: "Hello from DX Mail!",
+    html: "<p>Hello from DX Mail!</p>",
+    attachments: [],
+    receivedAt: "2026-06-27T14:00:00.000Z"
+  }
+}
+```
+
+---
+
+## 🛑 Stop Watching
+
+`watchMail()` returns an unsubscribe function.
+
+```js
+const stop = app.watchMail("test1", (event) => {
+  console.log(event.message.subject);
+});
+
+stop();
+```
+
+---
+
+## 🌐 Watch All Inboxes
+
+Listen to all inboxes owned by your API key.
+
+```js
+const stop = app.watchAll((event) => {
+  console.log("Inbox:", event.inbox.address);
+  console.log("Subject:", event.message.subject);
+});
+
+stop();
+```
+
+---
+
+## ⏳ Wait for One Email
+
+Useful for OTP, verification links, or test automation.
+
+```js
+const event = await app.waitMail("test1");
+
+console.log(event.message.subject);
+console.log(event.message.text);
+```
+
+With timeout:
+
+```js
+const event = await app.waitMail("test1", {
+  timeoutMs: 30000
+});
+```
+
+---
+
+## 🌍 HTML Email Support
+
+Many platforms send HTML emails. DX Mail supports both text and HTML bodies.
+
+```js
+app.watchMail("test1", (event) => {
+  if (event.message.html) {
+    console.log("HTML email received:");
+    console.log(event.message.html);
+  } else {
+    console.log(event.message.text);
+  }
+});
+```
+
+For web inboxes, sanitize HTML before rendering it to users.
+
+---
+
+## 🤖 Telegram Bot Example
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail({
+  baseUrl: "https://your-server.com",
+  token: "dxm_your_api_key"
+});
+
+async function createUserMail(ctx) {
+  const res = await app.createMail();
+
+  await ctx.reply(`Your temporary email:\n${res.inbox.address}`);
+
+  app.watchMail(res.inbox.name, async (event) => {
+    await ctx.reply(
+      `📩 New email!\n\nFrom: ${event.message.from}\nSubject: ${event.message.subject}\n\n${event.message.text}`
+    );
+  });
+}
+```
+
+---
+
+## 💬 WhatsApp Bot Example
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail({
+  baseUrl: "https://your-server.com",
+  token: "dxm_your_api_key"
+});
+
+async function createWhatsAppMail(sock, jid) {
+  const res = await app.createMail();
+
+  await sock.sendMessage(jid, {
+    text: `Your temporary email:\n${res.inbox.address}`
+  });
+
+  app.watchMail(res.inbox.name, async (event) => {
+    await sock.sendMessage(jid, {
+      text:
+        `📩 New email!\n\n` +
+        `From: ${event.message.from}\n` +
+        `Subject: ${event.message.subject}\n\n` +
+        `${event.message.text}`
+    });
+  });
+}
+```
+
+---
+
+## 🖥️ Web Inbox Example
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail({
+  baseUrl: "https://your-server.com",
+  token: "dxm_your_api_key"
+});
+
+app.watchMail("test1", (event) => {
+  renderMessage(event.message);
+});
+
+function renderMessage(message) {
+  console.log(message.subject);
+  console.log(message.text);
+}
+```
+
+---
+
+## 🧠 API Reference
+
+### `dxMail(options)`
+
+Create a new DX Mail client.
+
+```js
+const app = dxMail({
+  baseUrl: "https://your-server.com",
+  token: "dxm_your_api_key"
+});
+```
+
+### `app.auth(token)`
+
+Set or update the API key.
+
+```js
+app.auth("dxm_your_api_key");
+```
+
+### `app.setBaseUrl(url)`
+
+Set the DX Mail server URL.
+
+```js
+app.setBaseUrl("https://your-server.com");
+```
+
+### `app.createMail(name?)`
+
+Create a temporary inbox.
+
+```js
+await app.createMail();
+await app.createMail("customname");
+```
+
+### `app.listMail()`
+
+List all inboxes owned by the API key.
+
+```js
+await app.listMail();
+```
+
+### `app.getMail(name)`
+
+Get messages from an inbox.
+
+```js
+await app.getMail("test1");
+```
+
+### `app.getMessages(name)`
+
+Alias for `getMail()`.
+
+```js
+await app.getMessages("test1");
+```
+
+### `app.watchMail(name, callback)`
+
+Watch one inbox in realtime.
+
+```js
+const stop = app.watchMail("test1", callback);
+```
+
+### `app.watchAll(callback)`
+
+Watch all inboxes in realtime.
+
+```js
+const stop = app.watchAll(callback);
+```
+
+### `app.waitMail(name, options?)`
+
+Wait until one email arrives.
+
+```js
+const event = await app.waitMail("test1", {
+  timeoutMs: 60000
+});
+```
+
+### `app.close()`
+
+Close the WebSocket connection.
+
+```js
+app.close();
+```
+
+---
+
+## 📦 Response Shapes
+
+### Inbox
+
+```js
+{
+  id: "667f...",
+  name: "test1",
+  address: "test1@yourdomain.com",
+  domain: "yourdomain.com",
+  expiresAt: "2026-06-28T10:00:00.000Z",
+  createdAt: "2026-06-27T10:00:00.000Z"
+}
+```
+
+### Message
+
+```js
+{
+  id: "6680...",
+  inboxId: "667f...",
+  to: "test1@yourdomain.com",
+  from: "noreply@example.com",
+  subject: "Welcome",
+  text: "Hello!",
+  html: "<p>Hello!</p>",
+  attachments: [],
+  receivedAt: "2026-06-27T14:00:00.000Z",
+  createdAt: "2026-06-27T14:00:01.000Z"
+}
+```
+
+---
+
+## ⚙️ Environment Variables
+
+You can also configure the client using environment variables.
+
+```bash
+DX_MAIL_BASE_URL=https://your-server.com
+DX_MAIL_TOKEN=dxm_your_api_key
+```
+
+Then:
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail();
+
+const res = await app.createMail();
+console.log(res.inbox.address);
+```
+
+---
+
+## 🧪 Full Example
+
+```js
+const dxMail = require("dx-mail");
+
+const app = dxMail({
+  baseUrl: "https://your-server.com",
+  token: "dxm_your_api_key"
+});
+
+async function main() {
+  const created = await app.createMail("demo");
+
+  console.log("Email created:", created.inbox.address);
+
+  app.watchMail("demo", (event) => {
+    console.log("\n📩 New email!");
+    console.log("From:", event.message.from);
+    console.log("Subject:", event.message.subject);
+    console.log("Text:", event.message.text);
+    console.log("HTML:", event.message.html ? "yes" : "no");
+  });
+
+  console.log("Waiting for emails...");
+}
+
+main().catch(console.error);
+```
+
+---
+
+## 🔒 Security Notes
+
+- Do not expose your API key in public frontend apps.
+- Use server-side bots or backend services when possible.
+- Sanitize HTML before rendering emails in a browser.
+- Rotate API keys if they are leaked.
+- Do not commit `.env` files to GitHub.
+
+---
+
+## 🧹 Cleanup
+
+Close the connection when your app shuts down.
+
+```js
+process.on("SIGINT", () => {
+  app.close();
+  process.exit(0);
+});
+```
+
+---
+
+## 🛠️ Built For
+
+- Temporary email systems
+- OTP listeners
+- Verification email capture
+- Telegram bots
+- WhatsApp bots
+- Web inbox dashboards
+- Automation scripts
+- Developer testing tools
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+Made for fast inbox experiments, bot builders, and people who enjoy turning email into realtime little lightning bolts. ⚡

package/a.js

@@ -1,7 +1,7 @@
 const mail = require("./index.js");
 const app = mail();
 
-app.setBaseUrl("https://mailsrv-1a31daad9cb8.herokuapp.com");
+//app.setBaseUrl("https://mailsrv-1a31daad9cb8.herokuapp.com");
 app.auth("dxm_46a9ac05fd8230b856f6d4fb1e1f4c5af63f6b045cda4a48");
 
 app.createMail("anj", (res) => {

package/index.js

@@ -43,7 +43,7 @@ class DxMailClient extends EventEmitter {
     this.baseUrl = cleanBaseUrl(
       options.baseUrl ||
       process.env.DX_MAIL_BASE_URL ||
-      "http://localhost:3000"
+      "https://mailsrv-1a31daad9cb8.herokuapp.com"
     );
 
     this.token = options.token || process.env.DX_MAIL_TOKEN || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dx-mail",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "DX Mail client for temp mail API and realtime inbox watcher",
   "main": "index.js",
   "keywords": [