npm - universal-mailer-lib - Versions diffs - 2.0.2 - Mend

universal-mailer-lib 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +246 -0
package/dist/gmail-mailer.d.ts +60 -0
package/dist/gmail-mailer.js +154 -0
package/dist/index.d.ts +5 -0
package/dist/index.js +3 -0
package/dist/mime-builder.d.ts +33 -0
package/dist/mime-builder.js +43 -0
package/dist/template.d.ts +24 -0
package/dist/template.js +31 -0
package/dist/universal-mailer.d.ts +114 -0
package/dist/universal-mailer.js +317 -0
package/package.json +75 -0

package/README.md ADDED Viewed

@@ -0,0 +1,246 @@
+# universal-mailer-lib
+> Universal email client. Supports SMTP, Gmail API, and IMAP/POP3.
+## Install
+```bash
+npm install universal-mailer-lib
+```
+Requires peer dependencies: `googleapis`, `nodemailer`, `handlebars`, `imapflow`, `mailparser`
+```bash
+npm install universal-mailer-lib googleapis nodemailer handlebars imapflow mailparser
+```
+## Quick Start
+```typescript
+import { UniversalMailer } from 'universal-mailer-lib'
+const mailer = new UniversalMailer({
+  transport: 'smtp',
+  smtp: {
+    host: 'smtp.gmail.com',
+    port: 465,
+    secure: true,
+    auth: {
+      user: 'you@gmail.com',
+      pass: 'your-app-password',
+    },
+  },
+})
+const result = await mailer.sendEmail({
+  from: 'you@gmail.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from gmail-mailer',
+  html: '<h1>Hello World</h1><p>This is a test email.</p>',
+})
+console.log(result.messageId) // Gmail message ID
+```
+## OAuth2 Setup
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project and enable the **Gmail API**
+3. Create **OAuth 2.0 credentials** (Desktop app type)
+4. Get your `clientId` and `clientSecret`
+5. Obtain a `refreshToken` using [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)
+   - Select scope: `https://www.googleapis.com/auth/gmail.send`
+   - Authorize and exchange for tokens
+## Features
+### HTML Email
+```typescript
+await mailer.sendEmail({
+  from: 'you@gmail.com',
+  to: 'user@example.com',
+  subject: 'HTML Email',
+  html: `
+    <html>
+      <body>
+        <h1>Welcome!</h1>
+        <p>This is an <strong>HTML</strong> email.</p>
+      </body>
+    </html>
+  `,
+})
+```
+### Plain Text Email
+```typescript
+await mailer.sendEmail({
+  from: 'you@gmail.com',
+  to: 'user@example.com',
+  subject: 'Text Email',
+  text: 'This is a plain text email.',
+})
+```
+### Template Email (Handlebars)
+```typescript
+import { GmailMailer } from 'gmail-mailer'
+const mailer = new GmailMailer({ clientId, clientSecret, refreshToken })
+const result = await mailer.sendEmail({
+  from: 'noreply@yourapp.com',
+  to: 'user@example.com',
+  subject: 'Welcome, {{name}}!',
+  template: `
+    <h1>Hello {{name}}</h1>
+    <p>Your account has been created.</p>
+    <p>Verification code: <strong>{{code}}</strong></p>
+  `,
+  context: {
+    name: '王小明',
+    code: 'ABC123',
+  },
+})
+```
+### Email with Attachments
+```typescript
+import { GmailMailer } from 'gmail-mailer'
+import { readFileSync } from 'node:fs'
+const mailer = new GmailMailer({ clientId, clientSecret, refreshToken })
+await mailer.sendEmail({
+  from: 'you@gmail.com',
+  to: 'user@example.com',
+  subject: 'Report Attached',
+  html: '<p>Please find the attached report.</p>',
+  attachments: [
+    {
+      filename: 'report.pdf',
+      content: readFileSync('./report.pdf'),
+    },
+    {
+      filename: 'data.json',
+      content: JSON.stringify({ key: 'value' }),
+      contentType: 'application/json',
+    },
+  ],
+})
+```
+### CC, BCC, Reply-To
+```typescript
+await mailer.sendEmail({
+  from: 'you@gmail.com',
+  to: 'primary@example.com',
+  cc: 'manager@example.com',
+  bcc: 'archive@example.com',
+  replyTo: 'support@example.com',
+  subject: 'Important Update',
+  html: '<p>Please review the attached document.</p>',
+})
+```
+### Verify Connection
+```typescript
+const email = await mailer.verifyConnection()
+console.log(`Connected as: ${email}`) // your@gmail.com
+```
+## API Reference
+### `GmailMailer`
+#### Constructor
+```typescript
+new GmailMailer(config: OAuth2Config)
+```
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `clientId` | `string` | ✅ | Google OAuth2 client ID |
+| `clientSecret` | `string` | ✅ | Google OAuth2 client secret |
+| `refreshToken` | `string` | ✅ | OAuth2 refresh token |
+| `accessToken` | `string` | ❌ | Optional access token |
+#### `sendEmail(options)` → `Promise<SendResult>`
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `from` | `string` | ✅ | Sender email |
+| `to` | `string` | ✅ | Recipient email |
+| `cc` | `string` | ❌ | CC recipient |
+| `bcc` | `string` | ❌ | BCC recipient |
+| `replyTo` | `string` | ❌ | Reply-to address |
+| `subject` | `string` | ✅ | Email subject |
+| `text` | `string` | ❌ | Plain text body |
+| `html` | `string` | ❌ | HTML body |
+| `template` | `string` | ❌ | Handlebars template string |
+| `context` | `object` | ❌ | Template variables |
+| `attachments` | `Attachment[]` | ❌ | File attachments |
+**Returns:**
+```typescript
+{
+  messageId: string
+  threadId?: string
+  labelIds?: string[]
+}
+```
+#### `verifyConnection()` → `Promise<string>`
+Returns the authenticated user's email address.
+#### `getAccessToken()` → `Promise<string>`
+Returns the current OAuth2 access token (auto-refreshes if expired).
+### Utility Functions
+```typescript
+import { renderTemplate, registerTemplate, registerHelper } from 'gmail-mailer'
+// Render a Handlebars template
+const html = renderTemplate('<h1>Hello {{name}}</h1>', { name: 'World' })
+// Register a reusable partial
+registerTemplate('footer', '<footer>© 2026</footer>')
+// Register a custom helper
+registerHelper('upper', (text: string) => text.toUpperCase())
+```
+### MIME Builder
+```typescript
+import { buildRawMessage, buildMimeMessage } from 'gmail-mailer'
+// Build base64url encoded message (for Gmail API)
+const raw = await buildRawMessage({ from, to, subject, html })
+// Build raw Buffer (for SMTP or other transports)
+const buffer = await buildMimeMessage({ from, to, subject, html })
+```
+## Design
+| Feature | Why |
+|---------|-----|
+| Gmail API only | No SMTP needed, better security with OAuth2 |
+| OAuth2 auto-refresh | `google-auth-library` handles token refresh automatically |
+| Handlebars templates | Industry standard for email templating |
+| nodemailer MailComposer | Battle-tested MIME generation, no reinventing the wheel |
+| Zero SMTP | Bypasses SMTP entirely, uses Gmail REST API directly |
+## License
+MIT

