@kumix/email 0.1.0

package/dist/helpers.d.ts

@@ -0,0 +1,325 @@
+import React from "react";
+
+//#region src/helpers.d.ts
+/**
+ * Render React component to HTML string
+ *
+ * Converts a React email template component to HTML string that can be sent via email.
+ *
+ * @param Template - React component to render
+ * @param props - Props to pass to the component
+ * @returns Promise resolving to HTML string
+ * @example
+ * ```typescript
+ * const WelcomeEmail = ({ name }: { name: string }) => <h1>Welcome {name}!</h1>;
+ *
+ * const html = await renderEmailTemplate(WelcomeEmail, { name: 'John' });
+ * console.log(html); // "<h1>Welcome John!</h1>"
+ * ```
+ */
+declare function renderEmailTemplate<T extends Record<string, unknown>>(Template: React.ComponentType<T>, props: T): Promise<string>;
+/**
+ * Generate plain text from HTML
+ *
+ * Converts HTML content to plain text by removing tags and normalizing whitespace.
+ * Useful for creating text versions of HTML emails.
+ *
+ * @param html - HTML string to convert
+ * @returns Plain text version of the HTML
+ * @example
+ * ```typescript
+ * const html = '<h1>Hello</h1><p>Welcome to our <strong>platform</strong>!</p>';
+ * const text = htmlToText(html);
+ * console.log(text); // "Hello Welcome to our platform!"
+ * ```
+ */
+declare function htmlToText(html: string): string;
+/**
+ * Validate email address format
+ *
+ * Checks if an email address has a valid format using RFC 5322 compliant regex.
+ *
+ * @param email - Email address to validate
+ * @returns true if email format is valid, false otherwise
+ * @example
+ * ```typescript
+ * console.log(isValidEmail('user@example.com')); // true
+ * console.log(isValidEmail('invalid-email')); // false
+ * console.log(isValidEmail('user+tag@example.co.uk')); // true
+ * ```
+ */
+declare function isValidEmail(email: string): boolean;
+/**
+ * Validate multiple email addresses
+ *
+ * Validates an array of email addresses or a single email address.
+ *
+ * @param emails - Single email or array of emails to validate
+ * @returns true if all emails are valid, false if any are invalid
+ * @example
+ * ```typescript
+ * console.log(validateEmails('user@example.com')); // true
+ * console.log(validateEmails(['user1@example.com', 'user2@example.com'])); // true
+ * console.log(validateEmails(['valid@example.com', 'invalid-email'])); // false
+ * ```
+ */
+declare function validateEmails(emails: string | string[]): boolean;
+/**
+ * Filter valid emails from a list
+ *
+ * Returns only the valid email addresses from a list, filtering out invalid ones.
+ *
+ * @param emails - Array of email addresses to filter
+ * @returns Array containing only valid email addresses
+ * @example
+ * ```typescript
+ * const emails = ['valid@example.com', 'invalid-email', 'another@example.com'];
+ * const validEmails = filterValidEmails(emails);
+ * console.log(validEmails); // ['valid@example.com', 'another@example.com']
+ * ```
+ */
+declare function filterValidEmails(emails: string[]): string[];
+/**
+ * Format email address with display name
+ *
+ * Combines a display name with an email address in the standard format.
+ *
+ * @param name - Display name for the email address
+ * @param email - Email address
+ * @returns Formatted email address string
+ * @example
+ * ```typescript
+ * const formatted = formatEmailAddress('John Doe', 'john@example.com');
+ * console.log(formatted); // "John Doe <john@example.com>"
+ * ```
+ */
+declare function formatEmailAddress(name: string, email: string): string;
+/**
+ * Extract email address from formatted string
+ *
+ * Extracts the email address from a formatted "Name <email>" string.
+ *
+ * @param formattedAddress - Formatted email address string
+ * @returns Just the email address part
+ * @example
+ * ```typescript
+ * const email = extractEmail('John Doe <john@example.com>');
+ * console.log(email); // "john@example.com"
+ *
+ * const email2 = extractEmail('simple@example.com');
+ * console.log(email2); // "simple@example.com"
+ * ```
+ */
+declare function extractEmail(formattedAddress: string): string;
+/**
+ * Extract display name from formatted email address
+ *
+ * Extracts the display name from a formatted "Name <email>" string.
+ *
+ * @param formattedAddress - Formatted email address string
+ * @returns Display name or empty string if none found
+ * @example
+ * ```typescript
+ * const name = extractDisplayName('John Doe <john@example.com>');
+ * console.log(name); // "John Doe"
+ *
+ * const name2 = extractDisplayName('simple@example.com');
+ * console.log(name2); // ""
+ * ```
+ */
+declare function extractDisplayName(formattedAddress: string): string;
+/**
+ * Sanitize HTML content for email
+ *
+ * Removes potentially dangerous HTML elements and attributes while preserving
+ * email-safe formatting.
+ *
+ * @param html - HTML content to sanitize
+ * @returns Sanitized HTML safe for email
+ * @example
+ * ```typescript
+ * const unsafeHtml = '<script>alert("xss")</script><p>Safe content</p>';
+ * const safeHtml = sanitizeHtml(unsafeHtml);
+ * console.log(safeHtml); // "<p>Safe content</p>"
+ * ```
+ */
+declare function sanitizeHtml(html: string): string;
+/**
+ * Truncate text with ellipsis
+ *
+ * Truncates text to a specified length and adds ellipsis if needed.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length before truncation
+ * @param ellipsis - String to append when truncated (default: '...')
+ * @returns Truncated text
+ * @example
+ * ```typescript
+ * const text = 'This is a very long email subject line';
+ * const truncated = truncateText(text, 20);
+ * console.log(truncated); // "This is a very long..."
+ * ```
+ */
+declare function truncateText(text: string, maxLength: number, ellipsis?: string): string;
+/**
+ * Generate email preview text
+ *
+ * Creates a preview text from HTML content, suitable for email preview panes.
+ *
+ * @param html - HTML content to generate preview from
+ * @param maxLength - Maximum length of preview text (default: 150)
+ * @returns Preview text
+ * @example
+ * ```typescript
+ * const html = '<h1>Welcome!</h1><p>Thank you for joining our platform.</p>';
+ * const preview = generatePreviewText(html);
+ * console.log(preview); // "Welcome! Thank you for joining our platform."
+ * ```
+ */
+declare function generatePreviewText(html: string, maxLength?: number): string;
+/**
+ * Generate unsubscribe link
+ *
+ * Creates an unsubscribe URL with proper parameters.
+ *
+ * @param baseUrl - Base URL for unsubscribe endpoint
+ * @param email - Email address to unsubscribe
+ * @param token - Optional security token
+ * @returns Complete unsubscribe URL
+ * @example
+ * ```typescript
+ * const link = generateUnsubscribeLink(
+ *   'https://example.com/unsubscribe',
+ *   'user@example.com',
+ *   'secure-token-123'
+ * );
+ * console.log(link); // "https://example.com/unsubscribe?email=user%40example.com&token=secure-token-123"
+ * ```
+ */
+declare function generateUnsubscribeLink(baseUrl: string, email: string, token?: string): string;
+/**
+ * Generate tracking pixel URL
+ *
+ * Creates a tracking pixel URL for email open tracking.
+ *
+ * @param baseUrl - Base URL for tracking endpoint
+ * @param emailId - Unique identifier for the email
+ * @param recipientId - Unique identifier for the recipient
+ * @returns Tracking pixel URL
+ * @example
+ * ```typescript
+ * const pixelUrl = generateTrackingPixel(
+ *   'https://example.com/track',
+ *   'email-123',
+ *   'user-456'
+ * );
+ * // Use in email: <img src="${pixelUrl}" width="1" height="1" />
+ * ```
+ */
+declare function generateTrackingPixel(baseUrl: string, emailId: string, recipientId: string): string;
+/**
+ * Add UTM parameters to URL
+ *
+ * Adds UTM tracking parameters to a URL for campaign tracking.
+ *
+ * @param url - Original URL
+ * @param utmParams - UTM parameters object
+ * @returns URL with UTM parameters added
+ * @example
+ * ```typescript
+ * const trackedUrl = addUtmParams('https://example.com/product', {
+ *   source: 'email',
+ *   medium: 'newsletter',
+ *   campaign: 'summer_sale',
+ *   content: 'header_button'
+ * });
+ * ```
+ */
+declare function addUtmParams(url: string, utmParams: {
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  term?: string;
+  content?: string;
+}): string;
+/**
+ * Parse email list from string
+ *
+ * Parses a comma or semicolon separated string of email addresses.
+ *
+ * @param emailString - String containing multiple email addresses
+ * @returns Array of trimmed email addresses
+ * @example
+ * ```typescript
+ * const emails = parseEmailList('user1@example.com, user2@example.com; user3@example.com');
+ * console.log(emails); // ['user1@example.com', 'user2@example.com', 'user3@example.com']
+ * ```
+ */
+declare function parseEmailList(emailString: string): string[];
+/**
+ * Deduplicate email list
+ *
+ * Removes duplicate email addresses from a list (case-insensitive).
+ *
+ * @param emails - Array of email addresses
+ * @returns Array with duplicates removed
+ * @example
+ * ```typescript
+ * const emails = ['user@example.com', 'USER@EXAMPLE.COM', 'other@example.com'];
+ * const unique = deduplicateEmails(emails);
+ * console.log(unique); // ['user@example.com', 'other@example.com']
+ * ```
+ */
+declare function deduplicateEmails(emails: string[]): string[];
+/**
+ * Chunk email list for batch sending
+ *
+ * Splits a large email list into smaller chunks for batch processing.
+ *
+ * @param emails - Array of email addresses
+ * @param chunkSize - Size of each chunk (default: 100)
+ * @returns Array of email chunks
+ * @example
+ * ```typescript
+ * const emails = ['user1@example.com', 'user2@example.com', ...]; // 250 emails
+ * const chunks = chunkEmails(emails, 100);
+ * console.log(chunks.length); // 3 chunks
+ * console.log(chunks[0].length); // 100
+ * console.log(chunks[2].length); // 50
+ * ```
+ */
+declare function chunkEmails(emails: string[], chunkSize?: number): string[][];
+/**
+ * Get MIME type from file extension
+ *
+ * Returns the appropriate MIME type for common file extensions.
+ *
+ * @param filename - Filename or extension
+ * @returns MIME type string
+ * @example
+ * ```typescript
+ * console.log(getMimeType('document.pdf')); // 'application/pdf'
+ * console.log(getMimeType('image.jpg')); // 'image/jpeg'
+ * console.log(getMimeType('.png')); // 'image/png'
+ * ```
+ */
+declare function getMimeType(filename: string): string;
+/**
+ * Format file size for display
+ *
+ * Converts file size in bytes to human-readable format.
+ *
+ * @param bytes - File size in bytes
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted file size string
+ * @example
+ * ```typescript
+ * console.log(formatFileSize(1024)); // "1.00 KB"
+ * console.log(formatFileSize(1048576)); // "1.00 MB"
+ * console.log(formatFileSize(1073741824, 1)); // "1.0 GB"
+ * ```
+ */
+declare function formatFileSize(bytes: number, decimals?: number): string;
+//#endregion
+export { addUtmParams, chunkEmails, deduplicateEmails, extractDisplayName, extractEmail, filterValidEmails, formatEmailAddress, formatFileSize, generatePreviewText, generateTrackingPixel, generateUnsubscribeLink, getMimeType, htmlToText, isValidEmail, parseEmailList, renderEmailTemplate, sanitizeHtml, truncateText, validateEmails };
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","names":[],"sources":["../src/helpers.ts"],"mappings":";;;;;;AAsEuC;AA6BvC;;;;AAA0C;AAoB1C;;;;AAAwD;AAmBxD;;iBA1FsB,mBAAA,WAA8B,MAAA,mBAClD,QAAA,EAAU,KAAA,CAAM,aAAA,CAAc,CAAA,GAC9B,KAAA,EAAO,CAAA,GACN,OAAA;;AAuF+C;AAsBlD;;;;AAA8D;AAqB9D;;;;AAAqD;AAqBrD;;;iBApIgB,UAAA,CAAW,IAAY;AAoIoB;AAwB3D;;;;AAAyC;AA8BzC;;;;;;;;AAtD2D,iBAvG3C,YAAA,CAAa,KAAa;AAiL1C;;;;AAAyE;AA4BzE;;;;;;;;AAAsF;AA5BtF,iBA7JgB,cAAA,CAAe,MAAyB;;;;;;;;AAwNnC;AA2BrB;;;;;;iBAhOgB,iBAAA,CAAkB,MAAgB;;;;;;AAwO/C;AA8BH;;;;AAAkD;AAqBlD;;;iBArQgB,kBAAA,CAAmB,IAAA,UAAc,KAAa;AAqQZ;AA6BlD;;;;AAAqE;AA0BrE;;;;AAA4C;AAwD5C;;;;AAAkE;AA/GhB,iBAhPlC,YAAA,CAAa,gBAAwB;;;;;;;;;;;;;;;;;iBAqBrC,kBAAA,CAAmB,gBAAwB;;;;;;;;;;;;;;;;iBAwB3C,YAAA,CAAa,IAAY;;;;;;;;;;;;;;;;;iBA8BzB,YAAA,CAAa,IAAA,UAAc,SAAA,UAAmB,QAAA;;;;;;;;;;;;;;;;iBAoB9C,mBAAA,CAAoB,IAAA,UAAc,SAAuB;;;;;;;;;;;;;;;;;;;;iBA4BzD,uBAAA,CAAwB,OAAA,UAAiB,KAAA,UAAe,KAAA;;;;;;;;;;;;;;;;;;;;iBA4BxD,qBAAA,CACd,OAAA,UACA,OAAA,UACA,WAAA;;;;;;;;;;;;;;;;;;;iBA2Bc,YAAA,CACd,GAAA,UACA,SAAA;EACE,MAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;;;;;;;;iBA+BY,cAAA,CAAe,WAAmB;;;;;;;;;;;;;;;iBAqBlC,iBAAA,CAAkB,MAAgB;;;;;;;;;;;;;;;;;;iBA6BlC,WAAA,CAAY,MAAA,YAAkB,SAAuB;;;;;;;;;;;;;;;iBA0BrD,WAAA,CAAY,QAAgB;;;;;;;;;;;;;;;;iBAwD5B,cAAA,CAAe,KAAA,UAAe,QAAoB"}