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:

// Dedicated server-only plugin registration
import SvelarActivityLogPlugin from '@beeblock/svelar-activity-log/plugin';

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

// 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, ModelIdentifier, ActivityIdentifiable } 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

npx svelar plugin:publish @beeblock/svelar-activity-log
npx svelar migrate

The plugin publishes create_activity_log_table.ts, which creates the table and indexes through Svelar migrations. ActivityService.getMigrationSQL() is not part of the current API. Do not create this table from a route, service, or application bootstrap.

subject_id and causer_id are nullable VARCHAR(255) polymorphic references. Accept string | number inputs; storage and resources return canonical strings. UUIDs, ULIDs, custom primary keys, case, trailing spaces, and leading zeros retain their identity. A numeric 1 becomes '1', while '001' remains distinct. The activity row's own id remains numeric. MySQL queries compare both morph type and ID exactly with parameterized binary predicates.

These revised initial migrations belong to the unpublished alpha package. An existing installation must add a reviewed application migration that converts its old numeric morph columns and preserves its indexes and data. Polymorphic references do not add a host-user foreign key. Any application-owned foreign key must match its referenced primary key's actual database type, size, signedness, and collation; changing a column to VARCHAR does not make it compatible with a BIGINT or native UUID key.

3. Log an Activity

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

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

Configuration

The SvelarActivityLogPlugin constructor registers these defaults under the activity-log configuration key:

The logger, cleanup controller, and model mixin do not automatically read these configuration overrides. Pass the corresponding arguments or model settings explicitly. Publishing creates a migration; it does not bind routes or schedule retention cleanup.

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/server';

// 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

A Svelar ORM model with JSON-cast properties and a consistent resource representation:

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

entry.id;             // number
entry.logName;        // string
entry.description;    // string
entry.subjectType;    // string | null
entry.subjectId;      // string | null
entry.causerType;     // string
entry.causerId;       // string | 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/server';

// 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

The logger and mixin read a model key with model.getAttribute(model.constructor.primaryKey). Passing a real model also infers its table as the morph type, including custom primary-key names. setCauserResolver accepts a real model or { id: string | number, type?: string }.

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

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

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

Register one resolver at application setup and read the actor from request-scoped context. Do not replace a global resolver with a closure over each request's user.

// This wrapper runs after the application's Svelar authentication middleware.
import { ApplicationContext } from '@beeblock/svelar/support';
import { setCauserResolver } from '@beeblock/svelar-activity-log/server';

setCauserResolver(() => ApplicationContext.get('activityCauser') ?? null);

export async function handle({ event, resolve }) {
  return ApplicationContext.run(
    { activityCauser: event.locals.auth?.user() ?? null },
    () => resolve(event),
  );
}

Automatic logs follow instance lifecycle hooks. Hidden fields and logExcept are excluded. withoutLogging suppresses only its async operation, while disableLogging changes the model's shared setting.

Server-Side

ActivityController

Handles activity feed API routes with filtering and pagination. Authentication must populate the current user first. Configure the application policies/permissions behind both activity-log.view and activity-log.cleanup Gate abilities; missing or denied abilities fail closed. Register literal capability manifests and seed their catalogs/profiles when access is user-configurable. Protect the host page/controller with its reviewed capability scope as well.

Generic plugin endpoints reject bearer credentials, so a credential ceiling cannot inherit browser-user authority. POST requests require CSRF. Reads validate the shared filter schema; cleanup uses CleanupActivitiesRequest → CleanupActivitiesDTO → CleanupActivitiesAction → ORM service. Successful reads return { data: ActivityData[], meta: { total, page, perPage, lastPage, hasMore } }; cleanup returns { data: { deleted }, meta: {} }.

Keep route files thin:

// 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 = $derived(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/orm';
import { LogsActivity } from '@beeblock/svelar-activity-log/server';

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 { ApplicationContext } from '@beeblock/svelar/support';
import { setCauserResolver } from '@beeblock/svelar-activity-log/server';

setCauserResolver(() => ApplicationContext.get('activityCauser') ?? null);

// Run this wrapper after authentication has populated event.locals.auth.
export async function handle({ event, resolve }) {
  return ApplicationContext.run(
    { activityCauser: event.locals.auth?.user() ?? null },
    () => resolve(event),
  );
}

// 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 { error } from '@sveltejs/kit';
import { ActivityController } from '@beeblock/svelar-activity-log/server';

// Host page authorization and the controller's activity-log.view Gate both apply.
export async function load(event) {
  const response = await ActivityController.handle(event);
  const result = await response.json();
  if (!response.ok) error(response.status, result.meta?.message ?? 'Unable to load activity.');
  return { activities: result.data, total: result.meta.total, hasMore: result.meta.hasMore };
}

<!-- src/routes/admin/activity/+page.svelte -->
<script lang="ts">
  import { untrack } from 'svelte';
  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(untrack(() => data.activities));
  let hasMore = $state(untrack(() => data.hasMore));
  let page = $state(1);
  let loading = $state(false);

  let errorMessage = $state('');
  let currentFilters = $state<ActivityFilterOptions>({});

  async function fetchPage(filters: ActivityFilterOptions, nextPage: number) {
    const res = await apiFetch('/api/activities', {
      method: 'POST', showToast: false,
      body: JSON.stringify({
        log_name: filters.logName, subject_type: filters.subjectType,
        subject_id: filters.subjectId, causer_type: filters.causerType,
        causer_id: filters.causerId, description: filters.description,
        since: filters.since, until: filters.until, sort: filters.sortDirection,
        page: nextPage, per_page: 20,
      }),
    });
    const result = await res.json();
    if (!res.ok) throw new Error(result.meta?.message ?? 'Unable to load activity.');
    return result;
  }

  async function handleFilter(filters: ActivityFilterOptions) {
    if (loading) return;
    loading = true; errorMessage = '';
    try {
      const result = await fetchPage(filters, 1);
      currentFilters = filters; activities = result.data;
      hasMore = result.meta.hasMore; page = 1;
    } catch (error) { errorMessage = error instanceof Error ? error.message : 'Unable to load activity.'; }
    finally { loading = false; }
  }

  async function handleLoadMore() {
    if (loading || !hasMore) return;
    loading = true; errorMessage = '';
    try {
      const result = await fetchPage(currentFilters, page + 1);
      activities = [...activities, ...result.data];
      hasMore = result.meta.hasMore; page += 1;
    } catch (error) { errorMessage = error instanceof Error ? error.message : 'Unable to load activity.'; }
    finally { loading = false; }
  }
</script>

<h1>Activity Log</h1>
{#if errorMessage}<p role='alert'>{errorMessage}</p>{/if}

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