sovrium 0.0.2

package/src/infrastructure/email/index.ts

@@ -0,0 +1,107 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Email Infrastructure Module
+ *
+ * Provides email functionality using Nodemailer with Better Auth integration.
+ *
+ * ## Configuration
+ *
+ * Set the following environment variables for production SMTP:
+ *
+ * ```bash
+ * SMTP_HOST=smtp.example.com      # SMTP server hostname
+ * SMTP_PORT=587                   # SMTP port (587 for TLS, 465 for SSL)
+ * SMTP_USER=your-username         # SMTP authentication username
+ * SMTP_PASS=your-password         # SMTP authentication password
+ * SMTP_SECURE=false               # Use SSL (optional, auto-detected from port)
+ * SMTP_FROM=noreply@example.com   # Default "from" email address
+ * SMTP_FROM_NAME=Your App         # Default "from" display name
+ * ```
+ *
+ * If SMTP_HOST is not set, emails are sent via Ethereal (test SMTP service).
+ *
+ * ## Usage
+ *
+ * ### Direct Usage (async/await)
+ * ```typescript
+ * import { sendEmail } from '@/infrastructure/email'
+ *
+ * await sendEmail({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome',
+ *   html: '<h1>Welcome!</h1>',
+ *   text: 'Welcome!',
+ * })
+ * ```
+ *
+ * ### Effect Service Usage
+ * ```typescript
+ * import { Email, EmailLive } from '@/infrastructure/email'
+ * import { Effect } from 'effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const email = yield* Email
+ *   yield* email.sendWithDefaultFrom({
+ *     to: 'user@example.com',
+ *     subject: 'Welcome',
+ *     html: '<h1>Welcome!</h1>',
+ *   })
+ * }).pipe(Effect.provide(EmailLive))
+ * ```
+ *
+ * ### Using Templates
+ * ```typescript
+ * import { sendEmail, passwordResetEmail } from '@/infrastructure/email'
+ *
+ * const template = passwordResetEmail({
+ *   userName: 'John',
+ *   resetUrl: 'https://example.com/reset?token=...',
+ * })
+ *
+ * await sendEmail({
+ *   to: 'user@example.com',
+ *   ...template,
+ * })
+ * ```
+ *
+ * @module
+ */
+
+// Nodemailer configuration and transporter
+export {
+  transporter,
+  getDefaultFrom,
+  getEmailConfig,
+  createTransporter,
+  verifyConnection,
+  type EmailConfig,
+  type SendMailOptions,
+} from './nodemailer'
+
+// Effect service layer
+export {
+  Email,
+  EmailLive,
+  EmailError,
+  EmailConnectionError,
+  sendEmail,
+  sendEmailWithOptions,
+  type EmailService,
+} from './email-service'
+
+// Email configuration with Effect logging
+export { getEmailConfigFromEffect } from './email-config'
+
+// Email templates
+export {
+  passwordResetEmail,
+  emailVerificationEmail,
+  type PasswordResetEmailData,
+  type EmailVerificationData,
+} from './templates'

package/src/infrastructure/email/nodemailer.ts

