Activity Log Plugin

A Spatie-inspired activity log plugin for Svelar/SvelteKit that records user actions, tracks model changes, and provides a timeline feed with filtering, pagination, and pre-built UI components.

Package: @beeblock/svelar-activity-log

Install:

npx svelar plugin:install @beeblock/svelar-activity-log

Imports:

// Plugin registration
import { SvelarActivityLogPlugin } from '@beeblock/svelar-activity-log/server';

// Core API
import { Activity, ActivityLogger, activity, ActivityService, LogsActivity, setCauserResolver, getCauserResolver } from '@beeblock/svelar-activity-log';

// Server-side (controller)
import { ActivityController } from '@beeblock/svelar-activity-log/server';

// UI components
import { ActivityFeed, ActivityItem, ActivityFilters } from '@beeblock/svelar-activity-log/ui';

// Types
import type { ActivityRecord, ActivityData, ChangeProperties, ActivityFilterOptions, PaginatedActivities, ActivityLogPluginConfig, ActivityFeedItem, ActivityLogClassNames, LogsActivityConfig } from '@beeblock/svelar-activity-log';

Quick Start

1. Register the Plugin

// src/lib/plugins.ts
import { SvelarActivityLogPlugin } from '@beeblock/svelar-activity-log/server';

export const activityLogPlugin = new SvelarActivityLogPlugin({
  prefix: '/api',
  defaultLogName: 'default',
  defaultCauserType: 'users',
  cleanupDays: 90,
  logOnlyDirty: true,
});

2. Run the Migration

CREATE TABLE IF NOT EXISTS activity_log (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  log_name TEXT DEFAULT 'default',
  description TEXT NOT NULL,
  subject_type TEXT,
  subject_id INTEGER,
  causer_type TEXT DEFAULT 'users',
  causer_id INTEGER,
  properties TEXT DEFAULT '{}',
  created_at TEXT
);

CREATE INDEX IF NOT EXISTS idx_activity_log_subject ON activity_log(subject_type, subject_id);
CREATE INDEX IF NOT EXISTS idx_activity_log_causer ON activity_log(causer_type, causer_id);
CREATE INDEX IF NOT EXISTS idx_activity_log_name ON activity_log(log_name);

You can also retrieve this SQL programmatically:

import { ActivityService } from '@beeblock/svelar-activity-log';

const sql = ActivityService.getMigrationSQL();

3. Log an Activity

import { activity } from '@beeblock/svelar-activity-log';

await activity()
  .causedBy(user)
  .performedOn(post)
  .withProperties({ ip: '192.168.1.1' })
  .log('updated');

Configuration

The SvelarActivityLogPlugin constructor accepts the following options:

Core API

ActivityLogger (Fluent Builder)

The primary way to log activities. Create one via the activity() factory function:

import { activity } from '@beeblock/svelar-activity-log';

// Basic usage
await activity().log('user signed in');

// Full fluent API
await activity('billing')
  .causedBy(user)           // or .causedBy(userId, 'admins')
  .performedOn(invoice)     // or .onSubject('invoices', 42)
  .withProperties({ amount: 99.99, currency: 'USD' })
  .causerType('admins')
  .useLog('billing')
  .log('invoice paid');

Activity Class

Wraps a database row into a structured, read-only object:

const entry = await activity().causedBy(user).log('created');

entry.id;             // number
entry.logName;        // string
entry.description;    // string
entry.subjectType;    // string | null
entry.subjectId;      // number | null
entry.causerType;     // string
entry.causerId;       // number | null
entry.properties;     // Record<string, any>
entry.createdAt;      // string (ISO)

Instance methods:

Static methods:

ActivityService

Static service class for querying and managing activity logs:

import { ActivityService } from '@beeblock/svelar-activity-log';

// Fluent query builder
const activities = await ActivityService.query()
  .logName('billing')
  .forSubject('invoices', 42)
  .causedBy(1)
  .withDescription('paid')
  .since('2026-01-01')
  .until('2026-12-31')
  .latest()     // newest first (default)
  .limit(10)
  .get();

// Paginated results
const page = await ActivityService.query()
  .forSubject('posts')
  .paginate(1, 15);
// => { data: ActivityData[], total, page, perPage, lastPage, hasMore }

// Count matching activities
const count = await ActivityService.query()
  .logName('auth')
  .count();

Convenience methods:

Query builder methods:

LogsActivity Mixin

Automatically logs created, updated, and deleted events on any Model:

import { Model } from '@beeblock/svelar/database';
import { LogsActivity } from '@beeblock/svelar-activity-log';

class Post extends LogsActivity(Model) {
  static table = 'posts';
  static fillable = ['title', 'content', 'published'];

  // Which attributes to track (empty = all fillable)
  static logAttributes: string[] = ['title', 'content', 'published'];

  // Activity log name (defaults to table name)
  static logName = 'posts';

  // Only log attributes that actually changed (default: true)
  static logOnlyDirty = true;

  // Attributes to exclude from logging (hidden fields are also excluded)
  static logExcept: string[] = [];
}

When a model with LogsActivity is created, updated, or deleted, an activity log entry is automatically inserted with the tracked attribute changes in the properties field:

• Created: { new: { title: '...', content: '...' } }
• Updated: { old: { title: 'Old' }, new: { title: 'New' } }
• Deleted: { old: { title: '...', content: '...' } }

Static methods on the mixed model:

