@strav/signal 0.1.0

package/src/mail/mail_manager.ts

@@ -0,0 +1,111 @@
+import { inject } from '@stravigor/kernel/core/inject'
+import { ConfigurationError } from '@stravigor/kernel/exceptions/errors'
+import Configuration from '@stravigor/kernel/config/configuration'
+import { SmtpTransport } from './transports/smtp_transport.ts'
+import { ResendTransport } from './transports/resend_transport.ts'
+import { SendGridTransport } from './transports/sendgrid_transport.ts'
+import { MailgunTransport } from './transports/mailgun_transport.ts'
+import { AlibabaTransport } from './transports/alibaba_transport.ts'
+import { LogTransport } from './transports/log_transport.ts'
+import type { MailTransport, MailConfig } from './types.ts'
+
+/**
+ * Central mail configuration hub.
+ *
+ * Resolved once via the DI container — reads the mail config
+ * and initializes the appropriate transport driver.
+ *
+ * @example
+ * app.singleton(MailManager)
+ * app.resolve(MailManager)
+ *
+ * // Plug in a custom transport
+ * MailManager.useTransport(new MyCustomTransport())
+ */
+@inject
+export default class MailManager {
+  private static _transport: MailTransport
+  private static _config: MailConfig
+
+  constructor(config: Configuration) {
+    const driverName = config.get('mail.default', 'log') as string
+
+    MailManager._config = {
+      default: driverName,
+      from: config.get('mail.from', 'noreply@localhost') as string,
+      templatePrefix: config.get('mail.templatePrefix', 'emails') as string,
+      inlineCss: config.get('mail.inlineCss', true) as boolean,
+      tailwind: config.get('mail.tailwind', false) as boolean,
+      smtp: {
+        host: '127.0.0.1',
+        port: 587,
+        secure: false,
+        ...(config.get('mail.smtp', {}) as object),
+      },
+      resend: {
+        apiKey: '',
+        ...(config.get('mail.resend', {}) as object),
+      },
+      sendgrid: {
+        apiKey: '',
+        ...(config.get('mail.sendgrid', {}) as object),
+      },
+      mailgun: {
+        apiKey: '',
+        domain: '',
+        ...(config.get('mail.mailgun', {}) as object),
+      },
+      alibaba: {
+        accessKeyId: '',
+        accessKeySecret: '',
+        accountName: '',
+        ...(config.get('mail.alibaba', {}) as object),
+      },
+      log: {
+        output: 'console',
+        ...(config.get('mail.log', {}) as object),
+      },
+    }
+
+    MailManager._transport = MailManager.createTransport(driverName)
+  }
+
+  private static createTransport(driver: string): MailTransport {
+    switch (driver) {
+      case 'smtp':
+        return new SmtpTransport(MailManager._config.smtp)
+      case 'resend':
+        return new ResendTransport(MailManager._config.resend)
+      case 'sendgrid':
+        return new SendGridTransport(MailManager._config.sendgrid)
+      case 'mailgun':
+        return new MailgunTransport(MailManager._config.mailgun)
+      case 'alibaba':
+        return new AlibabaTransport(MailManager._config.alibaba)
+      case 'log':
+        return new LogTransport(MailManager._config.log)
+      default:
+        throw new ConfigurationError(
+          `Unknown mail transport: ${driver}. Use MailManager.useTransport() for custom transports.`
+        )
+    }
+  }
+
+  static get transport(): MailTransport {
+    if (!MailManager._transport) {
+      throw new ConfigurationError(
+        'MailManager not configured. Resolve it through the container first.'
+      )
+    }
+    return MailManager._transport
+  }
+
+  static get config(): MailConfig {
+    return MailManager._config
+  }
+
+  /** Swap the transport at runtime (e.g., for testing or a custom provider). */
+  static useTransport(transport: MailTransport): void {
+    MailManager._transport = transport
+  }
+}

package/src/mail/transports/alibaba_transport.ts

