qdadm 0.29.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -22,6 +22,7 @@
     ".": "./src/index.js",
     "./composables": "./src/composables/index.js",
     "./components": "./src/components/index.js",
+    "./editors": "./src/editors/index.js",
     "./module": "./src/module/index.js",
     "./utils": "./src/utils/index.js",
     "./styles": "./src/styles/index.scss",
@@ -40,10 +41,17 @@
   "peerDependencies": {
     "pinia": "^2.0.0",
     "primevue": "^4.0.0",
-    "vanilla-jsoneditor": "^0.23.0",
     "vue": "^3.3.0",
     "vue-router": "^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "vanilla-jsoneditor": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "vanilla-jsoneditor": "^0.23.0"
+  },
   "keywords": [
     "vue",
     "vue3",

package/src/components/index.js

@@ -32,15 +32,17 @@ export { default as ActionButtons } from './lists/ActionButtons.vue'
 export { default as ActionColumn } from './lists/ActionColumn.vue'
 export { default as FilterBar } from './lists/FilterBar.vue'
 
-// Editors
+// Editors (vanilla-jsoneditor free)
 export { default as KeyValueEditor } from './editors/KeyValueEditor.vue'
 export { default as LanguageEditor } from './editors/LanguageEditor.vue'
 export { default as ScopeEditor } from './editors/ScopeEditor.vue'
-export { default as VanillaJsonEditor } from './editors/VanillaJsonEditor.vue'
 export { default as JsonEditorFoldable } from './editors/JsonEditorFoldable.vue'
-export { default as JsonStructuredField } from './editors/JsonStructuredField.vue'
 export { default as JsonViewer } from './editors/JsonViewer.vue'
 
+// NOTE: VanillaJsonEditor and JsonStructuredField require vanilla-jsoneditor
+// Import from 'qdadm/editors' instead:
+// import { VanillaJsonEditor, JsonStructuredField } from 'qdadm/editors'
+
 // Dialogs
 export { default as SimpleDialog } from './dialogs/SimpleDialog.vue'
 export { default as MultiStepDialog } from './dialogs/MultiStepDialog.vue'

package/src/composables/index.js

@@ -20,5 +20,5 @@ export { useSignals } from './useSignals'
 export { useZoneRegistry } from './useZoneRegistry'
 export { useHooks } from './useHooks'
 export { useLayoutResolver, createLayoutComponents, layoutMeta, LAYOUT_TYPES } from './useLayoutResolver'
-export { useSSE } from './useSSE'
+export { useSSEBridge } from './useSSEBridge'
 export { useDeferred, useDeferredValue, DEFERRED_INJECTION_KEY } from './useDeferred'

package/src/composables/useSSEBridge.js

@@ -0,0 +1,118 @@
+/**
+ * useSSEBridge - Composable for SSE connection status
+ *
+ * Provides reactive connection status for SSEBridge.
+ * Components use this instead of managing their own EventSource.
+ *
+ * Usage:
+ * ```js
+ * const { connected, reconnecting, error, onEvent } = useSSEBridge()
+ *
+ * // Reactive connection status
+ * watchEffect(() => {
+ *   if (connected.value) {
+ *     console.log('SSE connected')
+ *   }
+ * })
+ *
+ * // Subscribe to specific event (auto-cleanup on unmount)
+ * onEvent('task:completed', (payload) => {
+ *   console.log('Task completed:', payload.data)
+ * })
+ * ```
+ */
+
+import { ref, inject, onUnmounted, onMounted } from 'vue'
+import { SSE_SIGNALS } from '../kernel/SSEBridge.js'
+
+/**
+ * @typedef {object} UseSSEBridgeReturn
+ * @property {import('vue').Ref<boolean>} connected - Connection status
+ * @property {import('vue').Ref<boolean>} reconnecting - Reconnection in progress
+ * @property {import('vue').Ref<string|null>} error - Last error message
+ * @property {function} onEvent - Subscribe to SSE event (auto-cleanup)
+ * @property {function} onAnyEvent - Subscribe to all SSE events (wildcard)
+ */
+
+/**
+ * Composable for SSEBridge connection status
+ * @returns {UseSSEBridgeReturn}
+ */
+export function useSSEBridge() {
+  const signals = inject('qdadmSignals')
+  const sseBridge = inject('qdadmSSEBridge', null)
+
+  const connected = ref(sseBridge?.isConnected() ?? false)
+  const reconnecting = ref(sseBridge?.isReconnecting() ?? false)
+  const error = ref(null)
+
+  const unbinders = []
+
+  // Track connection status via signals
+  if (signals) {
+    const unbindConnected = signals.on(SSE_SIGNALS.CONNECTED, () => {
+      connected.value = true
+      reconnecting.value = false
+      error.value = null
+    })
+    unbinders.push(unbindConnected)
+
+    const unbindDisconnected = signals.on(SSE_SIGNALS.DISCONNECTED, () => {
+      connected.value = false
+    })
+    unbinders.push(unbindDisconnected)
+
+    const unbindError = signals.on(SSE_SIGNALS.ERROR, (payload) => {
+      error.value = payload.error
+      reconnecting.value = true
+    })
+    unbinders.push(unbindError)
+  }
+
+  /**
+   * Subscribe to a specific SSE event
+   * Automatically cleans up on component unmount.
+   *
+   * @param {string} eventName - SSE event name (without 'sse:' prefix)
+   * @param {function} handler - Event handler (payload) => void
+   * @returns {function} Unbind function
+   */
+  const onEvent = (eventName, handler) => {
+    if (!signals) return () => {}
+
+    const signal = `sse:${eventName}`
+    const unbind = signals.on(signal, handler)
+    unbinders.push(unbind)
+
+    return unbind
+  }
+
+  /**
+   * Subscribe to all SSE events (wildcard)
+   * Automatically cleans up on component unmount.
+   *
+   * @param {function} handler - Event handler (payload) => void
+   * @returns {function} Unbind function
+   */
+  const onAnyEvent = (handler) => {
+    if (!signals) return () => {}
+
+    const unbind = signals.on('sse:*', handler)
+    unbinders.push(unbind)
+
+    return unbind
+  }
+
+  // Cleanup on unmount
+  onUnmounted(() => {
+    unbinders.forEach(unbind => unbind())
+  })
+
+  return {
+    connected,
+    reconnecting,
+    error,
+    onEvent,
+    onAnyEvent
+  }
+}

package/src/editors/index.js

@@ -0,0 +1,12 @@
+/**
+ * qdadm/editors - Optional editors that require vanilla-jsoneditor
+ *
+ * Import from 'qdadm/editors' only if you need VanillaJsonEditor.
+ * This keeps vanilla-jsoneditor out of the main bundle.
+ *
+ * Usage:
+ * import { VanillaJsonEditor, JsonStructuredField } from 'qdadm/editors'
+ */
+
+export { default as VanillaJsonEditor } from '../components/editors/VanillaJsonEditor.vue'
+export { default as JsonStructuredField } from '../components/editors/JsonStructuredField.vue'

package/src/gen/index.js

@@ -31,6 +31,9 @@ export { BaseConnector } from './connectors/index.js'
 // T00313: ManualConnector - Inline entity/field definitions
 export { ManualConnector } from './connectors/index.js'
 
+// OpenAPIConnector - Parse OpenAPI 3.x specifications
+export { OpenAPIConnector } from './connectors/index.js'
+
 // T00316: StorageProfileFactory - Type definitions for storage profile pattern
 // JSDoc types available when importing this module (no runtime exports)
 import './StorageProfileFactory.js'

package/src/kernel/Kernel.js

@@ -56,6 +56,7 @@ import { createManagers } from '../entity/factory.js'
 import { defaultStorageResolver } from '../entity/storage/factory.js'
 import { createDeferredRegistry } from '../deferred/DeferredRegistry.js'
 import { createEventRouter } from './EventRouter.js'
+import { createSSEBridge } from './SSEBridge.js'
 
 export class Kernel {
   /**
@@ -82,6 +83,7 @@ export class Kernel {
    * @param {object} options.security - Security config { role_hierarchy, role_permissions, entity_permissions }
    * @param {boolean} options.warmup - Enable warmup at boot (default: true)
    * @param {object} options.eventRouter - EventRouter config { 'source:signal': ['target:signal', ...] }
+   * @param {object} options.sse - SSEBridge config { url, reconnectDelay, signalPrefix, autoConnect, events }
    */
   constructor(options) {
     this.options = options
@@ -93,6 +95,7 @@ export class Kernel {
     this.hookRegistry = null
     this.deferred = null
     this.eventRouter = null
+    this.sseBridge = null
     this.layoutComponents = null
     this.securityChecker = null
   }
@@ -113,15 +116,19 @@ export class Kernel {
     this._initModules()
     // 4. Create router (needs routes from modules)
     this._createRouter()
-    // 5. Create orchestrator and remaining components
+    // 5. Setup auth:expired handler (needs router + authAdapter)
+    this._setupAuthExpiredHandler()
+    // 6. Create orchestrator and remaining components
     this._createOrchestrator()
-    // 6. Create EventRouter (needs signals + orchestrator)
+    // 7. Create EventRouter (needs signals + orchestrator)
     this._createEventRouter()
+    // 8. Create SSEBridge (needs signals + authAdapter for token)
+    this._createSSEBridge()
     this._setupSecurity()
     this._createLayoutComponents()
     this._createVueApp()
     this._installPlugins()
-    // 6. Fire warmups (fire-and-forget, pages await via DeferredRegistry)
+    // 9. Fire warmups (fire-and-forget, pages await via DeferredRegistry)
     this._fireWarmups()
     return this.vueApp
   }
@@ -144,6 +151,58 @@ export class Kernel {
     })
   }
 
+  /**
+   * Setup handler for auth:expired signal
+   *
+   * When auth:expired is emitted (e.g., from API 401/403 response),
+   * this handler:
+   * 1. Calls authAdapter.logout() to clear tokens
+   * 2. Redirects to login page
+   * 3. Optionally calls onAuthExpired callback
+   *
+   * To emit auth:expired from your API client:
+   * ```js
+   * axios.interceptors.response.use(
+   *   response => response,
+   *   error => {
+   *     if (error.response?.status === 401 || error.response?.status === 403) {
+   *       signals.emit('auth:expired', { status: error.response.status })
+   *     }
+   *     return Promise.reject(error)
+   *   }
+   * )
+   * ```
+   */
+  _setupAuthExpiredHandler() {
+    const { authAdapter, onAuthExpired } = this.options
+    if (!authAdapter) return
+
+    this.signals.on('auth:expired', async (payload) => {
+      const debug = this.options.debug ?? false
+      if (debug) {
+        console.warn('[Kernel] auth:expired received:', payload)
+      }
+
+      // 1. Logout (clear tokens)
+      if (authAdapter.logout) {
+        authAdapter.logout()
+      }
+
+      // 2. Emit auth:logout signal
+      await this.signals.emit('auth:logout', { reason: 'expired', ...payload })
+
+      // 3. Redirect to login (if not already there)
+      if (this.router.currentRoute.value.name !== 'login') {
+        this.router.push({ name: 'login', query: { expired: '1' } })
+      }
+
+      // 4. Optional callback
+      if (onAuthExpired) {
+        onAuthExpired(payload)
+      }
+    })
+  }
+
   /**
    * Fire entity cache warmups
    * Fire-and-forget: pages that need cache will await via DeferredRegistry.
@@ -368,6 +427,52 @@ export class Kernel {
     })
   }
 
+  /**
+   * Create SSEBridge for Server-Sent Events to SignalBus integration
+   *
+   * SSE config:
+   * ```js
+   * sse: {
+   *   url: '/api/events',       // SSE endpoint
+   *   reconnectDelay: 5000,     // Reconnect delay (ms), 0 to disable
+   *   signalPrefix: 'sse',      // Signal prefix (default: 'sse')
+   *   autoConnect: false,       // Connect immediately vs wait for auth:login
+   *   events: ['task:completed', 'bot:status']  // Event names to register
+   * }
+   * ```
+   */
+  _createSSEBridge() {
+    const { sse, authAdapter } = this.options
+    if (!sse?.url) return
+
+    const debug = this.options.debug ?? false
+
+    // Build getToken from authAdapter
+    const getToken = authAdapter?.getToken
+      ? () => authAdapter.getToken()
+      : () => localStorage.getItem('auth_token')
+
+    this.sseBridge = createSSEBridge({
+      signals: this.signals,
+      url: sse.url,
+      reconnectDelay: sse.reconnectDelay ?? 5000,
+      signalPrefix: sse.signalPrefix ?? 'sse',
+      autoConnect: sse.autoConnect ?? false,
+      withCredentials: sse.withCredentials ?? false,
+      tokenParam: sse.tokenParam ?? 'token',
+      getToken,
+      debug
+    })
+
+    // Register known event names if provided
+    if (sse.events?.length) {
+      // Wait for connection before registering
+      this.signals.once('sse:connected').then(() => {
+        this.sseBridge.registerEvents(sse.events)
+      })
+    }
+  }
+
   /**
    * Create layout components map for useLayoutResolver
    * Maps layout types to their Vue components.
@@ -438,6 +543,11 @@ export class Kernel {
     // Signal bus injection
     app.provide('qdadmSignals', this.signals)
 
+    // SSEBridge injection (if configured)
+    if (this.sseBridge) {
+      app.provide('qdadmSSEBridge', this.sseBridge)
+    }
+
     // Hook registry injection
     app.provide('qdadmHooks', this.hookRegistry)
 
@@ -538,6 +648,22 @@ export class Kernel {
     return this.eventRouter
   }
 
+  /**
+   * Get the SSEBridge instance
+   * @returns {import('./SSEBridge.js').SSEBridge|null}
+   */
+  getSSEBridge() {
+    return this.sseBridge
+  }
+
+  /**
+   * Shorthand accessor for SSE bridge
+   * @returns {import('./SSEBridge.js').SSEBridge|null}
+   */
+  get sse() {
+    return this.sseBridge
+  }
+
   /**
    * Get the layout components map
    * @returns {object} Layout components by type
@@ -570,4 +696,103 @@ export class Kernel {
   get security() {
     return this.securityChecker
   }
+
+  /**
+   * Setup an axios client with automatic auth and error handling
+   *
+   * Adds interceptors that:
+   * - Add Authorization header with token from authAdapter
+   * - Emit auth:expired on 401/403 responses (triggers auto-logout)
+   * - Emit api:error on all errors for centralized handling
+   *
+   * Usage:
+   * ```js
+   * import axios from 'axios'
+   *
+   * const apiClient = axios.create({ baseURL: '/api' })
+   * kernel.setupApiClient(apiClient)
+   *
+   * // Now 401/403 errors automatically trigger logout
+   * const storage = new ApiStorage({ endpoint: '/users', client: apiClient })
+   * ```
+   *
+   * Or let Kernel create the client:
+   * ```js
+   * const kernel = new Kernel({
+   *   ...options,
+   *   apiClient: { baseURL: '/api' }  // axios.create() options
+   * })
+   * const apiClient = kernel.getApiClient()
+   * ```
+   *
+   * @param {object} client - Axios instance to configure
+   * @returns {object} The configured axios instance
+   */
+  setupApiClient(client) {
+    const { authAdapter } = this.options
+    const signals = this.signals
+    const debug = this.options.debug ?? false
+
+    // Request interceptor: add Authorization header
+    client.interceptors.request.use(
+      (config) => {
+        if (authAdapter?.getToken) {
+          const token = authAdapter.getToken()
+          if (token) {
+            config.headers = config.headers || {}
+            config.headers.Authorization = `Bearer ${token}`
+          }
+        }
+        return config
+      },
+      (error) => Promise.reject(error)
+    )
+
+    // Response interceptor: handle auth errors
+    client.interceptors.response.use(
+      (response) => response,
+      async (error) => {
+        const status = error.response?.status
+        const url = error.config?.url
+
+        // Emit api:error for all errors
+        await signals.emit('api:error', {
+          status,
+          message: error.message,
+          url,
+          error
+        })
+
+        // Emit auth:expired for 401/403
+        if (status === 401 || status === 403) {
+          if (debug) {
+            console.warn(`[Kernel] API ${status} error on ${url}, emitting auth:expired`)
+          }
+          await signals.emit('auth:expired', { status, url })
+        }
+
+        return Promise.reject(error)
+      }
+    )
+
+    // Store reference
+    this._apiClient = client
+    return client
+  }
+
+  /**
+   * Get the configured API client
+   * @returns {object|null} Axios instance or null if not configured
+   */
+  getApiClient() {
+    return this._apiClient
+  }
+
+  /**
+   * Shorthand accessor for API client
+   * @returns {object|null}
+   */
+  get api() {
+    return this._apiClient
+  }
 }

