qdadm 0.28.0 → 0.30.0

package/src/gen/schema.js

@@ -0,0 +1,221 @@
+/**
+ * Unified Schema Types
+ *
+ * Core contracts that abstract differences between OpenAPI, Pydantic, and manual schema sources.
+ * These types provide a common format for entity and field definitions that can be used
+ * by connectors (schema sources) and generators (code output).
+ *
+ * @module gen/schema
+ */
+
+/**
+ * Field Type Enumeration
+ *
+ * Unified field types that abstract source-specific types (OpenAPI string/integer,
+ * Pydantic str/int, etc.) into a common set.
+ *
+ * @typedef {'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'email' | 'url' | 'uuid' | 'array' | 'object'} UnifiedFieldType
+ */
+
+/**
+ * Reference Definition
+ *
+ * Describes a relation to another entity for foreign key fields.
+ *
+ * @typedef {object} UnifiedFieldReference
+ * @property {string} entity - Target entity name (e.g., 'users', 'categories')
+ * @property {string} [labelField] - Field to display as label (e.g., 'name', 'title')
+ */
+
+/**
+ * Unified Field Schema
+ *
+ * Common field definition that abstracts OpenAPI property, Pydantic field, or manual definition.
+ * Connectors transform their source-specific formats into this common shape.
+ *
+ * @typedef {object} UnifiedFieldSchema
+ * @property {string} name - Field name (e.g., 'email', 'created_at')
+ * @property {UnifiedFieldType} type - Unified field type
+ * @property {string} [label] - Human-readable label (e.g., 'Email Address')
+ * @property {boolean} [required] - Whether field is required (default: false)
+ * @property {boolean} [readOnly] - Whether field is read-only (default: false)
+ * @property {boolean} [hidden] - Whether field should be hidden in UI (default: false)
+ * @property {string} [format] - Original format hint from source (e.g., 'date-time', 'uri', 'email')
+ * @property {string[]} [enum] - Allowed values for enumeration fields
+ * @property {*} [default] - Default value for the field
+ * @property {UnifiedFieldReference} [reference] - Relation to another entity
+ * @property {Record<string, *>} [extensions] - Project-specific extensions
+ *
+ * @example
+ * // Simple text field
+ * const nameField = {
+ *   name: 'name',
+ *   type: 'text',
+ *   label: 'Full Name',
+ *   required: true
+ * }
+ *
+ * @example
+ * // Enum field with options
+ * const statusField = {
+ *   name: 'status',
+ *   type: 'text',
+ *   label: 'Status',
+ *   enum: ['draft', 'published', 'archived'],
+ *   default: 'draft'
+ * }
+ *
+ * @example
+ * // Foreign key with reference
+ * const authorField = {
+ *   name: 'author_id',
+ *   type: 'number',
+ *   label: 'Author',
+ *   reference: {
+ *     entity: 'users',
+ *     labelField: 'username'
+ *   }
+ * }
+ */
+
+/**
+ * Unified Entity Schema
+ *
+ * Common entity definition that abstracts OpenAPI path/schema, Pydantic model, or manual definition.
+ * This is the primary contract between schema sources (connectors) and consumers (generators, runtime).
+ *
+ * @typedef {object} UnifiedEntitySchema
+ * @property {string} name - Entity name, typically plural lowercase (e.g., 'users', 'blog_posts')
+ * @property {string} endpoint - API endpoint path (e.g., '/users', '/api/v1/posts')
+ * @property {string} [label] - Human-readable singular label (e.g., 'User', 'Blog Post')
+ * @property {string} [labelPlural] - Human-readable plural label (e.g., 'Users', 'Blog Posts')
+ * @property {string} [labelField] - Field used as display label (e.g., 'name', 'title')
+ * @property {string} [routePrefix] - Route prefix for admin UI (e.g., 'user', 'blog-post')
+ * @property {string} [idField] - Primary key field name (default: 'id')
+ * @property {boolean} [readOnly] - Whether entity is read-only (no create/update/delete)
+ * @property {Record<string, UnifiedFieldSchema>} fields - Field definitions keyed by field name
+ * @property {Record<string, *>} [extensions] - Project-specific extensions
+ *
+ * @example
+ * // Complete entity schema
+ * const usersSchema = {
+ *   name: 'users',
+ *   endpoint: '/api/users',
+ *   label: 'User',
+ *   labelPlural: 'Users',
+ *   labelField: 'username',
+ *   routePrefix: 'user',
+ *   idField: 'id',
+ *   readOnly: false,
+ *   fields: {
+ *     id: { name: 'id', type: 'number', readOnly: true },
+ *     username: { name: 'username', type: 'text', required: true },
+ *     email: { name: 'email', type: 'email', required: true },
+ *     created_at: { name: 'created_at', type: 'datetime', readOnly: true }
+ *   }
+ * }
+ *
+ * @example
+ * // Read-only entity (external API)
+ * const countriesSchema = {
+ *   name: 'countries',
+ *   endpoint: 'https://restcountries.com/v3.1/all',
+ *   label: 'Country',
+ *   labelPlural: 'Countries',
+ *   labelField: 'name',
+ *   idField: 'cca3',
+ *   readOnly: true,
+ *   fields: {
+ *     cca3: { name: 'cca3', type: 'text', label: 'Code' },
+ *     name: { name: 'name', type: 'text', label: 'Name' }
+ *   }
+ * }
+ */
+
+/**
+ * Valid field types for UnifiedFieldSchema
+ *
+ * Used for validation and documentation. Maps to common UI input types:
+ * - text: Single-line text input
+ * - number: Numeric input
+ * - boolean: Checkbox/toggle
+ * - date: Date picker (date only)
+ * - datetime: Date-time picker
+ * - email: Email input with validation
+ * - url: URL input with validation
+ * - uuid: UUID text input
+ * - array: Multi-value field (tags, list)
+ * - object: Nested object (JSON editor or subform)
+ *
+ * @type {readonly UnifiedFieldType[]}
+ */
+export const UNIFIED_FIELD_TYPES = Object.freeze([
+  'text',
+  'number',
+  'boolean',
+  'date',
+  'datetime',
+  'email',
+  'url',
+  'uuid',
+  'array',
+  'object'
+])
+
+/**
+ * Check if a type is a valid UnifiedFieldType
+ *
+ * @param {string} type - Type to validate
+ * @returns {type is UnifiedFieldType} - True if valid
+ *
+ * @example
+ * isValidFieldType('text')     // true
+ * isValidFieldType('string')   // false (OpenAPI type, not unified)
+ */
+export function isValidFieldType(type) {
+  return UNIFIED_FIELD_TYPES.includes(type)
+}
+
+/**
+ * Create a minimal field schema with defaults
+ *
+ * @param {string} name - Field name
+ * @param {UnifiedFieldType} type - Field type
+ * @param {Partial<UnifiedFieldSchema>} [overrides] - Additional field properties
+ * @returns {UnifiedFieldSchema} - Complete field schema
+ *
+ * @example
+ * const field = createFieldSchema('email', 'email', { required: true })
+ * // { name: 'email', type: 'email', required: true }
+ */
+export function createFieldSchema(name, type, overrides = {}) {
+  return {
+    name,
+    type,
+    ...overrides
+  }
+}
+
+/**
+ * Create a minimal entity schema with defaults
+ *
+ * @param {string} name - Entity name
+ * @param {string} endpoint - API endpoint
+ * @param {Record<string, UnifiedFieldSchema>} fields - Field definitions
+ * @param {Partial<UnifiedEntitySchema>} [overrides] - Additional entity properties
+ * @returns {UnifiedEntitySchema} - Complete entity schema
+ *
+ * @example
+ * const schema = createEntitySchema('users', '/api/users', {
+ *   id: createFieldSchema('id', 'number', { readOnly: true }),
+ *   name: createFieldSchema('name', 'text', { required: true })
+ * })
+ */
+export function createEntitySchema(name, endpoint, fields, overrides = {}) {
+  return {
+    name,
+    endpoint,
+    fields,
+    ...overrides
+  }
+}

