@vulog/aima-notifier

Notification management module for the AIMA platform. This module provides functionality to send emails and other notifications to users.

Installation

npm install @vulog/aima-client @vulog/aima-core @vulog/aima-notifier

Usage

Initialize Client

import { getClient } from '@vulog/aima-client';
import { sendEmail } from '@vulog/aima-notifier';

const client = getClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://your-api-base-url',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    fleetId: 'your-fleet-id',
});

API Reference

sendEmail

Send an email notification to users.

const result = await sendEmail(client, {
    bodyData: {
        userName: 'John Doe',
        vehicleId: 'vehicle-123',
        tripId: 'trip-456'
    },
    lang: 'en_GB',
    to: ['[email protected]', '[email protected]'],
    type: 'trip_confirmation'
});

Parameters:

• client: AIMA client instance
• emailData: Email configuration object
  • bodyData: Dynamic data to include in the email template
  • lang: Language code (e.g., 'en_GB', 'fr_FR', 'es_ES')
  • to: Array of recipient email addresses
  • type: Email template type

Returns: Email sending result object

Types

SendEmailData

interface SendEmailData {
    [key: string]: any; // Dynamic data for email template
}

SendEmailParam

interface SendEmailParam {
    bodyData: SendEmailData;
    lang: string;
    to: string[];
    type: string;
}

Supported Email Types

Common email template types include:

• welcome: Welcome email for new users
• trip_confirmation: Trip booking confirmation
• trip_reminder: Trip reminder notification
• payment_receipt: Payment confirmation
• password_reset: Password reset instructions
• account_verification: Account verification email
• trip_completed: Trip completion summary
• vehicle_alert: Vehicle-related alerts
• billing_notification: Billing and invoice notifications

Error Handling

The function will throw appropriate errors if:

• Required parameters are missing
• Invalid email addresses are provided
• Email template type is not supported
• Network errors occur

Examples

Basic Email Sending

import { getClient } from '@vulog/aima-client';
import { sendEmail } from '@vulog/aima-notifier';

const client = getClient({
    apiKey: 'your-api-key',
    baseUrl: 'https://your-api-base-url',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    fleetId: 'your-fleet-id',
});

async function sendBasicEmail() {
    try {
        const result = await sendEmail(client, {
            bodyData: {
                userName: 'John Doe',
                message: 'Welcome to our service!'
            },
            lang: 'en_GB',
            to: ['[email protected]'],
            type: 'welcome'
        });
        
        console.log('Email sent successfully:', result);
        return result;
    } catch (error) {
        console.error('Email sending error:', error);
        throw error;
    }
}

Trip Confirmation Email

async function sendTripConfirmation(client, userEmail, tripData) {
    try {
        const result = await sendEmail(client, {
            bodyData: {
                userName: tripData.userName,
                vehicleName: tripData.vehicleName,
                vehiclePlate: tripData.vehiclePlate,
                startTime: tripData.startTime,
                endTime: tripData.endTime,
                startLocation: tripData.startLocation,
                endLocation: tripData.endLocation,
                totalCost: tripData.totalCost,
                currency: tripData.currency
            },
            lang: tripData.locale || 'en_GB',
            to: [userEmail],
            type: 'trip_confirmation'
        });
        
        console.log('Trip confirmation email sent:', result);
        return result;
    } catch (error) {
        console.error('Trip confirmation email error:', error);
        throw error;
    }
}

Multi-language Email Support

async function sendLocalizedEmail(client, userEmail, userLocale, emailType, data) {
    try {
        // Map common locales to supported language codes
        const localeMap = {
            'en': 'en_GB',
            'en-US': 'en_GB',
            'en-GB': 'en_GB',
            'fr': 'fr_FR',
            'fr-FR': 'fr_FR',
            'es': 'es_ES',
            'es-ES': 'es_ES',
            'de': 'de_DE',
            'de-DE': 'de_DE'
        };
        
        const lang = localeMap[userLocale] || 'en_GB';
        
        const result = await sendEmail(client, {
            bodyData: data,
            lang: lang,
            to: [userEmail],
            type: emailType
        });
        
        console.log(`Email sent in ${lang}:`, result);
        return result;
    } catch (error) {
        console.error('Localized email error:', error);
        throw error;
    }
}

Bulk Email Sending

async function sendBulkEmails(client, recipients, emailType, data) {
    try {
        const results = await Promise.all(
            recipients.map(recipient => 
                sendEmail(client, {
                    bodyData: {
                        ...data,
                        userName: recipient.name,
                        userEmail: recipient.email
                    },
                    lang: recipient.locale || 'en_GB',
                    to: [recipient.email],
                    type: emailType
                }).catch(error => {
                    console.error(`Failed to send email to ${recipient.email}:`, error);
                    return { error, recipient };
                })
            )
        );
        
        const successful = results.filter(r => !r.error);
        const failed = results.filter(r => r.error);
        
        console.log(`Bulk email results: ${successful.length} successful, ${failed.length} failed`);
        
        return { successful, failed };
    } catch (error) {
        console.error('Bulk email error:', error);
        throw error;
    }
}

Email Template Testing

async function testEmailTemplates(client) {
    try {
        const testTemplates = [
            'welcome',
            'trip_confirmation',
            'payment_receipt',
            'password_reset',
            'account_verification'
        ];
        
        const testData = {
            userName: 'Test User',
            vehicleName: 'Test Vehicle',
            vehiclePlate: 'TEST-123',
            startTime: '2024-01-01T10:00:00Z',
            endTime: '2024-01-01T11:00:00Z',
            totalCost: 15.50,
            currency: 'EUR'
        };
        
        const results = [];
        
        for (const template of testTemplates) {
            try {
                const result = await sendEmail(client, {
                    bodyData: testData,
                    lang: 'en_GB',
                    to: ['[email protected]'],
                    type: template
                });
                
                results.push({ template, status: 'success', result });
                console.log(`✅ Template ${template} sent successfully`);
            } catch (error) {
                results.push({ template, status: 'error', error: error.message });
                console.log(`❌ Template ${template} failed:`, error.message);
            }
        }
        
        return results;
    } catch (error) {
        console.error('Email template testing error:', error);
        throw error;
    }
}