@nice2dev/ui-communication 1.0.4 → 1.0.6

package/dist/services/emailTrackingService.d.ts

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview Email Tracking Service for open and click tracking
+ * @module @nice2dev/ui-communication/services/emailTrackingService
+ * @description Provides tracking pixel generation, link wrapping, and analytics
+ *              for email campaigns with privacy-compliant options.
+ */
+export type TrackingEventType = 'open' | 'click' | 'bounce' | 'unsubscribe' | 'complaint';
+export interface TrackingEvent {
+    /** Unique event ID */
+    id: string;
+    /** Type of tracking event */
+    type: TrackingEventType;
+    /** Email message ID */
+    messageId: string;
+    /** Recipient email (hashed for privacy) */
+    recipientHash: string;
+    /** Link URL (for click events) */
+    url?: string;
+    /** Timestamp of the event */
+    timestamp: Date;
+    /** User agent string */
+    userAgent?: string;
+    /** IP address (can be anonymized) */
+    ipAddress?: string;
+    /** Geo location derived from IP */
+    geoLocation?: {
+        country?: string;
+        region?: string;
+        city?: string;
+    };
+    /** Device type */
+    device?: 'desktop' | 'mobile' | 'tablet' | 'unknown';
+    /** Email client */
+    emailClient?: string;
+    /** Campaign ID if part of a campaign */
+    campaignId?: string;
+}
+export interface TrackingPixelOptions {
+    /** Base URL for tracking server */
+    trackingServerUrl: string;
+    /** Message ID to track */
+    messageId: string;
+    /** Recipient identifier (will be hashed) */
+    recipientId: string;
+    /** Campaign ID */
+    campaignId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+    /** Pixel dimensions (default 1x1) */
+    width?: number;
+    height?: number;
+}
+export interface TrackedLinkOptions {
+    /** Original URL */
+    url: string;
+    /** Base URL for tracking redirect */
+    trackingServerUrl: string;
+    /** Message ID */
+    messageId: string;
+    /** Recipient identifier */
+    recipientId: string;
+    /** Campaign ID */
+    campaignId?: string;
+    /** Link position/name for analytics */
+    linkName?: string;
+}
+export interface EmailTrackingStats {
+    /** Total emails sent */
+    sent: number;
+    /** Total emails delivered */
+    delivered: number;
+    /** Total opens (can include duplicates) */
+    opens: number;
+    /** Unique opens */
+    uniqueOpens: number;
+    /** Total clicks */
+    clicks: number;
+    /** Unique clicks */
+    uniqueClicks: number;
+    /** Bounced emails */
+    bounces: number;
+    /** Unsubscribes */
+    unsubscribes: number;
+    /** Spam complaints */
+    complaints: number;
+    /** Open rate (unique opens / delivered) */
+    openRate: number;
+    /** Click rate (unique clicks / delivered) */
+    clickRate: number;
+    /** Click-to-open rate (unique clicks / unique opens) */
+    clickToOpenRate: number;
+    /** Bounce rate */
+    bounceRate: number;
+}
+export interface LinkStats {
+    /** Link URL */
+    url: string;
+    /** Link name/identifier */
+    linkName?: string;
+    /** Total clicks */
+    totalClicks: number;
+    /** Unique clicks */
+    uniqueClicks: number;
+    /** Click share (% of total clicks) */
+    clickShare: number;
+}
+export interface EmailTrackingConfig {
+    /** Tracking server base URL */
+    serverUrl: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Whether to anonymize IP addresses */
+    anonymizeIp?: boolean;
+    /** Enable geo location lookup */
+    enableGeoLocation?: boolean;
+    /** Custom tracking pixel path */
+    pixelPath?: string;
+    /** Custom redirect path */
+    redirectPath?: string;
+    /** Hash algorithm for recipient IDs */
+    hashAlgorithm?: 'sha256' | 'sha512' | 'md5';
+}
+/**
+ * Service for tracking email opens and clicks.
+ *
+ * @example
+ * ```tsx
+ * const tracking = new EmailTrackingService({
+ *   serverUrl: 'https://track.example.com',
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * // Generate tracking pixel
+ * const pixel = tracking.generateTrackingPixel({
+ *   messageId: 'msg-123',
+ *   recipientId: 'user@example.com',
+ * });
+ *
+ * // Wrap links for click tracking
+ * const trackedHtml = tracking.wrapLinksForTracking(htmlContent, {
+ *   messageId: 'msg-123',
+ *   recipientId: 'user@example.com',
+ * });
+ * ```
+ */
+export declare class EmailTrackingService {
+    private config;
+    private events;
+    private eventListeners;
+    constructor(config: EmailTrackingConfig);
+    /**
+     * Generates a tracking pixel HTML for email opens.
+     */
+    generateTrackingPixel(options: Omit<TrackingPixelOptions, 'trackingServerUrl'>): string;
+    /**
+     * Generates tracking pixel URL only (without HTML).
+     */
+    generateTrackingPixelUrl(options: Omit<TrackingPixelOptions, 'trackingServerUrl'>): string;
+    /**
+     * Wraps a single URL for click tracking.
+     */
+    wrapLink(options: Omit<TrackedLinkOptions, 'trackingServerUrl'>): string;
+    /**
+     * Wraps all links in HTML content for click tracking.
+     */
+    wrapLinksForTracking(html: string, options: {
+        messageId: string;
+        recipientId: string;
+        campaignId?: string;
+        excludePatterns?: RegExp[];
+    }): string;
+    /**
+     * Records a tracking event.
+     */
+    recordEvent(event: Omit<TrackingEvent, 'id' | 'timestamp'>): TrackingEvent;
+    /**
+     * Parses tracking parameters from a request.
+     */
+    parseTrackingParams(params: URLSearchParams): {
+        messageId: string;
+        recipientHash: string;
+        campaignId?: string;
+        url?: string;
+        linkName?: string;
+        metadata?: Record<string, string>;
+    } | null;
+    /**
+     * Calculates tracking statistics for a campaign or message.
+     */
+    getStats(filter?: {
+        campaignId?: string;
+        messageId?: string;
+        startDate?: Date;
+        endDate?: Date;
+    }): EmailTrackingStats;
+    /**
+     * Gets click statistics per link.
+     */
+    getLinkStats(filter?: {
+        campaignId?: string;
+        messageId?: string;
+    }): LinkStats[];
+    /**
+     * Gets device/client breakdown.
+     */
+    getDeviceStats(filter?: {
+        campaignId?: string;
+    }): Record<string, number>;
+    /**
+     * Subscribes to tracking events.
+     */
+    on(eventType: TrackingEventType, callback: (event: TrackingEvent) => void): () => void;
+    /**
+     * Subscribes to all tracking events.
+     */
+    onAny(callback: (event: TrackingEvent) => void): () => void;
+    /**
+     * Generates a privacy-compliant unsubscribe link.
+     */
+    generateUnsubscribeLink(options: {
+        recipientId: string;
+        listId?: string;
+    }): string;
+    /**
+     * Generates List-Unsubscribe header value.
+     */
+    generateListUnsubscribeHeader(options: {
+        recipientId: string;
+        listId?: string;
+    }): string;
+    /**
+     * Clears all stored events (for privacy/GDPR compliance).
+     */
+    clearEvents(): void;
+    /**
+     * Exports events for backup/analysis (anonymized).
+     */
+    exportEvents(options?: {
+        anonymize?: boolean;
+    }): TrackingEvent[];
+    private buildTrackingParams;
+    private hashRecipientId;
+    private anonymizeIpAddress;
+    private extractLinkName;
+    private escapeHtml;
+    private generateEventId;
+    private notifyListeners;
+}
+/**
+ * Gets or creates the email tracking service singleton.
+ */
+export declare function getEmailTrackingService(config?: EmailTrackingConfig): EmailTrackingService;
+/**
+ * Disposes the email tracking service singleton.
+ */
+export declare function disposeEmailTrackingService(): void;
+export interface UseEmailTrackingOptions {
+    config?: EmailTrackingConfig;
+    campaignId?: string;
+    autoRefreshInterval?: number;
+}
+export interface UseEmailTrackingReturn {
+    /** Generate tracking pixel HTML */
+    generatePixel: (messageId: string, recipientId: string) => string;
+    /** Wrap links in HTML for tracking */
+    wrapLinks: (html: string, messageId: string, recipientId: string) => string;
+    /** Current statistics */
+    stats: EmailTrackingStats | null;
+    /** Link statistics */
+    linkStats: LinkStats[];
+    /** Record a tracking event */
+    recordEvent: (event: Omit<TrackingEvent, 'id' | 'timestamp'>) => void;
+    /** Refresh statistics */
+    refreshStats: () => void;
+}
+/**
+ * React hook for email tracking functionality.
+ */
+export declare function useEmailTracking(options: UseEmailTrackingOptions): UseEmailTrackingReturn;

