@codingfactory/socialkit-vue 0.3.0 → 0.4.0

package/src/services/echo.ts

@@ -0,0 +1,1072 @@
+/**
+ * Configurable Echo/Reverb client for SocialKit-powered frontends.
+ */
+
+import type { EchoConfig } from '../types/api.js'
+import type {
+  ConnectionStatus,
+  LiveCircleCountUpdatedEvent,
+  PresenceStatus,
+  PresenceStatusChangedEvent,
+  ProfileActivityCreatedEvent,
+  ProfileStatsUpdatedEvent,
+  StoryTrayUpdatedEvent,
+  TutorialCommentAddedEvent,
+  TutorialProgressUpdatedEvent
+} from '../types/realtime.js'
+
+export interface EchoChannelLike {
+  listen(event: string, callback: (data: unknown) => void): EchoChannelLike
+}
+
+export interface EchoInstanceLike {
+  connector?: {
+    pusher?: {
+      connection?: PusherConnectionBindings
+    }
+  }
+  private(channel: string): EchoChannelLike
+  join(channel: string): EchoChannelLike
+  leave(channel: string): void
+  disconnect(): void
+}
+
+export interface EchoConstructor<TInstance extends EchoInstanceLike = EchoInstanceLike> {
+  new (...args: any[]): TInstance
+}
+
+type UnknownRecord = Record<string, unknown>
+type EchoWindow = Window & {
+  Echo?: EchoInstanceLike | null
+  Pusher?: unknown
+}
+
+interface PusherConnectionEventHandler {
+  (data?: unknown): void
+}
+
+interface PusherConnectionBindings {
+  bind(event: string, handler: PusherConnectionEventHandler): void
+  state?: string
+}
+
+interface PusherConnectorInterface {
+  pusher: {
+    connection: PusherConnectionBindings
+  }
+}
+
+export interface EchoServiceLogger {
+  debug(message: string, context?: unknown): void
+  warn(message: string, context?: unknown): void
+  error(message: string, context?: unknown): void
+}
+
+export interface EchoConnectionConfig extends EchoConfig {
+  wsPath?: string
+}
+
+export interface EchoDisconnectOptions {
+  preventReconnect?: boolean
+  skipStatusUpdate?: boolean
+}
+
+export interface EchoReconnectOptions {
+  resetBackoff?: boolean
+}
+
+export interface ProfileUpdatesCallbacks {
+  onStatsUpdated?: (data: ProfileStatsUpdatedEvent) => void
+  onActivityCreated?: (data: ProfileActivityCreatedEvent) => void
+}
+
+export interface StoryTrayCallbacks {
+  onStoryTrayUpdated?: (data: StoryTrayUpdatedEvent) => void
+}
+
+export interface EchoServiceConfig {
+  Echo: EchoConstructor
+  pusher?: unknown
+  getToken: () => string | null
+  resolveConnectionConfig: (token: string) => EchoConnectionConfig
+  resolveTenantScope?: () => string
+  initializedEvent?: string
+  logger?: Partial<EchoServiceLogger>
+}
+
+export interface EchoServiceInstance<TInstance extends EchoInstanceLike = EchoInstanceLike> {
+  initializeEcho(): TInstance | null
+  getEcho(): TInstance | null
+  disconnectEcho(options?: EchoDisconnectOptions): void
+  reconnectEcho(options?: EchoReconnectOptions): void
+  getConnectionStatus(): ConnectionStatus
+  onConnectionStatusChange(callback: (status: ConnectionStatus) => void): () => void
+  onEchoReconnected(callback: () => void): () => void
+  subscribeToPresenceStatus(callback: (event: PresenceStatusChangedEvent) => void): void
+  unsubscribeFromPresenceStatus(): void
+  subscribeToLiveCircleCount(
+    circleId: string,
+    callback: (event: LiveCircleCountUpdatedEvent) => void
+  ): () => void
+  subscribeToTutorialComments(
+    tutorialId: string,
+    callback: (event: TutorialCommentAddedEvent) => void
+  ): () => void
+  subscribeToTutorialProgress(
+    tutorialId: string,
+    callback: (event: TutorialProgressUpdatedEvent) => void
+  ): () => void
+  subscribeToProfileUpdates(userId: string, callbacks: ProfileUpdatesCallbacks): void
+  unsubscribeFromProfileUpdates(userId: string): void
+  subscribeToStoryTray(callbacks: StoryTrayCallbacks): boolean
+  unsubscribeFromStoryTray(): void
+}
+
+const TRANSIENT_PUSHER_CLOSE_CODE = 1006
+const CONNECTION_STATE_RECONCILE_DELAYS_MS = [0, 50, 250, 1000, 5000] as const
+const FAST_RECONNECT_RETRY_COUNT = 10
+const MAX_RECONNECT_DELAY_MS = 30000
+const STEADY_RECONNECT_DELAY_MS = 60000
+const HEALTH_CHECK_INTERVAL_MS = 45000
+const DISCONNECT_SUPPRESSION_RESET_MS = 2000
+
+const noopLogger: EchoServiceLogger = {
+  debug: () => undefined,
+  warn: () => undefined,
+  error: () => undefined
+}
+
+function getBrowserWindow(): EchoWindow | null {
+  return typeof window === 'undefined' ? null : window as unknown as EchoWindow
+}
+
+function getBrowserDocument(): Document | null {
+  return typeof document === 'undefined' ? null : document
+}
+
+function ensurePusherGlobal(pusher?: unknown): void {
+  const liveWindow = getBrowserWindow()
+  if (liveWindow && pusher !== undefined) {
+    ;(liveWindow as { Pusher?: unknown }).Pusher = pusher
+  }
+}
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null
+}
+
+function hasString(obj: UnknownRecord, key: string): boolean {
+  return typeof obj[key] === 'string'
+}
+
+function getPresenceField(payload: UnknownRecord, snakeKey: string, camelKey: string): string | null {
+  const snakeValue = payload[snakeKey]
+  if (typeof snakeValue === 'string' && snakeValue.trim().length > 0) {
+    return snakeValue
+  }
+
+  const camelValue = payload[camelKey]
+  if (typeof camelValue === 'string' && camelValue.trim().length > 0) {
+    return camelValue
+  }
+
+  return null
+}
+
+function normalizePresenceStatus(rawStatus: unknown): PresenceStatus | null {
+  if (typeof rawStatus !== 'string') {
+    return null
+  }
+
+  const normalizedStatus = rawStatus.trim().toLowerCase()
+  if (
+    normalizedStatus === 'online'
+    || normalizedStatus === 'idle'
+    || normalizedStatus === 'dnd'
+    || normalizedStatus === 'offline'
+  ) {
+    return normalizedStatus
+  }
+
+  return null
+}
+
+function normalizePresenceStatusChangedPayload(
+  data: unknown,
+  resolveTenantScope: () => string
+): PresenceStatusChangedEvent | null {
+  if (!isRecord(data)) {
+    return null
+  }
+
+  const userId = getPresenceField(data, 'user_id', 'userId')
+  const status = normalizePresenceStatus(data.status)
+  if (!userId || !status) {
+    return null
+  }
+
+  const payload: PresenceStatusChangedEvent = {
+    user_id: userId,
+    tenant_scope: getPresenceField(data, 'tenant_scope', 'tenantScope') ?? resolveTenantScope(),
+    status,
+    ts: getPresenceField(data, 'ts', 'timestamp') ?? new Date().toISOString()
+  }
+
+  const tenantIdValue = data.tenant_id ?? data.tenantId
+  if (typeof tenantIdValue === 'string') {
+    payload.tenant_id = tenantIdValue
+  } else if (tenantIdValue === null) {
+    payload.tenant_id = null
+  }
+
+  const lastSeenValue = data.last_seen_at ?? data.lastSeenAt
+  if (typeof lastSeenValue === 'string') {
+    payload.last_seen_at = lastSeenValue
+  } else if (lastSeenValue === null) {
+    payload.last_seen_at = null
+  }
+
+  return payload
+}
+
+export function isValidPresenceStatusChangedEvent(data: unknown): data is PresenceStatusChangedEvent {
+  if (!isRecord(data)) {
+    return false
+  }
+
+  return hasString(data, 'user_id')
+    && (data.status === 'online' || data.status === 'idle' || data.status === 'dnd' || data.status === 'offline')
+}
+
+export function isValidLiveCircleCountUpdatedEvent(data: unknown): data is LiveCircleCountUpdatedEvent {
+  if (!isRecord(data)) {
+    return false
+  }
+
+  return hasString(data, 'circle_id') && typeof data.count === 'number'
+}
+
+export function isValidTutorialCommentAddedEvent(data: unknown): data is TutorialCommentAddedEvent {
+  if (!isRecord(data) || !hasString(data, 'tutorial_id') || !isRecord(data.comment)) {
+    return false
+  }
+
+  const comment = data.comment
+  return hasString(comment, 'id')
+    && hasString(comment, 'author_id')
+    && hasString(comment, 'author_name')
+    && hasString(comment, 'body')
+    && hasString(comment, 'created_at')
+}
+
+export function isValidTutorialProgressUpdatedEvent(data: unknown): data is TutorialProgressUpdatedEvent {
+  if (!isRecord(data)) {
+    return false
+  }
+
+  if (
+    !hasString(data, 'tutorial_id')
+    || !hasString(data, 'user_id')
+    || !hasString(data, 'current_step_id')
+    || typeof data.progress_percent !== 'number'
+    || typeof data.is_completed !== 'boolean'
+    || !hasString(data, 'updated_at')
+  ) {
+    return false
+  }
+
+  if (!Array.isArray(data.completed_steps)) {
+    return false
+  }
+
+  return data.completed_steps.every((stepId: unknown) => typeof stepId === 'string')
+}
+
+export function isValidProfileStatsUpdatedEvent(data: unknown): data is ProfileStatsUpdatedEvent {
+  if (!isRecord(data) || !isRecord(data.stats)) {
+    return false
+  }
+
+  const stats = data.stats
+  return typeof stats.followers_count === 'number' && typeof stats.following_count === 'number'
+}
+
+export function isValidProfileActivityCreatedEvent(data: unknown): data is ProfileActivityCreatedEvent {
+  if (!isRecord(data) || !isRecord(data.activity)) {
+    return false
+  }
+
+  const activity = data.activity
+  return hasString(activity, 'id') && hasString(activity, 'activity_type') && hasString(activity, 'created_at')
+}
+
+export function isValidStoryTrayUpdatedEvent(data: unknown): data is StoryTrayUpdatedEvent {
+  if (!isRecord(data)) {
+    return false
+  }
+
+  return hasString(data, 'story_id') && hasString(data, 'author_id')
+}
+
+function getPusherErrorCode(error: unknown): number | null {
+  if (!isRecord(error) || !isRecord(error.data)) {
+    return null
+  }
+
+  return typeof error.data.code === 'number' ? error.data.code : null
+}
+
+function resolvePusherConnection(echo: EchoInstanceLike | null): PusherConnectionBindings | null {
+  const connector = echo?.connector as PusherConnectorInterface | undefined
+  return connector?.pusher?.connection ?? null
+}
+
+function guardedListen<T>(
+  channel: EchoChannelLike,
+  event: string,
+  validator: (data: unknown) => data is T,
+  callback: (data: T) => void,
+  label: string,
+  logger: EchoServiceLogger
+): (data: unknown) => void {
+  const handler = (data: unknown): void => {
+    if (!validator(data)) {
+      logger.warn(`Dropping malformed ${label} event`, data)
+      return
+    }
+
+    try {
+      callback(data)
+    } catch (error) {
+      logger.error(`Error handling ${label} event`, error)
+    }
+  }
+
+  channel.listen(event, handler)
+  return handler
+}
+
+export function createEchoService<TInstance extends EchoInstanceLike = EchoInstanceLike>(
+  config: EchoServiceConfig & {
+    Echo: EchoConstructor<TInstance>
+  }
+): EchoServiceInstance<TInstance> {
+  const logger: EchoServiceLogger = {
+    ...noopLogger,
+    ...config.logger
+  }
+
+  const resolveTenantScope = (): string => {
+    const tenantScope = config.resolveTenantScope?.()
+    return typeof tenantScope === 'string' && tenantScope.length > 0 ? tenantScope : 'global'
+  }
+
+  let echoInstance: TInstance | null = null
+  let suppressNextDisconnectEvent = false
+  let suppressDisconnectResetTimeoutId: ReturnType<typeof setTimeout> | null = null
+  let connectionStateReconcileTimeoutId: ReturnType<typeof setTimeout> | null = null
+  let connectionStateReconcileAttempt = 0
+  let connectionStatus: ConnectionStatus = 'disconnected'
+  const connectionCallbacks = new Set<(status: ConnectionStatus) => void>()
+  const reconnectCallbacks = new Set<() => void>()
+  let hasConnectedAtLeastOnce = false
+  let reconnectAttempts = 0
+  let reconnectTimeoutId: ReturnType<typeof setTimeout> | null = null
+  let healthCheckIntervalId: ReturnType<typeof setInterval> | null = null
+  let connectionGeneration = 0
+
+  function clearConnectionStateReconcile(): void {
+    if (connectionStateReconcileTimeoutId) {
+      clearTimeout(connectionStateReconcileTimeoutId)
+      connectionStateReconcileTimeoutId = null
+    }
+
+    connectionStateReconcileAttempt = 0
+  }
+
+  function updateConnectionStatus(status: ConnectionStatus): void {
+    if (connectionStatus === status) {
+      return
+    }
+
+    const previousStatus = connectionStatus
+    connectionStatus = status
+    logger.debug(`Connection status changed to ${status}`)
+
+    for (const callback of connectionCallbacks) {
+      callback(status)
+    }
+
+    if (status !== 'connected') {
+      return
+    }
+
+    const recoveredConnection = hasConnectedAtLeastOnce && previousStatus !== 'connected'
+    hasConnectedAtLeastOnce = true
+
+    if (!recoveredConnection) {
+      return
+    }
+
+    for (const callback of reconnectCallbacks) {
+      callback()
+    }
+  }
+
+  function scheduleConnectionStateReconcile(connection: PusherConnectionBindings): void {
+    clearConnectionStateReconcile()
+
+    const reconcile = (): void => {
+      connectionStateReconcileTimeoutId = null
+
+      if (getConnectionStatus() !== 'connecting') {
+        clearConnectionStateReconcile()
+        return
+      }
+
+      if (connection.state === 'connected') {
+        updateConnectionStatus('connected')
+        clearConnectionStateReconcile()
+        return
+      }
+
+      connectionStateReconcileAttempt += 1
+      const nextDelay = CONNECTION_STATE_RECONCILE_DELAYS_MS[connectionStateReconcileAttempt]
+      if (typeof nextDelay !== 'number') {
+        clearConnectionStateReconcile()
+        return
+      }
+
+      connectionStateReconcileTimeoutId = setTimeout(reconcile, nextDelay)
+    }
+
+    connectionStateReconcileTimeoutId = setTimeout(reconcile, CONNECTION_STATE_RECONCILE_DELAYS_MS[0])
+  }
+
+  function stopHealthCheck(): void {
+    if (healthCheckIntervalId) {
+      clearInterval(healthCheckIntervalId)
+      healthCheckIntervalId = null
+    }
+  }
+
+  function startHealthCheck(): void {
+    if (healthCheckIntervalId) {
+      return
+    }
+
+    healthCheckIntervalId = setInterval(() => {
+      const liveDocument = getBrowserDocument()
+      if (liveDocument?.hidden) {
+        return
+      }
+
+      const status = getConnectionStatus()
+      if (status === 'disconnected' || status === 'error') {
+        logger.debug('Health check: connection is down, triggering reconnect')
+        reconnectAttempts = 0
+        scheduleReconnect()
+      }
+    }, HEALTH_CHECK_INTERVAL_MS)
+  }
+
+  function scheduleReconnect(): void {
+    const delay = reconnectAttempts < FAST_RECONNECT_RETRY_COUNT
+      ? Math.min(1000 * Math.pow(2, reconnectAttempts), MAX_RECONNECT_DELAY_MS)
+      : STEADY_RECONNECT_DELAY_MS
+
+    reconnectAttempts += 1
+    logger.debug(`Scheduling reconnect attempt ${reconnectAttempts} in ${delay}ms`)
+
+    if (reconnectTimeoutId) {
+      clearTimeout(reconnectTimeoutId)
+    }
+
+    reconnectTimeoutId = setTimeout(() => {
+      logger.debug(`Reconnect attempt ${reconnectAttempts}`)
+      reconnectEcho()
+    }, delay)
+  }
+
+  function initializeEcho(): TInstance | null {
+    connectionGeneration += 1
+    const thisGeneration = connectionGeneration
+
+    if (suppressDisconnectResetTimeoutId) {
+      clearTimeout(suppressDisconnectResetTimeoutId)
+      suppressDisconnectResetTimeoutId = null
+    }
+
+    clearConnectionStateReconcile()
+
+    const token = config.getToken()
+    if (!token) {
+      logger.warn('No auth token available, skipping initialization')
+      return null
+    }
+
+    if (echoInstance) {
+      logger.debug('Already initialized')
+      return echoInstance
+    }
+
+    ensurePusherGlobal(config.pusher)
+
+    logger.debug('Initializing connection to Reverb...')
+
+    const echoOptions = config.resolveConnectionConfig(token)
+    logger.debug('Resolved config', {
+      host: echoOptions.wsHost,
+      port: echoOptions.wsPort,
+      tls: echoOptions.forceTLS,
+      path: echoOptions.wsPath ?? '(default)',
+      authEndpoint: echoOptions.authEndpoint
+    })
+
+    echoInstance = new config.Echo(echoOptions) as TInstance
+
+    const liveWindow = getBrowserWindow()
+    if (liveWindow) {
+      ;(liveWindow as unknown as { Echo?: TInstance | null }).Echo = echoInstance
+      if (config.initializedEvent) {
+        liveWindow.dispatchEvent(new CustomEvent(config.initializedEvent))
+      }
+    }
+
+    const connection = resolvePusherConnection(echoInstance)
+    if (!connection) {
+      logger.error('Unable to access Pusher connection')
+      return echoInstance
+    }
+
+    connection.bind('connected', () => {
+      if (thisGeneration !== connectionGeneration) {
+        logger.debug('Ignoring stale connected event from old connection')
+        return
+      }
+
+      logger.debug('Connected to Reverb WebSocket server')
+      clearConnectionStateReconcile()
+      suppressNextDisconnectEvent = false
+
+      if (suppressDisconnectResetTimeoutId) {
+        clearTimeout(suppressDisconnectResetTimeoutId)
+        suppressDisconnectResetTimeoutId = null
+      }
+
+      updateConnectionStatus('connected')
+      reconnectAttempts = 0
+
+      if (reconnectTimeoutId) {
+        clearTimeout(reconnectTimeoutId)
+        reconnectTimeoutId = null
+      }
+
+      startHealthCheck()
+    })
+
+    connection.bind('disconnected', () => {
+      if (thisGeneration !== connectionGeneration) {
+        logger.debug('Ignoring stale disconnected event from old connection')
+        return
+      }
+
+      if (suppressNextDisconnectEvent) {
+        logger.debug('Skipping reconnect for intentional disconnect')
+        suppressNextDisconnectEvent = false
+
+        if (suppressDisconnectResetTimeoutId) {
+          clearTimeout(suppressDisconnectResetTimeoutId)
+          suppressDisconnectResetTimeoutId = null
+        }
+
+        return
+      }
+
+      logger.warn('Disconnected from Reverb WebSocket server')
+      updateConnectionStatus('disconnected')
+      scheduleReconnect()
+    })
+
+    connection.bind('error', (error?: unknown) => {
+      if (thisGeneration !== connectionGeneration) {
+        logger.debug('Ignoring stale error event from old connection')
+        return
+      }
+
+      const errorCode = getPusherErrorCode(error)
+      if (errorCode === TRANSIENT_PUSHER_CLOSE_CODE) {
+        if (suppressNextDisconnectEvent) {
+          logger.debug('Ignoring PusherError 1006 during intentional disconnect')
+          return
+        }
+
+        logger.debug('Received PusherError 1006; treating as disconnected')
+        updateConnectionStatus('disconnected')
+        scheduleReconnect()
+        return
+      }
+
+      logger.error('Connection error', error)
+      updateConnectionStatus('error')
+      scheduleReconnect()
+    })
+
+    connection.bind('unavailable', () => {
+      if (thisGeneration !== connectionGeneration) {
+        logger.debug('Ignoring stale unavailable event from old connection')
+        return
+      }
+
+      if (suppressNextDisconnectEvent) {
+        logger.debug('Ignoring unavailable event during intentional disconnect')
+        return
+      }
+
+      logger.debug('Connection unavailable; scheduling reconnect')
+      updateConnectionStatus('disconnected')
+      scheduleReconnect()
+    })
+
+    connection.bind('connecting', () => {
+      if (thisGeneration !== connectionGeneration) {
+        logger.debug('Ignoring stale connecting event from old connection')
+        return
+      }
+
+      logger.debug('Connecting to Reverb WebSocket server')
+      updateConnectionStatus('connecting')
+      scheduleConnectionStateReconcile(connection)
+    })
+
+    updateConnectionStatus('connecting')
+
+    if (connection.state === 'connected') {
+      updateConnectionStatus('connected')
+    }
+
+    scheduleConnectionStateReconcile(connection)
+
+    return echoInstance
+  }
+
+  function getEcho(): TInstance | null {
+    const liveWindow = getBrowserWindow()
+
+    if (!echoInstance && liveWindow?.Echo) {
+      echoInstance = liveWindow.Echo as TInstance
+
+      const liveConnection = resolvePusherConnection(echoInstance)
+      if (liveConnection?.state === 'connected') {
+        updateConnectionStatus('connected')
+      }
+    }
+
+    return echoInstance
+  }
+
+  function disconnectEcho(options: EchoDisconnectOptions = {}): void {
+    const preventReconnect = options.preventReconnect ?? true
+
+    if (!preventReconnect) {
+      suppressNextDisconnectEvent = false
+      if (suppressDisconnectResetTimeoutId) {
+        clearTimeout(suppressDisconnectResetTimeoutId)
+        suppressDisconnectResetTimeoutId = null
+      }
+    }
+
+    clearConnectionStateReconcile()
+    stopHealthCheck()
+
+    if (echoInstance) {
+      if (preventReconnect) {
+        suppressNextDisconnectEvent = true
+
+        if (suppressDisconnectResetTimeoutId) {
+          clearTimeout(suppressDisconnectResetTimeoutId)
+        }
+
+        suppressDisconnectResetTimeoutId = setTimeout(() => {
+          suppressNextDisconnectEvent = false
+          suppressDisconnectResetTimeoutId = null
+        }, DISCONNECT_SUPPRESSION_RESET_MS)
+
+        if (reconnectTimeoutId) {
+          clearTimeout(reconnectTimeoutId)
+          reconnectTimeoutId = null
+        }
+      }
+
+      logger.debug('Disconnecting...')
+      echoInstance.disconnect()
+      echoInstance = null
+
+      const liveWindow = getBrowserWindow()
+      if (liveWindow) {
+        delete liveWindow.Echo
+      }
+    }
+
+    if (preventReconnect && !options.skipStatusUpdate) {
+      updateConnectionStatus('disconnected')
+    }
+  }
+
+  function getConnectionStatus(): ConnectionStatus {
+    const liveState = resolvePusherConnection(getBrowserWindow()?.Echo ?? null)?.state
+    if (liveState === 'connected' && connectionStatus !== 'connected') {
+      updateConnectionStatus('connected')
+    }
+
+    return connectionStatus
+  }
+
+  function onConnectionStatusChange(callback: (status: ConnectionStatus) => void): () => void {
+    connectionCallbacks.add(callback)
+
+    return () => {
+      connectionCallbacks.delete(callback)
+    }
+  }
+
+  function onEchoReconnected(callback: () => void): () => void {
+    reconnectCallbacks.add(callback)
+
+    return () => {
+      reconnectCallbacks.delete(callback)
+    }
+  }
+
+  function subscribeToPresenceStatus(callback: (event: PresenceStatusChangedEvent) => void): void {
+    const echo = getEcho()
+    if (!echo) {
+      logger.warn('Cannot subscribe to presence status, not connected')
+      return
+    }
+
+    const channelName = `online-users.${resolveTenantScope()}`
+    logger.debug(`Subscribing to ${channelName}`)
+
+    const channel = echo.join(channelName) as EchoChannelLike
+    const presenceEventNames = [
+      '.PresenceStatusChanged',
+      'PresenceStatusChanged',
+      '.presence.status.changed',
+      'presence.status.changed',
+      '.Presence.StatusChanged',
+      'Presence.StatusChanged',
+      '.Modules\\Presence\\Events\\UserPresenceStatusChanged',
+      'Modules\\Presence\\Events\\UserPresenceStatusChanged'
+    ]
+
+    for (const eventName of presenceEventNames) {
+      const validator = (rawEvent: unknown): rawEvent is UnknownRecord => isRecord(rawEvent)
+      guardedListen(channel, eventName, validator, (rawEvent) => {
+        const event = normalizePresenceStatusChangedPayload(rawEvent, resolveTenantScope)
+        if (!event) {
+          logger.warn('Dropping malformed PresenceStatusChanged event', rawEvent)
+          return
+        }
+
+        logger.debug('Presence status event received', event)
+        callback(event)
+      }, 'PresenceStatusChanged', logger)
+    }
+  }
+
+  function unsubscribeFromPresenceStatus(): void {
+    const echo = getEcho()
+    if (!echo) {
+      return
+    }
+
+    const channelName = `online-users.${resolveTenantScope()}`
+    logger.debug(`Unsubscribing from ${channelName}`)
+    echo.leave(channelName)
+  }
+
+  function subscribeToLiveCircleCount(
+    circleId: string,
+    callback: (event: LiveCircleCountUpdatedEvent) => void
+  ): () => void {
+    const echo = getEcho()
+    if (!echo) {
+      logger.warn('Cannot subscribe to live circle count, not connected')
+      return () => undefined
+    }
+
+    const channelName = `live-circle.${circleId}`
+    logger.debug(`Subscribing to ${channelName}`)
+
+    const channel = echo.private(channelName) as EchoChannelLike
+    const handler = guardedListen(
+      channel,
+      '.LiveCircleCountUpdated',
+      isValidLiveCircleCountUpdatedEvent,
+      (data) => {
+        logger.debug('Live circle count updated event received', data)
+        callback(data)
+      },
+      'LiveCircleCountUpdated',
+      logger
+    )
+
+    let cleanedUp = false
+    return () => {
+      if (cleanedUp) {
+        return
+      }
+
+      cleanedUp = true
+      const stoppableChannel = channel as EchoChannelLike & {
+        stopListening?: (event: string, callback?: (data: unknown) => void) => unknown
+      }
+
+      if (typeof stoppableChannel.stopListening !== 'function') {
+        return
+      }
+
+      stoppableChannel.stopListening('.LiveCircleCountUpdated', handler)
+    }
+  }
+
+  function subscribeToTutorialComments(
+    tutorialId: string,
+    callback: (event: TutorialCommentAddedEvent) => void
+  ): () => void {
+    const echo = getEcho() ?? initializeEcho()
+    if (!echo) {
+      logger.warn('Cannot subscribe to tutorial comments, not connected')
+      return () => undefined
+    }
+
+    const channelName = `tutorial.${tutorialId}.comments`
+    logger.debug(`Subscribing to ${channelName}`)
+
+    const channel = echo.private(channelName) as EchoChannelLike
+    const handler = guardedListen(
+      channel,
+      '.comment.added',
+      isValidTutorialCommentAddedEvent,
+      (data) => {
+        logger.debug('Tutorial comment added event received', data)
+        callback(data)
+      },
+      'comment.added',
+      logger
+    )
+
+    let cleanedUp = false
+    return () => {
+      if (cleanedUp) {
+        return
+      }
+
+      cleanedUp = true
+      const stoppableChannel = channel as EchoChannelLike & {
+        stopListening?: (event: string, callback?: (data: unknown) => void) => unknown
+      }
+
+      if (typeof stoppableChannel.stopListening !== 'function') {
+        return
+      }
+
+      stoppableChannel.stopListening('.comment.added', handler)
+    }
+  }
+
+  function subscribeToTutorialProgress(
+    tutorialId: string,
+    callback: (event: TutorialProgressUpdatedEvent) => void
+  ): () => void {
+    const echo = getEcho() ?? initializeEcho()
+    if (!echo) {
+      logger.warn('Cannot subscribe to tutorial progress, not connected')
+      return () => undefined
+    }
+
+    const channelName = `tutorial.${tutorialId}.progress`
+    logger.debug(`Subscribing to ${channelName}`)
+
+    const channel = echo.private(channelName) as EchoChannelLike
+    channel.listen('pusher:subscription_error', (error: unknown) => {
+      logger.warn(`Channel subscription failed for ${channelName}`, error)
+    })
+
+    const handler = guardedListen(
+      channel,
+      '.progress.updated',
+      isValidTutorialProgressUpdatedEvent,
+      (data) => {
+        logger.debug('Tutorial progress updated event received', data)
+        callback(data)
+      },
+      'progress.updated',
+      logger
+    )
+
+    let cleanedUp = false
+    return () => {
+      if (cleanedUp) {
+        return
+      }
+
+      cleanedUp = true
+      const stoppableChannel = channel as EchoChannelLike & {
+        stopListening?: (event: string, callback?: (data: unknown) => void) => unknown
+      }
+
+      if (typeof stoppableChannel.stopListening !== 'function') {
+        return
+      }
+
+      stoppableChannel.stopListening('.progress.updated', handler)
+    }
+  }
+
+  function subscribeToProfileUpdates(userId: string, callbacks: ProfileUpdatesCallbacks): void {
+    const echo = getEcho()
+    if (!echo) {
+      logger.warn('Cannot subscribe to profile updates, not connected')
+      return
+    }
+
+    const channelName = `profiles.${userId}`
+    logger.debug(`Subscribing to ${channelName}`)
+
+    const channel = echo.private(channelName) as EchoChannelLike
+
+    if (callbacks.onStatsUpdated) {
+      const onStatsUpdated = callbacks.onStatsUpdated
+      guardedListen(
+        channel,
+        '.Profiles.StatsUpdated',
+        isValidProfileStatsUpdatedEvent,
+        (data) => {
+          logger.debug('Profile stats updated event received', data)
+          onStatsUpdated(data)
+        },
+        'Profiles.StatsUpdated',
+        logger
+      )
+    }
+
+    if (callbacks.onActivityCreated) {
+      const onActivityCreated = callbacks.onActivityCreated
+      guardedListen(
+        channel,
+        '.Profiles.ActivityCreated',
+        isValidProfileActivityCreatedEvent,
+        (data) => {
+          logger.debug('Profile activity created event received', data)
+          onActivityCreated(data)
+        },
+        'Profiles.ActivityCreated',
+        logger
+      )
+    }
+  }
+
+  function unsubscribeFromProfileUpdates(userId: string): void {
+    const echo = getEcho()
+    if (!echo) {
+      return
+    }
+
+    const channelName = `profiles.${userId}`
+    logger.debug(`Unsubscribing from ${channelName}`)
+    echo.leave(channelName)
+  }
+
+  function subscribeToStoryTray(callbacks: StoryTrayCallbacks): boolean {
+    const echo = getEcho() ?? initializeEcho()
+    if (!echo) {
+      logger.warn('Cannot subscribe to story tray channel, not connected')
+      return false
+    }
+
+    const channelName = `story-tray.${resolveTenantScope()}`
+    logger.debug(`Subscribing to ${channelName}`)
+
+    const channel = echo.private(channelName) as EchoChannelLike
+
+    if (callbacks.onStoryTrayUpdated) {
+      const onStoryTrayUpdated = callbacks.onStoryTrayUpdated
+      guardedListen(
+        channel,
+        '.StoryTrayUpdated',
+        isValidStoryTrayUpdatedEvent,
+        (data) => {
+          logger.debug('Story tray updated event received', data)
+          onStoryTrayUpdated(data)
+        },
+        'StoryTrayUpdated',
+        logger
+      )
+    }
+
+    return true
+  }
+
+  function unsubscribeFromStoryTray(): void {
+    const echo = getEcho()
+    if (!echo) {
+      return
+    }
+
+    const channelName = `story-tray.${resolveTenantScope()}`
+    logger.debug(`Unsubscribing from ${channelName}`)
+    echo.leave(channelName)
+  }
+
+  function reconnectEcho(options: EchoReconnectOptions = {}): void {
+    if (options.resetBackoff) {
+      reconnectAttempts = 0
+    }
+
+    if (reconnectTimeoutId) {
+      clearTimeout(reconnectTimeoutId)
+      reconnectTimeoutId = null
+    }
+
+    updateConnectionStatus('connecting')
+
+    if (echoInstance) {
+      logger.debug('Disconnecting before reconnect')
+      disconnectEcho({ preventReconnect: true, skipStatusUpdate: true })
+    }
+
+    try {
+      echoInstance = initializeEcho()
+      if (!echoInstance) {
+        logger.error('Reconnect failed: initializeEcho returned null')
+        updateConnectionStatus('error')
+        scheduleReconnect()
+      }
+    } catch (error) {
+      logger.error('Reconnect failed', error)
+      updateConnectionStatus('error')
+      scheduleReconnect()
+    }
+  }
+
+  return {
+    initializeEcho,
+    getEcho,
+    disconnectEcho,
+    reconnectEcho,
+    getConnectionStatus,
+    onConnectionStatusChange,
+    onEchoReconnected,
+    subscribeToPresenceStatus,
+    unsubscribeFromPresenceStatus,
+    subscribeToLiveCircleCount,
+    subscribeToTutorialComments,
+    subscribeToTutorialProgress,
+    subscribeToProfileUpdates,
+    unsubscribeFromProfileUpdates,
+    subscribeToStoryTray,
+    unsubscribeFromStoryTray
+  }
+}