@bloomneo/appkit 1.2.9

package/dist/email/email.js

@@ -0,0 +1,316 @@
+/**
+ * Core email class with automatic strategy selection and ultra-simple API
+ * @module @bloomneo/appkit/email
+ * @file src/email/email.ts
+ *
+ * @llm-rule WHEN: Building apps that need email sending with automatic provider selection
+ * @llm-rule AVOID: Using directly - always get instance via emailClass.get()
+ * @llm-rule NOTE: Auto-detects Resend → SMTP → Console based on environment variables
+ */
+import { ResendStrategy } from './strategies/resend.js';
+import { SmtpStrategy } from './strategies/smtp.js';
+import { ConsoleStrategy } from './strategies/console.js';
+/**
+ * Email class with automatic strategy selection and ultra-simple API
+ */
+export class EmailClass {
+    config;
+    strategy;
+    connected = false;
+    constructor(config) {
+        this.config = config;
+        this.strategy = this.createStrategy();
+    }
+    /**
+     * Creates appropriate strategy based on configuration
+     * @llm-rule WHEN: Email initialization - selects Resend, SMTP, or Console based on environment
+     * @llm-rule AVOID: Manual strategy creation - configuration handles strategy selection
+     */
+    createStrategy() {
+        switch (this.config.strategy) {
+            case 'resend':
+                return new ResendStrategy(this.config);
+            case 'smtp':
+                return new SmtpStrategy(this.config);
+            case 'console':
+                return new ConsoleStrategy(this.config);
+            default:
+                throw new Error(`Unknown email strategy: ${this.config.strategy}`);
+        }
+    }
+    /**
+     * Sends email with automatic strategy handling
+     * @llm-rule WHEN: Sending any email - this is the main email sending method
+     * @llm-rule AVOID: Manual strategy calls - this handles all email complexity
+     * @llm-rule NOTE: Auto-fills FROM address from config if not provided
+     */
+    async send(data) {
+        try {
+            // Validate email data
+            this.validateEmailData(data);
+            // Auto-fill FROM address if not provided
+            const emailData = this.prepareEmailData(data);
+            // Send via strategy
+            const result = await this.strategy.send(emailData);
+            // Log success in development
+            if (this.config.environment.isDevelopment && result.success) {
+                console.log(`✅ [AppKit] Email sent successfully${result.messageId ? ` (ID: ${result.messageId})` : ''}`);
+            }
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            console.error(`❌ [AppKit] Email send failed:`, errorMessage);
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Sends multiple emails efficiently (batch operation)
+     * @llm-rule WHEN: Sending multiple emails like newsletters or notifications
+     * @llm-rule AVOID: Multiple individual send() calls - this handles batching efficiently
+     * @llm-rule NOTE: Processes in batches to avoid overwhelming email providers
+     */
+    async sendBatch(emails, batchSize = 10) {
+        const results = [];
+        // Process in batches
+        for (let i = 0; i < emails.length; i += batchSize) {
+            const batch = emails.slice(i, i + batchSize);
+            // Send batch concurrently
+            const batchPromises = batch.map(email => this.send(email));
+            const batchResults = await Promise.allSettled(batchPromises);
+            // Process results
+            for (const result of batchResults) {
+                if (result.status === 'fulfilled') {
+                    results.push(result.value);
+                }
+                else {
+                    results.push({
+                        success: false,
+                        error: result.reason?.message || 'Unknown error',
+                    });
+                }
+            }
+            // Small delay between batches to be respectful to email providers
+            if (i + batchSize < emails.length) {
+                await this.sleep(100);
+            }
+        }
+        return results;
+    }
+    /**
+     * Sends simple text email (convenience method)
+     * @llm-rule WHEN: Sending simple text-only emails quickly
+     * @llm-rule AVOID: Complex EmailData object for simple emails - this is more convenient
+     */
+    async sendText(to, subject, text) {
+        return await this.send({
+            to,
+            subject,
+            text,
+        });
+    }
+    /**
+     * Sends HTML email (convenience method)
+     * @llm-rule WHEN: Sending HTML emails with formatting
+     * @llm-rule AVOID: Manual HTML/text preparation - this handles both formats
+     */
+    async sendHtml(to, subject, html, text) {
+        return await this.send({
+            to,
+            subject,
+            html,
+            text: text || this.htmlToText(html),
+        });
+    }
+    /**
+     * Sends email with template (future extension point)
+     * @llm-rule WHEN: Sending templated emails with data substitution
+     * @llm-rule AVOID: Manual template processing - this will handle template rendering
+     * @llm-rule NOTE: Basic implementation - can be extended with template engines
+     */
+    async sendTemplate(templateName, data) {
+        // Simple template processing (can be extended)
+        const template = this.loadTemplate(templateName);
+        const processedHtml = this.processTemplate(template.html, data);
+        const processedText = this.processTemplate(template.text, data);
+        return await this.send({
+            to: data.to,
+            subject: this.processTemplate(template.subject, data),
+            html: processedHtml,
+            text: processedText,
+        });
+    }
+    /**
+     * Disconnects email strategy gracefully
+     * @llm-rule WHEN: App shutdown or email cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents connection issues
+     */
+    async disconnect() {
+        if (!this.connected)
+            return;
+        try {
+            await this.strategy.disconnect();
+            this.connected = false;
+            if (this.config.environment.isDevelopment) {
+                console.log(`👋 [AppKit] Email disconnected`);
+            }
+        }
+        catch (error) {
+            console.error(`⚠️ [AppKit] Email disconnect error:`, error.message);
+        }
+    }
+    /**
+     * Gets current email strategy name for debugging
+     * @llm-rule WHEN: Debugging or health checks to see which strategy is active
+     * @llm-rule AVOID: Using for application logic - email should be transparent
+     */
+    getStrategy() {
+        return this.config.strategy;
+    }
+    /**
+     * Gets email configuration summary for debugging
+     * @llm-rule WHEN: Health checks or debugging email configuration
+     * @llm-rule AVOID: Exposing sensitive details - this only shows safe info
+     */
+    getConfig() {
+        return {
+            strategy: this.config.strategy,
+            fromName: this.config.from.name,
+            fromEmail: this.config.from.email,
+            connected: this.connected,
+        };
+    }
+    // Private helper methods
+    /**
+     * Validates email data before sending
+     */
+    validateEmailData(data) {
+        if (!data.to) {
+            throw new Error('Email "to" field is required');
+        }
+        if (!data.subject) {
+            throw new Error('Email "subject" field is required');
+        }
+        if (!data.text && !data.html) {
+            throw new Error('Email must have either "text" or "html" content');
+        }
+        // Validate email addresses
+        const recipients = Array.isArray(data.to) ? data.to : [data.to];
+        for (const recipient of recipients) {
+            const email = typeof recipient === 'string' ? recipient : recipient.email;
+            if (!this.isValidEmail(email)) {
+                throw new Error(`Invalid email address: ${email}`);
+            }
+        }
+        // Validate FROM address if provided
+        if (data.from) {
+            const fromEmail = typeof data.from === 'string' ? data.from : data.from.email;
+            if (!this.isValidEmail(fromEmail)) {
+                throw new Error(`Invalid FROM email address: ${fromEmail}`);
+            }
+        }
+    }
+    /**
+     * Prepares email data with defaults
+     */
+    prepareEmailData(data) {
+        const prepared = { ...data };
+        // Auto-fill FROM address if not provided
+        if (!prepared.from) {
+            prepared.from = {
+                name: this.config.from.name,
+                email: this.config.from.email,
+            };
+        }
+        return prepared;
+    }
+    /**
+     * Validates email address format
+     */
+    isValidEmail(email) {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(email);
+    }
+    /**
+     * Converts HTML to plain text (basic implementation)
+     */
+    htmlToText(html) {
+        return html
+            .replace(/<br\s*\/?>/gi, '\n')
+            .replace(/<\/p>/gi, '\n\n')
+            .replace(/<[^>]+>/g, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+    }
+    /**
+     * Loads email template (basic implementation)
+     */
+    loadTemplate(templateName) {
+        // Basic built-in templates
+        const templates = {
+            welcome: {
+                subject: 'Welcome to {{appName}}!',
+                html: `
+          <h1>Welcome {{name}}!</h1>
+          <p>Thanks for joining {{appName}}. We're excited to have you!</p>
+          <p>Best regards,<br>The {{appName}} Team</p>
+        `,
+                text: `
+          Welcome {{name}}!
+          
+          Thanks for joining {{appName}}. We're excited to have you!
+          
+          Best regards,
+          The {{appName}} Team
+        `,
+            },
+            reset: {
+                subject: 'Reset your {{appName}} password',
+                html: `
+          <h1>Reset your password</h1>
+          <p>Hi {{name}},</p>
+          <p>Click the link below to reset your password:</p>
+          <a href="{{resetUrl}}">Reset Password</a>
+          <p>If you didn't request this, please ignore this email.</p>
+        `,
+                text: `
+          Reset your password
+          
+          Hi {{name}},
+          
+          Click the link below to reset your password:
+          {{resetUrl}}
+          
+          If you didn't request this, please ignore this email.
+        `,
+            },
+        };
+        const template = templates[templateName];
+        if (!template) {
+            throw new Error(`Template not found: ${templateName}`);
+        }
+        return template;
+    }
+    /**
+     * Processes template with data substitution
+     */
+    processTemplate(template, data) {
+        let processed = template;
+        // Simple {{key}} substitution
+        for (const [key, value] of Object.entries(data)) {
+            const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+            processed = processed.replace(regex, String(value));
+        }
+        return processed.trim();
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=email.js.map

package/dist/email/email.js.map

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

package/dist/email/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Ultra-simple email sending that just works with automatic provider detection
+ * @module @bloomneo/appkit/email
+ * @file src/email/index.ts
+ *
+ * @llm-rule WHEN: Building apps that need email sending with zero configuration
+ * @llm-rule AVOID: Complex email setups - this auto-detects Resend/SMTP/Console from environment
+ * @llm-rule NOTE: Uses emailClass.get() pattern like auth - get() → email.send() → done
+ * @llm-rule NOTE: Common pattern - emailClass.get() → email.send({ to, subject, text }) → sent
+ */
+import { type EmailConfig } from './defaults.js';
+export interface Email {
+    send(data: EmailData): Promise<EmailResult>;
+    sendBatch(emails: EmailData[], batchSize?: number): Promise<EmailResult[]>;
+    sendText(to: string, subject: string, text: string): Promise<EmailResult>;
+    sendHtml(to: string, subject: string, html: string, text?: string): Promise<EmailResult>;
+    sendTemplate(templateName: string, data: any): Promise<EmailResult>;
+    disconnect(): Promise<void>;
+    getStrategy(): string;
+    getConfig(): any;
+}
+export interface EmailData {
+    to: string | EmailAddress | (string | EmailAddress)[];
+    from?: string | EmailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+    attachments?: EmailAttachment[];
+    replyTo?: string | EmailAddress;
+    cc?: string | EmailAddress | (string | EmailAddress)[];
+    bcc?: string | EmailAddress | (string | EmailAddress)[];
+}
+export interface EmailAddress {
+    name?: string;
+    email: string;
+}
+export interface EmailAttachment {
+    filename: string;
+    content: Buffer | string;
+    contentType?: string;
+}
+export interface EmailResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+}
+/**
+ * Get email instance - the only function you need to learn
+ * Strategy auto-detected from environment (RESEND_API_KEY → Resend, SMTP_HOST → SMTP, default → Console)
+ * @llm-rule WHEN: Need email sending in any part of your app - this is your main entry point
+ * @llm-rule AVOID: Creating EmailClass directly - always use this function
+ * @llm-rule NOTE: Typical flow - get() → email.send() → email delivered/logged
+ */
+declare function get(): Email;
+/**
+ * Clear email instance and disconnect - essential for testing
+ * @llm-rule WHEN: Testing email logic with different configurations or app shutdown
+ * @llm-rule AVOID: Using in production except for graceful shutdown
+ */
+declare function clear(): Promise<void>;
+/**
+ * Reset email configuration (useful for testing)
+ * @llm-rule WHEN: Testing email logic with different environment configurations
+ * @llm-rule AVOID: Using in production - only for tests and development
+ */
+declare function reset(newConfig?: Partial<EmailConfig>): Promise<void>;
+/**
+ * Get active email strategy for debugging
+ * @llm-rule WHEN: Debugging or health checks to see which strategy is active (Resend/SMTP/Console)
+ * @llm-rule AVOID: Using for application logic - email should be transparent
+ */
+declare function getStrategy(): string;
+/**
+ * Get email configuration summary for debugging
+ * @llm-rule WHEN: Health checks or debugging email configuration
+ * @llm-rule AVOID: Exposing sensitive API keys or passwords - this only shows safe info
+ */
+declare function getConfig(): {
+    strategy: string;
+    fromName: string;
+    fromEmail: string;
+    environment: string;
+};
+/**
+ * Check if Resend is available and configured
+ * @llm-rule WHEN: Conditional logic based on email capabilities
+ * @llm-rule AVOID: Complex email detection - just use email normally, it handles strategy
+ */
+declare function hasResend(): boolean;
+/**
+ * Check if SMTP is available and configured
+ * @llm-rule WHEN: Conditional logic based on email capabilities
+ * @llm-rule AVOID: Complex email detection - just use email normally, it handles strategy
+ */
+declare function hasSmtp(): boolean;
+/**
+ * Check if any email provider is configured (not just console)
+ * @llm-rule WHEN: Determining if real emails can be sent
+ * @llm-rule AVOID: Using for validation - email.send() will return success/error appropriately
+ */
+declare function hasProvider(): boolean;
+/**
+ * Send simple email (convenience function)
+ * @llm-rule WHEN: Quick email sending without getting instance first
+ * @llm-rule AVOID: For complex emails - use get() and full EmailData object instead
+ */
+declare function send(data: EmailData): Promise<EmailResult>;
+/**
+ * Send simple text email (ultra-convenience function)
+ * @llm-rule WHEN: Sending basic notifications or alerts quickly
+ * @llm-rule AVOID: For formatted emails - use send() with HTML content instead
+ */
+declare function sendText(to: string, subject: string, text: string): Promise<EmailResult>;
+/**
+ * Validate email configuration at startup with detailed feedback
+ * @llm-rule WHEN: App startup to ensure email is properly configured
+ * @llm-rule AVOID: Skipping validation - missing email config causes runtime issues
+ * @llm-rule NOTE: Returns validation results instead of throwing - allows graceful handling
+ */
+declare function validateConfig(): {
+    valid: boolean;
+    strategy: string;
+    warnings: string[];
+    errors: string[];
+    ready: boolean;
+};
+/**
+ * Validate production requirements and throw if critical issues found
+ * @llm-rule WHEN: Production deployment validation - ensures email works in production
+ * @llm-rule AVOID: Skipping in production - email failures are often silent
+ * @llm-rule NOTE: Throws on critical issues, warns on non-critical ones
+ */
+declare function validateProduction(): void;
+/**
+ * Get comprehensive health check status for monitoring
+ * @llm-rule WHEN: Health check endpoints or monitoring systems
+ * @llm-rule AVOID: Using in critical application path - this is for monitoring only
+ * @llm-rule NOTE: Returns detailed status without exposing sensitive configuration
+ */
+declare function getHealthStatus(): {
+    status: 'healthy' | 'warning' | 'error';
+    strategy: string;
+    configured: boolean;
+    issues: string[];
+    ready: boolean;
+    timestamp: string;
+};
+/**
+ * Graceful shutdown for email instance
+ * @llm-rule WHEN: App shutdown or process termination
+ * @llm-rule AVOID: Abrupt process exit - graceful shutdown prevents connection issues
+ */
+declare function shutdown(): Promise<void>;
+/**
+ * Single email export with minimal API (like auth module)
+ */
+export declare const emailClass: {
+    readonly get: typeof get;
+    readonly clear: typeof clear;
+    readonly reset: typeof reset;
+    readonly getStrategy: typeof getStrategy;
+    readonly getConfig: typeof getConfig;
+    readonly hasResend: typeof hasResend;
+    readonly hasSmtp: typeof hasSmtp;
+    readonly hasProvider: typeof hasProvider;
+    readonly send: typeof send;
+    readonly sendText: typeof sendText;
+    readonly validateConfig: typeof validateConfig;
+    readonly validateProduction: typeof validateProduction;
+    readonly getHealthStatus: typeof getHealthStatus;
+    readonly shutdown: typeof shutdown;
+};
+export type { EmailConfig } from './defaults.js';
+export { EmailClass } from './email.js';
+export default emailClass;
+//# sourceMappingURL=index.d.ts.map

package/dist/email/index.d.ts.map

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