@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import nodemailer from 'nodemailer'
+import { getEmailConfigFromEffect } from './email-config'
+import type Mail from 'nodemailer/lib/mailer'
+import type SMTPTransport from 'nodemailer/lib/smtp-transport'
+
+/**
+ * Email configuration from environment variables
+ *
+ * Required environment variables:
+ * - SMTP_HOST: SMTP server hostname (e.g., smtp.gmail.com)
+ * - SMTP_PORT: SMTP server port (e.g., 587 for TLS, 465 for SSL)
+ * - SMTP_USER: SMTP authentication username
+ * - SMTP_PASS: SMTP authentication password
+ *
+ * Optional environment variables:
+ * - SMTP_SECURE: Use SSL (true for port 465, false for other ports)
+ * - SMTP_FROM: Default "from" email address
+ * - SMTP_FROM_NAME: Default "from" display name
+ */
+export interface EmailConfig {
+  readonly host: string
+  readonly port: number
+  readonly secure: boolean
+  readonly auth: {
+    readonly user: string
+    readonly pass: string
+  }
+  readonly from: {
+    readonly email: string
+    readonly name: string
+  }
+}
+
+/**
+ * Get email configuration from environment variables
+ *
+ * Uses Effect.Config under the hood for type-safe configuration with:
+ * - Automatic validation
+ * - Secret handling (passwords redacted in logs)
+ * - Composable defaults
+ *
+ * In production, SMTP_HOST is required. In development, falls back to
+ * localhost:1025 (Mailpit) for local email testing.
+ *
+ * Environment Variables:
+ * - SMTP_HOST: SMTP server hostname (required in production)
+ * - SMTP_PORT: SMTP server port (default: 587)
+ * - SMTP_SECURE: Use SSL/TLS (default: false for port 587, true for port 465)
+ * - SMTP_USER: SMTP authentication username
+ * - SMTP_PASS: SMTP authentication password
+ * - SMTP_FROM: Default "from" email address (default: noreply@sovrium.com)
+ * - SMTP_FROM_NAME: Default "from" display name (default: 'Sovrium')
+ *
+ * @see https://mailpit.axllent.org/ for local development email testing
+ * @see ./email-config.ts for Effect-based configuration (preferred for new code)
+ */
+export function getEmailConfig(): EmailConfig {
+  return getEmailConfigFromEffect()
+}
+
+/**
+ * Create a nodemailer transporter from configuration
+ */
+/* eslint-disable functional/prefer-immutable-types -- nodemailer transporter is inherently mutable */
+export function createTransporter(
+  config: Readonly<EmailConfig>
+): nodemailer.Transporter<SMTPTransport.SentMessageInfo> {
+  return nodemailer.createTransport({
+    host: config.host,
+    port: config.port,
+    secure: config.secure,
+    auth: config.auth,
+  })
+}
+/* eslint-enable functional/prefer-immutable-types */
+
+/**
+ * Pre-configured transporter using environment variables
+ *
+ * @example
+ * ```typescript
+ * import { transporter, getDefaultFrom } from '@/infrastructure/email/nodemailer'
+ *
+ * await transporter.sendMail({
+ *   from: getDefaultFrom(),
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   text: 'Hello World',
+ * })
+ * ```
+ */
+const config = getEmailConfig()
+export const transporter = createTransporter(config)
+
+/**
+ * Get the default "from" address formatted for email headers
+ */
+export function getDefaultFrom(): string {
+  const { email, name } = config.from
+  return `"${name}" <${email}>`
+}
+
+/**
+ * Send email options type (re-exported for convenience)
+ */
+export type SendMailOptions = Mail.Options
+
+/**
+ * Verify SMTP connection
+ *
+ * Useful for health checks and startup validation.
+ *
+ * @returns Promise that resolves if connection is valid
+ * @throws Error if connection fails
+ */
+export async function verifyConnection(): Promise<boolean> {
+  return transporter.verify()
+}

package/src/infrastructure/email/templates.ts

