@mostajs/audit 2.2.2 → 2.3.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { logAudit, getAuditUser } from './lib/audit';
+export { configureAudit, getAuditRepo, resetAuditRepo, type IAuditLogRepository } from './lib/audit-factory';
 export { dlog, dwarn, createLogger, isDebugEnabled, type ScopedLogger } from './lib/debug-log';
 export { AuditLogRepository } from './repositories/audit-log.repository';
 export { AuditLogSchema } from './schemas/audit-log.schema';

package/dist/index.js

@@ -2,6 +2,8 @@
 // Author: Dr Hamid MADANI drmdh@msn.com
 // Core
 export { logAudit, getAuditUser } from './lib/audit';
+// Configuration (DI) : l'hôte injecte son dialecte ORM (depuis son .env) — voie recommandée.
+export { configureAudit, getAuditRepo, resetAuditRepo } from './lib/audit-factory';
 // Volatile debug logger (complement de logAudit pour la trace pm2/stdout)
 export { dlog, dwarn, createLogger, isDebugEnabled } from './lib/debug-log';
 // Repository & Schema

package/dist/lib/audit-factory.d.ts

@@ -8,7 +8,16 @@ export interface IAuditLogRepository {
     findByResource(resourceId: string, modules?: string[]): Promise<AuditLogDTO[]>;
     deleteOlderThan(days: number): Promise<number>;
 }
-/** Get audit repository — dialect resolved by octoswitcher (ORM or NET) */
+/**
+ * Injection de dépendance (RECOMMANDÉ) : l'application hôte fournit SON dialecte ORM, construit
+ * depuis SON `.env`. C'est la voie la moins dépendante et la moins risquée — aucun résolveur,
+ * aucune seconde instance d'ORM (donc pas de double-package). Sans injection, repli sur
+ * `@mostajs/data-plug` (résolution depuis le `.env` de l'hôte).
+ */
+export declare function configureAudit(opts: {
+    dialect: unknown;
+}): void;
+/** Get audit repository — dialecte injecté (DI) sinon résolu depuis le `.env` via data-plug. */
 export declare function getAuditRepo(): Promise<IAuditLogRepository>;
 /** Reset cache (for tests) */
 export declare function resetAuditRepo(): void;

package/dist/lib/audit-factory.js

@@ -1,26 +1,44 @@
 // audit-factory.ts — Centralized repository factory
-// Uses @mostajs/octoswitcher to get the right dialect (ORM or NET)
-// Author: Dr Hamid MADANI drmdh@msn.com
-import { AuditLogSchema } from '../schemas/audit-log.schema.js';
+// DI-first : l'application hôte injecte SON dialecte (depuis SON .env). Repli optionnel sur
+// @mostajs/data-plug (remplace @mostajs/octoswitcher). Aucune dépendance dure de résolveur.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
 // ============================================================
-// Factory — dialect resolved by octoswitcher
+// Factory — DI-first, repli .env via data-plug
 // ============================================================
 let _cached = null;