package/dist/gmail-mailer.d.ts ADDED Viewed

@@ -0,0 +1,60 @@
+/**
+ * GmailMailer — Gmail API email sender with OAuth2 auto-refresh.
+ *
+ * Usage:
+ *   const mailer = new GmailMailer({ clientId, clientSecret, refreshToken })
+ *   const result = await mailer.sendEmail({ from, to, subject, html })
+ */
+import { type Attachment } from './mime-builder.js';
+export interface OAuth2Config {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    accessToken?: string;
+    redirectUri?: string;
+}
+export interface SendOptions {
+    from: string;
+    to: string;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+    subject: string;
+    text?: string;
+    html?: string;
+    template?: string;
+    context?: Record<string, unknown>;
+    attachments?: Attachment[];
+}
+export interface SendResult {
+    messageId: string;
+    threadId?: string;
+    labelIds?: string[];
+}
+export declare const GMAIL_SCOPES: string[];
+export declare class GmailMailer {
+    private oauth2Client;
+    constructor(config: OAuth2Config);
+    /**
+     * Ensure a valid access token is available (refreshes if needed).
+     */
+    private ensureAccessToken;
+    /**
+     * Manually refresh the access token using the refresh token.
+     * Use this if automatic refresh fails.
+     */
+    forceRefreshToken(): Promise<void>;
+    /**
+     * Send an email via Gmail API.
+     * Supports raw HTML, plain text, or Handlebars templates.
+     */
+    sendEmail(options: SendOptions): Promise<SendResult>;
+    /**
+     * Get the current OAuth2 access token (triggers refresh if needed).
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Verify OAuth2 credentials by fetching the Gmail user's profile.
+     */
+    verifyConnection(): Promise<string>;
+}