@@ -0,0 +1,88 @@
+import crypto from 'node:crypto'
+import { ExternalServiceError } from '@stravigor/kernel/exceptions/errors'
+import type { MailTransport, MailMessage, MailResult, AlibabaConfig } from '../types.ts'
+
+/**
+ * Alibaba Cloud DirectMail (SingleSendMail) transport.
+ * Uses fetch with HMAC-SHA1 signature — no SDK dependency required.
+ *
+ * Note: SingleSendMail does not support CC, BCC, or attachments.
+ * Use the SMTP interface for those features.
+ *
+ * @see https://www.alibabacloud.com/help/en/directmail/latest/SingleSendMail
+ */
+export class AlibabaTransport implements MailTransport {
+  private accessKeyId: string
+  private accessKeySecret: string
+  private accountName: string
+  private region: string
+
+  constructor(config: AlibabaConfig) {
+    this.accessKeyId = config.accessKeyId
+    this.accessKeySecret = config.accessKeySecret
+    this.accountName = config.accountName
+    this.region = config.region ?? 'cn-hangzhou'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const toAddress = Array.isArray(message.to) ? message.to.join(',') : message.to
+
+    const params: Record<string, string> = {
+      Action: 'SingleSendMail',
+      AccountName: this.accountName,
+      AddressType: '1',
+      ReplyToAddress: message.replyTo ? 'true' : 'false',
+      ToAddress: toAddress,
+      Subject: message.subject,
+      Format: 'JSON',
+      Version: '2015-11-23',
+      AccessKeyId: this.accessKeyId,
+      SignatureMethod: 'HMAC-SHA1',
+      SignatureVersion: '1.0',
+      SignatureNonce: crypto.randomUUID(),
+      Timestamp: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    }
+
+    if (message.html) params.HtmlBody = message.html
+    if (message.text) params.TextBody = message.text
+    if (message.from) params.FromAlias = message.from
+
+    const signature = this.sign(params)
+    params.Signature = signature
+
+    const body = new URLSearchParams(params).toString()
+    const url = `https://dm.${this.region}.aliyuncs.com`
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+    })
+
+    if (!response.ok) {
+      const error = await response.text()
+      throw new ExternalServiceError('Alibaba DirectMail', response.status, error)
+    }
+
+    const data = (await response.json()) as { EnvId?: string; RequestId?: string }
+    const toArray = Array.isArray(message.to) ? message.to : [message.to]
+    return { messageId: data.EnvId ?? data.RequestId, accepted: toArray }
+  }
+
+  private percentEncode(str: string): string {
+    return encodeURIComponent(str).replace(/\+/g, '%20').replace(/\*/g, '%2A').replace(/~/g, '%7E')
+  }
+
+  private sign(params: Record<string, string>): string {
+    const sortedKeys = Object.keys(params).sort()
+    const canonicalized = sortedKeys
+      .map(k => `${this.percentEncode(k)}=${this.percentEncode(params[k]!)}`)
+      .join('&')
+
+    const stringToSign = `POST&${this.percentEncode('/')}&${this.percentEncode(canonicalized)}`
+
+    const hmac = crypto.createHmac('sha1', `${this.accessKeySecret}&`)
+    hmac.update(stringToSign)
+    return hmac.digest('base64')
+  }
+}

package/src/mail/transports/log_transport.ts

