Skip to main content

​
AuthEvent

Represents a single authentication event. 
interface AuthEvent {
  id: string;
  type: AuthEventType;
  timestamp: Date;
  status: "success" | "failed";
  userId?: string;
  sessionId?: string;
  organizationId?: string;
  metadata?: Record<string, any>;
  ipAddress?: string;
  userAgent?: string;
  source: "app" | "api";
  display?: {
    message: string;
    severity?: "info" | "success" | "warning" | "failed";
  };
}

​
Fields

​
id
string
required
Unique identifier for the event (UUID)
​
type
AuthEventType
required
The type of authentication event (e.g., "user.joined", "user.logged_in")
​
timestamp
Date
required
When the event occurred
​
status
'success' | 'failed'
required
Whether the event completed successfully or failed
​
userId
string
ID of the user associated with this event
​
sessionId
string
ID of the session associated with this event
​
organizationId
string
ID of the organization associated with this event
​
metadata
Record<string, any>
Additional event-specific data (e.g., user name, email, changed fields)
​
ipAddress
string
IP address where the event originated
​
userAgent
string
User agent string from the client
​
source
'app' | 'api'
required
Source of the event - either from your app or API
​
display
object
Display information for rendering in UI
​
display.message
string
Human-readable message describing the event
​
display.severity
'info' | 'success' | 'warning' | 'failed'
Severity level for UI styling

​
AuthEventType

String union type of all possible authentication event types. 
type AuthEventType =
  // User events
  | "user.joined"
  | "user.logged_in"
  | "user.updated"
  | "user.logged_out"
  | "user.password_changed"
  | "user.email_verified"
  | "user.banned"
  | "user.unbanned"
  | "user.deleted"
  | "user.delete_verification_requested"
  // Organization events
  | "organization.created"
  | "organization.deleted"
  | "organization.updated"
  // Member events
  | "member.added"
  | "member.removed"
  | "member.role_changed"
  // Session events
  | "session.created"
  // Auth events
  | "login.failed"
  // Password events
  | "password.reset_requested"
  | "password.reset_completed"
  | "password.reset_requested_otp"
  | "password.reset_completed_otp"
  // OAuth events
  | "oauth.linked"
  | "oauth.unlinked"
  | "oauth.sign_in"
  // Team events
  | "team.created"
  | "team.updated"
  | "team.deleted"
  | "team.member.added"
  | "team.member.removed"
  // Invitation events
  | "invitation.created"
  | "invitation.accepted"
  | "invitation.rejected"
  | "invitation.cancelled"
  // Phone number events
  | "phone_number.otp_requested"
  | "phone_number.verification";

​
EventQueryOptions

Options for querying events. 
interface EventQueryOptions {
  limit?: number;
  offset?: number;
  after?: string;
  sort?: "asc" | "desc";
  type?: string;
  userId?: string;
  since?: Date;
}

​
Fields

​
limit
number
default:20
Maximum number of events to return
​
offset
number
Offset for pagination (fetch from N). When provided, cursor-based pagination is disabled.
​
after
string
Cursor for pagination (used when offset not provided). Returns events after this event ID.
​
sort
'asc' | 'desc'
default:"desc"
Sort order:
  • "desc": Newest first (default)
  • "asc": Oldest first
​
type
string
Filter by event type (e.g., "user.logged_in")
​
userId
string
Filter events for a specific user
​
since
Date
Filter events since this timestamp

​
EventQueryResult

Result from querying events. 
interface EventQueryResult {
  events: AuthEvent[];
  hasMore: boolean;
  nextCursor: string | null;
}

​
Fields

​
events
AuthEvent[]
required
Array of events matching the query
​
hasMore
boolean
required
Whether there are more events available for pagination
​
nextCursor
string | null
required
Cursor to use for fetching the next page. null if no more events.

​
EventStats

Statistical breakdown of events by severity. 
interface EventStats {
  total: number;
  success: number;
  failed: number;
  warning: number;
  info: number;
}

​
Fields

​
total
number
required
Total number of events
​
success
number
required
Number of events with success severity
​
failed
number
required
Number of events with failed severity
​
warning
number
required
Number of events with warning severity
​
info
number
required
Number of events with info severity

​
EVENT_TEMPLATES

Mapping of event types to message template functions. Used to generate human-readable messages for events. 
const EVENT_TEMPLATES: Record<AuthEventType, (event: AuthEvent) => string>

​
Usage

import { EVENT_TEMPLATES } from "better-auth-studio";
import type { AuthEvent } from "better-auth-studio";

const event: AuthEvent = {
  id: "123",
  type: "user.logged_in",
  timestamp: new Date(),
  status: "success",
  userId: "user-456",
  metadata: { name: "Alice", email: "[email protected]" },
  source: "app",
};

const message = EVENT_TEMPLATES[event.type](event);
console.log(message); // "Alice logged in"

​
Template Examples

  • user.joined (success): "Alice joined!"
  • user.joined (failed): "[email protected] failed to join"
  • user.logged_in (success): "Alice logged in"
  • organization.created (success): "New organization \"Acme Corp\" created by Alice"
  • login.failed: "Failed login attempt for [email protected]"

​
getEventSeverity

Helper function to determine the severity level of an event. 
function getEventSeverity(
  event: AuthEvent | { type: AuthEventType; status?: "success" | "failed" },
  status?: "success" | "failed"
): "info" | "success" | "warning" | "failed"

​
Parameters

​
event
AuthEvent | { type: AuthEventType; status?: 'success' | 'failed' }
required
The event object or minimal event-like object with type and status
​
status
'success' | 'failed'
Optional status override. If provided, uses this instead of event.status.

​
Returns

​
severity
'info' | 'success' | 'warning' | 'failed'
required
The severity level based on event type and status:
  • "failed": Status is failed, or event type indicates failure/ban/deletion
  • "success": Event indicates successful completion (joined, created, verified, logged in)
  • "warning": Event indicates caution (reset requests, verifications)
  • "info": Default for updates, changes, and other informational events

​
Example

import { getEventSeverity } from "better-auth-studio";

const severity1 = getEventSeverity({ type: "user.joined", status: "success" });
console.log(severity1); // "success"

const severity2 = getEventSeverity({ type: "login.failed" });
console.log(severity2); // "failed"

const severity3 = getEventSeverity({ type: "password.reset_requested" });
console.log(severity3); // "warning"

Build docs developers (and LLMs) love

Get started for freeTalk to us