package/dist/services/mailMergeService.d.ts

@@ -0,0 +1,365 @@
+/**
+ * @fileoverview Mail Merge Service for bulk personalized emails
+ * @module @nice2dev/ui-communication/services/mailMergeService
+ * @description Provides template processing, variable substitution,
+ *              recipient management, and batch sending for email campaigns.
+ */
+export type MergeFieldType = 'text' | 'number' | 'date' | 'currency' | 'boolean' | 'list' | 'conditional';
+export interface MergeField {
+    /** Field name (used in template as {{fieldName}}) */
+    name: string;
+    /** Field type for formatting */
+    type: MergeFieldType;
+    /** Default value if not provided */
+    defaultValue?: string | number | boolean;
+    /** Whether field is required */
+    required?: boolean;
+    /** Format string (for dates, numbers, currency) */
+    format?: string;
+    /** Description for UI */
+    description?: string;
+}
+export interface MergeRecipient {
+    /** Unique recipient ID */
+    id: string;
+    /** Primary email address */
+    email: string;
+    /** Additional email addresses (CC) */
+    cc?: string[];
+    /** BCC addresses */
+    bcc?: string[];
+    /** Merge field values */
+    data: Record<string, unknown>;
+    /** Custom subject override */
+    subjectOverride?: string;
+    /** Recipient tags for filtering */
+    tags?: string[];
+    /** Send status */
+    status?: 'pending' | 'sent' | 'failed' | 'bounced';
+    /** Error message if failed */
+    error?: string;
+    /** Scheduled send time */
+    scheduledAt?: Date;
+}
+export interface MergeTemplate {
+    /** Template ID */
+    id: string;
+    /** Template name */
+    name: string;
+    /** Email subject (can contain merge fields) */
+    subject: string;
+    /** HTML body (can contain merge fields) */
+    htmlBody: string;
+    /** Plain text body (can contain merge fields) */
+    textBody?: string;
+    /** Defined merge fields */
+    fields: MergeField[];
+    /** Template tags */
+    tags?: string[];
+    /** Created timestamp */
+    createdAt: Date;
+    /** Last modified timestamp */
+    updatedAt: Date;
+}
+export interface MergeCampaign {
+    /** Campaign ID */
+    id: string;
+    /** Campaign name */
+    name: string;
+    /** Template ID */
+    templateId: string;
+    /** Sender email */
+    fromEmail: string;
+    /** Sender name */
+    fromName: string;
+    /** Reply-to address */
+    replyTo?: string;
+    /** Recipients */
+    recipients: MergeRecipient[];
+    /** Campaign status */
+    status: 'draft' | 'scheduled' | 'sending' | 'paused' | 'completed' | 'cancelled';
+    /** Scheduled send time */
+    scheduledAt?: Date;
+    /** Send rate limit (emails per minute) */
+    rateLimit?: number;
+    /** Enable tracking */
+    enableTracking?: boolean;
+    /** Campaign metadata */
+    metadata?: Record<string, unknown>;
+    /** Created timestamp */
+    createdAt: Date;
+    /** Started timestamp */
+    startedAt?: Date;
+    /** Completed timestamp */
+    completedAt?: Date;
+}
+export interface MergeProgress {
+    /** Campaign ID */
+    campaignId: string;
+    /** Total recipients */
+    total: number;
+    /** Sent count */
+    sent: number;
+    /** Failed count */
+    failed: number;
+    /** Pending count */
+    pending: number;
+    /** Current recipient being processed */
+    current?: string;
+    /** Progress percentage */
+    percentage: number;
+    /** Estimated time remaining (seconds) */
+    estimatedTimeRemaining?: number;
+    /** Is complete */
+    isComplete: boolean;
+}
+export interface MergeValidationResult {
+    /** Is template valid */
+    isValid: boolean;
+    /** Validation errors */
+    errors: MergeValidationError[];
+    /** Warnings */
+    warnings: MergeValidationWarning[];
+    /** Missing fields per recipient */
+    missingFields: Map<string, string[]>;
+}
+export interface MergeValidationError {
+    /** Error type */
+    type: 'missing_field' | 'invalid_format' | 'syntax_error' | 'empty_recipient';
+    /** Field name if applicable */
+    field?: string;
+    /** Recipient ID if applicable */
+    recipientId?: string;
+    /** Error message */
+    message: string;
+}
+export interface MergeValidationWarning {
+    /** Warning type */
+    type: 'unused_field' | 'long_content' | 'suspicious_content';
+    /** Field name if applicable */
+    field?: string;
+    /** Warning message */
+    message: string;
+}
+export interface MailMergeConfig {
+    /** Email sending function */
+    sendEmail: (email: SendEmailParams) => Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+    /** Rate limit (emails per minute, default: 60) */
+    rateLimit?: number;
+    /** Batch size for processing */
+    batchSize?: number;
+    /** Retry failed sends */
+    retryOnFail?: boolean;
+    /** Max retries per recipient */
+    maxRetries?: number;
+    /** Custom date formatter */
+    dateFormatter?: (date: Date, format: string) => string;
+    /** Custom number formatter */
+    numberFormatter?: (num: number, format: string) => string;
+    /** Custom currency formatter */
+    currencyFormatter?: (amount: number, currency: string, locale: string) => string;
+}
+export interface SendEmailParams {
+    to: string;
+    cc?: string[];
+    bcc?: string[];
+    from: string;
+    fromName?: string;
+    replyTo?: string;
+    subject: string;
+    html: string;
+    text?: string;
+    headers?: Record<string, string>;
+    attachments?: Array<{
+        filename: string;
+        content: string | Buffer;
+        contentType?: string;
+    }>;
+}
+/**
+ * Service for mail merge and bulk email campaigns with personalization.
+ *
+ * @example
+ * ```tsx
+ * const mergeService = new MailMergeService({
+ *   sendEmail: async (params) => {
+ *     // Your email sending logic
+ *     return { success: true, messageId: 'msg-123' };
+ *   },
+ *   rateLimit: 100,
+ * });
+ *
+ * // Create template
+ * const template = mergeService.createTemplate({
+ *   name: 'Welcome Email',
+ *   subject: 'Welcome, {{firstName}}!',
+ *   htmlBody: '<p>Hello {{firstName}} {{lastName}},</p><p>Welcome to our platform!</p>',
+ *   fields: [
+ *     { name: 'firstName', type: 'text', required: true },
+ *     { name: 'lastName', type: 'text', required: true },
+ *   ],
+ * });
+ *
+ * // Create campaign
+ * const campaign = mergeService.createCampaign({
+ *   name: 'Welcome Campaign',
+ *   templateId: template.id,
+ *   fromEmail: 'hello@example.com',
+ *   fromName: 'Example Team',
+ *   recipients: [
+ *     { id: '1', email: 'john@example.com', data: { firstName: 'John', lastName: 'Doe' } },
+ *     { id: '2', email: 'jane@example.com', data: { firstName: 'Jane', lastName: 'Smith' } },
+ *   ],
+ * });
+ *
+ * // Send campaign
+ * for await (const progress of mergeService.sendCampaign(campaign.id)) {
+ *   console.log(`Progress: ${progress.percentage}%`);
+ * }
+ * ```
+ */
+export declare class MailMergeService {
+    private config;
+    private templates;
+    private campaigns;
+    private abortControllers;
+    constructor(config: MailMergeConfig);
+    /**
+     * Creates a new merge template.
+     */
+    createTemplate(input: Omit<MergeTemplate, 'id' | 'createdAt' | 'updatedAt'>): MergeTemplate;
+    /**
+     * Updates an existing template.
+     */
+    updateTemplate(id: string, updates: Partial<Omit<MergeTemplate, 'id' | 'createdAt'>>): MergeTemplate;
+    /**
+     * Gets a template by ID.
+     */
+    getTemplate(id: string): MergeTemplate | undefined;
+    /**
+     * Deletes a template.
+     */
+    deleteTemplate(id: string): boolean;
+    /**
+     * Lists all templates.
+     */
+    listTemplates(): MergeTemplate[];
+    /**
+     * Extracts merge fields from template content.
+     */
+    extractFields(content: string): string[];
+    /**
+     * Creates a new mail merge campaign.
+     */
+    createCampaign(input: Omit<MergeCampaign, 'id' | 'status' | 'createdAt'>): MergeCampaign;
+    /**
+     * Gets a campaign by ID.
+     */
+    getCampaign(id: string): MergeCampaign | undefined;
+    /**
+     * Updates a campaign.
+     */
+    updateCampaign(id: string, updates: Partial<Omit<MergeCampaign, 'id' | 'createdAt'>>): MergeCampaign;
+    /**
+     * Adds recipients to a campaign.
+     */
+    addRecipients(campaignId: string, recipients: MergeRecipient[]): void;
+    /**
+     * Removes a recipient from a campaign.
+     */
+    removeRecipient(campaignId: string, recipientId: string): boolean;
+    /**
+     * Lists all campaigns.
+     */
+    listCampaigns(): MergeCampaign[];
+    /**
+     * Validates a campaign before sending.
+     */
+    validateCampaign(campaignId: string): MergeValidationResult;
+    /**
+     * Previews merged content for a specific recipient.
+     */
+    previewMerge(templateId: string, recipientData: Record<string, unknown>): {
+        subject: string;
+        html: string;
+        text?: string;
+    };
+    /**
+     * Sends a campaign. Returns an async generator for progress updates.
+     */
+    sendCampaign(campaignId: string): AsyncGenerator<MergeProgress, void, unknown>;
+    /**
+     * Pauses a running campaign.
+     */
+    pauseCampaign(campaignId: string): void;
+    /**
+     * Resumes a paused campaign.
+     */
+    resumeCampaign(campaignId: string): AsyncGenerator<MergeProgress, void, unknown>;
+    /**
+     * Cancels a campaign.
+     */
+    cancelCampaign(campaignId: string): void;
+    /**
+     * Retries failed recipients in a campaign.
+     */
+    retryFailed(campaignId: string): AsyncGenerator<MergeProgress, void, unknown>;
+    private processTemplate;
+    private processConditionals;
+    private processLoops;
+    private formatValue;
+    private applyFormatter;
+    private getNestedValue;
+    private isTruthy;
+    private defaultDateFormatter;
+    private defaultNumberFormatter;
+    private defaultCurrencyFormatter;
+    private generateId;
+    private escapeHtml;
+    private delay;
+}
+/**
+ * Gets or creates the mail merge service singleton.
+ */
+export declare function getMailMergeService(config?: MailMergeConfig): MailMergeService;
+/**
+ * Disposes the mail merge service singleton.
+ */
+export declare function disposeMailMergeService(): void;
+export interface UseMailMergeOptions {
+    config?: MailMergeConfig;
+}
+export interface UseMailMergeReturn {
+    /** Create a merge template */
+    createTemplate: (input: Omit<MergeTemplate, 'id' | 'createdAt' | 'updatedAt'>) => MergeTemplate;
+    /** Create a campaign */
+    createCampaign: (input: Omit<MergeCampaign, 'id' | 'status' | 'createdAt'>) => MergeCampaign;
+    /** Preview merge for a recipient */
+    preview: (templateId: string, data: Record<string, unknown>) => {
+        subject: string;
+        html: string;
+        text?: string;
+    };
+    /** Validate a campaign */
+    validate: (campaignId: string) => MergeValidationResult;
+    /** Send campaign (returns progress generator) */
+    send: (campaignId: string) => AsyncGenerator<MergeProgress, void, unknown>;
+    /** Pause sending */
+    pause: (campaignId: string) => void;
+    /** Current progress */
+    progress: MergeProgress | null;
+    /** Is sending */
+    isSending: boolean;
+    /** Templates */
+    templates: MergeTemplate[];
+    /** Campaigns */
+    campaigns: MergeCampaign[];
+}
+/**
+ * React hook for mail merge functionality.
+ */
+export declare function useMailMerge(options?: UseMailMergeOptions): UseMailMergeReturn;