qdadm 0.35.0 → 0.38.0

package/README.md

@@ -2,61 +2,38 @@
 
 **Vue 3 admin framework. PrimeVue. Zero boilerplate.**
 
-Full documentation: [../../README.md](../../README.md)
+Quick start: [../../README.md](../../README.md) (5 min tutorial)
+
+Concepts & patterns: [QDADM_CREDO.md](QDADM_CREDO.md)
 
 Changelog: [../../CHANGELOG.md](../../CHANGELOG.md)
 
 ## Installation
 
 ```bash
-npm install qdadm
+npm install qdadm primevue @primeuix/themes
 ```
 
-## Quick Start
+## Exports
 
 ```js
-import { Kernel, EntityManager, LocalStorage } from 'qdadm'
-import PrimeVue from 'primevue/config'
-import Aura from '@primeuix/themes/aura'
-import 'qdadm/styles'
-
-const kernel = new Kernel({
-  root: App,
-  modules: import.meta.glob('./modules/*/init.js', { eager: true }),
-  managers: {
-    books: new EntityManager({
-      name: 'books',
-      storage: new LocalStorage({ key: 'books' }),
-      labelField: 'title'
-    })
-  },
-  authAdapter,
-  pages: { login: LoginPage, layout: MainLayout },
-  homeRoute: 'book',
-  app: { name: 'My App' },
-  primevue: { plugin: PrimeVue, theme: Aura }
-})
+// Core
+import { Kernel, EntityManager } from 'qdadm'
 
-kernel.createApp().mount('#app')
-```
+// Storage backends
+import { MockApiStorage, ApiStorage, SdkStorage } from 'qdadm'
 
-## Exports
-
-```js
-// Main
-import { Kernel, createQdadm, EntityManager, ApiStorage, LocalStorage, SdkStorage } from 'qdadm'
+// Auth
+import { SessionAuthAdapter, LocalStorageSessionAuthAdapter } from 'qdadm'
 
 // Composables
 import { useForm, useBareForm, useListPageBuilder } from 'qdadm/composables'
 
 // Components
-import { ListPage, PageLayout, FormField, FormActions } from 'qdadm/components'
+import { ListPage, PageLayout, AppLayout, FormField, FormActions } from 'qdadm/components'
 
 // Module system
-import { initModules, getRoutes, setSectionOrder } from 'qdadm/module'
-
-// Utilities
-import { formatDate, truncate } from 'qdadm/utils'
+import { KernelContext } from 'qdadm/module'
 
 // Styles
 import 'qdadm/styles'
@@ -64,155 +41,32 @@ import 'qdadm/styles'
 
 ## SdkStorage
 
-Adapter for generated SDK clients (hey-api, openapi-generator, etc.). Maps SDK methods to standard CRUD operations with optional transforms.
-
-### Basic Usage
+Adapter for generated SDK clients (hey-api, openapi-generator, etc.):
 
 ```js
-import { EntityManager, SdkStorage } from 'qdadm'
-import { Sdk } from './generated/sdk.gen.js'
-
-const sdk = new Sdk({ client: myClient })
+import { SdkStorage } from 'qdadm'
 
 const storage = new SdkStorage({
   sdk,
   methods: {
-    list: 'getApiAdminTasks',
-    get: 'getApiAdminTasksById',
-    create: 'postApiAdminTasks',
-    update: 'patchApiAdminTasksById',
-    delete: 'deleteApiAdminTasksById'
+    list: 'getApiBooks',
+    get: 'getApiBooksById',
+    create: 'postApiBooks',
+    update: 'patchApiBooksById',
+    delete: 'deleteApiBooksById'
   }
 })
