@sibiltech/sibil-mail 1.0.2 → 1.0.3

package/README.md

@@ -1,2 +1,325 @@
-# Sibil-mail
-Sibil Mail is used for all sending and receiving emails
+# @sibiltech/sibil-mail
+
+A production-ready npm package for sending emails using nodemailer with TypeScript support. Part of the Sibil platform for sending and receiving emails.
+
+## Features
+
+- TypeScript support with full type definitions
+- Simple, class-based API with `SibilMail` instance
+- Automatic retry with configurable backoff
+- Comprehensive error handling with custom error classes
+- Support for HTML and plain text emails
+- Attachment support
+- CC and BCC support
+- Connection verification with retry
+- Provider-specific optimizations (Gmail, Outlook, Yahoo)
+- Email validation utilities
+- Template utilities for variable replacement
+
+## Installation
+
+```bash
+npm install @sibiltech/sibil-mail
+```
+
+## Quick Start
+
+```typescript
+import { SibilMail } from '@sibiltech/sibil-mail';
+
+// Create a mailer instance
+const mailer = new SibilMail({
+  host: 'smtp.gmail.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'your-email@gmail.com',
+    pass: 'your-app-password',
+  },
+});
+
+// Send an email
+const result = await mailer.send({
+  from: 'your-email@gmail.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from Sibil Mail',
+  text: 'This is a plain text email',
+  html: '<p>This is an HTML email</p>',
+});
+
+console.log(result.success ? 'Sent!' : result.error);
+```
+
+## API Reference
+
+### `SibilMail` class
+
+Create an instance with SMTP configuration. Each instance manages its own transporter and retry behavior.
+
+#### Constructor: `new SibilMail(config: SmtpConfig, retryConfig?)`
+
+**Parameters:**
+
+- `config.host` (string, required): SMTP server hostname
+- `config.port` (number, required): SMTP server port (e.g. 587, 465, 25)
+- `config.secure` (boolean, optional): Use TLS (typically true for port 465)
+- `config.auth.user` (string, required): SMTP username/email
+- `config.auth.pass` (string, required): SMTP password or app password
+- `config.tls` (object, optional): TLS options (e.g. `rejectUnauthorized: false`)
+- `retryConfig` (optional): `{ maxRetries?: number; retryDelay?: number }` for send/verify retries
+
+**Example:**
+
+```typescript
+const mailer = new SibilMail({
+  host: 'smtp.gmail.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'your-email@gmail.com',
+    pass: 'your-app-password',
+  },
+  tls: {
+    rejectUnauthorized: false, // For self-signed certificates
+  },
+}, { maxRetries: 3, retryDelay: 1000 });
+```
+
+#### `mailer.send(options: EmailOptions): Promise<EmailResult>`
+
+Sends an email with validation and automatic retry.
+
+**Parameters:**
+
+- `options.from` (string, required): Sender email address
+- `options.to` (string | string[], required): Recipient email address(es)
+- `options.subject` (string, required): Email subject
+- `options.text` (string, optional): Plain text content
+- `options.html` (string, optional): HTML content (at least one of `text` or `html` is required)
+- `options.cc` (string | string[], optional): CC recipients
+- `options.bcc` (string | string[], optional): BCC recipients
+- `options.replyTo` (string, optional): Reply-to address
+- `options.attachments` (array, optional): Email attachments
+
+**Returns:** `Promise<EmailResult>` with `{ success, messageId?, error?, response? }`
+
+**Example:**
+
+```typescript
+// Simple email
+const result = await mailer.send({
+  from: 'you@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello',
+  text: 'Hello world!',
+});
+
+// HTML email
+await mailer.send({
+  from: 'you@example.com',
+  to: 'recipient@example.com',
+  subject: 'Welcome',
+  html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
+});
+
+// Multiple recipients and CC
+await mailer.send({
+  from: 'you@example.com',
+  to: ['user1@example.com', 'user2@example.com'],
+  subject: 'Newsletter',
+  html: '<p>Check out our latest updates!</p>',
+  cc: 'manager@example.com',
+});
+
+// With attachments
+await mailer.send({
+  from: 'you@example.com',
+  to: 'recipient@example.com',
+  subject: 'Report',
+  text: 'Please find the report attached.',
+  attachments: [
+    { filename: 'report.pdf', path: './reports/report.pdf' },
+    { filename: 'data.txt', content: 'Some file content' },
+  ],
+});
+```
+
+#### `mailer.verifyConnection(): Promise<boolean>`
+
+Verifies the SMTP connection. Useful for checking credentials at startup.
+
+**Example:**
+
+```typescript
+try {
+  await mailer.verifyConnection();
+  console.log('SMTP connection verified successfully!');
+} catch (error) {
+  console.error('SMTP verification failed:', error);
+}
+```
+
+#### `mailer.getTransporter()`
+
+Returns the underlying nodemailer transporter instance.
+
+#### `mailer.updateConfig(config: SmtpConfig): void`
+
+Updates SMTP configuration and recreates the transporter.
+
+#### `mailer.getConfig()`
+
+Returns current SMTP configuration (password masked).
+
+#### `mailer.close(): Promise<void>`
+
+Closes the transporter connection. Call when done using the mailer instance.
+
+---
+
+### Standalone utilities
+
+You can also use transport and validation helpers without the class:
+
+```typescript
+import {
+  createSmtpTransport,
+  verifySmtpConnection,
+  closeTransport,
+  isValidEmail,
+  validateEmails,
+  replaceVariables,
+  createEmailTemplate,
+} from '@sibiltech/sibil-mail';
+```
+
+---
+
+## Error Handling
+
+The package provides custom error classes for better error handling:
+
+```typescript
+import {
+  SibilMail,
+  SmtpConnectionError,
+  EmailValidationError,
+  EmailSendError,
+  SibilMailError,
+} from '@sibiltech/sibil-mail';
+
+const mailer = new SibilMail({ /* config */ });
+
+try {
+  await mailer.send({
+    from: 'you@example.com',
+    to: 'recipient@example.com',
+    subject: 'Test',
+    text: 'Test email',
+  });
+} catch (error) {
+  if (error instanceof EmailValidationError) {
+    console.error('Invalid email:', error.invalidEmails);
+  } else if (error instanceof SmtpConnectionError) {
+    console.error('Connection failed:', error.message);
+  } else if (error instanceof EmailSendError) {
+    console.error('Send failed:', error.message, error.originalError);
+  } else if (error instanceof SibilMailError) {
+    console.error('Sibil Mail error:', error.message, error.code);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Type Definitions
+
+All types are exported for use in your TypeScript projects:
+
+```typescript
+import type {
+  SmtpConfig,
+  EmailOptions,
+  EmailResult,
+  EmailAttachment,
+  TransportFactory,
+} from '@sibiltech/sibil-mail';
+```
+
+## Common SMTP Providers
+
+### Gmail
+
+```typescript
+new SibilMail({
+  host: 'smtp.gmail.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'your-email@gmail.com',
+    pass: 'your-app-password', // Use App Password, not regular password
+  },
+});
+```
+
+### Outlook / Hotmail
+
+```typescript
+new SibilMail({
+  host: 'smtp-mail.outlook.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'your-email@outlook.com',
+    pass: 'your-password',
+  },
+});
+```
+
+### SendGrid
+
+```typescript
+new SibilMail({
+  host: 'smtp.sendgrid.net',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'apikey',
+    pass: 'your-sendgrid-api-key',
+  },
+});
+```
+
+### Mailgun
+
+```typescript
+new SibilMail({
+  host: 'smtp.mailgun.org',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'your-mailgun-username',
+    pass: 'your-mailgun-password',
+  },
+});
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Watch / run dev scripts
+npm run dev
+```
+
+## License
+
+See [LICENSE](LICENSE) for terms. For licensing inquiries, contact sibiltech at info@sibiltech.com.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sibiltech/sibil-mail",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "SMTP Email Sending Library for Sibil Platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",