@volcanicminds/tools 0.0.3 → 0.0.4

package/README.md

@@ -19,46 +19,120 @@ npm install @volcanicminds/tools
 npm run upgrade-deps
 ```
 
-## Environment
-
-```bash
-# or automatically use LOG_LEVEL
-SOME_KEY=true
-```
-
 ## Usage
 
-This package supports both root imports and sub-path imports to optimize bundle size.
-
-### Import everything
-
-```typescript
-import { mfa, log } from '@volcanicminds/tools'
-```
+This package supports both root imports and sub-path imports to optimize bundle size and tree-shaking.
 
-### Import specific features (Recommended for smaller bundles)
+### Import specific features (Recommended)
 
 ```typescript
 import * as mfa from '@volcanicminds/tools/mfa'
+import { Mailer } from '@volcanicminds/tools/mailer'
 import * as logger from '@volcanicminds/tools/logger'
 ```
 
+---
+
 ## Features
 
 ### MFA (Multi-Factor Authentication)
 
-Utilities for generating secrets, QR codes, and verifying TOTP tokens.
+Utilities for generating secrets, QR codes, and verifying TOTP tokens based on `otpauth`.
 
 ```typescript
 import * as mfa from '@volcanicminds/tools/mfa'
 
-// Generate Setup
-const { secret, uri, qrCode } = await mfa.generateSetupDetails('MyApp', 'user@example.com')
+// 1. Generate a generic base32 secret (Optional, useful if you need to store it before setup)
+const secret = mfa.generateSecret()
+
+// 2. Generate Setup Details for the User (returns secret, otpauth URI, and QR Code Data URL)
+// If secret is omitted, a new one is generated automatically.
+const setup = await mfa.generateSetupDetails('MyApp', 'user@example.com', secret)
+
+console.log(setup.secret) // Save this to DB
+console.log(setup.qrCode) // Send this to Frontend to display QR
+
+// 3. Verify a Token provided by the user
+const userToken = '123456' // From input
+const isValid = mfa.verifyToken(userToken, setup.secret)
 
