@mostajs/audit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dr Hamid MADANI <drmdh@msn.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @mostajs/audit
+
+> Reusable audit logging module — fire-and-forget `logAudit()` with paginated consultation.
+
+[![npm version](https://img.shields.io/npm/v/@mostajs/audit.svg)](https://www.npmjs.com/package/@mostajs/audit)
+[![license](https://img.shields.io/npm/l/@mostajs/audit.svg)](LICENSE)
+
+Part of the [@mosta suite](https://mostajs.dev).
+
+---
+
+## Installation
+
+```bash
+npm install @mostajs/audit @mostajs/orm
+```
+
+## Quick Start
+
+### 1. Register the schema
+
+```typescript
+import { registerSchema } from '@mostajs/orm'
+import { AuditLogSchema } from '@mostajs/audit'
+
+registerSchema(AuditLogSchema)
+```
+
+### 2. Log an audit event
+
+```typescript
+import { logAudit } from '@mostajs/audit'
+
+await logAudit({
+  userId: session.user.id,
+  userName: session.user.name,
+  userRole: 'admin',
+  action: 'create',
+  module: 'users',
+  resource: 'User',
+  resourceId: newUser.id,
+})
+```
+
+### 3. Query audit logs (API route)
+
+```typescript
+import { createAuditHandlers } from '@mostajs/audit'
+import { checkPermission } from '@/lib/auth'
+
+export const { GET } = createAuditHandlers('audit:view', checkPermission)
+```
+
+## API Reference
+
+| Export | Description |
+|--------|-------------|
+| `logAudit(params)` | Fire-and-forget audit entry |
+| `getAuditUser(session)` | Extract user info from NextAuth session |
+| `AuditLogRepository` | Repository with `findPaginated()`, `findByResource()`, `deleteOlderThan()` |
+| `AuditLogSchema` | Entity schema for registration |
+| `createAuditHandlers()` | API route factory for paginated consultation |
+
+## Related Packages
+
+- [@mostajs/orm](https://www.npmjs.com/package/@mostajs/orm) — Multi-dialect ORM (required)
+- [@mostajs/auth](https://www.npmjs.com/package/@mostajs/auth) — Authentication & RBAC
+
+## License
+
+MIT — © 2025 Dr Hamid MADANI <drmdh@msn.com>

package/dist/api/route.d.ts

@@ -0,0 +1,12 @@
+import { NextRequest, NextResponse } from 'next/server';
+type PermissionChecker = (permission: string) => Promise<{
+    error: NextResponse | null;
+    session: any;
+}>;
+/**
+ * Creates a GET handler for paginated audit log consultation.
+ */
+export declare function createAuditHandlers(permission: string, checkPermission: PermissionChecker): {
+    GET: (req: NextRequest) => Promise<NextResponse<unknown>>;
+};
+export {};

package/dist/api/route.js

@@ -0,0 +1,47 @@
+"use strict";
+// @mosta/audit — API Route template
+// Author: Dr Hamid MADANI drmdh@msn.com
+//
+// Copy to: src/app/api/admin/audit/route.ts
+// Usage:
+//   import { createAuditHandlers } from '@mosta/audit/api/route'
+//   import { checkPermission } from '@mosta/auth'
+//   export const { GET } = createAuditHandlers('audit:view', checkPermission)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuditHandlers = createAuditHandlers;
+const server_1 = require("next/server");
+const orm_1 = require("@mostajs/orm");
+const audit_log_repository_1 = require("../repositories/audit-log.repository");
+/**
+ * Creates a GET handler for paginated audit log consultation.
+ */
+function createAuditHandlers(permission, checkPermission) {
+    async function GET(req) {
+        const { error } = await checkPermission(permission);
+        if (error)
+            return error;
+        const url = req.nextUrl;
+        const filters = {
+            module: url.searchParams.get('module') || undefined,
+            action: url.searchParams.get('action') || undefined,
+            userId: url.searchParams.get('userId') || undefined,
+            status: url.searchParams.get('status') || undefined,
+            from: url.searchParams.get('from') ? new Date(url.searchParams.get('from')) : undefined,
+            to: url.searchParams.get('to') ? new Date(url.searchParams.get('to')) : undefined,
+            page: parseInt(url.searchParams.get('page') || '1', 10),
+            limit: parseInt(url.searchParams.get('limit') || '50', 10),
+        };
+        const repo = new audit_log_repository_1.AuditLogRepository(await (0, orm_1.getDialect)());
+        const { data, total } = await repo.findPaginated(filters);
+        return server_1.NextResponse.json({
+            data,
+            meta: {
+                total,
+                page: filters.page,
+                limit: filters.limit,
+                pages: Math.ceil(total / filters.limit),
+            },
+        });
+    }
+    return { GET };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { logAudit, getAuditUser } from './lib/audit';
+export { AuditLogRepository } from './repositories/audit-log.repository';
+export { AuditLogSchema } from './schemas/audit-log.schema';
+export { createAuditHandlers } from './api/route';
+export type { MostaAuditConfig, AuditParams, AuditFilters, AuditLogDTO, } from './types';

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+// @mosta/audit — Barrel exports
+// Author: Dr Hamid MADANI drmdh@msn.com
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuditHandlers = exports.AuditLogSchema = exports.AuditLogRepository = exports.getAuditUser = exports.logAudit = void 0;
+// Core
+var audit_1 = require("./lib/audit");
+Object.defineProperty(exports, "logAudit", { enumerable: true, get: function () { return audit_1.logAudit; } });
+Object.defineProperty(exports, "getAuditUser", { enumerable: true, get: function () { return audit_1.getAuditUser; } });
+// Repository & Schema
+var audit_log_repository_1 = require("./repositories/audit-log.repository");
+Object.defineProperty(exports, "AuditLogRepository", { enumerable: true, get: function () { return audit_log_repository_1.AuditLogRepository; } });
+var audit_log_schema_1 = require("./schemas/audit-log.schema");
+Object.defineProperty(exports, "AuditLogSchema", { enumerable: true, get: function () { return audit_log_schema_1.AuditLogSchema; } });
+// API helpers
+var route_1 = require("./api/route");
+Object.defineProperty(exports, "createAuditHandlers", { enumerable: true, get: function () { return route_1.createAuditHandlers; } });

package/dist/lib/audit.d.ts

@@ -0,0 +1,13 @@
+import type { AuditParams } from '../types';
+/**
+ * Log an audit entry. Fire-and-forget — never throws, never blocks.
+ */
+export declare function logAudit(params: AuditParams): Promise<void>;
+/**
+ * Extract audit user info from a NextAuth-style session.
+ */
+export declare function getAuditUser(session: any): {
+    userId: string;
+    userName: string;
+    userRole: string;
+};

package/dist/lib/audit.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logAudit = logAudit;
+exports.getAuditUser = getAuditUser;
+// @mosta/audit — Core audit functions
+// Author: Dr Hamid MADANI drmdh@msn.com
+const orm_1 = require("@mostajs/orm");
+const audit_log_repository_1 = require("../repositories/audit-log.repository");
+/**
+ * Log an audit entry. Fire-and-forget — never throws, never blocks.
+ */
+async function logAudit(params) {
+    try {
+        const repo = new audit_log_repository_1.AuditLogRepository(await (0, orm_1.getDialect)());
+        await repo.create({
+            userId: params.userId,
+            userName: params.userName,
+            userRole: params.userRole,
+            action: params.action,
+            module: params.module,
+            resource: params.resource || '',
+            resourceId: params.resourceId || '',
+            details: params.details || {},
+            ipAddress: params.ipAddress || '',
+            status: params.status || 'success',
+            timestamp: new Date().toISOString(),
+        });
+    }
+    catch (err) {
+        console.error('[MostaAudit] Error:', err);
+    }
+}
+/**
+ * Extract audit user info from a NextAuth-style session.
+ */
+function getAuditUser(session) {
+    const { role, roles } = session.user;
+    return {
+        userId: session.user.id,
+        userName: session.user.name || session.user.email,
+        userRole: role || (Array.isArray(roles) ? roles.join(', ') : 'unknown'),
+    };
+}

package/dist/repositories/audit-log.repository.d.ts

@@ -0,0 +1,15 @@
+import { BaseRepository } from '@mostajs/orm';
+import type { IDialect, QueryOptions } from '@mostajs/orm';
+import type { AuditLogDTO, AuditFilters } from '../types';
+export declare class AuditLogRepository extends BaseRepository<AuditLogDTO> {
+    constructor(dialect: IDialect);
+    /** Find paginated audit logs with optional filters */
+    findPaginated(filters?: AuditFilters, options?: QueryOptions): Promise<{
+        data: AuditLogDTO[];
+        total: number;
+    }>;
+    /** Find audit logs related to a specific resource */
+    findByResource(resourceId: string, modules?: string[], options?: QueryOptions): Promise<AuditLogDTO[]>;
+    /** Delete logs older than N days */
+    deleteOlderThan(days: number): Promise<number>;
+}

package/dist/repositories/audit-log.repository.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditLogRepository = void 0;
+// @mosta/audit — AuditLogRepository
+// Author: Dr Hamid MADANI drmdh@msn.com
+const orm_1 = require("@mostajs/orm");
+const audit_log_schema_1 = require("../schemas/audit-log.schema");
+class AuditLogRepository extends orm_1.BaseRepository {
+    constructor(dialect) {
+        super(audit_log_schema_1.AuditLogSchema, dialect);
+    }
+    /** Find paginated audit logs with optional filters */
+    async findPaginated(filters = {}, options) {
+        const query = {};
+        if (filters.module)
+            query.module = filters.module;
+        if (filters.action)
+            query.action = { $regex: filters.action, $regexFlags: 'i' };
+        if (filters.userId)
+            query.userId = filters.userId;
+        if (filters.status)
+            query.status = filters.status;
+        if (filters.from || filters.to) {
+            query.timestamp = {};
+            if (filters.from)
+                query.timestamp.$gte = filters.from;
+            if (filters.to)
+                query.timestamp.$lte = filters.to;
+        }
+        const page = filters.page || 1;
+        const limit = filters.limit || 50;
+        const skip = (page - 1) * limit;
+        const [data, total] = await Promise.all([
+            this.findAll(query, { sort: { timestamp: -1 }, skip, limit, ...options }),
+            this.count(query),
+        ]);
+        return { data, total };
+    }
+    /** Find audit logs related to a specific resource */
+    async findByResource(resourceId, modules, options) {
+        const query = { resourceId };
+        if (modules && modules.length > 0) {
+            query.module = { $in: modules };
+        }
+        return this.findAll(query, { sort: { timestamp: -1 }, ...options });
+    }
+    /** Delete logs older than N days */
+    async deleteOlderThan(days) {
+        const cutoff = new Date(Date.now() - days * 86400000);
+        return this.deleteMany({ timestamp: { $lt: cutoff } });
+    }
+}
+exports.AuditLogRepository = AuditLogRepository;

package/dist/schemas/audit-log.schema.d.ts

@@ -0,0 +1,2 @@
+import type { EntitySchema } from '@mostajs/orm';
+export declare const AuditLogSchema: EntitySchema;

package/dist/schemas/audit-log.schema.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditLogSchema = void 0;
+exports.AuditLogSchema = {
+    name: 'AuditLog',
+    collection: 'auditlogs',
+    timestamps: false,
+    fields: {
+        userName: { type: 'string', required: true },
+        userRole: { type: 'string', required: true },
+        action: { type: 'string', required: true },
+        module: { type: 'string', required: true },
+        resource: { type: 'string', default: '' },
+        resourceId: { type: 'string', default: '' },
+        details: { type: 'json' },
+        ipAddress: { type: 'string', default: '' },
+        status: { type: 'string', enum: ['success', 'failure'], default: 'success' },
+        timestamp: { type: 'date', default: 'now' },
+    },
+    relations: {
+        userId: { target: 'User', type: 'many-to-one', required: true },
+    },
+    indexes: [
+        { fields: { timestamp: 'desc' } },
+        { fields: { module: 'asc', timestamp: 'desc' } },
+        { fields: { userId: 'asc', timestamp: 'desc' } },
+    ],
+};

package/dist/types/index.d.ts

@@ -0,0 +1,46 @@
+export interface MostaAuditConfig {
+    /** Collection/table name (default: 'auditlogs') */
+    collection?: string;
+    /** Retention in days, 0 = unlimited (default: 0) */
+    retentionDays?: number;
+    /** Known modules for UI filters */
+    modules?: string[];
+    /** Known actions for UI filters */
+    actions?: string[];
+}
+export interface AuditParams {
+    userId: string;
+    userName: string;
+    userRole: string;
+    action: string;
+    module: string;
+    resource?: string;
+    resourceId?: string;
+    details?: Record<string, any>;
+    ipAddress?: string;
+    status?: 'success' | 'failure';
+}
+export interface AuditFilters {
+    module?: string;
+    action?: string;
+    userId?: string;
+    status?: 'success' | 'failure';
+    from?: Date;
+    to?: Date;
+    page?: number;
+    limit?: number;
+}
+export interface AuditLogDTO {
+    id: string;
+    userId: any;
+    userName: string;
+    userRole: string;
+    action: string;
+    module: string;
+    resource: string;
+    resourceId: string;
+    details: Record<string, unknown> | null;
+    ipAddress: string;
+    status: 'success' | 'failure';
+    timestamp: string;
+}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+"use strict";
+// @mosta/audit — Types
+// Author: Dr Hamid MADANI drmdh@msn.com
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mostajs/audit",
+  "version": "1.0.0",
+  "description": "Reusable audit logging module — fire-and-forget logAudit() with paginated consultation",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./api/route": {
+      "types": "./dist/api/route.d.ts",
+      "import": "./dist/api/route.js",
+      "require": "./dist/api/route.js",
+      "default": "./dist/api/route.js"
+    }
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "keywords": ["audit", "audit-log", "logging", "nextjs", "mosta"],
+  "repository": { "type": "git", "url": "https://github.com/apolocine/mosta-audit" },
+  "homepage": "https://mostajs.dev/packages/audit",
+  "engines": { "node": ">=18.0.0" },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@mostajs/orm": "^1.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "next": { "optional": true },
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}