@strav/signal 0.1.0

package/src/broadcast/client.ts

@@ -0,0 +1,308 @@
+/**
+ * Browser-side Broadcast client.
+ *
+ * Connects to the server's broadcast WebSocket endpoint,
+ * manages channel subscriptions, auto-reconnects, and routes
+ * events to subscription listeners.
+ *
+ * Zero dependencies — works in any browser.
+ *
+ * @example
+ * import { Broadcast } from '@stravigor/signal/broadcast/client'
+ *
+ * const bc = new Broadcast()
+ *
+ * const chat = bc.subscribe('chat/1')
+ * chat.on('new_message', (data) => console.log(data))
+ * chat.send('send', { text: 'Hello!' })
+ *
+ * bc.on('connected', () => console.log('Online'))
+ * bc.on('disconnected', () => console.log('Offline'))
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BroadcastOptions {
+  /** WebSocket URL. Default: auto-detected from current host + `/_broadcast`. */
+  url?: string
+  /** Maximum reconnection attempts. Default: Infinity */
+  maxReconnectAttempts?: number
+}
+
+type Callback = (...args: any[]) => void
+
+// ---------------------------------------------------------------------------
+// Subscription
+// ---------------------------------------------------------------------------
+
+/**
+ * A subscription to a single broadcast channel.
+ *
+ * Listen for server events, send messages to the channel,
+ * or leave the channel entirely.
+ *
+ * @example
+ * const sub = bc.subscribe('chat/1')
+ * sub.on('message', (data) => { ... })
+ * sub.send('typing', { active: true })
+ * sub.leave()
+ */
+export class Subscription {
+  private listeners = new Map<string, Set<Callback>>()
+
+  constructor(
+    /** The channel name this subscription is bound to. */
+    readonly channel: string,
+    private sendFn: (msg: object) => void,
+    private leaveFn: () => void
+  ) {}
+
+  /**
+   * Listen for a specific event on this channel.
+   * Returns a function that removes the listener when called.
+   *
+   * @example
+   * const stop = sub.on('message', (data) => console.log(data))
+   * stop() // remove listener
+   */
+  on(event: string, callback: Callback): () => void {
+    let set = this.listeners.get(event)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(callback)
+    return () => {
+      set!.delete(callback)
+    }
+  }
+
+  /**
+   * Send a message to the server on this channel.
+   *
+   * @example
+   * sub.send('typing', { active: true })
+   */
+  send(event: string, data?: unknown): void {
+    this.sendFn({ t: 'msg', c: this.channel, e: event, d: data })
+  }
+
+  /** Unsubscribe from this channel. */
+  leave(): void {
+    this.sendFn({ t: 'unsub', c: this.channel })
+    this.listeners.clear()
+    this.leaveFn()
+  }
+
+  /** @internal Dispatch an incoming event to registered listeners. */
+  _dispatch(event: string, data: unknown): void {
+    const set = this.listeners.get(event)
+    if (set) for (const cb of set) cb(data)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Broadcast
+// ---------------------------------------------------------------------------
+
+/**
+ * Broadcast client — manages a single WebSocket connection
+ * with multiplexed channel subscriptions.
+ *
+ * @example
+ * const bc = new Broadcast()
+ * const chat = bc.subscribe('chat/1')
+ * chat.on('message', (data) => console.log(data))
+ */
+export class Broadcast {
+  private ws: WebSocket | null = null
+  private url: string
+  private maxReconnectAttempts: number
+  private reconnectAttempt = 0
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  private subscriptions = new Map<string, Subscription>()
+  private listeners = new Map<string, Set<Callback>>()
+  private queue: string[] = []
+  private _connected = false
+  private _clientId: string | null = null
+
+  constructor(options?: BroadcastOptions) {
+    this.url = options?.url ?? this.autoUrl()
+    this.maxReconnectAttempts = options?.maxReconnectAttempts ?? Infinity
+    this.connect()
+  }
+
+  /** Whether the WebSocket connection is currently open. */
+  get connected(): boolean {
+    return this._connected
+  }
+
+  /** The unique client ID assigned by the server, or null if not yet connected. */
+  get clientId(): string | null {
+    return this._clientId
+  }
+
+  /**
+   * Subscribe to a broadcast channel.
+   *
+   * Returns an existing subscription if already subscribed.
+   * On reconnect, all active subscriptions are automatically re-established.
+   *
+   * @example
+   * const notifications = bc.subscribe('notifications')
+   * notifications.on('alert', (data) => showToast(data.text))
+   */
+  subscribe(channel: string): Subscription {
+    const existing = this.subscriptions.get(channel)
+    if (existing) return existing
+
+    const sub = new Subscription(
+      channel,
+      msg => this.send(msg),
+      () => this.subscriptions.delete(channel)
+    )
+
+    this.subscriptions.set(channel, sub)
+
+    if (this._connected) {
+      this.rawSend({ t: 'sub', c: channel })
+    }
+
+    return sub
+  }
+
+  /**
+   * Listen for connection lifecycle events.
+   *
+   * Events:
+   * - `connected` — WebSocket connection established
+   * - `disconnected` — WebSocket connection lost
+   * - `reconnecting` — reconnection attempt (callback receives attempt number)
+   * - `subscribed` — channel subscription confirmed (callback receives channel name)
+   * - `error` — subscription error (callback receives `{ channel, reason }`)
+   *
+   * Returns a function that removes the listener.
+   */
+  on(event: string, callback: Callback): () => void {
+    let set = this.listeners.get(event)
+    if (!set) {
+      set = new Set()
+      this.listeners.set(event, set)
+    }
+    set.add(callback)
+    return () => {
+      set!.delete(callback)
+    }
+  }
+
+  /** Close the connection permanently (no reconnection). */
+  close(): void {
+    this.reconnectAttempt = Infinity
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
+    this.ws?.close()
+    this.ws = null
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private autoUrl(): string {
+    // @ts-ignore browser-only API
+    const proto = location.protocol === 'https:' ? 'wss:' : 'ws:'
+    // @ts-ignore browser-only API
+    return `${proto}//${location.host}/_broadcast`
+  }
+
+  private connect(): void {
+    this.ws = new WebSocket(this.url)
+
+    this.ws.onopen = () => {
+      this._connected = true
+      this.reconnectAttempt = 0
+      this.emit('connected')
+    }
+
+    this.ws.onmessage = event => {
+      try {
+        const msg = JSON.parse(event.data)
+        this.handleMessage(msg)
+      } catch {}
+    }
+
+    this.ws.onclose = () => {
+      const wasConnected = this._connected
+      this._connected = false
+      if (wasConnected) this.emit('disconnected')
+      this.scheduleReconnect()
+    }
+
+    this.ws.onerror = () => {
+      this.ws?.close()
+    }
+  }
+
+  private handleMessage(msg: any): void {
+    switch (msg.t) {
+      case 'welcome':
+        this._clientId = msg.id
+        // Re-subscribe to all active channels
+        for (const channel of this.subscriptions.keys()) {
+          this.rawSend({ t: 'sub', c: channel })
+        }
+        // Flush queued messages
+        for (const raw of this.queue) {
+          this.ws!.send(raw)
+        }
+        this.queue = []
+        break
+
+      case 'ok':
+        this.emit('subscribed', msg.c)
+        break
+
+      case 'err':
+        this.emit('error', { channel: msg.c, reason: msg.r })
+        break
+
+      case 'msg':
+        this.subscriptions.get(msg.c)?._dispatch(msg.e, msg.d)
+        break
+
+      case 'ping':
+        this.rawSend({ t: 'pong' })
+        break
+    }
+  }
+
+  private send(msg: object): void {
+    const raw = JSON.stringify(msg)
+    if (this._connected && this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(raw)
+    } else {
+      this.queue.push(raw)
+    }
+  }
+
+  private rawSend(msg: object): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg))
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectAttempt >= this.maxReconnectAttempts) return
+
+    this.reconnectAttempt++
+    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempt - 1), 30_000)
+    this.emit('reconnecting', this.reconnectAttempt)
+    this.reconnectTimer = setTimeout(() => this.connect(), delay)
+  }
+
+  private emit(event: string, data?: unknown): void {
+    const set = this.listeners.get(event)
+    if (set) for (const cb of set) cb(data)
+  }
+}