Causer Resolver

Set a global causer resolver so LogsActivity automatically knows who performed the action:

// In hooks.server.ts
import { setCauserResolver } from '@beeblock/svelar-activity-log';

setCauserResolver(() => {
  // Return the current authenticated user
  const user = getCurrentUser();
  return user ? { id: user.id, type: 'users' } : null;
});

Server-Side

ActivityController

Handles activity feed API routes with filtering and pagination:

// src/routes/api/activities/+server.ts
import { ActivityController } from '@beeblock/svelar-activity-log/server';

// Supports both GET (query params) and POST (JSON body)
export const GET = async (event) => ActivityController.handle(event);
export const POST = async (event) => ActivityController.handle(event);

// src/routes/api/activities/cleanup/+server.ts
import { ActivityController } from '@beeblock/svelar-activity-log/server';

export const POST = async (event) => ActivityController.handleCleanup(event);

Query parameters / body fields:

UI Components

ActivityFeed

A timeline feed that displays activity entries with icons, relative timestamps, and expandable change details:

<script lang="ts">
  import { ActivityFeed } from '@beeblock/svelar-activity-log/ui';
  import type { ActivityData, ActivityFilterOptions } from '@beeblock/svelar-activity-log';

  interface Props {
    data: { activities: ActivityData[] };
  }
  let { data }: Props = $props();
  let activities = $state(data.activities);
</script>

<ActivityFeed
  {activities}
  showFilters={true}
  showSubject={true}
  showCauser={true}
  showProperties={true}
  logNames={['default', 'auth', 'billing']}
  subjectTypes={['posts', 'users']}
  emptyText="No activity yet"
  hasMore={false}
  loading={false}
  onFilter={(filters) => console.log('Filter:', filters)}
  onLoadMore={() => console.log('Load more')}
/>

ActivityItem

A single timeline entry with icon, description, causer, subject, and expandable change table:

<script lang="ts">
  import { ActivityItem } from '@beeblock/svelar-activity-log/ui';
</script>

<ActivityItem
  activity={feedItem}
  showSubject={true}
  showCauser={true}
  showProperties={true}
/>

ActivityFilters

A filter panel with inputs for log name, subject type, causer ID, description, and date range:

<script lang="ts">
  import { ActivityFilters } from '@beeblock/svelar-activity-log/ui';
</script>

<ActivityFilters
  onFilter={(filters) => console.log(filters)}
  logNames={['default', 'auth']}
  subjectTypes={['posts', 'users']}
/>

Full Working Example

// src/lib/models/Post.ts
import { Model } from '@beeblock/svelar/database';
import { LogsActivity } from '@beeblock/svelar-activity-log';

export class Post extends LogsActivity(Model) {
  static table = 'posts';
  static fillable = ['title', 'content', 'published'];
  static logAttributes = ['title', 'content', 'published'];
  static logName = 'posts';
}

// src/hooks.server.ts
import { setCauserResolver } from '@beeblock/svelar-activity-log';

setCauserResolver(() => {
  // Your logic to get the current user
  return currentUser ? { id: currentUser.id, type: 'users' } : null;
});

// src/routes/api/activities/+server.ts
import { ActivityController } from '@beeblock/svelar-activity-log/server';

export const GET = async (event) => ActivityController.handle(event);
export const POST = async (event) => ActivityController.handle(event);

// src/routes/api/activities/cleanup/+server.ts
import { ActivityController } from '@beeblock/svelar-activity-log/server';

export const POST = async (event) => ActivityController.handleCleanup(event);

// src/routes/admin/activity/+page.server.ts
import { ActivityService } from '@beeblock/svelar-activity-log';

export async function load() {
  const result = await ActivityService.query()
    .latest()
    .paginate(1, 20);

  return { activities: result.data, total: result.total, hasMore: result.hasMore };
}

<!-- src/routes/admin/activity/+page.svelte -->
<script lang="ts">
  import { ActivityFeed } from '@beeblock/svelar-activity-log/ui';
  import { apiFetch } from '@beeblock/svelar/http';
  import type { ActivityData, ActivityFilterOptions } from '@beeblock/svelar-activity-log';

  interface Props {
    data: { activities: ActivityData[]; total: number; hasMore: boolean };
  }
  let { data }: Props = $props();
  let activities = $state(data.activities);
  let hasMore = $state(data.hasMore);
  let page = $state(1);
  let loading = $state(false);

  async function handleFilter(filters: ActivityFilterOptions) {
    loading = true;
    const res = await apiFetch('/api/activities', {
      method: 'POST',
      body: JSON.stringify({ ...filters, page: 1, per_page: 20 }),
    });
    const result = await res.json();
    activities = result.data;
    hasMore = result.hasMore;
    page = 1;
    loading = false;
  }

  async function handleLoadMore() {
    loading = true;
    page += 1;
    const res = await apiFetch(`/api/activities?page=${page}&per_page=20`);
    const result = await res.json();
    activities = [...activities, ...result.data];
    hasMore = result.hasMore;
    loading = false;
  }
</script>

<h1>Activity Log</h1>

<ActivityFeed
  {activities}
  showFilters={true}
  logNames={['default', 'auth', 'posts', 'billing']}
  subjectTypes={['posts', 'users', 'invoices']}
  onFilter={handleFilter}
  onLoadMore={handleLoadMore}
  {hasMore}
  {loading}
/>