@@ -0,0 +1,69 @@
+import type { MailTransport, MailMessage, MailResult, LogConfig } from '../types.ts'
+
+/**
+ * Development/testing transport — logs email details to console or a file.
+ * No external dependencies required.
+ */
+export class LogTransport implements MailTransport {
+  private output: 'console' | string
+
+  constructor(config: LogConfig) {
+    this.output = config.output ?? 'console'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const timestamp = new Date().toISOString()
+    const separator = '─'.repeat(60)
+    const toList = Array.isArray(message.to) ? message.to.join(', ') : message.to
+
+    const lines = [
+      separator,
+      `[Mail] ${timestamp}`,
+      `From:     ${message.from}`,
+      `To:       ${toList}`,
+    ]
+
+    if (message.cc) {
+      const cc = Array.isArray(message.cc) ? message.cc.join(', ') : message.cc
+      lines.push(`CC:       ${cc}`)
+    }
+    if (message.bcc) {
+      const bcc = Array.isArray(message.bcc) ? message.bcc.join(', ') : message.bcc
+      lines.push(`BCC:      ${bcc}`)
+    }
+    if (message.replyTo) lines.push(`Reply-To: ${message.replyTo}`)
+
+    lines.push(`Subject:  ${message.subject}`)
+
+    if (message.text) {
+      lines.push('', '--- Text ---', message.text)
+    }
+    if (message.html) {
+      lines.push('', '--- HTML ---', message.html)
+    }
+    if (message.attachments?.length) {
+      lines.push('', `--- Attachments (${message.attachments.length}) ---`)
+      for (const a of message.attachments) {
+        lines.push(`  ${a.filename} (${a.contentType ?? 'unknown'})`)
+      }
+    }
+
+    lines.push(separator, '')
+
+    const output = lines.join('\n')
+
+    if (this.output === 'console') {
+      console.log(output)
+    } else {
+      const file = Bun.file(this.output)
+      const existing = (await file.exists()) ? await file.text() : ''
+      await Bun.write(this.output, existing + output + '\n')
+    }
+
+    const messageId = `log-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    return {
+      messageId,
+      accepted: Array.isArray(message.to) ? message.to : [message.to],
+    }
+  }
+}

package/src/mail/transports/mailgun_transport.ts

@@ -0,0 +1,74 @@
+import { ExternalServiceError } from '@stravigor/kernel/exceptions/errors'
+import type { MailTransport, MailMessage, MailResult, MailgunConfig } from '../types.ts'
+
+/**
+ * Mailgun HTTP API transport.
+ * Uses fetch with FormData — no SDK dependency required.
+ *
+ * @see https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Messages/
+ */
+export class MailgunTransport implements MailTransport {
+  private apiKey: string
+  private domain: string
+  private baseUrl: string
+
+  constructor(config: MailgunConfig) {
+    this.apiKey = config.apiKey
+    this.domain = config.domain
+    this.baseUrl = config.baseUrl ?? 'https://api.mailgun.net'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const form = new FormData()
+
+    form.append('from', message.from)
+    form.append('subject', message.subject)
+
+    const toArray = Array.isArray(message.to) ? message.to : [message.to]
+    form.append('to', toArray.join(', '))
+
+    if (message.cc) {
+      const ccArray = Array.isArray(message.cc) ? message.cc : [message.cc]
+      form.append('cc', ccArray.join(', '))
+    }
+    if (message.bcc) {
+      const bccArray = Array.isArray(message.bcc) ? message.bcc : [message.bcc]
+      form.append('bcc', bccArray.join(', '))
+    }
+    if (message.replyTo) form.append('h:Reply-To', message.replyTo)
+    if (message.html) form.append('html', message.html)
+    if (message.text) form.append('text', message.text)
+
+    if (message.attachments?.length) {
+      for (const a of message.attachments) {
+        const content =
+          typeof a.content === 'string'
+            ? new Blob([a.content], { type: a.contentType ?? 'application/octet-stream' })
+            : new Blob([a.content], { type: a.contentType ?? 'application/octet-stream' })
+
+        if (a.cid) {
+          form.append('inline', content, a.filename)
+        } else {
+          form.append('attachment', content, a.filename)
+        }
+      }
+    }
+
+    const credentials = btoa(`api:${this.apiKey}`)
+    const response = await fetch(`${this.baseUrl}/v3/${this.domain}/messages`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Basic ${credentials}`,
+      },
+      body: form,
+    })
+
+    if (!response.ok) {
+      const error = await response.text()
+      throw new ExternalServiceError('Mailgun', response.status, error)
+    }
+
+    const data = (await response.json()) as { id: string }
+    return { messageId: data.id, accepted: toArray }
+  }
+}

package/src/mail/transports/resend_transport.ts

@@ -0,0 +1,58 @@
+import { ExternalServiceError } from '@stravigor/kernel/exceptions/errors'
+import type { MailTransport, MailMessage, MailResult, ResendConfig } from '../types.ts'
+
+/**
+ * Resend HTTP API transport.
+ * Uses fetch — no SDK dependency required.
+ *
+ * @see https://resend.com/docs/api-reference/emails/send-email
+ */
+export class ResendTransport implements MailTransport {
+  private apiKey: string
+  private baseUrl: string
+
+  constructor(config: ResendConfig) {
+    this.apiKey = config.apiKey
+    this.baseUrl = config.baseUrl ?? 'https://api.resend.com'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const body: Record<string, unknown> = {
+      from: message.from,
+      to: Array.isArray(message.to) ? message.to : [message.to],
+      subject: message.subject,
+    }
+
+    if (message.cc) body.cc = Array.isArray(message.cc) ? message.cc : [message.cc]
+    if (message.bcc) body.bcc = Array.isArray(message.bcc) ? message.bcc : [message.bcc]
+    if (message.replyTo) body.reply_to = message.replyTo
+    if (message.html) body.html = message.html
+    if (message.text) body.text = message.text
+
+    if (message.attachments?.length) {
+      body.attachments = message.attachments.map(a => ({
+        filename: a.filename,
+        content:
+          typeof a.content === 'string' ? a.content : Buffer.from(a.content).toString('base64'),
+        content_type: a.contentType,
+      }))
+    }
+
+    const response = await fetch(`${this.baseUrl}/emails`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const error = await response.text()
+      throw new ExternalServiceError('Resend', response.status, error)
+    }
+
+    const data = (await response.json()) as { id: string }
+    return { messageId: data.id }
+  }
+}