package/src/gen/vite-plugin.js

@@ -0,0 +1,105 @@
+/**
+ * Vite Plugin for qdadm EntityManager Generation
+ *
+ * Integrates generateManagers with Vite's build pipeline, triggering
+ * entity manager file generation during the buildStart hook.
+ *
+ * @module gen/vite-plugin
+ */
+
+import { generateManagers } from './generateManagers.js'
+import { pathToFileURL } from 'node:url'
+import { resolve } from 'node:path'
+
+/**
+ * Plugin options for qdadmGen
+ *
+ * @typedef {object} QdadmGenOptions
+ * @property {string} [config] - Path to qdadm config file (default: 'qdadm.config.js')
+ * @property {string} [output] - Override output directory for generated files
+ */
+
+/**
+ * Vite plugin for generating EntityManager files at build time
+ *
+ * Loads the qdadm configuration file and calls generateManagers during
+ * Vite's buildStart hook. Supports both ESM and CommonJS config files.
+ *
+ * @param {QdadmGenOptions} [options={}] - Plugin options
+ * @returns {import('vite').Plugin} Vite plugin object
+ *
+ * @example
+ * // vite.config.js
+ * import { defineConfig } from 'vite'
+ * import { qdadmGen } from 'qdadm/gen/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     qdadmGen({
+ *       config: './qdadm.config.js',
+ *       output: 'src/generated/managers/'
+ *     })
+ *   ]
+ * })
+ *
+ * @example
+ * // qdadm.config.js
+ * export default {
+ *   output: 'src/generated/managers/',
+ *   entities: {
+ *     users: {
+ *       schema: { name: 'users', fields: { id: { type: 'integer' } } },
+ *       endpoint: '/api/users',
+ *       storageImport: 'qdadm',
+ *       storageClass: 'ApiStorage'
+ *     }
+ *   }
+ * }
+ */
+export function qdadmGen(options = {}) {
+  const configPath = options.config || 'qdadm.config.js'
+
+  return {
+    name: 'qdadm-gen',
+
+    async buildStart() {
+      try {
+        // Resolve config path relative to cwd
+        const resolvedConfigPath = resolve(process.cwd(), configPath)
+
+        // Load config file dynamically
+        const configUrl = pathToFileURL(resolvedConfigPath).href
+        const configModule = await import(configUrl)
+        const loadedConfig = configModule.default || configModule
+
+        // Validate loaded config
+        if (!loadedConfig || typeof loadedConfig !== 'object') {
+          throw new Error(`Invalid qdadm config at '${configPath}': must export an object`)
+        }
+
+        if (!loadedConfig.entities) {
+          throw new Error(`Invalid qdadm config at '${configPath}': missing 'entities' property`)
+        }
+
+        // Merge plugin options with config (plugin options take precedence)
+        const mergedConfig = {
+          ...loadedConfig,
+          ...(options.output && { output: options.output })
+        }
+
+        // Generate managers
+        const generatedFiles = await generateManagers(mergedConfig)
+
+        // Log results
+        console.log(`[qdadm-gen] Generated ${generatedFiles.length} manager file(s)`)
+        for (const file of generatedFiles) {
+          console.log(`  - ${file}`)
+        }
+      } catch (error) {
+        // Wrap error with plugin context for clearer messages
+        const message = error instanceof Error ? error.message : String(error)
+        throw new Error(`[qdadm-gen] Failed to generate managers: ${message}`)
+      }
+    }
+  }
+}

package/src/generated/managers/testManager.js

@@ -0,0 +1,45 @@
+/**
+ * TestManager - Auto-generated EntityManager
+ *
+ * Generated by qdadm/gen/generateManagers
+ * DO NOT EDIT MANUALLY - Changes will be overwritten
+ *
+ * Entity: test
+ * Endpoint: /test
+ */
+
+import { EntityManager } from 'qdadm'
+import { ApiStorage } from 'qdadm'
+
+/**
+ * Schema definition for test
+ * @type {import('qdadm/gen').UnifiedEntitySchema}
+ */
+export const testSchema = {
+  name: "test",
+  endpoint: "/test",
+  fields: {}
+}
+
+/**
+ * Storage options for test
+ */
+const storageOptions = {
+  endpoint: "/test"
+}
+
+/**
+ * TestManager instance
+ *
+ * Provides CRUD operations for test entity.
+ *
+ * @type {EntityManager}
+ */
+export const testManager = new EntityManager({
+  ...{
+  name: "test",
+  idField: "id",
+  fields: {}
+},
+  storage: new ApiStorage(storageOptions)
+})

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
+  }
 }