dx-mail 1.0.2 → 1.0.3

package/README.md

@@ -4,30 +4,39 @@
 ![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 powered by WebSocket.
+Fast temporary email client with realtime inbox updates.
 
-Create temporary emails, receive messages instantly, and integrate easily with Telegram bots, WhatsApp bots, web dashboards, or Node.js applications.
+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.
 
-✨ Features
+Perfect for Telegram bots, WhatsApp bots, web inboxes, OTP listeners, verification flows, testing tools, and custom mail automation.
 
-- 🚀 Create random or custom temporary email addresses
+---
+
+## ✨ Features
+
+- 🚀 Create random temporary email addresses
+- 🏷️ Create custom email addresses
 - ⚡ Realtime inbox updates using WebSocket
-- 📥 Fetch message history
-- 🤖 Perfect for Telegram and WhatsApp bots
-- 🌐 Works for web inbox applications
-- 🔑 API Key authentication
-- 📦 Lightweight and easy to use
+- 📥 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
+## 📦 Installation
 
+```bash
 npm install dx-mail
+```
 
 ---
 
-Quick Start
+## 🚀 Quick Start
 
+```js
 const dxMail = require("dx-mail");
 
 const app = dxMail({
@@ -38,198 +47,488 @@ const app = dxMail({
 async function main() {
   const res = await app.createMail();
 
-  console.log("Email:");
+  console.log("Your email address:");
   console.log(res.inbox.address);
 }
 
-main();
+main().catch(console.error);
+```
+
+Example output:
+
+```txt
+m7fa8d3c21a@yourdomain.com
+```
 
 ---
 
-Authentication
+## 🔐 Authentication
 
-Option 1
+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"
 });
+```
 
-Option 2
+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");
+```
 
 ---
 
-API
-
-createMail()
-
-Create a random email address.
+## 📮 Create a Random Email
 
+```js
 const res = await app.createMail();
 
 console.log(res.inbox.address);
+```
 
 Example:
 
-m7fa8d3c21a@danxy.web.id
+```txt
+m9c81a7e231@yourdomain.com
+```
 
 ---
 
-createMail(name)
-
-Create a custom email address.
+## 🏷️ Create a Custom Email
 
-const res = await app.createMail("test");
+```js
+const res = await app.createMail("test1");
 
 console.log(res.inbox.address);
+```
 
-Output:
+Example:
 
-test@danxy.web.id
+```txt
+test1@yourdomain.com
+```
 
 ---
 
-createMail(callback)
+## 🧵 Callback Style
 
-Callback style.
+DX Mail supports both Promise and callback styles.
 