package/src/broadcast/index.ts

@@ -0,0 +1,58 @@
+export { default, default as BroadcastManager } from './broadcast_manager.ts'
+export type {
+  AuthorizeCallback,
+  MessageHandler,
+  ChannelConfig,
+  BootOptions,
+  PendingBroadcast,
+} from './broadcast_manager.ts'
+export { Broadcast, Subscription } from './client.ts'
+export type { BroadcastOptions } from './client.ts'
+
+import BroadcastManager from './broadcast_manager.ts'
+import type { AuthorizeCallback, ChannelConfig, BootOptions } from './broadcast_manager.ts'
+import type Router from '@stravigor/http/http/router'
+
+/**
+ * Broadcast helper — convenience object that delegates to `BroadcastManager`.
+ *
+ * @example
+ * import { broadcast } from '@stravigor/signal/broadcast'
+ *
+ * // Bootstrap
+ * broadcast.boot(router, { middleware: [session()] })
+ *
+ * // Define channels
+ * broadcast.channel('notifications')
+ * broadcast.channel('chats/:id', async (ctx, { id }) => !!ctx.get('user'))
+ *
+ * // Broadcast from anywhere
+ * broadcast.to('notifications').send('alert', { text: 'Hello' })
+ * broadcast.to(`chats/${chatId}`).except(senderId).send('message', data)
+ */
+export const broadcast = {
+  /** Register the broadcast WebSocket endpoint on the router. */
+  boot(router: Router, options?: BootOptions): void {
+    BroadcastManager.boot(router, options)
+  },
+
+  /** Register a channel with optional authorization and message handlers. */
+  channel(pattern: string, config?: AuthorizeCallback | ChannelConfig): void {
+    BroadcastManager.channel(pattern, config)
+  },
+
+  /** Begin a broadcast to a channel. */
+  to(channel: string) {
+    return BroadcastManager.to(channel)
+  },
+
+  /** Number of active WebSocket connections. */
+  get clientCount() {
+    return BroadcastManager.clientCount
+  },
+
+  /** Number of subscribers on a specific channel. */
+  subscriberCount(channel: string) {
+    return BroadcastManager.subscriberCount(channel)
+  },
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './mail/index.ts'
+export * from './notification/index.ts'
+export * from './broadcast/index.ts'
+export * from './providers/index.ts'

package/src/mail/css_inliner.ts

@@ -0,0 +1,79 @@
+import juice from 'juice'
+
+export interface InlinerOptions {
+  /** Enable CSS inlining (default: true). */
+  enabled: boolean
+  /** Enable Tailwind CSS compilation before inlining (default: false). */
+  tailwind: boolean
+}
+
+/**
+ * Process rendered HTML for email delivery:
+ * 1. Optionally compile Tailwind classes to CSS
+ * 2. Inline all <style> blocks into style="" attributes via juice
+ */
+export async function inlineCss(html: string, options: InlinerOptions): Promise<string> {
+  if (!options.enabled) return html
+
+  let processed = html
+
+  if (options.tailwind) {
+    processed = await compileTailwind(processed)
+  }
+
+  return juice(processed, {
+    removeStyleTags: true,
+    preserveMediaQueries: true,
+    preserveFontFaces: true,
+    preserveKeyFrames: true,
+    applyWidthAttributes: true,
+    applyHeightAttributes: true,
+    applyAttributesTableElements: true,
+  })
+}
+
+/**
+ * Extract Tailwind utility classes from HTML and compile them to CSS,
+ * then inject a <style> block for juice to inline.
+ *
+ * Uses dynamic import — silently skips if tailwindcss is not installed.
+ */
+async function compileTailwind(html: string): Promise<string> {
+  try {
+    // @ts-ignore: Tailwind is optional
+    const { compile } = await import('tailwindcss')
+
+    const compiler = await compile('@tailwind utilities;')
+    const classes = extractClasses(html)
+
+    if (classes.length === 0) return html
+
+    const css = compiler.build(classes)
+    if (!css) return html
+
+    const insertPoint = html.indexOf('</head>')
+    if (insertPoint !== -1) {
+      return html.slice(0, insertPoint) + `<style>${css}</style>` + html.slice(insertPoint)
+    }
+    return `<style>${css}</style>` + html
+  } catch {
+    // tailwindcss not installed or API mismatch — skip silently
+    return html
+  }
+}
+
+/** Extract class names from HTML class="..." attributes. */
+function extractClasses(html: string): string[] {
+  const classRegex = /class\s*=\s*["']([^"']*)["']/gi
+  const classes = new Set<string>()
+
+  let match
+  while ((match = classRegex.exec(html)) !== null) {
+    for (const cls of match[1]!.split(/\s+/)) {
+      const trimmed = cls.trim()
+      if (trimmed) classes.add(trimmed)
+    }
+  }
+
+  return [...classes]
+}

package/src/mail/helpers.ts

@@ -0,0 +1,212 @@
+import MailManager from './mail_manager.ts'
+import { ViewEngine } from '@stravigor/view'
+import { inlineCss } from './css_inliner.ts'
+import Queue from '@stravigor/queue/queue/queue'
+import type { MailMessage, MailResult, MailAttachment } from './types.ts'
+
+/**
+ * Fluent email builder. Returned by `mail.to()`.
+ *
+ * @example
+ * await mail.to('user@example.com')
+ *   .subject('Welcome!')
+ *   .template('welcome', { name: 'Alice' })
+ *   .send()
+ *
+ * await mail.to(user.email)
+ *   .from('support@app.com')
+ *   .subject('Reset Password')
+ *   .template('reset', { token })
+ *   .queue()
+ */
+export class PendingMail {
+  private _from?: string
+  private _to: string | string[]
+  private _cc?: string | string[]
+  private _bcc?: string | string[]
+  private _replyTo?: string
+  private _subject = ''
+  private _html?: string
+  private _text?: string
+  private _attachments: MailAttachment[] = []
+  private _template?: string
+  private _templateData?: Record<string, unknown>
+
+  constructor(to: string | string[]) {
+    this._to = to
+  }
+
+  from(address: string): this {
+    this._from = address
+    return this
+  }
+
+  cc(address: string | string[]): this {
+    this._cc = address
+    return this
+  }
+
+  bcc(address: string | string[]): this {
+    this._bcc = address
+    return this
+  }
+
+  replyTo(address: string): this {
+    this._replyTo = address
+    return this
+  }
+
+  subject(value: string): this {
+    this._subject = value
+    return this
+  }
+
+  /** Set raw HTML content (bypasses template rendering). */
+  html(value: string): this {
+    this._html = value
+    return this
+  }
+
+  /** Set plain text content. */
+  text(value: string): this {
+    this._text = value
+    return this
+  }
+
+  /** Use a .strav template. Name is relative to the mail template prefix. */
+  template(name: string, data: Record<string, unknown> = {}): this {
+    this._template = name
+    this._templateData = data
+    return this
+  }
+
+  attach(attachment: MailAttachment): this {
+    this._attachments.push(attachment)
+    return this
+  }
+
+  /** Build the MailMessage, rendering template + inlining CSS if needed. */
+  async build(): Promise<MailMessage> {
+    const config = MailManager.config
+    let html = this._html
+    const text = this._text
+
+    if (this._template) {
+      const templateName = `${config.templatePrefix}.${this._template}`
+      html = await ViewEngine.instance.render(templateName, this._templateData ?? {})
+    }
+
+    if (html) {
+      html = await inlineCss(html, {
+        enabled: config.inlineCss,
+        tailwind: config.tailwind,
+      })
+    }
+
+    return {
+      from: this._from ?? config.from,
+      to: this._to,
+      cc: this._cc,
+      bcc: this._bcc,
+      replyTo: this._replyTo,
+      subject: this._subject,
+      html,
+      text,
+      attachments: this._attachments.length > 0 ? this._attachments : undefined,
+    }
+  }
+
+  /** Send the email immediately via the configured transport. */
+  async send(): Promise<MailResult> {
+    const message = await this.build()
+    return MailManager.transport.send(message)
+  }
+
+  /** Push the email onto the job queue for async sending. */
+  async queue(options?: { queue?: string; delay?: number }): Promise<number> {
+    const message = await this.build()
+    return Queue.push('strav:send-mail', message, options)
+  }
+}
+
+/**
+ * Mail helper object — the primary API for sending emails.
+ *
+ * @example
+ * import { mail } from '@stravigor/signal/mail'
+ *
+ * // Fluent builder
+ * await mail.to('user@example.com').subject('Hello').template('welcome', { name }).send()
+ *
+ * // Convenience send
+ * await mail.send({ to: 'user@example.com', subject: 'Hello', template: 'welcome', data: { name } })
+ *
+ * // Raw HTML send
+ * await mail.raw({ to: 'user@example.com', subject: 'Hello', html: '<h1>Hi</h1>' })
+ */
+export const mail = {
+  /** Start building an email to the given recipient(s). Returns a fluent PendingMail. */
+  to(address: string | string[]): PendingMail {
+    return new PendingMail(address)
+  },
+
+  /** Send an email using a template. Convenience wrapper for the fluent API. */
+  async send(options: {
+    to: string | string[]
+    from?: string
+    cc?: string | string[]
+    bcc?: string | string[]
+    replyTo?: string
+    subject: string
+    template: string
+    data?: Record<string, unknown>
+    attachments?: MailAttachment[]
+  }): Promise<MailResult> {
+    const pending = new PendingMail(options.to)
+      .subject(options.subject)
+      .template(options.template, options.data)
+    if (options.from) pending.from(options.from)
+    if (options.cc) pending.cc(options.cc)
+    if (options.bcc) pending.bcc(options.bcc)
+    if (options.replyTo) pending.replyTo(options.replyTo)
+    if (options.attachments) {
+      for (const a of options.attachments) pending.attach(a)
+    }
+    return pending.send()
+  },
+
+  /** Send a raw email without template rendering. */
+  async raw(options: {
+    to: string | string[]
+    from?: string
+    cc?: string | string[]
+    bcc?: string | string[]
+    replyTo?: string
+    subject: string
+    html?: string
+    text?: string
+    attachments?: MailAttachment[]
+  }): Promise<MailResult> {
+    const pending = new PendingMail(options.to).subject(options.subject)
+    if (options.from) pending.from(options.from)
+    if (options.html) pending.html(options.html)
+    if (options.text) pending.text(options.text)
+    if (options.cc) pending.cc(options.cc)
+    if (options.bcc) pending.bcc(options.bcc)
+    if (options.replyTo) pending.replyTo(options.replyTo)
+    if (options.attachments) {
+      for (const a of options.attachments) pending.attach(a)
+    }
+    return pending.send()
+  },
+
+  /**
+   * Register the built-in queue handler for async mail sending.
+   * Call this in your app bootstrap after Queue is configured.
+   */
+  registerQueueHandler(): void {
+    Queue.handle<MailMessage>('strav:send-mail', async message => {
+      await MailManager.transport.send(message)
+    })
+  },
+}

package/src/mail/index.ts

@@ -0,0 +1,23 @@
+export { default, default as MailManager } from './mail_manager.ts'
+export { mail, PendingMail } from './helpers.ts'
+export { SmtpTransport } from './transports/smtp_transport.ts'
+export { ResendTransport } from './transports/resend_transport.ts'
+export { SendGridTransport } from './transports/sendgrid_transport.ts'
+export { MailgunTransport } from './transports/mailgun_transport.ts'
+export { AlibabaTransport } from './transports/alibaba_transport.ts'
+export { LogTransport } from './transports/log_transport.ts'
+export { inlineCss } from './css_inliner.ts'
+export type {
+  MailTransport,
+  MailMessage,
+  MailResult,
+  MailAttachment,
+  MailConfig,
+  SmtpConfig,
+  ResendConfig,
+  SendGridConfig,
+  MailgunConfig,
+  AlibabaConfig,
+  LogConfig,
+} from './types.ts'
+export type { InlinerOptions } from './css_inliner.ts'