package/src/mail/transports/sendgrid_transport.ts

@@ -0,0 +1,80 @@
+import { ExternalServiceError } from '@stravigor/kernel/exceptions/errors'
+import type { MailTransport, MailMessage, MailResult, SendGridConfig } from '../types.ts'
+
+/**
+ * SendGrid v3 Mail Send API transport.
+ * Uses fetch — no SDK dependency required.
+ *
+ * @see https://docs.sendgrid.com/api-reference/mail-send/mail-send
+ */
+export class SendGridTransport implements MailTransport {
+  private apiKey: string
+  private baseUrl: string
+
+  constructor(config: SendGridConfig) {
+    this.apiKey = config.apiKey
+    this.baseUrl = config.baseUrl ?? 'https://api.sendgrid.com/v3'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const toArray = Array.isArray(message.to) ? message.to : [message.to]
+
+    const personalizations: Record<string, unknown>[] = [
+      {
+        to: toArray.map(email => ({ email })),
+      },
+    ]
+
+    if (message.cc) {
+      const ccArray = Array.isArray(message.cc) ? message.cc : [message.cc]
+      personalizations[0]!.cc = ccArray.map(email => ({ email }))
+    }
+    if (message.bcc) {
+      const bccArray = Array.isArray(message.bcc) ? message.bcc : [message.bcc]
+      personalizations[0]!.bcc = bccArray.map(email => ({ email }))
+    }
+
+    const content: { type: string; value: string }[] = []
+    if (message.text) content.push({ type: 'text/plain', value: message.text })
+    if (message.html) content.push({ type: 'text/html', value: message.html })
+
+    const body: Record<string, unknown> = {
+      personalizations,
+      from: { email: message.from },
+      subject: message.subject,
+      content,
+    }
+
+    if (message.replyTo) body.reply_to = { email: message.replyTo }
+
+    if (message.attachments?.length) {
+      body.attachments = message.attachments.map(a => ({
+        filename: a.filename,
+        content:
+          typeof a.content === 'string'
+            ? Buffer.from(a.content).toString('base64')
+            : Buffer.from(a.content).toString('base64'),
+        type: a.contentType,
+        disposition: a.cid ? 'inline' : 'attachment',
+        content_id: a.cid,
+      }))
+    }
+
+    const response = await fetch(`${this.baseUrl}/mail/send`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const error = await response.text()
+      throw new ExternalServiceError('SendGrid', response.status, error)
+    }
+
+    const messageId = response.headers.get('X-Message-Id') ?? undefined
+    return { messageId, accepted: toArray }
+  }
+}

package/src/mail/transports/smtp_transport.ts

@@ -0,0 +1,48 @@
+import nodemailer from 'nodemailer'
+import type { MailTransport, MailMessage, MailResult, SmtpConfig } from '../types.ts'
+
+/**
+ * SMTP transport via nodemailer.
+ * Supports all standard SMTP features including TLS, auth, and attachments.
+ */
+export class SmtpTransport implements MailTransport {
+  private transporter: nodemailer.Transporter
+
+  constructor(config: SmtpConfig) {
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.secure,
+      auth: config.auth?.user ? { user: config.auth.user, pass: config.auth.pass } : undefined,
+    })
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const info = await this.transporter.sendMail({
+      from: message.from,
+      to: Array.isArray(message.to) ? message.to.join(', ') : message.to,
+      cc: message.cc ? (Array.isArray(message.cc) ? message.cc.join(', ') : message.cc) : undefined,
+      bcc: message.bcc
+        ? Array.isArray(message.bcc)
+          ? message.bcc.join(', ')
+          : message.bcc
+        : undefined,
+      replyTo: message.replyTo,
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      attachments: message.attachments?.map(a => ({
+        filename: a.filename,
+        content: a.content,
+        contentType: a.contentType,
+        cid: a.cid,
+      })),
+    })
+
+    return {
+      messageId: info.messageId,
+      accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [],
+      rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [],
+    }
+  }
+}

package/src/mail/types.ts