-app.createMail((res) => {
+```js
+app.createMail("test1", (res) => {
   console.log(res.inbox.address);
 });
+```
 
----
-
-createMail(name, callback)
-
-app.createMail("test", (res) => {
-  console.log(res.inbox.address);
+```js
+app.listMail((res) => {
+  console.log(res.inboxes);
 });
+```
 
 ---
 
-listMail()
+## 📚 List All Emails
 
 Get all inboxes owned by your API key.
 
+```js
 const res = await app.listMail();
 
 console.log(res.inboxes);
+```
 
-Example:
+Example response:
 
-[
-  {
-    id: "...",
-    name: "test",
-    address: "test@danxy.web.id"
-  }
-]
+```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"
+    }
+  ]
+}
+```
 
 ---
 
-getMail(name)
+## 📥 Read Messages
+
+```js
+const res = await app.getMail("test1");
+
+console.log(res.messages);
+```
 
-Get message history.
+You can also use:
 
-const res = await app.getMail("test");
+```js
+const res = await app.getMessages("test1");
 
 console.log(res.messages);
+```
 
 ---
 
-watchMail(name)
+## ⚡ Watch an Inbox Realtime
 
-Receive emails instantly.
+Listen for incoming emails instantly.
 
-app.watchMail("test", (event) => {
-  console.log(event.message.subject);
-  console.log(event.message.text);
+```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);
 });
+```
 
-Example:
+When an email arrives, you will receive an event like this:
 
-📩 New Email
-Subject: Hello
-Text: Welcome to DX Mail
+```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"
+  }
+}
+```
 
 ---
 
-HTML Emails
+## 🛑 Stop Watching
 
-DX Mail supports HTML emails.
+`watchMail()` returns an unsubscribe function.
 
-app.watchMail("test", (event) => {
-  console.log(event.message.html);
+```js
+const stop = app.watchMail("test1", (event) => {
+  console.log(event.message.subject);
 });
 
-Useful for:
+stop();
+```
+
+---
 
-- OpenAI verification emails
-- GitHub notifications
-- Discord verification emails
-- Banking emails
-- Newsletter emails
-- OTP services
+## 🌐 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();
+```
 
 ---
 
-waitMail(name)
+## ⏳ Wait for One Email
 
-Wait until a new email arrives.
+Useful for OTP, verification links, or test automation.
 
-const event = await app.waitMail("test");
+```js
+const event = await app.waitMail("test1");
 
 console.log(event.message.subject);
+console.log(event.message.text);
+```
 
 With timeout:
 
-const event = await app.waitMail("test", {
+```js
+const event = await app.waitMail("test1", {
   timeoutMs: 30000
 });
+```
 
 ---
 
-watchAll()
+## 🌍 HTML Email Support
 
-Watch all inboxes owned by the API key.
+Many platforms send HTML emails. DX Mail supports both text and HTML bodies.
 
-app.watchAll((event) => {
-  console.log(event.inbox.address);
-  console.log(event.message.subject);
+```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}`
+    });
+  });
+}
+```
 
 ---
 
-close()
+## 🖥️ Web Inbox Example
 
-Close WebSocket connection.
+```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();
+```
 
 ---
 
-Message Object
+## 📦 Response Shapes
+
+### Inbox
 
+```js
 {
-  id: "...",
-  to: "test@danxy.web.id",
+  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: "Hello",
-  text: "Welcome!",
-  html: "<h1>Welcome!</h1>",
+  subject: "Welcome",
+  text: "Hello!",
+  html: "<p>Hello!</p>",
   attachments: [],
-  receivedAt: "2026-06-27T14:00:00.000Z"
+  receivedAt: "2026-06-27T14:00:00.000Z",
+  createdAt: "2026-06-27T14:00:01.000Z"
 }
+```
 
 ---
 
-Telegram Example
+## ⚙️ 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({
@@ -237,37 +536,67 @@ const app = dxMail({
   token: "dxm_your_api_key"
 });
 
-const inbox = await app.createMail();
+async function main() {
+  const created = await app.createMail("demo");
+
+  console.log("Email created:", created.inbox.address);
 
-app.watchMail(inbox.inbox.name, (event) => {
-  bot.telegram.sendMessage(
-    chatId,
-    `📩 ${event.message.subject}\n\n${event.message.text}`
-  );
-});
+  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);
+```
 
 ---
 
-Web Dashboard Example
+## 🔒 Security Notes
 
-app.watchMail("test", (event) => {
-  renderMessage(event.message);
+- 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);
 });
+```
 
 ---
 
-Requirements
+## 🛠️ Built For
 
-- Node.js 18+
-- DX Mail Server
-- Valid API Key
+- Temporary email systems
+- OTP listeners
+- Verification email capture
+- Telegram bots
+- WhatsApp bots
+- Web inbox dashboards
+- Automation scripts
+- Developer testing tools
 
 ---
 
-License
+## 📄 License
 
 MIT
 
 ---
 
-Made with ❤️ for developers who need fast temporary emails and realtime inbox updates.
+Made for fast inbox experiments, bot builders, and people who enjoy turning email into realtime little lightning bolts. ⚡

package/package.json

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