alepha 0.9.4 → 0.10.0

package/email.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/email');
+Object.keys(m).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return m[k]; }
+	});
+});

package/email.d.ts

@@ -0,0 +1,328 @@
+import * as _alepha_core1 from "alepha";
+import { Descriptor, KIND, Service, Static, TSchema } from "alepha";
+import * as _alepha_logger1 from "alepha/logger";
+import { Transporter } from "nodemailer";
+
+//#region src/providers/EmailProvider.d.ts
+/**
+ * Email provider interface.
+ *
+ * All methods are asynchronous and return promises.
+ */
+declare abstract class EmailProvider {
+  /**
+   * Send an email.
+   *
+   * @param to The recipient email address.
+   * @param subject The email subject.
+   * @param body The email body (HTML content).
+   *
+   * @return Promise that resolves when the email is sent.
+   */
+  abstract send(to: string, subject: string, body: string): Promise<void>;
+}
+//#endregion
+//#region src/providers/MemoryEmailProvider.d.ts
+interface EmailRecord {
+  to: string;
+  subject: string;
+  body: string;
+  sentAt: Date;
+}
+declare class MemoryEmailProvider implements EmailProvider {
+  protected readonly log: _alepha_logger1.Logger;
+  protected emails: EmailRecord[];
+  send(to: string, subject: string, body: string): Promise<void>;
+  /**
+   * Get all emails sent through this provider (for testing purposes).
+   */
+  getEmails(): EmailRecord[];
+  /**
+   * Clear all stored emails (for testing purposes).
+   */
+  clearEmails(): void;
+  /**
+   * Get the last email sent (for testing purposes).
+   */
+  getLastEmail(): EmailRecord | undefined;
+}
+//#endregion
+//#region src/services/TemplateService.d.ts
+/**
+ * Minimal template service with Handlebars-like syntax for email templating.
+ * Supports simple variable substitution with {{variableName}} syntax.
+ */
+declare class TemplateService {
+  /**
+   * Compile a template string with the provided values.
+   *
+   * @param template Template string with {{variableName}} placeholders
+   * @param values Object containing values to substitute
+   * @returns Compiled template string with values substituted
+   *
+   * @example
+   * ```ts
+   * const service = new TemplateService();
+   * const result = service.compile("Hello {{name}}!", { name: "John" });
+   * // Result: "Hello John!"
+   * ```
+   */
+  compile(template: string, values: Record<string, unknown>): string;
+  /**
+   * Validate that all required template variables are provided.
+   *
+   * @param template Template string
+   * @param values Values object
+   * @returns Array of missing variable names
+   */
+  validateTemplate(template: string, values: Record<string, unknown>): string[];
+  /**
+   * Extract all variable names from a template.
+   *
+   * @param template Template string
+   * @returns Array of variable names found in the template
+   */
+  extractVariables(template: string): string[];
+}
+//#endregion
+//#region src/descriptors/$email.d.ts
+/**
+ * Creates an email descriptor for sending type-safe templated emails.
+ *
+ * The $email descriptor provides a powerful templating system for creating and sending emails
+ * with full type safety and validation. It supports multiple email providers, template variable
+ * validation, and automatic HTML rendering.
+ *
+ * **Template Engine**
+ * - Simple {{variable}} syntax for dynamic content
+ * - Automatic template variable validation at runtime
+ * - Support for nested object properties in templates
+ * - HTML email support with rich formatting
+ *
+ * **Type Safety**
+ * - Full TypeScript support with schema validation using TypeBox
+ * - Compile-time type checking for template variables
+ * - Runtime validation of email data before sending
+ * - Automatic type inference from schema definitions
+ *
+ * **Provider Flexibility**
+ * - Memory provider for development and testing
+ * - Support for SMTP, SendGrid, AWS SES, and other providers
+ * - Custom provider implementation for specialized services
+ * - Automatic fallback and error handling
+ *
+ * **Template Management**
+ * - Reusable email templates across your application
+ * - Centralized template configuration and maintenance
+ * - Template variable documentation through schemas
+ * - Easy testing and preview capabilities
+ *
+ * **Development Experience**
+ * - Clear error messages for missing template variables
+ * - Comprehensive logging for debugging email delivery
+ * - Memory provider captures emails for testing
+ * - Template validation before sending
+ *
+ * @example Welcome email template
+ * ```typescript
+ * const welcomeEmail = $email({
+ *   subject: "Welcome to {{companyName}}, {{firstName}}!",
+ *   body: `
+ *     <h1>Welcome {{firstName}} {{lastName}}!</h1>
+ *     <p>Thank you for joining {{companyName}}.</p>
+ *     <p>Your account role is: <strong>{{role}}</strong></p>
+ *     <p>Get started by visiting your <a href="{{dashboardUrl}}">dashboard</a>.</p>
+ *   `,
+ *   schema: t.object({
+ *     firstName: t.string(),
+ *     lastName: t.string(),
+ *     companyName: t.string(),
+ *     role: t.enum(["admin", "user", "manager"]),
+ *     dashboardUrl: t.string()
+ *   })
+ * });
+ *
+ * // Send with full type safety
+ * await welcomeEmail.send("user@example.com", {
+ *   firstName: "John",
+ *   lastName: "Doe",
+ *   companyName: "Acme Corp",
+ *   role: "user",
+ *   dashboardUrl: "https://app.acme.com/dashboard"
+ * });
+ * ```
+ *
+ * @example Order confirmation email
+ * ```typescript
+ * const orderConfirmation = $email({
+ *   subject: "Order #{{orderNumber}} confirmed - {{totalAmount}}",
+ *   body: `
+ *     <h1>Order Confirmed!</h1>
+ *     <p>Hi {{customerName}},</p>
+ *     <p>Your order #{{orderNumber}} has been confirmed.</p>
+ *     <h2>Order Details:</h2>
+ *     <p><strong>Total: {{totalAmount}}</strong></p>
+ *     <p>Estimated delivery: {{deliveryDate}}</p>
+ *   `,
+ *   schema: t.object({
+ *     customerName: t.string(),
+ *     orderNumber: t.string(),
+ *     totalAmount: t.string(),
+ *     deliveryDate: t.string()
+ *   })
+ * });
+ * ```
+ *
+ * @example Development with memory provider
+ * ```typescript
+ * const testEmail = $email({
+ *   subject: "Test: {{subject}}",
+ *   body: "<p>{{message}}</p>",
+ *   provider: "memory", // Captures emails for testing
+ *   schema: t.object({
+ *     subject: t.string(),
+ *     message: t.string()
+ *   })
+ * });
+ *
+ * // In tests - emails are captured, not actually sent
+ * await testEmail.send("test@example.com", {
+ *   subject: "Unit Test",
+ *   message: "This email was captured for testing"
+ * });
+ * ```
+ */
+declare const $email: {
+  <T extends TSchema>(options: EmailDescriptorOptions<T>): EmailDescriptor<T>;
+  [KIND]: typeof EmailDescriptor;
+};
+interface EmailDescriptorOptions<T extends TSchema> {
+  /**
+   * Email subject template. Supports {{variableName}} syntax.
+   */
+  subject: string;
+  /**
+   * Email body template (HTML content). Supports {{variableName}} syntax.
+   */
+  body: string;
+  /**
+   * Schema defining the structure of template variables.
+   */
+  schema: T;
+  /**
+   * Optional name of the email template.
+   * @default Descriptor key
+   */
+  name?: string;
+  /**
+   * Optional description of the email template.
+   */
+  description?: string;
+  /**
+   * Email provider to use. If not provided, the default provider will be used.
+   */
+  provider?: Service<EmailProvider> | "memory";
+}
+declare class EmailDescriptor<T extends TSchema> extends Descriptor<EmailDescriptorOptions<T>> {
+  protected readonly log: _alepha_logger1.Logger;
+  protected readonly templateService: TemplateService;
+  readonly provider: EmailProvider | MemoryEmailProvider;
+  get name(): string;
+  /**
+   * Send an email using the template with the provided values.
+   *
+   * @param to Recipient email address
+   * @param values Template variable values
+   */
+  send(to: string, values: Static<T>): Promise<void>;
+  protected $provider(): EmailProvider | MemoryEmailProvider;
+}
+//#endregion
+//#region src/errors/EmailError.d.ts
+declare class EmailError extends Error {
+  constructor(message: string, cause?: Error);
+}
+//#endregion
+//#region src/providers/LocalEmailProvider.d.ts
+interface LocalEmailProviderOptions {
+  /**
+   * Directory to save email files.
+   * @default "email" (relative to project root)
+   */
+  directory?: string;
+}
+declare class LocalEmailProvider implements EmailProvider {
+  protected readonly log: _alepha_logger1.Logger;
+  protected readonly directory: string;
+  constructor(options?: LocalEmailProviderOptions);
+  send(to: string, subject: string, body: string): Promise<void>;
+  protected createEmailHtml(to: string, subject: string, body: string): string;
+  protected escapeHtml(text: string): string;
+}
+//#endregion
+//#region src/providers/NodemailerEmailProvider.d.ts
+interface NodemailerEmailProviderOptions {
+  /**
+   * Custom transporter configuration.
+   * If provided, will override environment variables.
+   */
+  transporter?: Transporter;
+  /**
+   * Custom from email address.
+   * If not provided, will use EMAIL_FROM from environment.
+   */
+  from?: string;
+  /**
+   * Additional nodemailer options.
+   */
+  options?: {
+    pool?: boolean;
+    maxConnections?: number;
+    maxMessages?: number;
+    rateDelta?: number;
+    rateLimit?: number;
+  };
+}
+declare class NodemailerEmailProvider implements EmailProvider {
+  protected readonly env: {
+    EMAIL_HOST: string;
+    EMAIL_PORT: number;
+    EMAIL_USER: string;
+    EMAIL_PASS: string;
+    EMAIL_FROM: string;
+    EMAIL_SECURE: boolean;
+  };
+  protected readonly log: _alepha_logger1.Logger;
+  protected transporter: Transporter;
+  protected fromAddress: string;
+  readonly options: NodemailerEmailProviderOptions;
+  constructor();
+  send(to: string, subject: string, body: string): Promise<void>;
+  protected createTransporter(): Transporter;
+  /**
+   * Verify the connection to the email server.
+   */
+  verify(): Promise<boolean>;
+  /**
+   * Close the transporter connection.
+   */
+  close(): void;
+  protected readonly onStart: _alepha_core1.HookDescriptor<"start">;
+  protected readonly onStop: _alepha_core1.HookDescriptor<"stop">;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Provides email sending capabilities for Alepha applications with multiple provider backends.
+ *
+ * The email module enables declarative email sending through the `$email` descriptor, allowing you to send
+ * emails through different providers: memory (for testing), local file system, or SMTP via Nodemailer.
+ * It supports HTML email content and automatic provider selection based on environment configuration.
+ *
+ * @see {@link EmailProvider}
+ * @module alepha.email
+ */
+declare const AlephaEmail: _alepha_core1.Service<_alepha_core1.Module>;
+//#endregion
+export { $email, AlephaEmail, EmailDescriptor, EmailDescriptorOptions, EmailError, EmailProvider, EmailRecord, LocalEmailProvider, LocalEmailProviderOptions, MemoryEmailProvider, NodemailerEmailProvider, NodemailerEmailProviderOptions, TemplateService };
+//# sourceMappingURL=index.d.ts.map

package/email.js

@@ -0,0 +1 @@
+export * from '@alepha/email'