@@ -0,0 +1,98 @@
+/** Core message structure passed to transports. */
+export interface MailMessage {
+  from: string
+  to: string | string[]
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string
+  subject: string
+  html?: string
+  text?: string
+  attachments?: MailAttachment[]
+}
+
+export interface MailAttachment {
+  filename: string
+  content: Buffer | string
+  contentType?: string
+  /** For CID-referenced inline images. */
+  cid?: string
+}
+
+export interface MailResult {
+  messageId?: string
+  accepted?: string[]
+  rejected?: string[]
+}
+
+/**
+ * Pluggable transport backend.
+ * Implement this interface for custom mail providers.
+ */
+export interface MailTransport {
+  send(message: MailMessage): Promise<MailResult>
+}
+
+// -- Per-driver configs -------------------------------------------------------
+
+export interface SmtpConfig {
+  host: string
+  port: number
+  secure: boolean
+  auth?: {
+    user: string
+    pass: string
+  }
+}
+
+export interface ResendConfig {
+  apiKey: string
+  baseUrl?: string
+}
+
+export interface SendGridConfig {
+  apiKey: string
+  baseUrl?: string
+}
+
+export interface MailgunConfig {
+  apiKey: string
+  domain: string
+  /** Default: 'https://api.mailgun.net'. EU: 'https://api.eu.mailgun.net' */
+  baseUrl?: string
+}
+
+export interface AlibabaConfig {
+  accessKeyId: string
+  accessKeySecret: string
+  /** Sender address configured in Alibaba DirectMail. */
+  accountName: string
+  /** Default: 'cn-hangzhou' */
+  region?: string
+}
+
+export interface LogConfig {
+  /** Write to 'console' or a file path. */
+  output: 'console' | string
+}
+
+// -- Top-level mail config ----------------------------------------------------
+
+export interface MailConfig {
+  /** Default transport name: 'smtp' | 'resend' | 'sendgrid' | 'mailgun' | 'alibaba' | 'log' */
+  default: string
+  /** Default "from" address. */
+  from: string
+  /** Template prefix for ViewEngine (default: 'emails'). */
+  templatePrefix: string
+  /** Enable CSS inlining via juice (default: true). */
+  inlineCss: boolean
+  /** Enable Tailwind CSS compilation before inlining (default: false). */
+  tailwind: boolean
+  smtp: SmtpConfig
+  resend: ResendConfig
+  sendgrid: SendGridConfig
+  mailgun: MailgunConfig
+  alibaba: AlibabaConfig
+  log: LogConfig
+}

package/src/notification/base_notification.ts

@@ -0,0 +1,67 @@
+import type {
+  Notifiable,
+  MailEnvelope,
+  DatabaseEnvelope,
+  WebhookEnvelope,
+  DiscordEnvelope,
+  NotificationPayload,
+} from './types.ts'
+
+/**
+ * Base class for all notifications.
+ *
+ * Extend this class and implement `via()` plus at least one `toXxx()` method
+ * to define how the notification should be delivered on each channel.
+ *
+ * @example
+ * class TaskAssignedNotification extends BaseNotification {
+ *   constructor(private task: Task, private assigner: User) { super() }
+ *
+ *   via() { return ['email', 'database'] }
+ *
+ *   toEmail(notifiable: Notifiable): MailEnvelope {
+ *     return { subject: `Assigned: ${this.task.title}`, template: 'task-assigned', templateData: { ... } }
+ *   }
+ *
+ *   toDatabase(): DatabaseEnvelope {
+ *     return { type: 'task.assigned', data: { taskId: this.task.id } }
+ *   }
+ *
+ *   shouldQueue() { return true }
+ * }
+ */
+export abstract class BaseNotification {
+  /** Which channels this notification should be sent on. */
+  abstract via(notifiable: Notifiable): string[]
+
+  /** Build the email envelope. */
+  toEmail?(notifiable: Notifiable): MailEnvelope
+  /** Build the database (in-app) envelope. */
+  toDatabase?(notifiable: Notifiable): DatabaseEnvelope
+  /** Build the webhook envelope. */
+  toWebhook?(notifiable: Notifiable): WebhookEnvelope
+  /** Build the Discord envelope. */
+  toDiscord?(notifiable: Notifiable): DiscordEnvelope
+
+  /** Whether this notification should be queued for async delivery. */
+  shouldQueue(): boolean {
+    return false
+  }
+
+  /** Queue options (queue name, delay in ms, max attempts). */
+  queueOptions(): { queue?: string; delay?: number; attempts?: number } {
+    return {}
+  }
+
+  /** Build a serializable payload containing all channel envelopes. */
+  buildPayload(notifiable: Notifiable): NotificationPayload {
+    return {
+      notificationClass: this.constructor.name,
+      channels: this.via(notifiable),
+      mail: this.toEmail?.(notifiable),
+      database: this.toDatabase?.(notifiable),
+      webhook: this.toWebhook?.(notifiable),
+      discord: this.toDiscord?.(notifiable),
+    }
+  }
+}