package/dist/gmail-mailer.js ADDED Viewed

@@ -0,0 +1,154 @@
+/**
+ * GmailMailer — Gmail API email sender with OAuth2 auto-refresh.
+ *
+ * Usage:
+ *   const mailer = new GmailMailer({ clientId, clientSecret, refreshToken })
+ *   const result = await mailer.sendEmail({ from, to, subject, html })
+ */
+import { google } from 'googleapis';
+import { renderTemplate } from './template.js';
+import { buildRawMessage } from './mime-builder.js';
+/**
+ * Redact sensitive information from error messages.
+ * Prevents accidental leakage of tokens, secrets, and emails.
+ */
+function redactSensitiveInfo(message) {
+    return message
+        .replace(/ya29\.[A-Za-z0-9_-]+/g, '[REDACTED_TOKEN]')
+        .replace(/1\/\/[A-Za-z0-9_-]+/g, '[REDACTED_REFRESH_TOKEN]')
+        .replace(/GOCSPX-[A-Za-z0-9_-]+/g, '[REDACTED_SECRET]')
+        .replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[REDACTED_EMAIL]');
+}
+export const GMAIL_SCOPES = ['https://www.googleapis.com/auth/gmail.send'];
+export class GmailMailer {
+    oauth2Client;
+    constructor(config) {
+        if (!config.clientId || !config.clientSecret || !config.refreshToken) {
+            throw new Error('OAuth2 config requires clientId, clientSecret, and refreshToken');
+        }
+        this.oauth2Client = new google.auth.OAuth2(config.clientId, config.clientSecret, config.redirectUri);
+        this.oauth2Client.setCredentials({
+            refresh_token: config.refreshToken,
+            access_token: config.accessToken,
+        });
+    }
+    /**
+     * Ensure a valid access token is available (refreshes if needed).
+     */
+    async ensureAccessToken() {
+        // Force a token refresh by calling getRequestHeaders which triggers the refresh flow
+        await this.oauth2Client.getRequestHeaders();
+    }
+    /**
+     * Manually refresh the access token using the refresh token.
+     * Use this if automatic refresh fails.
+     */
+    async forceRefreshToken() {
+        const credentials = this.oauth2Client.credentials;
+        const refreshToken = credentials.refresh_token;
+        if (!refreshToken) {
+            throw new Error('No refresh token available');
+        }
+        // Direct token refresh via Google's token endpoint
+        const tokenUrl = 'https://oauth2.googleapis.com/token';
+        const params = new URLSearchParams({
+            client_id: this.oauth2Client._clientId ?? '',
+            client_secret: this.oauth2Client._clientSecret ?? '',
+            refresh_token: refreshToken,
+            grant_type: 'refresh_token',
+        });
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Token refresh failed: ${redactSensitiveInfo(error)}`);
+        }
+        const data = await response.json();
+        this.oauth2Client.setCredentials({
+            access_token: data.access_token,
+            refresh_token: data.refresh_token ?? refreshToken,
+        });
+    }
+    /**
+     * Send an email via Gmail API.
+     * Supports raw HTML, plain text, or Handlebars templates.
+     */
+    async sendEmail(options) {
+        // Ensure we have a valid access token before sending
+        await this.ensureAccessToken();
+        const token = await this.getAccessToken();
+        let html = options.html;
+        let text = options.text;
+        // Render template if provided
+        if (options.template && options.context) {
+            html = renderTemplate(options.template, options.context);
+        }
+        if (!html && !text) {
+            throw new Error('Email requires html, text, or template');
+        }
+        // Build MIME message
+        const raw = await buildRawMessage({
+            from: options.from,
+            to: options.to,
+            cc: options.cc,
+            bcc: options.bcc,
+            replyTo: options.replyTo,
+            subject: options.subject,
+            text,
+            html,
+            attachments: options.attachments,
+        });
+        // Send via Gmail API using fetch directly
+        const response = await fetch('https://gmail.googleapis.com/gmail/v1/users/me/messages/send', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ raw }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Gmail API error (${response.status}): ${redactSensitiveInfo(errorText)}`);
+        }
+        const data = await response.json();
+        return {
+            messageId: data.id,
+            threadId: data.threadId,
+            labelIds: data.labelIds,
+        };
+    }
+    /**
+     * Get the current OAuth2 access token (triggers refresh if needed).
+     */
+    async getAccessToken() {
+        const token = await this.oauth2Client.getAccessToken();
+        if (!token.token) {
+            throw new Error('Failed to obtain access token');
+        }
+        return token.token;
+    }
+    /**
+     * Verify OAuth2 credentials by fetching the Gmail user's profile.
+     */
+    async verifyConnection() {
+        // Ensure we have a valid access token before verifying
+        await this.ensureAccessToken();
+        const token = await this.getAccessToken();
+        const response = await fetch('https://gmail.googleapis.com/gmail/v1/users/me/profile', {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Gmail profile error (${response.status}): ${redactSensitiveInfo(errorText)}`);
+        }
+        const data = await response.json();
+        if (!data.emailAddress) {
+            throw new Error('Could not retrieve user email');
+        }
+        return data.emailAddress;
+    }
+}

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export { UniversalMailer } from './universal-mailer.js';
+export type { MailerConfig, SendOptions, SendResult, FetchOptions, EmailMessage } from './universal-mailer.js';
+export { renderTemplate, registerTemplate, registerHelper } from './template.js';
+export { buildMimeMessage, buildRawMessage } from './mime-builder.js';
+export type { MimeOptions, Attachment } from './mime-builder.js';

package/dist/index.js ADDED Viewed

@@ -0,0 +1,3 @@
+export { UniversalMailer } from './universal-mailer.js';
+export { renderTemplate, registerTemplate, registerHelper } from './template.js';
+export { buildMimeMessage, buildRawMessage } from './mime-builder.js';

package/dist/mime-builder.d.ts ADDED Viewed

@@ -0,0 +1,33 @@
+/**
+ * MIME message builder using nodemailer's internal MailComposer.
+ * Generates RFC 2822 compliant email messages.
+ */
+export interface Attachment {
+    filename: string;
+    content: string | Buffer;
+    contentType?: string;
+}
+export interface MimeOptions {
+    from: string;
+    to: string;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+    subject: string;
+    text?: string;
+    html?: string;
+    attachments?: Attachment[];
+}
+/**
+ * Build a raw RFC 2822 email message.
+ * @param options - Email message options
+ * @returns Raw email buffer
+ */
+export declare function buildMimeMessage(options: MimeOptions): Promise<Buffer>;
+/**
+ * Build and encode a raw email message as base64url string.
+ * Required for Gmail API messages.send endpoint.
+ * @param options - Email message options
+ * @returns Base64url encoded string
+ */
+export declare function buildRawMessage(options: MimeOptions): Promise<string>;

package/dist/mime-builder.js ADDED Viewed

@@ -0,0 +1,43 @@
+/**
+ * MIME message builder using nodemailer's internal MailComposer.
+ * Generates RFC 2822 compliant email messages.
+ */
+import MailComposer from 'nodemailer/lib/mail-composer/index.js';
+/**
+ * Build a raw RFC 2822 email message.
+ * @param options - Email message options
+ * @returns Raw email buffer
+ */
+export async function buildMimeMessage(options) {
+    const mailOptions = {
+        from: options.from,
+        to: options.to,
+        cc: options.cc,
+        bcc: options.bcc,
+        replyTo: options.replyTo,
+        subject: options.subject,
+        text: options.text,
+        html: options.html,
+        attachments: options.attachments?.map(a => ({
+            filename: a.filename,
+            content: a.content,
+            contentType: a.contentType,
+        })),
+    };
+    const composer = new MailComposer(mailOptions);
+    return composer.compile().build();
+}
+/**
+ * Build and encode a raw email message as base64url string.
+ * Required for Gmail API messages.send endpoint.
+ * @param options - Email message options
+ * @returns Base64url encoded string
+ */
+export async function buildRawMessage(options) {
+    const buffer = await buildMimeMessage(options);
+    return buffer
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}

package/dist/template.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/**
+ * Handlebars template engine for email content.
+ * Pure function, no side effects.
+ */
+import Handlebars from 'handlebars';
+/**
+ * Register a Handlebars template by name.
+ * @param name - Template identifier
+ * @param source - Handlebars template string
+ */
+export declare function registerTemplate(name: string, source: string): void;
+/**
+ * Render a Handlebars template with context data.
+ * @param template - Handlebars template string
+ * @param context - Data object for template variables
+ * @returns Rendered HTML string
+ */
+export declare function renderTemplate(template: string, context: Record<string, unknown>): string;
+/**
+ * Register a custom Handlebars helper.
+ * @param name - Helper name
+ * @param fn - Helper function
+ */
+export declare function registerHelper(name: string, fn: Handlebars.HelperDelegate): void;

package/dist/template.js ADDED Viewed

@@ -0,0 +1,31 @@
+/**
+ * Handlebars template engine for email content.
+ * Pure function, no side effects.
+ */
+import Handlebars from 'handlebars';
+/**
+ * Register a Handlebars template by name.
+ * @param name - Template identifier
+ * @param source - Handlebars template string
+ */
+export function registerTemplate(name, source) {
+    Handlebars.registerPartial(name, source);
+}
+/**
+ * Render a Handlebars template with context data.
+ * @param template - Handlebars template string
+ * @param context - Data object for template variables
+ * @returns Rendered HTML string
+ */
+export function renderTemplate(template, context) {
+    const compiled = Handlebars.compile(template);
+    return compiled(context);
+}
+/**
+ * Register a custom Handlebars helper.
+ * @param name - Helper name
+ * @param fn - Helper function
+ */
+export function registerHelper(name, fn) {
+    Handlebars.registerHelper(name, fn);
+}

package/dist/universal-mailer.d.ts ADDED Viewed

@@ -0,0 +1,114 @@
+/**
+ * Universal Mailer — Universal email client.
+ * Supports SMTP, Gmail API, and IMAP/POP3.
+ *
+ * Architecture: Strategy Pattern
+ * - SendTransport: SMTP or Gmail API
+ * - FetchTransport: IMAP or POP3
+ */
+import { type Attachment } from './mime-builder.js';
+export type TransportType = 'smtp' | 'gmail-api';
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth: {
+        user: string;
+        pass: string;
+    };
+}
+export interface GmailApiConfig {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    accessToken?: string;
+    redirectUri?: string;
+}
+export interface ImapConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth: {
+        user: string;
+        pass: string;
+    };
+}
+export interface Pop3Config {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth: {
+        user: string;
+        pass: string;
+    };
+}
+export interface MailerConfig {
+    transport: TransportType;
+    smtp?: SmtpConfig;
+    gmailApi?: GmailApiConfig;
+    fetchTransport?: 'imap' | 'pop3';
+    imap?: ImapConfig;
+    pop3?: Pop3Config;
+}
+export interface SendOptions {
+    from: string;
+    to: string;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+    subject: string;
+    text?: string;
+    html?: string;
+    template?: string;
+    context?: Record<string, unknown>;
+    attachments?: Attachment[];
+}
+export interface SendResult {
+    messageId: string;
+    threadId?: string;
+    labelIds?: string[];
+}
+export interface FetchOptions {
+    limit?: number;
+    seen?: boolean;
+    mailbox?: string;
+}
+export interface EmailMessage {
+    id: string;
+    from: string;
+    to: string;
+    subject: string;
+    date: Date;
+    text?: string;
+    html?: string;
+    seen: boolean;
+    attachments: Array<{
+        filename: string;
+        contentType: string;
+    }>;
+}
+export declare class UniversalMailer {
+    private sender;
+    private fetcher?;
+    constructor(config: MailerConfig);
+    /**
+     * Send an email via the configured transport.
+     */
+    sendEmail(options: SendOptions): Promise<SendResult>;
+    /**
+     * Verify the send transport connection.
+     */
+    verifyConnection(): Promise<string>;
+    /**
+     * Fetch emails via IMAP (if configured).
+     */
+    fetchEmails(options?: FetchOptions): Promise<EmailMessage[]>;
+    /**
+     * Get OAuth2 access token (Gmail API only).
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Force refresh OAuth2 token (Gmail API only).
+     */
+    forceRefreshToken(): Promise<void>;
+}

package/dist/universal-mailer.js ADDED Viewed

@@ -0,0 +1,317 @@
+/**
+ * Universal Mailer — Universal email client.
+ * Supports SMTP, Gmail API, and IMAP/POP3.
+ *
+ * Architecture: Strategy Pattern
+ * - SendTransport: SMTP or Gmail API
+ * - FetchTransport: IMAP or POP3
+ */
+import { createTransport } from 'nodemailer';
+import { google } from 'googleapis';
+import { ImapFlow } from 'imapflow';
+import { simpleParser } from 'mailparser';
+import { renderTemplate } from './template.js';
+import { buildRawMessage } from './mime-builder.js';
+// ============================================================
+// Security
+// ============================================================
+function redactSensitiveInfo(message) {
+    return message
+        .replace(/ya29\.[A-Za-z0-9_-]+/g, '[REDACTED_TOKEN]')
+        .replace(/1\/\/[A-Za-z0-9_-]+/g, '[REDACTED_REFRESH_TOKEN]')
+        .replace(/GOCSPX-[A-Za-z0-9_-]+/g, '[REDACTED_SECRET]')
+        .replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[REDACTED_EMAIL]');
+}
+// ============================================================
+// Gmail API Transport
+// ============================================================
+class GmailApiSender {
+    oauth2Client;
+    constructor(config) {
+        if (!config.clientId || !config.clientSecret || !config.refreshToken) {
+            throw new Error('Gmail API config requires clientId, clientSecret, and refreshToken');
+        }
+        this.oauth2Client = new google.auth.OAuth2(config.clientId, config.clientSecret, config.redirectUri);
+        this.oauth2Client.setCredentials({
+            refresh_token: config.refreshToken,
+            access_token: config.accessToken,
+        });
+    }
+    async ensureAccessToken() {
+        await this.oauth2Client.getRequestHeaders();
+    }
+    async getAccessToken() {
+        await this.ensureAccessToken();
+        const token = await this.oauth2Client.getAccessToken();
+        if (!token.token) {
+            throw new Error('Failed to obtain access token');
+        }
+        return token.token;
+    }
+    async forceRefreshToken() {
+        const credentials = this.oauth2Client.credentials;
+        const refreshToken = credentials.refresh_token;
+        if (!refreshToken)
+            throw new Error('No refresh token available');
+        const tokenUrl = 'https://oauth2.googleapis.com/token';
+        const params = new URLSearchParams({
+            client_id: this.oauth2Client._clientId ?? '',
+            client_secret: this.oauth2Client._clientSecret ?? '',
+            refresh_token: refreshToken,
+            grant_type: 'refresh_token',
+        });
+        const response = await fetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Token refresh failed: ${redactSensitiveInfo(error)}`);
+        }
+        const data = await response.json();
+        this.oauth2Client.setCredentials({
+            access_token: data.access_token,
+            refresh_token: data.refresh_token ?? refreshToken,
+        });
+    }
+    async sendEmail(options) {
+        await this.ensureAccessToken();
+        const token = await this.getAccessToken();
+        let html = options.html;
+        let text = options.text;
+        if (options.template && options.context) {
+            html = renderTemplate(options.template, options.context);
+        }
+        if (!html && !text) {
+            throw new Error('Email requires html, text, or template');
+        }
+        const raw = await buildRawMessage({
+            from: options.from,
+            to: options.to,
+            cc: options.cc,
+            bcc: options.bcc,
+            replyTo: options.replyTo,
+            subject: options.subject,
+            text,
+            html,
+            attachments: options.attachments,
+        });
+        const response = await fetch('https://gmail.googleapis.com/gmail/v1/users/me/messages/send', {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ raw }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Gmail API error (${response.status}): ${redactSensitiveInfo(errorText)}`);
+        }
+        const data = await response.json();
+        return {
+            messageId: data.id,
+            threadId: data.threadId,
+            labelIds: data.labelIds,
+        };
+    }
+    async verifyConnection() {
+        await this.ensureAccessToken();
+        const token = await this.getAccessToken();
+        const response = await fetch('https://gmail.googleapis.com/gmail/v1/users/me/profile', {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Gmail profile error (${response.status}): ${redactSensitiveInfo(errorText)}`);
+        }
+        const data = await response.json();
+        if (!data.emailAddress)
+            throw new Error('Could not retrieve user email');
+        return data.emailAddress;
+    }
+}
+// ============================================================
+// SMTP Transport
+// ============================================================
+class SmtpSender {
+    transporter;
+    constructor(config) {
+        if (!config.host || !config.port || !config.auth?.user || !config.auth?.pass) {
+            throw new Error('SMTP config requires host, port, user, and pass');
+        }
+        this.transporter = createTransport({
+            host: config.host,
+            port: config.port,
+            secure: config.secure ?? config.port === 465,
+            auth: config.auth,
+        });
+    }
+    async sendEmail(options) {
+        let html = options.html;
+        let text = options.text;
+        if (options.template && options.context) {
+            html = renderTemplate(options.template, options.context);
+        }
+        if (!html && !text) {
+            throw new Error('Email requires html, text, or template');
+        }
+        const info = await this.transporter.sendMail({
+            from: options.from,
+            to: options.to,
+            cc: options.cc,
+            bcc: options.bcc,
+            replyTo: options.replyTo,
+            subject: options.subject,
+            text,
+            html,
+            attachments: options.attachments?.map(a => ({
+                filename: a.filename,
+                content: a.content,
+                contentType: a.contentType,
+            })),
+        });
+        return {
+            messageId: info.messageId,
+        };
+    }
+    async verifyConnection() {
+        await this.transporter.verify();
+        return 'SMTP connection verified';
+    }
+}
+// ============================================================
+// IMAP Fetcher
+// ============================================================
+class ImapFetcher {
+    config;
+    constructor(config) {
+        if (!config.host || !config.port || !config.auth?.user || !config.auth?.pass) {
+            throw new Error('IMAP config requires host, port, user, and pass');
+        }
+        this.config = config;
+    }
+    async fetchEmails(options = {}) {
+        const { limit = 10, seen, mailbox = 'INBOX' } = options;
+        const client = new ImapFlow({
+            host: this.config.host,
+            port: this.config.port,
+            secure: this.config.secure ?? this.config.port === 993,
+            auth: this.config.auth,
+        });
+        try {
+            await client.connect();
+            const lock = await client.getMailboxLock(mailbox);
+            try {
+                const messages = [];
+                const search = {};
+                if (seen !== undefined)
+                    search.seen = seen;
+                let count = 0;
+                for await (const message of client.fetch(search, {
+                    envelope: true,
+                    source: true,
+                })) {
+                    if (count >= limit)
+                        break;
+                    count++;
+                    const parsed = await simpleParser(message.source ?? '');
+                    messages.push({
+                        id: message.uid?.toString() ?? '',
+                        from: parsed.from?.text ?? '',
+                        to: parsed.to?.text ?? '',
+                        subject: parsed.subject ?? '',
+                        date: parsed.date ?? new Date(),
+                        text: parsed.text ?? undefined,
+                        html: parsed.html ?? undefined,
+                        seen: message.flags?.has('\\Seen') ?? false,
+                        attachments: (parsed.attachments ?? []).map((a) => ({
+                            filename: a.filename ?? 'unknown',
+                            contentType: a.contentType ?? 'application/octet-stream',
+                        })),
+                    });
+                }
+                return messages;
+            }
+            finally {
+                lock.release();
+            }
+        }
+        finally {
+            client.close();
+        }
+    }
+}
+// ============================================================
+// Universal Mailer (Facade)
+// ============================================================
+export class UniversalMailer {
+    sender;
+    fetcher;
+    constructor(config) {
+        // Setup send transport
+        if (config.transport === 'gmail-api') {
+            if (!config.gmailApi) {
+                throw new Error('Gmail API transport requires gmailApi config');
+            }
+            this.sender = new GmailApiSender(config.gmailApi);
+        }
+        else if (config.transport === 'smtp') {
+            if (!config.smtp) {
+                throw new Error('SMTP transport requires smtp config');
+            }
+            this.sender = new SmtpSender(config.smtp);
+        }
+        else {
+            throw new Error(`Unknown transport: ${config.transport}`);
+        }
+        // Setup fetch transport
+        if (config.fetchTransport === 'imap') {
+            if (!config.imap) {
+                throw new Error('IMAP fetch transport requires imap config');
+            }
+            this.fetcher = new ImapFetcher(config.imap);
+        }
+        // POP3: not implemented yet (future)
+    }
+    /**
+     * Send an email via the configured transport.
+     */
+    async sendEmail(options) {
+        return this.sender.sendEmail(options);
+    }
+    /**
+     * Verify the send transport connection.
+     */
+    async verifyConnection() {
+        return this.sender.verifyConnection();
+    }
+    /**
+     * Fetch emails via IMAP (if configured).
+     */
+    async fetchEmails(options = {}) {
+        if (!this.fetcher) {
+            throw new Error('Fetch transport not configured. Set fetchTransport to "imap" in config.');
+        }
+        return this.fetcher.fetchEmails(options);
+    }
+    /**
+     * Get OAuth2 access token (Gmail API only).
+     */
+    async getAccessToken() {
+        if (this.sender instanceof GmailApiSender) {
+            return this.sender.getAccessToken();
+        }
+        throw new Error('getAccessToken is only available for Gmail API transport');
+    }
+    /**
+     * Force refresh OAuth2 token (Gmail API only).
+     */
+    async forceRefreshToken() {
+        if (this.sender instanceof GmailApiSender) {
+            return this.sender.forceRefreshToken();
+        }
+        throw new Error('forceRefreshToken is only available for Gmail API transport');
+    }
+}