-// Verify Token
-const isValid = mfa.verifyToken('123456', secret)
+if (isValid) {
+  // Proceed with login/action
+}
+
+// 4. Generate a valid token (Useful for testing or recovery codes)
+const currentToken = mfa.generateToken(setup.secret)
 ```
 
-## Logging
+---
+
+### Mailer
+
+A wrapper around `nodemailer` designed for simplicity and configuration injection. It automatically handles HTML-to-Text conversion if the text body is missing.
 
-Use Pino logger if in your project you have a `global.log` with a valid instance.
+#### Configuration & Initialization
+
+```typescript
+import { Mailer } from '@volcanicminds/tools/mailer'
+
+// Initialize with a config object (not bound to process.env)
+const mailer = new Mailer({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false, // true for 465, false for other ports
+  auth: {
+    user: 'my-user',
+    pass: 'my-password'
+  },
+  defaultFrom: '"My Service" <noreply@example.com>', // Optional: used if not specified in send()
+  defaultReplyTo: 'support@example.com' // Optional
+})
+
+// Optional: Verify connection on startup
+const isConnected = await mailer.verifyConnection()
+if (isConnected) console.log('SMTP Ready')
+```
+
+#### Sending Emails
+
+```typescript
+try {
+  const info = await mailer.send({
+    // Optional if defaultFrom is set in config, otherwise Mandatory
+    from: '"Support Team" <support@example.com>',
+
+    to: 'user@destination.com', // Can be a string or array of strings
+    cc: ['manager@destination.com'],
+    subject: 'Welcome to Volcanic Tools',
+
+    // Text version is automatically generated from HTML if omitted,
+    // converting <br> to newlines and stripping tags.
+    text: 'Hello, World! Welcome aboard.',
+    html: '<p>Hello, <strong>World</strong>!<br/>Welcome aboard.</p>',
+
+    attachments: [
+      {
+        filename: 'license.txt',
+        content: 'MIT License...'
+      }
+    ]
+  })
+
+  console.log('Message sent: %s', info.messageId)
+} catch (error) {
+  console.error('Error sending email:', error)
+}
+```
+
+---
+
+### Logging
+
+Use Pino logger wrapper if in your project you have a `global.log` with a valid instance.
+
+```typescript
+import * as log from '@volcanicminds/tools/logger'
+
+log.info('Application started')
+log.error({ err: new Error('Oops') }, 'Something went wrong')
+```

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * as mfa from './lib/mfa/index.js';
+export * as mailer from './lib/mailer/index.js';
 export * as log from './lib/util/logger.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export * as mfa from './lib/mfa/index.js';
+export * as mailer from './lib/mailer/index.js';
 export * as log from './lib/util/logger.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,KAAK,GAAG,MAAM,sBAAsB,CAAA"}

package/dist/lib/mailer/index.d.ts

@@ -0,0 +1,43 @@
+export interface MailerConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    defaultFrom?: string;
+    defaultReplyTo?: string;
+    tls?: {
+        rejectUnauthorized?: boolean;
+        ciphers?: string;
+    };
+}
+export interface MailAttachment {
+    filename: string;
+    content?: string | Buffer;
+    path?: string;
+    contentType?: string;
+    cid?: string;
+}
+export interface MailOptions {
+    to: string | string[];
+    subject: string;
+    html: string;
+    text?: string;
+    from?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    attachments?: MailAttachment[];
+}
+export declare class Mailer {
+    private transporter;
+    private defaultFrom?;
+    private defaultReplyTo?;
+    constructor(config: MailerConfig);
+    private stripHtml;
+    send(options: MailOptions): Promise<any>;
+    verifyConnection(): Promise<boolean>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/mailer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/mailer/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;IACD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,GAAG,CAAC,EAAE;QACJ,kBAAkB,CAAC,EAAE,OAAO,CAAA;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;CACF;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACtB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,cAAc,EAAE,CAAA;CAC/B;AAMD,qBAAa,MAAM;IACjB,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,WAAW,CAAC,CAAQ;IAC5B,OAAO,CAAC,cAAc,CAAC,CAAQ;gBAEnB,MAAM,EAAE,YAAY;IAqBhC,OAAO,CAAC,SAAS;IAcJ,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAwCxC,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;CASlD"}

package/dist/lib/mailer/index.js

@@ -0,0 +1,73 @@
+import nodemailer from 'nodemailer';
+export class Mailer {
+    transporter;
+    defaultFrom;
+    defaultReplyTo;
+    constructor(config) {
+        this.defaultFrom = config.defaultFrom;
+        this.defaultReplyTo = config.defaultReplyTo;
+        this.transporter = nodemailer.createTransport({
+            host: config.host,
+            port: config.port,
+            secure: config.secure ?? config.port === 465,
+            auth: config.auth
+                ? {
+                    user: config.auth.user,
+                    pass: config.auth.pass
+                }
+                : undefined,
+            tls: config.tls
+        });
+    }
+    stripHtml(html) {
+        if (!html)
+            return '';
+        return html
+            .replace(/<br\s*\/?>/gi, '\n')
+            .replace(/<\/p>/gi, '\n\n')
+            .replace(/<[^>]*>?/gm, '')
+            .trim();
+    }
+    async send(options) {
+        const from = options.from || this.defaultFrom;
+        const replyTo = options.replyTo || this.defaultReplyTo;
+        if (!from) {
+            throw new Error('Email "from" address is required (either in options or config.defaultFrom)');
+        }
+        const mailPayload = {
+            from,
+            to: Array.isArray(options.to) ? options.to.join(', ') : options.to,
+            subject: options.subject,
+            html: options.html,
+            text: options.text || this.stripHtml(options.html),
+            attachments: options.attachments
+        };
+        if (options.cc) {
+            mailPayload.cc = Array.isArray(options.cc) ? options.cc.join(', ') : options.cc;
+        }
+        if (options.bcc) {
+            mailPayload.bcc = Array.isArray(options.bcc) ? options.bcc.join(', ') : options.bcc;
+        }
+        if (replyTo) {
+            mailPayload.replyTo = replyTo;
+        }
+        try {
+            const info = await this.transporter.sendMail(mailPayload);
+            return info;
+        }
+        catch (error) {
+            throw new Error(`Failed to send email to ${mailPayload.to}: ${error.message}`);
+        }
+    }
+    async verifyConnection() {
+        try {
+            await this.transporter.verify();
+            return true;
+        }
+        catch (error) {
+            console.error('Mailer connection verification failed:', error);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/mailer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/mailer/index.ts"],"names":[],"mappings":"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"}

package/lib/mailer/index.ts

@@ -0,0 +1,132 @@
+import nodemailer, { Transporter, SendMailOptions } from 'nodemailer'
+
+export interface MailerConfig {
+  host: string
+  port: number
+  secure?: boolean // true for 465, false for other ports
+  auth?: {
+    user: string
+    pass: string
+  }
+  defaultFrom?: string
+  defaultReplyTo?: string
+  tls?: {
+    rejectUnauthorized?: boolean
+    ciphers?: string
+  }
+}
+
+export interface MailAttachment {
+  filename: string
+  content?: string | Buffer
+  path?: string
+  contentType?: string
+  cid?: string
+}
+
+export interface MailOptions {
+  to: string | string[]
+  subject: string
+  html: string
+  text?: string // If not provided, it will be generated from html
+  from?: string
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string
+  attachments?: MailAttachment[]
+}
+
+/**
+ * Mailer class wrapper around nodemailer.
+ * Designed to be tree-shakeable and configuration-driven without relying on process.env directly.
+ */
+export class Mailer {
+  private transporter: Transporter
+  private defaultFrom?: string
+  private defaultReplyTo?: string
+
+  constructor(config: MailerConfig) {
+    this.defaultFrom = config.defaultFrom
+    this.defaultReplyTo = config.defaultReplyTo
+
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.secure ?? config.port === 465, // Default secure if port is 465
+      auth: config.auth
+        ? {
+            user: config.auth.user,
+            pass: config.auth.pass
+          }
+        : undefined,
+      tls: config.tls
+    })
+  }
+
+  /**
+   * Helper to strip HTML tags for plain text fallback
+   */
+  private stripHtml(html: string): string {
+    if (!html) return ''
+    return html
+      .replace(/<br\s*\/?>/gi, '\n') // Replace <br> with newlines
+      .replace(/<\/p>/gi, '\n\n') // Replace </p> with double newlines
+      .replace(/<[^>]*>?/gm, '') // Remove all other tags
+      .trim()
+  }
+
+  /**
+   * Sends an email.
+   * @param options Mail options including to, subject, html, etc.
+   * @returns The info object from nodemailer.
+   */
+  public async send(options: MailOptions): Promise<any> {
+    const from = options.from || this.defaultFrom
+    const replyTo = options.replyTo || this.defaultReplyTo
+
+    if (!from) {
+      throw new Error('Email "from" address is required (either in options or config.defaultFrom)')
+    }
+
+    const mailPayload: SendMailOptions = {
+      from,
+      to: Array.isArray(options.to) ? options.to.join(', ') : options.to,
+      subject: options.subject,
+      html: options.html,
+      text: options.text || this.stripHtml(options.html),
+      attachments: options.attachments
+    }
+
+    if (options.cc) {
+      mailPayload.cc = Array.isArray(options.cc) ? options.cc.join(', ') : options.cc
+    }
+
+    if (options.bcc) {
+      mailPayload.bcc = Array.isArray(options.bcc) ? options.bcc.join(', ') : options.bcc
+    }
+
+    if (replyTo) {
+      mailPayload.replyTo = replyTo
+    }
+
+    try {
+      const info = await this.transporter.sendMail(mailPayload)
+      return info
+    } catch (error: any) {
+      throw new Error(`Failed to send email to ${mailPayload.to}: ${error.message}`)
+    }
+  }
+
+  /**
+   * Verifies the connection configuration.
+   */
+  public async verifyConnection(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch (error) {
+      console.error('Mailer connection verification failed:', error)
+      return false
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanicminds/tools",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Tools for the volcanic (minds) backend",
   "keywords": [
     "volcanic",
@@ -10,7 +10,9 @@
     "esm",
     "mfa",
     "otp",
-    "totp"
+    "totp",
+    "mailer",
+    "nodemailer"
   ],
   "homepage": "https://volcanicminds.com",
   "bugs": {
@@ -41,6 +43,11 @@
       "import": "./dist/lib/mfa/index.js",
       "require": "./dist/lib/mfa/index.js"
     },
+    "./mailer": {
+      "types": "./dist/lib/mailer/index.d.ts",
+      "import": "./dist/lib/mailer/index.js",
+      "require": "./dist/lib/mailer/index.js"
+    },
     "./logger": {
       "types": "./dist/lib/util/logger.d.ts",
       "import": "./dist/lib/util/logger.js",
@@ -69,12 +76,14 @@
     "combine": "node combine.js"
   },
   "dependencies": {
+    "nodemailer": "^6.10.1",
     "otpauth": "^9.3.5",
     "qrcode": "^1.5.4"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/node": "^24.10.1",
+    "@types/nodemailer": "^6.4.14",
     "@types/qrcode": "^1.5.5",
     "eslint": "^9.39.1",
     "globals": "^16.5.0",
@@ -95,6 +104,9 @@
       "mfa": [
         "dist/lib/mfa/index.d.ts"
       ],
+      "mailer": [
+        "dist/lib/mailer/index.d.ts"
+      ],
       "logger": [
         "dist/lib/util/logger.d.ts"
       ]