@kumix/email 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,401 @@
+import React from "react";
+
+//#region src/types.d.ts
+/**
+ * Email service type definitions and interfaces
+ * Provides comprehensive TypeScript types for email configuration, sending options, and results
+ */
+/**
+ * Supported email service providers
+ * @public
+ */
+type EmailProvider = "resend" | "nodemailer";
+/**
+ * Base email configuration interface
+ * Common properties shared by all email providers
+ * @public
+ */
+interface BaseEmailConfig {
+  /** Email service provider */
+  provider: EmailProvider;
+  /** Default sender information */
+  from: {
+    /** Sender name */name: string; /** Sender email address */
+    email: string;
+  };
+  /** Reply-to email address */
+  replyTo?: string;
+}
+/**
+ * Resend email service configuration
+ * @public
+ */
+interface ResendConfig extends BaseEmailConfig {
+  provider: "resend";
+  /** Resend API key */
+  apiKey: string;
+}
+/**
+ * Nodemailer/SMTP email service configuration
+ * @public
+ */
+interface NodemailerConfig extends BaseEmailConfig {
+  provider: "nodemailer";
+  /** SMTP server configuration */
+  smtp: {
+    /** SMTP server hostname */host: string; /** SMTP server port */
+    port: number; /** Use secure connection (TLS) */
+    secure: boolean; /** Authentication credentials */
+    auth: {
+      /** SMTP username */user: string; /** SMTP password */
+      pass: string;
+    };
+  };
+}
+/**
+ * Union type for all email configurations
+ * @public
+ */
+type EmailConfig = ResendConfig | NodemailerConfig;
+/**
+ * Email attachment configuration
+ * @public
+ */
+interface EmailAttachment {
+  /** Attachment filename */
+  filename: string;
+  /** Attachment content as Uint8Array, Buffer, or string */
+  content: Uint8Array | string;
+  /** MIME type of the attachment */
+  contentType?: string;
+  /** Content-ID for inline images */
+  cid?: string;
+}
+/**
+ * Email sending options
+ * @public
+ */
+interface SendEmailOptions {
+  /** Recipient email address(es) */
+  to: string | string[];
+  /** CC recipient email address(es) */
+  cc?: string | string[];
+  /** BCC recipient email address(es) */
+  bcc?: string | string[];
+  /** Email subject line */
+  subject: string;
+  /** HTML content of the email */
+  html?: string;
+  /** Plain text content of the email */
+  text?: string;
+  /** Email attachments */
+  attachments?: EmailAttachment[];
+  /** Custom email headers */
+  headers?: Record<string, string>;
+  /** Email tags for tracking and analytics */
+  tags?: Record<string, string>;
+  /** Email priority (1=highest, 3=normal, 5=lowest) */
+  priority?: 1 | 2 | 3 | 4 | 5;
+  /** Schedule email delivery for later */
+  scheduledAt?: Date;
+}
+/**
+ * Email template data interface
+ * @public
+ */
+interface EmailTemplateData {
+  /** Template data properties */
+  [key: string]: unknown;
+}
+/**
+ * Email sending result
+ * @public
+ */
+interface EmailResult {
+  /** Whether the email was sent successfully */
+  success: boolean;
+  /** Unique message ID from the email provider */
+  messageId?: string;
+  /** Error message if sending failed */
+  error?: string;
+  /** Additional metadata from the provider */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Email validation result
+ * @public
+ */
+interface EmailValidationResult {
+  /** Whether the email address is valid */
+  valid: boolean;
+  /** Error message if validation failed */
+  error?: string;
+}
+/**
+ * Email service provider interface
+ * @public
+ */
+interface IEmailProvider {
+  /** Send an email */
+  send(options: SendEmailOptions): Promise<EmailResult>;
+  /** Validate provider configuration */
+  validateConfig?(): Promise<EmailValidationResult>;
+}
+/**
+ * Email template options
+ * @public
+ */
+interface EmailTemplateOptions {
+  /** Template name or ID */
+  template: string;
+  /** Template data/variables */
+  data: EmailTemplateData;
+  /** Recipient email address(es) */
+  to: string | string[];
+  /** CC recipient email address(es) */
+  cc?: string | string[];
+  /** BCC recipient email address(es) */
+  bcc?: string | string[];
+  /** Email subject (if not defined in template) */
+  subject?: string;
+  /** Email attachments */
+  attachments?: EmailAttachment[];
+  /** Custom email headers */
+  headers?: Record<string, string>;
+  /** Email tags for tracking and analytics */
+  tags?: Record<string, string>;
+}
+/**
+ * Bulk email sending options
+ * @public
+ */
+interface BulkEmailOptions {
+  /** Array of email sending options */
+  emails: SendEmailOptions[];
+  /** Batch size for sending (default: 100) */
+  batchSize?: number;
+  /** Delay between batches in milliseconds (default: 1000) */
+  batchDelay?: number;
+}
+/**
+ * Bulk email sending result
+ * @public
+ */
+interface BulkEmailResult {
+  /** Whether all emails were processed */
+  success: boolean;
+  /** Total number of emails processed */
+  total: number;
+  /** Number of successfully sent emails */
+  sent: number;
+  /** Number of failed emails */
+  failed: number;
+  /** Array of individual email results */
+  results: EmailResult[];
+  /** Array of errors for failed emails */
+  errors: Array<{
+    index: number;
+    error: string;
+  }>;
+}
+/**
+ * Email configuration validation result
+ * @public
+ */
+interface ConfigValidationResult {
+  /** Whether the configuration is valid */
+  valid: boolean;
+  /** Array of missing required fields */
+  missing: string[];
+  /** Array of validation errors */
+  errors: string[];
+}
+/**
+ * Email analytics data
+ * @public
+ */
+interface EmailAnalytics {
+  /** Number of emails sent */
+  sent: number;
+  /** Number of emails delivered */
+  delivered: number;
+  /** Number of emails opened */
+  opened: number;
+  /** Number of emails clicked */
+  clicked: number;
+  /** Number of emails bounced */
+  bounced: number;
+  /** Number of emails marked as spam */
+  spam: number;
+  /** Delivery rate percentage */
+  deliveryRate: number;
+  /** Open rate percentage */
+  openRate: number;
+  /** Click rate percentage */
+  clickRate: number;
+}
+/**
+ * Email webhook event types
+ * @public
+ */
+type EmailWebhookEvent = "sent" | "delivered" | "opened" | "clicked" | "bounced" | "spam" | "unsubscribed";
+/**
+ * Email webhook payload
+ * @public
+ */
+interface EmailWebhookPayload {
+  /** Event type */
+  event: EmailWebhookEvent;
+  /** Message ID */
+  messageId: string;
+  /** Recipient email */
+  email: string;
+  /** Timestamp of the event */
+  timestamp: Date;
+  /** Additional event data */
+  data?: Record<string, unknown>;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Cross-runtime environment record.
+ * Pass `process.env` on Node.js, `ctx.env` on Cloudflare Workers,
+ * `Deno.env.toObject()` on Deno, or a plain object in the browser.
+ */
+type EnvRecord = Record<string, string | undefined>;
+declare function loadResendConfig(env?: EnvRecord): ResendConfig | null;
+declare function loadNodemailerConfig(env?: EnvRecord): NodemailerConfig | null;
+declare function loadEmailConfig(env?: EnvRecord): EmailConfig | null;
+declare function hasEmailConfig(env?: EnvRecord): boolean;
+declare function getEmailEnvVars(env?: EnvRecord): Record<string, string | undefined>;
+declare function validateResendEnvVars(env?: EnvRecord): ConfigValidationResult;
+declare function validateNodemailerEnvVars(env?: EnvRecord): ConfigValidationResult;
+declare function validateEmailEnvVars(env?: EnvRecord): ConfigValidationResult;
+//#endregion
+//#region src/services.d.ts
+declare class EmailService {
+  private provider;
+  private config;
+  constructor(config: EmailConfig);
+  private createProvider;
+  sendEmail(options: SendEmailOptions): Promise<EmailResult>;
+  sendTemplate<T extends EmailTemplateData>(Template: React.ComponentType<T>, props: T, options: Omit<SendEmailOptions, "html" | "text">): Promise<EmailResult>;
+  getConfig(): EmailConfig;
+  updateConfig(config: EmailConfig): void;
+  validateConfig(): Promise<EmailValidationResult>;
+}
+//#endregion
+//#region src/factory.d.ts
+declare function createEmail(config?: EmailConfig, env?: EnvRecord): EmailService;
+declare function createResend(config?: Omit<ResendConfig, "provider"> & {
+  provider?: "resend";
+}, env?: EnvRecord): EmailService;
+declare function createNodemailer(config?: Omit<NodemailerConfig, "provider"> & {
+  provider?: "nodemailer";
+}, env?: EnvRecord): EmailService;
+declare function isEmailConfigured(env?: EnvRecord): boolean;
+declare function getConfiguredProvider(env?: EnvRecord): EmailProvider | null;
+//#endregion
+//#region src/providers/nodemailer.d.ts
+declare class NodemailerProvider implements IEmailProvider {
+  private config;
+  private _transporter;
+  constructor(config: NodemailerConfig);
+  private getTransporter;
+  validateConfig(): Promise<EmailValidationResult>;
+  send(options: SendEmailOptions): Promise<EmailResult>;
+}
+//#endregion
+//#region src/providers/resend.d.ts
+/**
+ * Resend email provider implementation
+ * @public
+ *
+ * @example
+ * ```typescript
+ * import { ResendProvider } from '@kumix/email';
+ *
+ * const provider = new ResendProvider({
+ *   provider: 'resend',
+ *   apiKey: 'your-resend-api-key',
+ *   from: {
+ *     name: 'Your App',
+ *     email: 'noreply@yourapp.com'
+ *   }
+ * });
+ *
+ * const result = await provider.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   html: '<h1>Hello World</h1>'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Email sent with ID:', result.messageId);
+ * } else {
+ *   console.error('Failed to send email:', result.error);
+ * }
+ * ```
+ */
+declare class ResendProvider implements IEmailProvider {
+  private resend;
+  private config;
+  /**
+   * Create a new Resend provider instance
+   * @param config Resend configuration including API key and sender info
+   * @throws Error if API key is missing
+   */
+  constructor(config: ResendConfig);
+  /**
+   * Validate Resend configuration
+   * @returns Promise resolving to validation result
+   * @public
+   *
+   * @example
+   * ```typescript
+   * const validation = await provider.validateConfig();
+   * if (!validation.valid) {
+   *   console.error('Configuration error:', validation.error);
+   * } else {
+   *   console.log('Resend configuration is valid');
+   * }
+   * ```
+   */
+  validateConfig(): Promise<EmailValidationResult>;
+  /**
+   * Send an email using Resend
+   * @param options Email sending options
+   * @returns Promise resolving to email sending result
+   * @public
+   *
+   * @example
+   * ```typescript
+   * const result = await provider.send({
+   *   to: ['user1@example.com', 'user2@example.com'],
+   *   cc: 'manager@example.com',
+   *   subject: 'Important Update',
+   *   html: '<h1>Hello</h1><p>This is an important update.</p>',
+   *   text: 'Hello\n\nThis is an important update.',
+   *   attachments: [{
+   *     filename: 'document.pdf',
+   *     content: pdfBuffer,
+   *     contentType: 'application/pdf'
+   *   }],
+   *   tags: {
+   *     category: 'notification',
+   *     priority: 'high'
+   *   }
+   * });
+   *
+   * if (result.success) {
+   *   console.log('Email sent with ID:', result.messageId);
+   * } else {
+   *   console.error('Failed to send email:', result.error);
+   * }
+   * ```
+   */
+  send(options: SendEmailOptions): Promise<EmailResult>;
+}
+//#endregion
+export { type BulkEmailOptions, type BulkEmailResult, type ConfigValidationResult, type EmailAnalytics, type EmailAttachment, type EmailConfig, type EmailProvider, type EmailResult, EmailService, type EmailTemplateData, type EmailTemplateOptions, type EmailValidationResult, type EmailWebhookEvent, type EmailWebhookPayload, type EnvRecord, type IEmailProvider, type NodemailerConfig, NodemailerProvider, type ResendConfig, ResendProvider, type SendEmailOptions, createEmail, createNodemailer, createResend, getConfiguredProvider, getEmailEnvVars, hasEmailConfig, isEmailConfigured, loadEmailConfig, loadNodemailerConfig, loadResendConfig, validateEmailEnvVars, validateNodemailerEnvVars, validateResendEnvVars };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/config.ts","../src/services.ts","../src/factory.ts","../src/providers/nodemailer.ts","../src/providers/resend.ts"],"mappings":";;;;;;AASA;;;;AAAyB;KAAb,aAAA;;;;;;UAOK,eAAA;EAMb;EAJF,QAAA,EAAU,aAAa;EASvB;EAPA,IAAA;IAOO,kBALL,IAAA,UAY0B;IAV1B,KAAA;EAAA;EAUkC;EAPpC,OAAA;AAAA;;AAUM;AAOR;;UAViB,YAAA,SAAqB,eAAe;EACnD,QAAA;EASwC;EAPxC,MAAA;AAAA;;;;;UAOe,gBAAA,SAAyB,eAAe;EACvD,QAAA;EAcQ;EAZR,IAAA;IAqBU,2BAnBR,IAAA,UAmBsB;IAjBtB,IAAA,UAiBqD;IAfrD,MAAA,WAqB4B;IAnB5B,IAAA;MAuBiB,oBArBf,IAAA,UAqBJ;MAnBI,IAAA;IAAA;EAAA;AAAA;AAuBD;AAOL;;;AAPK,KAdO,WAAA,GAAc,YAAA,GAAe,gBAAgB;;;;;UAMxC,eAAA;EAiBf;EAfA,QAAA;EAmBA;EAjBA,OAAA,EAAS,UAAU;EAqBnB;EAnBA,WAAA;EAuBA;EArBA,GAAA;AAAA;;;;;UAOe,gBAAA;EAsBD;EApBd,EAAA;EAoBkB;EAlBlB,EAAA;EAyBgC;EAvBhC,GAAA;EAyBY;EAvBZ,OAAA;EA8Be;EA5Bf,IAAA;;EAEA,IAAA;EA4BA;EA1BA,WAAA,GAAc,eAAA;EA8Bd;EA5BA,OAAA,GAAU,MAAA;EA8BC;EA5BX,IAAA,GAAO,MAAA;EA4BU;EA1BjB,QAAA;EAiCoC;EA/BpC,WAAA,GAAc,IAAA;AAAA;AAmCT;AAOP;;;AAPO,UA5BU,iBAAA;EAqC0B;EAAA,CAnCxC,GAAW;AAAA;;;;;UAOG,WAAA;EA4BV;EA1BL,OAAA;EA0ByC;EAxBzC,SAAA;EA0BmB;EAxBnB,KAAA;EAwBgD;EAtBhD,QAAA,GAAW,MAAM;AAAA;;;;;UAOF,qBAAA;EAwCR;EAtCP,KAAA;EAsCa;EApCb,KAAK;AAAA;;;;;UAOU,cAAA;EAyBf;EAvBA,IAAA,CAAK,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,WAAA;EAyBzC;EAvBA,cAAA,KAAmB,OAAA,CAAQ,qBAAA;AAAA;;;AAyBd;AAOf;UAzBiB,oBAAA;;EAEf,QAAA;EAyBA;EAvBA,IAAA,EAAM,iBAAA;EAyBN;EAvBA,EAAA;EAyBU;EAvBV,EAAA;EA8Be;EA5Bf,GAAA;;EAEA,OAAA;EA4BA;EA1BA,WAAA,GAAc,eAAA;EA8Bd;EA5BA,OAAA,GAAU,MAAA;EAgCV;EA9BA,IAAA,GAAO,MAAA;AAAA;;;;;UAOQ,gBAAA;EAgCA;EA9Bf,MAAA,EAAQ,gBAAgB;;EAExB,SAAA;EA8BA;EA5BA,UAAA;AAAA;;AAgCM;AAOR;;UAhCiB,eAAA;EAgCc;EA9B7B,OAAA;EAkCA;EAhCA,KAAA;EAoCA;EAlCA,IAAA;EAsCA;EApCA,MAAA;EAwCA;EAtCA,OAAA,EAAS,WAAA;EAwCA;EAtCT,MAAA,EAAQ,KAAK;IAAG,KAAA;IAAe,KAAA;EAAA;AAAA;AA6CJ;AAa7B;;;AAb6B,UAtCZ,sBAAA;EA2DJ;EAzDX,KAAA;EA2Da;EAzDb,OAAA;EAiDA;EA/CA,MAAA;AAAA;;;;;UAOe,cAAA;EAgDF;EA9Cb,IAAA;;EAEA,SAAA;;EAEA,MAAA;ECzOmB;ED2OnB,OAAA;EC3O4B;ED6O5B,OAAA;EChOc;EDkOd,IAAA;;EAEA,YAAA;ECpOqC;EDsOrC,QAAA;ECtOiD;EDwOjD,SAAA;AAAA;AC1NF;;;;AAAA,KDiOY,iBAAA;;;;ACjO2D;UD8OtD,mBAAA;ECvNc;EDyN7B,KAAA,EAAO,iBAAA;ECzNoD;ED2N3D,SAAA;EC3N8B;ED6N9B,KAAA;EC7N2D;ED+N3D,SAAA,EAAW,IAAA;ECzNG;ED2Nd,IAAA,GAAO,MAAA;AAAA;;;;;AAjRT;;;KCFY,SAAA,GAAY,MAAM;AAAA,iBAad,gBAAA,CAAiB,GAAA,GAAM,SAAA,GAAY,YAAY;AAAA,iBAc/C,oBAAA,CAAqB,GAAA,GAAM,SAAA,GAAY,gBAAgB;AAAA,iBAuBvD,eAAA,CAAgB,GAAA,GAAM,SAAA,GAAY,WAAW;AAAA,iBAM7C,cAAA,CAAe,GAAe,GAAT,SAAS;AAAA,iBAI9B,eAAA,CAAgB,GAAA,GAAM,SAAA,GAAY,MAAM;AAAA,iBAiBxC,qBAAA,CAAsB,GAAA,GAAM,SAAA,GAAY,sBAAsB;AAAA,iBAoB9D,yBAAA,CAA0B,GAAA,GAAM,SAAA,GAAY,sBAAsB;AAAA,iBAwBlE,oBAAA,CAAqB,GAAA,GAAM,SAAA,GAAY,sBAAsB;;;cCjHhE,YAAA;EAAA,QACH,QAAA;EAAA,QACA,MAAA;cAEI,MAAA,EAAQ,WAAA;EAAA,QAKZ,cAAA;EAWF,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,WAAA;EAI9C,YAAA,WAAuB,iBAAA,EAC3B,QAAA,EAAU,KAAA,CAAM,aAAA,CAAc,CAAA,GAC9B,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,IAAA,CAAK,gBAAA,qBACb,OAAA,CAAQ,WAAA;EAcX,SAAA,IAAa,WAAA;EAIb,YAAA,CAAa,MAAA,EAAQ,WAAA;EAKf,cAAA,IAAc,OAAA,CALY,qBAAA;AAAA;;;iBCvDlB,WAAA,CAAY,MAAA,GAAS,WAAA,EAAa,GAAA,GAAM,SAAA,GAAY,YAAA;AAAA,iBAapD,YAAA,CACd,MAAA,GAAS,IAAA,CAAK,YAAA;EAA8B,QAAA;AAAA,GAC5C,GAAA,GAAM,SAAA,GACL,YAAA;AAAA,iBAYa,gBAAA,CACd,MAAA,GAAS,IAAA,CAAK,gBAAA;EAAkC,QAAA;AAAA,GAChD,GAAA,GAAM,SAAA,GACL,YAAA;AAAA,iBAYa,iBAAA,CAAkB,GAAe,GAAT,SAAS;AAAA,iBAIjC,qBAAA,CAAsB,GAAA,GAAM,SAAA,GAAY,aAAa;;;cC3CxD,kBAAA,YAA8B,cAAA;EAAA,QACjC,MAAA;EAAA,QACA,YAAA;cAEI,MAAA,EAAQ,gBAAA;EAAA,QAON,cAAA;EA0BR,cAAA,IAAkB,OAAA,CAAQ,qBAAA;EA0B1B,IAAA,CAAK,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,WAAA;AAAA;;;;;AJhExB;AAOzB;;;;;;;;;;;AAWS;AAOT;;;;;;;;AAGQ;AAOR;;;;;;cKEa,cAAA,YAA0B,cAAA;EAAA,QAC7B,MAAA;EAAA,QACA,MAAA;ELKN;;;;;cKEU,MAAA,EAAQ,YAAA;ELaV;;;;AAA6C;AAMzD;;;;;;;;;;EKMQ,cAAA,IAAkB,OAAA,CAAQ,qBAAA;ELSjB;;;;;;;;;;;;;;;;;;;;;;;;;AAsBG;AAOpB;;;;AAEc;AAOd;EKoBQ,IAAA,CAAK,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,WAAA;AAAA"}