@veloxts/mail 0.6.87 → 0.6.89

package/GUIDE.md

@@ -1,28 +1,50 @@
 # @veloxts/mail Guide
 
-## Drivers
+Email sending for VeloxTS applications with React Email templates, supporting SMTP and Resend.
 
-### Log Driver (default)
+## Installation
 
-Logs emails to console. Best for development.
+```bash
+pnpm add @veloxts/mail
+
+# For Resend (recommended for production)
+pnpm add resend
+```
+
+## Quick Start
+
+### Development (Log)
+
+Logs emails to console instead of sending:
 
 ```typescript
+import { veloxApp } from '@veloxts/core';
 import { mailPlugin } from '@veloxts/mail';
 
-app.use(mailPlugin({ driver: 'log' }));
-```
+const app = veloxApp();
 
-### SMTP Driver
+app.register(mailPlugin({
+  driver: 'log',
+  from: { name: 'My App', email: 'noreply@myapp.com' },
+}));
+
+await app.start();
+```
 
-Send via any SMTP server.
+### Production (SMTP)
 
 ```typescript
-app.use(mailPlugin({
+import { veloxApp } from '@veloxts/core';
+import { mailPlugin } from '@veloxts/mail';
+
+const app = veloxApp();
+
+app.register(mailPlugin({
   driver: 'smtp',
   config: {
-    host: 'smtp.example.com',
-    port: 587,
-    secure: false,
+    host: process.env.SMTP_HOST,
+    port: parseInt(process.env.SMTP_PORT || '587'),
+    secure: process.env.SMTP_SECURE === 'true',
     auth: {
       user: process.env.SMTP_USER,
       pass: process.env.SMTP_PASS,
@@ -30,32 +52,50 @@ app.use(mailPlugin({
   },
   from: { name: 'My App', email: 'noreply@myapp.com' },
 }));
+
+await app.start();
 ```
 
-### Resend Driver
+### Production (Resend)
 
-Send via Resend API.
+```typescript
+import { veloxApp } from '@veloxts/core';
+import { mailPlugin } from '@veloxts/mail';
 
-```bash
-npm install resend
-```
+const app = veloxApp();
 
-```typescript
-app.use(mailPlugin({
+app.register(mailPlugin({
   driver: 'resend',
   config: {
     apiKey: process.env.RESEND_API_KEY,
   },
   from: { name: 'My App', email: 'noreply@myapp.com' },
 }));
+
+await app.start();
+```
+
+**Environment Variables:**
+
+```bash
+# .env (SMTP)
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=your-username
+SMTP_PASS=your-password
+
+# .env (Resend)
+RESEND_API_KEY=re_xxxxxxxxxxxx
 ```
 
 ## Defining Email Templates
 
 Using React Email components:
 
-```typescript
+```tsx
 import { defineMail } from '@veloxts/mail';
+import { z } from 'zod';
 import { Html, Head, Body, Container, Text, Button } from '@react-email/components';
 
 export const WelcomeEmail = defineMail({
@@ -104,6 +144,13 @@ await ctx.mail.send(InvoiceEmail, {
     { filename: 'invoice.pdf', content: pdfBuffer },
   ],
 });
+
+// Override subject
+await ctx.mail.send(WelcomeEmail, {
+  to: 'user@example.com',
+  subject: 'Custom Subject',
+  data: { user, activationUrl },
+});
 ```
 
 ## Bulk Sending
@@ -117,7 +164,7 @@ const results = await ctx.mail.sendBulk(WelcomeEmail, [
 
 ## Preview Emails
 
-Render without sending (useful for testing):
+Render without sending (useful for testing or previews):
 
 ```typescript
 const { html, text, subject } = await ctx.mail.render(WelcomeEmail, {
@@ -125,8 +172,68 @@ const { html, text, subject } = await ctx.mail.render(WelcomeEmail, {
 });
 ```
 
-## CLI Commands
+## Production Deployment
 
-```bash
-velox make mail WelcomeEmail     # Generate email template
+### Choosing a Provider
+
+| Provider | Best For |
+|----------|----------|
+| [Resend](https://resend.com) | Simple API, React Email native, generous free tier |
+| [AWS SES](https://aws.amazon.com/ses/) | High volume, cost-effective |
+| [SendGrid](https://sendgrid.com) | Enterprise features |
+| [Postmark](https://postmarkapp.com) | Transactional email focus |
+
+### Production Checklist
+
+1. **Verify sending domain** - SPF, DKIM, DMARC records
+2. **Use environment variables** - Never hardcode credentials
+3. **Set proper From address** - Use verified domain email
+4. **Handle bounces** - Configure bounce/complaint webhooks
+5. **Queue emails** - Use `@veloxts/queue` for background sending
+
+### Sending Emails in Background
+
+For better performance, queue emails instead of sending synchronously:
+
+```typescript
+// Define a job for sending emails
+const sendEmailJob = defineJob({
+  name: 'email.send',
+  schema: z.object({
+    template: z.string(),
+    to: z.string().email(),
+    data: z.record(z.unknown()),
+  }),
+  handler: async ({ data, ctx }) => {
+    const template = emailTemplates[data.template];
+    await ctx.mail.send(template, { to: data.to, data: data.data });
+  },
+});
+
+// Dispatch instead of sending directly
+await ctx.queue.dispatch(sendEmailJob, {
+  template: 'welcome',
+  to: 'user@example.com',
+  data: { user, activationUrl },
+});
+```
+
+## Standalone Usage
+
+Use mail outside of Fastify request context (CLI commands, background jobs):
+
+```typescript
+import { getMail, closeMail } from '@veloxts/mail';
+
+// Get standalone mail instance
+const mail = await getMail({
+  driver: 'resend',
+  config: { apiKey: process.env.RESEND_API_KEY },
+  from: { email: 'noreply@example.com' },
+});
+
+await mail.send(WelcomeEmail, { to: 'user@example.com', data: {...} });
+
+// Clean up when done
+await closeMail();
 ```

package/dist/manager.d.ts

@@ -78,5 +78,8 @@ export interface MailManager {
 export declare function createMailManager(options?: MailPluginOptions): Promise<MailManager>;
 /**
  * Alias for createMailManager.
+ *
+ * Note: `mail` is already used as an alias for `defineMail` (for defining templates),
+ * following the same pattern as queue (`job` = `defineJob`, `queue` = `createQueueManager`).
  */
 export declare const mailer: typeof createMailManager;

package/dist/manager.js

@@ -149,5 +149,8 @@ export async function createMailManager(options = {}) {
 }
 /**
  * Alias for createMailManager.
+ *
+ * Note: `mail` is already used as an alias for `defineMail` (for defining templates),
+ * following the same pattern as queue (`job` = `defineJob`, `queue` = `createQueueManager`).
  */
 export const mailer = createMailManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/mail",
-  "version": "0.6.87",
+  "version": "0.6.89",
   "description": "Email templating and sending for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,19 +28,19 @@
     "nodemailer": "7.0.13",
     "resend": "4.1.2",
     "zod": "3.24.4",
-    "@veloxts/core": "0.6.87"
+    "@veloxts/core": "0.6.89"
   },
   "devDependencies": {
     "@biomejs/biome": "2.0.0",
-    "@types/node": "22.15.29",
+    "@types/node": "25.0.3",
     "@types/nodemailer": "7.0.9",
     "@types/react": "19.2.7",
     "@vitest/coverage-v8": "4.0.16",
     "fastify": "5.6.2",
     "react": "19.2.3",
-    "typescript": "5.8.3",
+    "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.87"
+    "@veloxts/testing": "0.6.89"
   },
   "peerDependencies": {
     "fastify": "^5.0.0",