package/src/kernel/SSEBridge.js

@@ -0,0 +1,354 @@
+/**
+ * SSEBridge - Server-Sent Events to SignalBus bridge
+ *
+ * Manages a single SSE connection and emits all events to SignalBus.
+ * Components subscribe via signals.on('sse:eventName', handler) instead of
+ * managing their own EventSource connections.
+ *
+ * Benefits:
+ * - Single SSE connection per app (vs. one per component)
+ * - Decoupled event handling via SignalBus
+ * - Automatic reconnection with configurable delay
+ * - Connection status available via signals
+ *
+ * Signal naming:
+ * - `sse:connected` - Emitted when connection established
+ * - `sse:disconnected` - Emitted when connection lost
+ * - `sse:error` - Emitted on connection error
+ * - `sse:{eventName}` - SSE event forwarded (e.g., sse:task:completed)
+ *
+ * Usage in Kernel:
+ * ```js
+ * new Kernel({
+ *   sse: {
+ *     url: '/api/events',
+ *     reconnectDelay: 5000,
+ *     signalPrefix: 'sse',
+ *     autoConnect: true
+ *   }
+ * })
+ * ```
+ *
+ * Usage in components:
+ * ```js
+ * const signals = inject('qdadmSignals')
+ *
+ * // Subscribe to specific SSE events
+ * signals.on('sse:task:completed', ({ data }) => {
+ *   console.log('Task completed:', data)
+ * })
+ *
+ * // Subscribe to all SSE events via wildcard
+ * signals.on('sse:*', ({ event, data }) => {
+ *   console.log(`SSE event ${event}:`, data)
+ * })
+ * ```
+ */
+
+export const SSE_SIGNALS = {
+  CONNECTED: 'sse:connected',
+  DISCONNECTED: 'sse:disconnected',
+  ERROR: 'sse:error',
+  MESSAGE: 'sse:message'
+}
+
+export class SSEBridge {
+  /**
+   * @param {object} options
+   * @param {SignalBus} options.signals - SignalBus instance
+   * @param {string} options.url - SSE endpoint URL
+   * @param {number} options.reconnectDelay - Delay before reconnect (ms), 0 to disable
+   * @param {string} options.signalPrefix - Prefix for emitted signals (default: 'sse')
+   * @param {boolean} options.autoConnect - Connect immediately (default: false, waits for auth:login)
+   * @param {boolean} options.withCredentials - Include credentials in request
+   * @param {string} options.tokenParam - Query param name for auth token
+   * @param {function} options.getToken - Function to get auth token
+   * @param {boolean} options.debug - Enable debug logging
+   */
+  constructor(options) {
+    const {
+      signals,
+      url,
+      reconnectDelay = 5000,
+      signalPrefix = 'sse',
+      autoConnect = false,
+      withCredentials = false,
+      tokenParam = 'token',
+      getToken = null,
+      debug = false
+    } = options
+
+    if (!signals) {
+      throw new Error('[SSEBridge] signals (SignalBus) is required')
+    }
+    if (!url) {
+      throw new Error('[SSEBridge] url is required')
+    }
+
+    this._signals = signals
+    this._url = url
+    this._reconnectDelay = reconnectDelay
+    this._signalPrefix = signalPrefix
+    this._withCredentials = withCredentials
+    this._tokenParam = tokenParam
+    this._getToken = getToken
+    this._debug = debug
+
+    this._eventSource = null
+    this._reconnectTimer = null
+    this._connected = false
+    this._reconnecting = false
+
+    // Auto-connect or wait for auth:login
+    if (autoConnect) {
+      this.connect()
+    } else {
+      // Wait for auth:login signal to connect
+      this._signals.once('auth:login').then(() => {
+        this._log('Received auth:login, connecting SSE')
+        this.connect()
+      })
+    }
+
+    // Disconnect on auth:logout
+    this._signals.on('auth:logout', () => {
+      this._log('Received auth:logout, disconnecting SSE')
+      this.disconnect()
+    })
+  }
+
+  /**
+   * Build signal name with prefix
+   * @param {string} eventName - Event name
+   * @returns {string} Full signal name
+   */
+  _buildSignal(eventName) {
+    return `${this._signalPrefix}:${eventName}`
+  }
+
+  /**
+   * Debug logging
+   */
+  _log(...args) {
+    if (this._debug) {
+      console.debug('[SSEBridge]', ...args)
+    }
+  }
+
+  /**
+   * Build SSE URL with auth token
+   * @returns {string}
+   */
+  _buildUrl() {
+    const token = this._getToken?.()
+    const sseUrl = new URL(this._url, window.location.origin)
+
+    if (token && this._tokenParam) {
+      sseUrl.searchParams.set(this._tokenParam, token)
+    }
+
+    return sseUrl.toString()
+  }
+
+  /**
+   * Connect to SSE endpoint
+   */
+  connect() {
+    // Clean up existing
+    if (this._eventSource) {
+      this._eventSource.close()
+      this._eventSource = null
+    }
+
+    // Clear pending reconnect
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+
+    try {
+      const url = this._buildUrl()
+      this._log('Connecting to', url)
+
+      this._eventSource = new EventSource(url, {
+        withCredentials: this._withCredentials
+      })
+
+      this._eventSource.onopen = () => {
+        this._connected = true
+        this._reconnecting = false
+        this._log('Connected')
+
+        this._signals.emit(SSE_SIGNALS.CONNECTED, {
+          url: this._url,
+          timestamp: new Date()
+        })
+      }
+
+      this._eventSource.onerror = (err) => {
+        this._connected = false
+        this._log('Connection error')
+
+        this._signals.emit(SSE_SIGNALS.ERROR, {
+          error: 'Connection error',
+          timestamp: new Date()
+        })
+
+        // Close broken connection
+        if (this._eventSource) {
+          this._eventSource.close()
+          this._eventSource = null
+        }
+
+        this._signals.emit(SSE_SIGNALS.DISCONNECTED, {
+          timestamp: new Date()
+        })
+
+        // Schedule reconnect
+        this._scheduleReconnect()
+      }
+
+      // Handle generic message events (event: message)
+      this._eventSource.onmessage = (event) => {
+        this._handleEvent('message', event)
+      }
+
+      // For named events, we need to add listeners dynamically
+      // Since EventSource doesn't expose event names, we use a wrapper approach:
+      // The server should send events with `event:` field, we handle them generically
+
+      // Note: Named events require explicit addEventListener.
+      // To support arbitrary event names, the app should either:
+      // 1. Use `message` event type and include event name in data
+      // 2. Pre-register known event names via registerEvents()
+
+    } catch (err) {
+      this._log('Connect error:', err.message)
+      this._signals.emit(SSE_SIGNALS.ERROR, {
+        error: err.message,
+        timestamp: new Date()
+      })
+      this._scheduleReconnect()
+    }
+  }
+
+  /**
+   * Register listeners for specific SSE event types
+   * Required because EventSource requires explicit addEventListener for named events.
+   *
+   * @param {string[]} eventNames - Event names to listen for
+   */
+  registerEvents(eventNames) {
+    if (!this._eventSource) {
+      this._log('Cannot register events: not connected')
+      return
+    }
+
+    for (const eventName of eventNames) {
+      this._eventSource.addEventListener(eventName, (event) => {
+        this._handleEvent(eventName, event)
+      })
+      this._log('Registered event:', eventName)
+    }
+  }
+
+  /**
+   * Handle incoming SSE event
+   * @param {string} eventName - Event name
+   * @param {MessageEvent} event - SSE event
+   */
+  _handleEvent(eventName, event) {
+    let data
+    try {
+      data = JSON.parse(event.data)
+    } catch {
+      data = event.data
+    }
+
+    const signal = this._buildSignal(eventName)
+    this._log(`Emitting ${signal}:`, data)
+
+    this._signals.emit(signal, {
+      event: eventName,
+      data,
+      timestamp: new Date(),
+      lastEventId: event.lastEventId
+    })
+  }
+
+  /**
+   * Schedule reconnection
+   */
+  _scheduleReconnect() {
+    if (this._reconnectDelay <= 0) return
+    if (this._reconnectTimer) return
+
+    this._reconnecting = true
+    this._log(`Reconnecting in ${this._reconnectDelay}ms`)
+
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null
+      if (!this._connected) {
+        this.connect()
+      }
+    }, this._reconnectDelay)
+  }
+
+  /**
+   * Disconnect from SSE endpoint
+   */
+  disconnect() {
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer)
+      this._reconnectTimer = null
+    }
+
+    if (this._eventSource) {
+      this._eventSource.close()
+      this._eventSource = null
+    }
+
+    if (this._connected) {
+      this._connected = false
+      this._signals.emit(SSE_SIGNALS.DISCONNECTED, {
+        timestamp: new Date()
+      })
+    }
+
+    this._reconnecting = false
+    this._log('Disconnected')
+  }
+
+  /**
+   * Reconnect (disconnect + connect)
+   */
+  reconnect() {
+    this.disconnect()
+    this.connect()
+  }
+
+  /**
+   * Check if connected
+   * @returns {boolean}
+   */
+  isConnected() {
+    return this._connected
+  }
+
+  /**
+   * Check if reconnecting
+   * @returns {boolean}
+   */
+  isReconnecting() {
+    return this._reconnecting
+  }
+}
+
+/**
+ * Factory function to create SSEBridge
+ * @param {object} options - SSEBridge options
+ * @returns {SSEBridge}
+ */
+export function createSSEBridge(options) {
+  return new SSEBridge(options)
+}

