Better Auth Audit Logs Plugin

Common errors

• Error: Cannot find module 'better-auth-audit-logs/client'

  cause Incorrect import path for the client-side plugin, or missing package installation.
  fix Ensure `better-auth-audit-logs` is installed and the client plugin is imported as `import { auditLogClient } from 'better-auth-audit-logs/client';`.

• Error: 'auditLog' table not found or column missing in database.

  cause Database migrations for the audit log schema have not been generated or applied.
  fix Run `npx @better-auth/cli generate` to create the migration files, then apply them using your ORM's migration command (e.g., `npx prisma migrate dev`).

• TypeError: Cannot read properties of undefined (reading 'auditLog') on authClient

  cause The `auditLogClient()` plugin was not correctly registered with `createAuthClient`.
  fix Ensure `auditLogClient()` is included in the `plugins` array when calling `createAuthClient({ plugins: [auditLogClient()] })`.

• ZodError: Validation failed: Expected string, received undefined at 'action'

  cause When manually inserting an audit log, a required field (like `action`, `status`, `severity`) was omitted or provided with an incorrect type.
  fix Review the `insertAuditLog` call and ensure all required fields are present and conform to the expected schema (e.g., `action: 'some-action'`, `status: 'success'`, `severity: 'low'`).

Warnings

• breaking The default `modelName` for the audit log table changed from `audit_log` to `auditLog` to improve compatibility with Prisma adapters.
  Fix: If you are using a non-Prisma adapter and have an existing `audit_log` table, explicitly set `schema.auditLog.modelName: "audit_log"` in your plugin configuration to maintain compatibility.
• gotcha Requires `better-auth >= 1.0.0` and `typescript >= 5`. Older versions of `better-auth` are not compatible and will likely lead to runtime errors due to API mismatches.
  Fix: Ensure your `better-auth` and `typescript` peer dependencies are up-to-date by running `npm install better-auth@latest typescript@^5`.
• gotcha The audit log plugin adds an `auditLog` table to your database. You must run `npx @better-auth/cli generate` after installing to create the necessary migrations for your database adapter.
  Fix: After installing the plugin, execute `npx @better-auth/cli generate` and then apply the generated migrations using your ORM's migration tool (e.g., `npx prisma migrate dev`).
• gotcha The client-side `auditLogClient` plugin must be imported from `better-auth-audit-logs/client`.
  Fix: Always use `import { auditLogClient } from 'better-auth-audit-logs/client';` for client-side functionality. Importing from the main package path will lead to bundling issues or runtime errors in browser environments.

Install

• npm install better-auth-audit-logs npm
• yarn add better-auth-audit-logs yarn
• pnpm add better-auth-audit-logs pnpm

Imports

• auditLog
  wrong:

  const { auditLog } = require('better-auth-audit-logs');

  correct:

  import { auditLog } from 'better-auth-audit-logs';

  This is the primary server-side plugin factory for integrating with `better-auth`.
• auditLogClient
  wrong:

  import { auditLogClient } from 'better-auth-audit-logs';

  correct:

  import { auditLogClient } from 'better-auth-audit-logs/client';

  The client-side plugin has a distinct import path to avoid bundling server-side code in browser environments.
• AuditLogSchema

  import type { AuditLogSchema } from 'better-auth-audit-logs';

  Type import for the audit log entry structure. Available for both server and client contexts.

Quickstart

This quickstart demonstrates how to integrate the audit log plugin into a `better-auth` server instance and how to use its client-side capabilities to list existing logs and manually insert custom audit events.

import { betterAuth } from 'better-auth';
import { auditLog } from 'better-auth-audit-logs';

// Initialize Better Auth with the audit log plugin
export const auth = betterAuth({
  plugins: [auditLog()],
  // Assuming other Better Auth configurations here, e.g., adapters
  // adapter: someAdapter(...),
});

// In a separate script or CLI for database migrations:
// Make sure to have `@better-auth/cli` installed.
// Run `npx @better-auth/cli generate`
// This command will generate database migrations for the `auditLog` table.
// Subsequently, run your database migration command (e.g., `npx prisma migrate dev` for Prisma).

// Example of client-side usage (e.g., in a React component or API handler)
import { createAuthClient } from 'better-auth/client';
import { auditLogClient } from 'better-auth-audit-logs/client';

const authClient = createAuthClient({
  plugins: [auditLogClient()],
});

async function fetchAuditLogs() {
  try {
    const { data } = await authClient.auditLog.listAuditLogs({
      query: { status: 'failed', limit: 5, action: 'sign-in:email' },
    });
    console.log('Recent failed sign-ins:', data);

    await authClient.auditLog.insertAuditLog({
      action: 'admin:user-delete',
      status: 'success',
      severity: 'high',
      metadata: { deletedUserId: 'user-xyz', adminId: 'admin-abc' },
    });
    console.log('Manually logged an admin action.');

  } catch (error) {
    console.error('Error fetching or inserting audit logs:', error);
  }
}

// Call the function, typically triggered by a user action or on mount
// fetchAuditLogs();