package/package.json ADDED Viewed

@@ -0,0 +1,75 @@
+{
+  "name": "universal-mailer-lib",
+  "version": "2.0.2",
+  "description": "Universal email client. Supports SMTP, Gmail API, and IMAP/POP3.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/gmail-mailer.js",
+    "dist/gmail-mailer.d.ts",
+    "dist/universal-mailer.js",
+    "dist/universal-mailer.d.ts",
+    "dist/mime-builder.js",
+    "dist/mime-builder.d.ts",
+    "dist/template.js",
+    "dist/template.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node dist/test-runner.js",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "npm run build && node dist/index.js",
+    "client": "npm run build && node dist/test-send.js",
+    "security:audit": "node scripts/security-audit.mjs",
+    "release:dry": "node scripts/release.mjs --dry-run",
+    "release": "node scripts/release.mjs",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "email",
+    "mailer",
+    "smtp",
+    "imap",
+    "pop3",
+    "gmail-api",
+    "oauth2",
+    "handlebars",
+    "template",
+    "attachments",
+    "universal-mailer"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "googleapis": ">=140.0.0",
+    "nodemailer": ">=7.0.0",
+    "handlebars": ">=4.7.0",
+    "imapflow": ">=1.0.0",
+    "mailparser": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "googleapis": "^171.0.0",
+    "nodemailer": "^8.0.0",
+    "handlebars": "^4.7.9",
+    "imapflow": "^1.0.179",
+    "mailparser": "^3.7.2",
+    "typescript": "^5.7.2"
+  }
+}