package/src/kernel/SignalBus.js

@@ -25,6 +25,14 @@ export const SIGNALS = {
   ENTITY_UPDATED: 'entity:updated',
   ENTITY_DELETED: 'entity:deleted',
 
+  // Auth lifecycle signals
+  AUTH_LOGIN: 'auth:login',
+  AUTH_LOGOUT: 'auth:logout',
+  AUTH_EXPIRED: 'auth:expired',  // Emitted on 401/403 API responses
+
+  // API error signals
+  API_ERROR: 'api:error',  // Emitted on any API error { status, message, url }
+
   // Pattern for entity-specific signals
   // Use buildSignal(entityName, action) for these
 }

package/src/kernel/index.js

@@ -16,3 +16,8 @@ export {
   EventRouter,
   createEventRouter,
 } from './EventRouter.js'
+export {
+  SSEBridge,
+  createSSEBridge,
+  SSE_SIGNALS,
+} from './SSEBridge.js'

package/src/composables/useSSE.js

@@ -1,212 +0,0 @@
-/**
- * useSSE - Server-Sent Events composable
- *
- * Manages EventSource connection with automatic reconnection and cleanup.
- * Uses authAdapter.getToken() for authentication if available.
- *
- * Usage:
- *   const { connected, error, reconnect, close } = useSSE('/api/events', {
- *     eventHandlers: {
- *       'bot:status': (data) => console.log('Bot status:', data),
- *       'task:complete': (data) => handleTaskComplete(data)
- *     }
- *   })
- *
- * Options:
- *   - eventHandlers: Object mapping event names to handler functions
- *   - reconnectDelay: Delay in ms before reconnecting (default: 5000)
- *   - autoConnect: Start connection immediately (default: true)
- *   - withCredentials: Include credentials in request (default: false)
- *   - tokenParam: Query param name for token (default: 'token')
- *   - getToken: Custom token getter function (default: uses authAdapter)
- */
-
-import { ref, inject, onUnmounted, onMounted } from 'vue'
-
-export function useSSE(url, options = {}) {
-  const {
-    eventHandlers = {},
-    reconnectDelay = 5000,
-    autoConnect = true,
-    withCredentials = false,
-    tokenParam = 'token',
-    getToken: customGetToken = null
-  } = options
-
-  const authAdapter = inject('authAdapter', null)
-
-  const connected = ref(false)
-  const error = ref(null)
-  const reconnecting = ref(false)
-
-  let eventSource = null
-  let reconnectTimer = null
-
-  /**
-   * Get authentication token
-   */
-  const getToken = () => {
-    // Custom getter takes precedence
-    if (customGetToken) {
-      return customGetToken()
-    }
-    // Try authAdapter
-    if (authAdapter?.getToken) {
-      return authAdapter.getToken()
-    }
-    // Fallback to localStorage
-    return localStorage.getItem('auth_token')
-  }
-
-  /**
-   * Build SSE URL with token
-   */
-  const buildUrl = () => {
-    const token = getToken()
-    const sseUrl = new URL(url, window.location.origin)
-
-    if (token && tokenParam) {
-      sseUrl.searchParams.set(tokenParam, token)
-    }
-
-    return sseUrl.toString()
-  }
-
-  /**
-   * Connect to SSE endpoint
-   */
-  const connect = () => {
-    // Clean up existing connection
-    if (eventSource) {
-      eventSource.close()
-      eventSource = null
-    }
-
-    // Clear any pending reconnect
-    if (reconnectTimer) {
-      clearTimeout(reconnectTimer)
-      reconnectTimer = null
-    }
-
-    try {
-      const sseUrl = buildUrl()
-
-      eventSource = new EventSource(sseUrl, {
-        withCredentials
-      })
-
-      eventSource.onopen = () => {
-        connected.value = true
-        error.value = null
-        reconnecting.value = false
-      }
-
-      eventSource.onerror = (err) => {
-        connected.value = false
-        error.value = 'Connection error'
-
-        // Close broken connection
-        if (eventSource) {
-          eventSource.close()
-          eventSource = null
-        }
-
-        // Schedule reconnect
-        if (reconnectDelay > 0) {
-          reconnecting.value = true
-          reconnectTimer = setTimeout(() => {
-            if (!connected.value) {
-              connect()
-            }
-          }, reconnectDelay)
-        }
-      }
-
-      // Register custom event handlers
-      for (const [eventName, handler] of Object.entries(eventHandlers)) {
-        if (eventName === 'message') continue // Handle below
-
-        eventSource.addEventListener(eventName, (event) => {
-          try {
-            const data = JSON.parse(event.data)
-            handler(data, event)
-          } catch (err) {
-            console.error(`[useSSE] Error parsing event "${eventName}":`, err)
-            // Call handler with raw data on parse error
-            handler(event.data, event)
-          }
-        })
-      }
-
-      // Handle generic message events
-      eventSource.onmessage = (event) => {
-        if (!eventHandlers.message) return
-
-        try {
-          const data = JSON.parse(event.data)
-          eventHandlers.message(data, event)
-        } catch (err) {
-          console.error('[useSSE] Error parsing message:', err)
-          eventHandlers.message(event.data, event)
-        }
-      }
-
-    } catch (err) {
-      error.value = err.message
-      connected.value = false
-    }
-  }
-
-  /**
-   * Close connection
-   */
-  const close = () => {
-    if (reconnectTimer) {
-      clearTimeout(reconnectTimer)
-      reconnectTimer = null
-    }
-
-    if (eventSource) {
-      eventSource.close()
-      eventSource = null
-    }
-
-    connected.value = false
-    reconnecting.value = false
-  }
-
-  /**
-   * Reconnect (close and connect)
-   */
-  const reconnect = () => {
-    close()
-    connect()
-  }
-
-  // Auto-connect on mount if enabled
-  onMounted(() => {
-    if (autoConnect) {
-      connect()
-    }
-  })
-
-  // Cleanup on unmount
-  onUnmounted(() => {
-    close()
-  })
-
-  return {
-    /** Reactive connection state */
-    connected,
-    /** Reactive error message */
-    error,
-    /** Reactive reconnecting state */
-    reconnecting,
-    /** Manually connect */
-    connect,
-    /** Close connection */
-    close,
-    /** Reconnect (close + connect) */
-    reconnect
-  }
-}