-/** Get audit repository — dialect resolved by octoswitcher (ORM or NET) */
+let _injectedDialect = null;
+/**
+ * Injection de dépendance (RECOMMANDÉ) : l'application hôte fournit SON dialecte ORM, construit
+ * depuis SON `.env`. C'est la voie la moins dépendante et la moins risquée — aucun résolveur,
+ * aucune seconde instance d'ORM (donc pas de double-package). Sans injection, repli sur
+ * `@mostajs/data-plug` (résolution depuis le `.env` de l'hôte).
+ */
+export function configureAudit(opts) {
+    if (opts && opts.dialect) {
+        _injectedDialect = opts.dialect;
+        _cached = null;
+    }
+}
+/** Get audit repository — dialecte injecté (DI) sinon résolu depuis le `.env` via data-plug. */
 export async function getAuditRepo() {
     if (_cached)
         return _cached;
-    const { getDialect } = await import('@mostajs/octoswitcher');
-    const { registerSchemas } = await import('@mostajs/orm');
     const { AuditLogRepository } = await import('../repositories/audit-log.repository.js');
-    registerSchemas([AuditLogSchema]);
-    const dialect = await getDialect();
-    if (typeof dialect.initSchema === 'function') {
-        const { getAllSchemas } = await import('@mostajs/orm');
-        await dialect.initSchema(getAllSchemas());
+    // 1) Dialecte injecté par l'hôte (DI) — chemin principal, zéro dépendance résolveur.
+    if (_injectedDialect) {
+        _cached = new AuditLogRepository(_injectedDialect);
+        return _cached;
     }
+    // 2) Repli : résolution depuis le `.env` de l'hôte via @mostajs/data-plug (remplace octoswitcher).
+    //    Import par spécifieur variable → dépendance OPTIONNELLE (inutile si l'hôte injecte).
+    const spec = '@mostajs/data-plug';
+    const mod = (await import(spec));
+    const dialect = await mod.getDialect();
     _cached = new AuditLogRepository(dialect);
     return _cached;
 }
 /** Reset cache (for tests) */
-export function resetAuditRepo() { _cached = null; }
+export function resetAuditRepo() {
+    _cached = null;
+    _injectedDialect = null;
+}

package/llms.txt

@@ -0,0 +1,130 @@
+# @mostajs/audit — fiche LLM
+> Journalisation d'audit fire-and-forget : logAudit() non bloquant + consultation paginée, stats, export CSV/JSON.
+
+- Version: 2.2.2 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Chemin: mostajs/mosta-audit · Statut audit: complet (dist/)
+
+## RÔLE
+Module de journalisation d'audit de l'écosystème mostajs. Expose un `logAudit()` fire-and-forget — il ne lève jamais d'exception et ne bloque jamais le flux appelant — pour tracer les actions métier (création, modification, suppression…). Fournit la consultation paginée et filtrée des logs (handler API Next.js), un export CSV/JSON, des statistiques agrégées, une page d'administration et un logger debug volatile complémentaire (stdout/pm2). Fonctionne en mode ORM ou NET selon `MOSTA_DATA`.
+
+## INSTALLATION
+npm i @mostajs/audit @mostajs/orm
+
+## EXPORTS
+Point d'entrée racine (`.`) :
+- Core: logAudit, getAuditUser
+- Debug logger: dlog, dwarn, createLogger, isDebugEnabled
+- Repository/Schéma: AuditLogRepository, AuditLogSchema
+- API: createAuditHandlers, createAuditExportHandler
+- Export: auditToCsv, auditToJson
+- Stats: getAuditStats
+- Menu/i18n/Page: auditMenuContribution, auditT, AuditPage (default)
+- Types: MostaAuditConfig, AuditParams, AuditFilters, AuditLogDTO, ExportOptions, AuditStats, ScopedLogger
+
+## EXPORTS PAR SOUS-CHEMIN
+- `./lib/audit` — logAudit, getAuditUser
+- `./api/route` — createAuditHandlers
+- `./types` — MostaAuditConfig, AuditParams, AuditFilters, AuditLogDTO
+- `./lib/menu` — auditMenuContribution
+- `./register` — register(registry)
+- `./pages/AuditPage` — page d'administration
+- `./lib/i18n` — t (auditT)
+- `./lib/module-info` — getSchemas, moduleInfo (pour @mostajs/setup)
+- `./lib/export` — auditToCsv, auditToJson ; type ExportOptions
+- `./lib/audit-stats` — getAuditStats ; type AuditStats
+- `./lib/handlers/audit-export` — createAuditExportHandler
+- `./lib/debug-log` — dlog, dwarn, createLogger, isDebugEnabled ; type ScopedLogger
+- `./schemas/audit-log.schema` — AuditLogSchema
+- `./repositories/audit-log.repository` — AuditLogRepository
+
+## API — SIGNATURES
+logAudit(params: AuditParams): Promise<void>  // fire-and-forget : ne throw jamais, ne bloque jamais
+getAuditUser(session: any): { userId, userName, userRole }  // extrait d'une session NextAuth
+createAuditHandlers(permission: string, checkPermission: PermissionChecker): { GET }  // consultation paginée
+createAuditExportHandler(...)  // handler d'export
+auditToCsv(logs: any[]): string  · auditToJson(logs: any[]): string
+getAuditStats(repo: any, days?: number): Promise<AuditStats>
+dlog(scope, data): void  // actif si MOSTAJS_DEBUG=1 ou hors prod
+dwarn(scope, data): void  // toujours actif
+createLogger(namespace: string): ScopedLogger  // { dlog, dwarn }
+isDebugEnabled(): boolean
+
+AuditLogRepository extends BaseRepository<AuditLogDTO> (dialect: IDialect) :
+  findPaginated(filters?: AuditFilters, options?): Promise<{ data: AuditLogDTO[], total: number }>
+  findByResource(resourceId, modules?, options?): Promise<AuditLogDTO[]>
+  deleteOlderThan(days: number): Promise<number>  // rétention / purge
+
+PermissionChecker = (permission: string) => Promise<{ error: NextResponse|null, session: any }>
+
+## TYPES CLÉS
+AuditParams { userId, userName, userRole, action, module, resource?, resourceId?, details?:Record<string,any>, ipAddress?, status?:'success'|'failure' }
+AuditLogDTO { id, userId, userName, userRole, action, module, resource, resourceId, details:Record|null, ipAddress, status:'success'|'failure', timestamp }
+AuditFilters { module?, action?, userId?, status?, from?:Date, to?:Date, page?, limit? }
+MostaAuditConfig { modules?:string[], actions?:string[] }  // valeurs pour les filtres UI
+AuditStats { totalLogs, byModule:Record<string,number>, byAction:Record<string,number>, byStatus:{success,failure}, topUsers:[{userName,count}], recentErrors[] }
+ExportOptions { format:'csv'|'json', from?, to?, module?, action?, limit? }
+ScopedLogger { dlog(scope,data), dwarn(scope,data) }
+
+## PATTERN
+```ts
+// Tracer une action
+import { logAudit, getAuditUser } from '@mostajs/audit'
+await logAudit({
+  ...getAuditUser(session),
+  action: 'user_create',
+  module: 'users',
+  resource: 'John Doe',
+  resourceId: user.id,
+  details: { email: 'john@x.com' },
+  status: 'success',
+})
+
+// Route de consultation Next.js
+import { createAuditHandlers } from '@mostajs/audit/api/route'
+export const { GET } = createAuditHandlers('audit:view', checkPermission)
+// GET /api/audit-log?page=1&limit=50&module=users&action=create
+
+// Purge de rétention
+const repo = new AuditLogRepository(await getDialect())
+await repo.deleteOlderThan(90)
+```
+
+## INTÉGRATION (DI-first, depuis le .env de l'hôte) — depuis 2.3.0
+`getAuditRepo()`/`logAudit()` résolvent le dialecte ainsi :
+1. **Injecté** par l'hôte (RECOMMANDÉ) : `configureAudit({ dialect })` — zéro résolveur, copie ORM unique.
+2. **Repli** : `@mostajs/data-plug` (`getDialect()` lit le `.env` de l'hôte) — remplace octoswitcher, optionnel.
+```ts
+import { configureAudit } from '@mostajs/audit'            // ou '@mostajs/audit/lib/audit-factory'
+import { logAudit } from '@mostajs/audit/lib/audit'
+import { AuditLogSchema } from '@mostajs/audit/schemas/audit-log.schema'
+import { AuditLogRepository } from '@mostajs/audit/repositories/audit-log.repository'
+
+// 1) Ajouter AuditLogSchema à VOS schémas (migration crée la table `auditlogs`).
+//    ⚠ relation `userId → User` (m2o, requise) : l'hôte DOIT exposer un schéma `name:"User"`.
+// 2) Injecter VOTRE dialecte (construit depuis VOTRE .env) — une fois :
+configureAudit({ dialect: await getOrm() })
+// 3) Tracer (fire-and-forget) :
+await logAudit({ userId, userName, userRole, action: 'order.create', module: 'commandes', resource: '2026-…' })
+// 4) Consulter : new AuditLogRepository(await getOrm()).findPaginated(filters) → { data, total } ; UI native.
+```
+> En test : importer par SOUS-CHEMINS (la racine charge AuditPage → lucide-react). Voir @mostajs/mjs-unit.
+
+## DÉPEND DE (depuis 2.3.0 — « le moins dépendant »)
+- **Aucune dépendance dure** (`dependencies: {}`).
+- Peers : **@mostajs/orm** (requis — l'hôte le fournit → copie unique, pas de double-package) ;
+  **@mostajs/data-plug** (optionnel — uniquement pour le repli `.env`) ; @mostajs/menu/socle/ui, lucide-react,
+  next, react (tous optionnels, UI seulement).
+- ❌ Retirés : @mostajs/net (inutilisé), @mostajs/octoswitcher (→ remplacé par data-plug, optionnel).
+
+## PIÈGES
+- logAudit est volontairement fire-and-forget : il avale ses propres erreurs (échec d'écriture audit → silencieux). Ne pas s'en servir comme garantie transactionnelle ; ne pas l'attendre comme bloquant critique.
+- logAudit ≠ debug-log : `logAudit` persiste en DB ; `dlog`/`dwarn` ne font que tracer en stdout (volatile, pour pm2). dlog n'est actif que si `MOSTAJS_DEBUG=1` ou hors production ; dwarn est toujours actif.
+- createAuditHandlers exige une callback `checkPermission` (typiquement fournie par `@mostajs/auth`) ; le module ne gère pas la session.
+- Le mode de données (ORM/NET) est piloté par `MOSTA_DATA` ; le repo factory interne lit l'environnement automatiquement.
+- getAuditUser attend une session de forme NextAuth ; si la forme diffère, fournir manuellement userId/userName/userRole.
+- deleteOlderThan supprime définitivement les lignes : prévoir l'archivage avant purge si rétention légale.
+
+## RÉFÉRENCES
+- README.md (racine du module)
+- audit.wire.json, wire.json — déclaration de câblage
+- LICENSE (AGPL-3.0-or-later)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/audit",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Reusable audit logging module — fire-and-forget logAudit() with paginated consultation",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",
@@ -90,7 +90,8 @@
     "wire.json",
     "audit.wire.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
   "keywords": [
     "audit",
@@ -107,17 +108,15 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build"
-  },
   "peerDependencies": {
     "@mostajs/menu": ">=1.0.2",
     "@mostajs/socle": ">=2.0.0",
     "@mostajs/ui": ">=1.0.0",
     "lucide-react": ">=0.400.0",
     "next": ">=14",
-    "react": ">=18"
+    "react": ">=18",
+    "@mostajs/orm": ">=1.7.0",
+    "@mostajs/data-plug": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -134,6 +133,12 @@
     },
     "lucide-react": {
       "optional": true
+    },
+    "@mostajs/data-plug": {
+      "optional": true
+    },
+    "@mostajs/socle": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -145,15 +150,15 @@
     "lucide-react": "^0.575.0",
     "next": "^16.1.6",
     "react": "^19.0.0",
-    "typescript": "^5.6.0"
-  },
-  "dependencies": {
-    "@mostajs/net": "^2.0.0",
-    "@mostajs/octoswitcher": "^1.0.0",
-    "@mostajs/orm": "^1.7.0"
+    "typescript": "^5.6.0",
+    "@mostajs/mjs-unit": "^0.3.0"
   },
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/apolocine"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bash test-scripts/run-tests.sh"
   }
-}
+}