@@ -0,0 +1,244 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Email template data types for Better Auth integration
+ */
+export interface PasswordResetEmailData {
+  readonly userName?: string
+  readonly resetUrl: string
+  readonly expiresIn?: string
+}
+
+export interface EmailVerificationData {
+  readonly userName?: string
+  readonly verifyUrl: string
+  readonly expiresIn?: string
+}
+
+/**
+ * Email CSS styles
+ */
+const EMAIL_STYLES = `
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  line-height: 1.6;
+  color: #333;
+  max-width: 600px;
+  margin: 0 auto;
+  padding: 20px;
+  background-color: #f5f5f5;
+}
+.container {
+  background-color: #ffffff;
+  border-radius: 8px;
+  padding: 40px;
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+.header {
+  text-align: center;
+  margin-bottom: 30px;
+}
+.logo {
+  font-size: 28px;
+  font-weight: bold;
+  color: #1a1a1a;
+}
+.content {
+  margin-bottom: 30px;
+}
+.button {
+  display: inline-block;
+  background-color: #0066cc;
+  color: #ffffff !important;
+  text-decoration: none;
+  padding: 14px 28px;
+  border-radius: 6px;
+  font-weight: 600;
+  margin: 20px 0;
+}
+.button:hover {
+  background-color: #0052a3;
+}
+.footer {
+  text-align: center;
+  margin-top: 30px;
+  padding-top: 20px;
+  border-top: 1px solid #eee;
+  color: #666;
+  font-size: 12px;
+}
+.link-fallback {
+  word-break: break-all;
+  color: #666;
+  font-size: 12px;
+  margin-top: 15px;
+}
+.warning {
+  background-color: #fff3cd;
+  border: 1px solid #ffc107;
+  border-radius: 4px;
+  padding: 12px;
+  margin-top: 20px;
+  font-size: 13px;
+  color: #856404;
+}
+`
+
+/**
+ * Base email layout wrapper
+ *
+ * Provides consistent styling for all email templates.
+ */
+function emailLayout(content: string): string {
+  const year = new Date().getFullYear()
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Sovrium</title>
+  <style>${EMAIL_STYLES}</style>
+</head>
+<body>
+  <div class="container">
+    <div class="header"><div class="logo">Sovrium</div></div>
+    ${content}
+    <div class="footer">
+      <p>&copy; ${year} ESSENTIAL SERVICES. All rights reserved.</p>
+      <p>This email was sent by Sovrium. If you didn't request this, please ignore this email.</p>
+    </div>
+  </div>
+</body>
+</html>`
+}
+
+/**
+ * Password reset email template
+ *
+ * Used by Better Auth's sendResetPassword callback.
+ *
+ * @example
+ * ```typescript
+ * const { subject, html, text } = passwordResetEmail({
+ *   userName: 'John',
+ *   resetUrl: 'https://app.sovrium.com/reset-password?token=...',
+ *   expiresIn: '1 hour',
+ * })
+ * ```
+ */
+export function passwordResetEmail(data: PasswordResetEmailData): {
+  readonly subject: string
+  readonly html: string
+  readonly text: string
+} {
+  const greeting = data.userName ? `Hi ${data.userName},` : 'Hi,'
+  const expiry = data.expiresIn ?? '1 hour'
+
+  const content = `
+    <div class="content">
+      <p>${greeting}</p>
+      <p>We received a request to reset your password for your Sovrium account.</p>
+      <p>Click the button below to reset your password:</p>
+      <p style="text-align: center;">
+        <a href="${data.resetUrl}" class="button">Reset Password</a>
+      </p>
+      <p class="link-fallback">
+        If the button doesn't work, copy and paste this link into your browser:<br>
+        ${data.resetUrl}
+      </p>
+      <div class="warning">
+        This link will expire in ${expiry}. If you didn't request a password reset, you can safely ignore this email.
+      </div>
+    </div>
+  `
+
+  const text = `
+${greeting}
+
+We received a request to reset your password for your Sovrium account.
+
+Reset your password by visiting this link:
+${data.resetUrl}
+
+This link will expire in ${expiry}.
+
+If you didn't request a password reset, you can safely ignore this email.
+
+---
+© ${new Date().getFullYear()} ESSENTIAL SERVICES. All rights reserved.
+`.trim()
+
+  return {
+    subject: 'Reset your Sovrium password',
+    html: emailLayout(content),
+    text,
+  }
+}
+
+/**
+ * Email verification template
+ *
+ * Used by Better Auth's sendVerificationEmail callback.
+ *
+ * @example
+ * ```typescript
+ * const { subject, html, text } = emailVerificationEmail({
+ *   userName: 'John',
+ *   verifyUrl: 'https://app.sovrium.com/verify-email?token=...',
+ *   expiresIn: '24 hours',
+ * })
+ * ```
+ */
+export function emailVerificationEmail(data: EmailVerificationData): {
+  readonly subject: string
+  readonly html: string
+  readonly text: string
+} {
+  const greeting = data.userName ? `Hi ${data.userName},` : 'Hi,'
+  const expiry = data.expiresIn ?? '24 hours'
+
+  const content = `
+    <div class="content">
+      <p>${greeting}</p>
+      <p>Welcome to Sovrium! Please verify your email address to complete your registration.</p>
+      <p>Click the button below to verify your email:</p>
+      <p style="text-align: center;">
+        <a href="${data.verifyUrl}" class="button">Verify Email</a>
+      </p>
+      <p class="link-fallback">
+        If the button doesn't work, copy and paste this link into your browser:<br>
+        ${data.verifyUrl}
+      </p>
+      <div class="warning">
+        This link will expire in ${expiry}. If you didn't create a Sovrium account, you can safely ignore this email.
+      </div>
+    </div>
+  `
+
+  const text = `
+${greeting}
+
+Welcome to Sovrium! Please verify your email address to complete your registration.
+
+Verify your email by visiting this link:
+${data.verifyUrl}
+
+This link will expire in ${expiry}.
+
+If you didn't create a Sovrium account, you can safely ignore this email.
+
+---
+© ${new Date().getFullYear()} ESSENTIAL SERVICES. All rights reserved.
+`.trim()
+
+  return {
+    subject: 'Verify your Sovrium email address',
+    html: emailLayout(content),
+    text,
+  }
+}

package/src/infrastructure/errors/auth-config-required-error.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Data } from 'effect'
+
+/**
+ * Error when user fields are used without auth configuration
+ *
+ * User fields (user, created-by, updated-by) require Better Auth's users table.
+ * This error is thrown when tables with these field types are defined but
+ * no auth configuration is present in the app schema.
+ */
+export class AuthConfigRequiredForUserFields extends Data.TaggedError(
+  'AuthConfigRequiredForUserFields'
+)<{
+  readonly message: string
+}> {}

package/src/infrastructure/errors/auth-error.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { createTaggedError } from '@/domain/errors/create-tagged-error'
+
+/**
+ * Auth Error
+ *
+ * Tagged error for authentication failures.
+ */
+export const AuthError = createTaggedError('AuthError')
+export type AuthError = InstanceType<typeof AuthError>

package/src/infrastructure/errors/css-compilation-error.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { createTaggedError } from '@/domain/errors/create-tagged-error'
+
+/**
+ * Error class for CSS compilation failures
+ */
+export const CSSCompilationError = createTaggedError('CSSCompilationError')
+export type CSSCompilationError = InstanceType<typeof CSSCompilationError>

package/src/infrastructure/errors/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Infrastructure Error Classes Module
+ *
+ * Centralized error definitions for infrastructure layer failures.
+ * All errors use tagged union pattern (_tag property) for type-safe error handling.
+ *
+ * @example
+ * ```typescript
+ * import { ServerCreationError } from '@/infrastructure/errors'
+ *
+ * throw new ServerCreationError(error)
+ * ```
+ */
+
+export { AuthConfigRequiredForUserFields } from './auth-config-required-error'
+export { AuthError } from './auth-error'
+export { CSSCompilationError } from './css-compilation-error'
+export { SchemaInitializationError } from './schema-initialization-error'
+export { ServerCreationError } from './server-creation-error'

package/src/infrastructure/errors/schema-initialization-error.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Data } from 'effect'
+
+/**
+ * Error during schema initialization
+ *
+ * This error is thrown when database schema initialization fails,
+ * indicating that table creation or migration failed.
+ */
+export class SchemaInitializationError extends Data.TaggedError('SchemaInitializationError')<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}

package/src/infrastructure/errors/server-creation-error.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { createTaggedError } from '@/domain/errors/create-tagged-error'
+
+/**
+ * Error class for server creation failures
+ */
+export const ServerCreationError = createTaggedError('ServerCreationError')
+export type ServerCreationError = InstanceType<typeof ServerCreationError>