Payload Audit Log Plugin

Plugin de auditoría para Payload CMS que registra cambios a nivel de campo en documentos.

Características

• Colección de auditoría centralizada: Todos los cambios se almacenan en audit-logs
• Campo de historial en cada documento: Muestra los cambios realizados directamente en el documento
• Seguimiento a nivel de campo: Registra qué campos cambiaron, valores antiguos y nuevos
• Soporte multi-colección: Configurable por colección
• Control de usuario: Registra qué usuario realizó cada cambio
• Timestamps precisos: Fecha y hora de cada operación

Instalación

npm install @fumh_terol/payload-plugin-audit-log

Uso

Configuración básica

import { auditLogPlugin } from '@fumh_terol/payload-plugin-audit-log'
import { buildConfig } from 'payload'

export default buildConfig({
  // ... tu config
  plugins: [
    auditLogPlugin({
      // Colecciones a monitorear
      watch: [
        {
          collection: 'posts',
          // Campos específicos a trackear (null = todos)
          fields: ['title', 'content', 'status'],
        },
        {
          collection: 'products',
          fields: null, // Trackea todos los campos
        },
      ],
      collectionsUrl: '/collections',
      // Permite borrar logs si req.user.roles incluye 'admin'
      deleteAccess: {
        field: 'roles',
        values: ['admin'],
      },
      logUser: true, // Registrar usuario
      logTimestamp: true, // Registrar timestamp
    }),
  ],
})

Opciones del plugin

| Opción | Tipo | Descripción | |--------|------|-------------| | auditCollectionSlug | string | Slug de la colección de auditoría (default: 'audit-logs') | | collectionsUrl | string | URL base para enlaces a documentos (default: '/collections') | | deleteAccess | { field: string; values: unknown \| unknown[] } | Permite borrar logs a usuarios cuyo campo coincida con alguno de los valores | | watch | WatchConfig[] | Array de configuraciones por colección | | trackedFields | Record<string, string[]> | Campos a trackear por colección (alternativa a watch) | | logUser | boolean | Registrar el usuario que hizo el cambio (default: true) | | logTimestamp | boolean | Registrar timestamp (default: true) | | includeDiffs | boolean | Incluir diferencias old/new (default: true) |

Colecciones monitoreadas

El plugin añade automáticamente a cada colección monitorizada:

1. Campo audit_logs_changes: Array de solo lectura con el historial de cambios
2. Hooks: beforeChange, afterChange, afterDelete para registrar cambios

Colección de Auditoría

La colección audit-logs almacena:

| Campo | Tipo | Descripción | |-------|------|-------------| | auditTitle | text | Título legible del evento | | timestamp | date | Fecha y hora del cambio | | collectionSlug | text | Nombre de la colección | | documentId | text | ID del documento afectado | | operation | select | create, update, delete, restore | | userEmail | text | Email del usuario (si está habilitado) | | userId | text | ID del usuario (si está habilitado) | | changes | array | Array de cambios con field, label, oldValue, newValue |

Ejemplo de uso

// En payload.config.ts
import { auditLogPlugin } from '@fumh_terol/payload-plugin-audit-log'

export default buildConfig({
  // ...
  plugins: [
    auditLogPlugin({
      watch: [
        { collection: 'posts', fields: ['title', 'content'] },
        { collection: 'pages', fields: null }, // Todos los campos
        { collection: 'users', fields: ['name', 'email', 'role'] },
      ],
      collectionsUrl: '/admin/collections',
      deleteAccess: {
        field: 'roles',
        values: ['admin'],
      },
      logUser: true,
    }),
  ],
})

Desarrollo

# Instalar dependencias
npm install

# Compilar
npm run build

# Desarrollo (requiere MongoDB)
cp dev/.env.example dev/.env
npm run dev

Licencia

MIT