-
-const manager = new EntityManager({
-  name: 'tasks',
-  storage,
-  labelField: 'name'
-})
-```
-
-### Configuration Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `sdk` | object | SDK instance |
-| `getSdk` | function | Callback for lazy SDK loading |
-| `methods` | object | Map operations to SDK method names or callbacks |
-| `transformRequest` | function | Global request transform `(operation, params) => params` |
-| `transformResponse` | function | Global response transform `(operation, data) => data` |
-| `transforms` | object | Per-method transforms (override global) |
-| `responseFormat` | object | Configure response normalization |
-| `clientSidePagination` | boolean | Handle pagination locally (default: false) |
-
-### Method Mapping
-
-Methods can be strings (SDK method name) or callbacks for full control:
-
-```js
-methods: {
-  // String: calls sdk.getItems({ query: params })
-  list: 'getItems',
-
-  // Callback: full control over SDK invocation
-  get: async (sdk, id) => {
-    const result = await sdk.getItemById({ path: { id } })
-    return result.data
-  }
-}
 ```
 
-### Transform Callbacks
+Options: `transformRequest`, `transformResponse`, `responseFormat`, `clientSidePagination`.
 
-**Global transforms** apply to all operations:
+## Documentation
 
-```js
-new SdkStorage({
-  sdk,
-  methods: { list: 'getItems', get: 'getItemById' },
-  transformRequest: (operation, params) => {
-    if (operation === 'list') {
-      return { query: params }
-    }
-    return params
-  },
-  transformResponse: (operation, response) => response.data
-})
-```
-
-**Per-method transforms** override global ones:
-
-```js
-new SdkStorage({
-  sdk,
-  methods: { list: 'getItems' },
-  transforms: {
-    list: {
-      request: (params) => ({ query: { ...params, active: true } }),
-      response: (data) => ({ items: data.results, total: data.count })
-    }
-  }
-})
-```
-
-### Response Format Normalization
-
-For APIs with non-standard response shapes, configure normalization before transforms:
-
-```js
-new SdkStorage({
-  sdk,
-  methods: { list: 'getItems' },
-  responseFormat: {
-    dataField: 'results',      // Field containing array (e.g., 'data', 'results')
-    totalField: 'count',       // Field for total count (null = compute from array)
-    itemsField: 'data.items'   // Nested path (takes precedence over dataField)
-  }
-})
-```
-
-### Client-Side Pagination
-
-For SDKs that return all items without server-side pagination:
-
-```js
-new SdkStorage({
-  sdk,
-  methods: { list: 'getAllItems' },
-  clientSidePagination: true  // Fetches all, paginates/sorts/filters in-memory
-})
-```
-
-### Real-World Example (hey-api SDK)
-
-```js
-import { Sdk } from '@/generated/sdk.gen.js'
-import { client } from '@/generated/client.gen.js'
-
-// Configure client
-client.setConfig({ baseUrl: '/api' })
-
-const sdk = new Sdk({ client })
-
-const taskStorage = new SdkStorage({
-  sdk,
-  methods: {
-    list: 'getApiAdminTasks',
-    get: 'getApiAdminTasksById',
-    create: 'postApiAdminTasks',
-    patch: 'patchApiAdminTasksById',
-    delete: 'deleteApiAdminTasksById'
-  },
-  transforms: {
-    list: {
-      response: (data) => ({
-        items: data.items.map(t => ({ ...t, statusLabel: t.status.toUpperCase() })),
-        total: data.total
-      })
-    }
-  }
-})
-```
+| Doc | Purpose |
+|-----|---------|
+| [QDADM_CREDO](QDADM_CREDO.md) | Philosophy, patterns, concepts |
+| [Architecture](docs/architecture.md) | PAC pattern, layers |
+| [Extension](docs/extension.md) | Hooks, signals, zones |
 
 ## Peer Dependencies
 
@@ -220,7 +74,6 @@ const taskStorage = new SdkStorage({
 - vue-router ^4.0.0
 - primevue ^4.0.0
 - pinia ^2.0.0
-- vanilla-jsoneditor ^0.23.0
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.35.0",
+  "version": "0.38.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -21,6 +21,7 @@
   "exports": {
     ".": "./src/index.js",
     "./auth": "./src/auth/index.js",
+    "./security": "./src/security/index.js",
     "./composables": "./src/composables/index.js",
     "./components": "./src/components/index.js",
     "./editors": "./src/editors/index.js",

package/src/auth/SessionAuthAdapter.js

@@ -196,6 +196,7 @@ export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
   constructor(storageKey = 'qdadm_auth') {
     super()
     this._storageKey = storageKey
+    this._originalUser = null  // Stores original user during impersonation
     this._restore()
   }
 
@@ -207,9 +208,10 @@ export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
     try {
       const stored = localStorage.getItem(this._storageKey)
       if (stored) {
-        const { token, user } = JSON.parse(stored)
+        const { token, user, originalUser } = JSON.parse(stored)
         this._token = token
         this._user = user
+        this._originalUser = originalUser || null
       }
     } catch {
       // Invalid stored data, ignore
@@ -223,10 +225,14 @@ export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
    */
   persist() {
     if (this._token && this._user) {
-      localStorage.setItem(this._storageKey, JSON.stringify({
+      const data = {
         token: this._token,
         user: this._user
-      }))
+      }
+      if (this._originalUser) {
+        data.originalUser = this._originalUser
+      }
+      localStorage.setItem(this._storageKey, JSON.stringify(data))
     } else {
       localStorage.removeItem(this._storageKey)
     }
@@ -234,6 +240,7 @@ export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
 
   // Arrow functions to preserve `this` when used as callbacks
   logout = () => {
+    this._originalUser = null
     this.clearSession()
     localStorage.removeItem(this._storageKey)
   }
@@ -249,6 +256,110 @@ export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
   getUser = () => {
     return this._user
   }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Impersonation support
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if currently impersonating another user
+   * @returns {boolean}
+   */
+  isImpersonating = () => {
+    return this._originalUser !== null
+  }
+
+  /**
+   * Get the original user (admin) when impersonating
+   * @returns {object|null} Original user or null if not impersonating
+   */
+  getOriginalUser = () => {
+    return this._originalUser
+  }
+
+  /**
+   * Start impersonating another user
+   *
+   * @param {object} targetUser - User to impersonate
+   * @returns {object} The impersonated user
+   */
+  impersonate = (targetUser) => {
+    if (!this._user) {
+      throw new Error('Must be authenticated to impersonate')
+    }
+    if (this._originalUser) {
+      throw new Error('Already impersonating. Stop first.')
+    }
+
+    this._originalUser = this._user
+    this._user = targetUser
+    this.persist()
+
+    return targetUser
+  }
+
+  /**
+   * Stop impersonating and return to original user
+   *
+   * @returns {object} The original user
+   */
+  stopImpersonating = () => {
+    if (!this._originalUser) {
+      throw new Error('Not currently impersonating')
+    }
+
+    const original = this._originalUser
+    this._user = this._originalUser
+    this._originalUser = null
+    this.persist()
+
+    return original
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Signal integration
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Connect authAdapter to signals for reactive impersonation
+   *
+   * Call this during kernel boot to enable signal-driven impersonation.
+   * The adapter will listen to auth:impersonate and auth:impersonate:stop
+   * signals and update its internal state automatically.
+   *
+   * @param {object} signals - Signals instance (from orchestrator.signals)
+   * @returns {Function} Cleanup function to unsubscribe
+   */
+  connectSignals(signals) {
+    if (!signals) return () => {}
+
+    const cleanups = []
+
+    // Listen for impersonate signal
+    cleanups.push(signals.on('auth:impersonate', (event) => {
+      const data = event?.data || event
+      const targetUser = data?.target
+      if (targetUser && !this._originalUser) {
+        this._originalUser = this._user
+        this._user = targetUser
+        this.persist()
+      }
+    }))
+
+    // Listen for stop impersonation signal
+    cleanups.push(signals.on('auth:impersonate:stop', () => {
+      if (this._originalUser) {
+        this._user = this._originalUser
+        this._originalUser = null
+        this.persist()
+      }
+    }))
+
+    // Return cleanup function
+    return () => {
+      cleanups.forEach(cleanup => cleanup?.())
+    }
+  }
 }
 
 export default SessionAuthAdapter