TypeScript Types

Everything you can import for type safety. Copy-paste from here when you need it.

Importing Types

import type {
  // Core
  Analytics,
  AnalyticsConfig,
  ErrorCaptureConfig,

  // User types
  UserTraits,
  AccountTraits,
  UserState,

  // Event types
  TrackEvent,
  IdentifyEvent,
  PageEvent,
  GroupEvent,
  EventContext,

  // Error types
  ErrorPayload,
  Breadcrumb,

  // Utility types
  LogLevel,
} from '@thisbefine/analytics';

Core Types

Analytics

The main class you interact with.

interface Analytics {
  // Event tracking
  track(event: string, properties?: Record<string, unknown>): void;
  page(name?: string, properties?: Record<string, unknown>): void;

  // User identification
  identify(userId: string, traits?: UserTraits): void;
  group(accountId: string, traits?: AccountTraits): void;
  reset(): void;
  getUser(): UserState;

  // Error tracking
  captureException(error: Error, context?: Record<string, unknown>): void;
  captureMessage(
    message: string,
    level?: 'warning' | 'error' | 'fatal',
    context?: Record<string, unknown>
  ): void;
  addBreadcrumb(breadcrumb: Omit<Breadcrumb, 'timestamp'>): void;

  // Logging
  log(
    message: string,
    level: LogLevel,
    metadata?: Record<string, unknown>
  ): void;

  // Privacy
  optOut(): void;
  optIn(): void;
  isOptedOut(): boolean;

  // Queue management
  flush(): Promise<void>;
}

AnalyticsConfig

Configuration for initializing the SDK.

interface AnalyticsConfig {
  apiKey: string;
  host?: string;
  flushAt?: number;
  flushInterval?: number;
  sessionTimeout?: number;
  cookieDomain?: string;
  debug?: boolean;
  respectDNT?: boolean;
  maxRetries?: number;
  errors?: ErrorCaptureConfig;
}

ErrorCaptureConfig

Configuration for error tracking.

interface ErrorCaptureConfig {
  enabled?: boolean;
  captureConsoleErrors?: boolean;
  captureNetworkErrors?: boolean;
  maxBreadcrumbs?: number;
  beforeSend?: (payload: ErrorPayload) => ErrorPayload | null;
}

User Types

UserTraits

Info about your users. The standard fields plus whatever you want.

interface UserTraits {
  email?: string;
  name?: string;
  avatar?: string;
  [key: string]: unknown;
}

Prop

Type

Example:

const traits: UserTraits = {
  email: 'jane@example.com',
  name: 'Jane Doe',
  avatar: 'https://example.com/avatar.jpg',
  // Go wild with custom fields
  plan: 'pro',
  role: 'admin',
  department: 'Engineering',
  signupDate: '2025-01-15',
};

AccountTraits

Info about accounts/teams/organizations.

interface AccountTraits {
  name?: string;
  plan?: string;
  mrr?: number;
  industry?: string;
  employeeCount?: number;
  createdAt?: string | Date;
  [key: string]: unknown;
}

Prop

Type

Example:

const accountTraits: AccountTraits = {
  name: 'Acme Corporation',
  plan: 'enterprise',
  mrr: 12000,
  industry: 'Technology',
  employeeCount: 150,
  createdAt: '2024-01-15',
  // Custom stuff
  region: 'north_america',
  contractType: 'annual',
};

UserState

What getUser() returns. The current state of user identification.

interface UserState {
  anonymousId: string;
  userId?: string;
  traits?: UserTraits;
  accountId?: string;
  accountTraits?: AccountTraits;
}

Prop

Type

Event Types

TrackEvent

interface TrackEvent {
  type: 'track';
  event: string;
  properties?: Record<string, unknown>;
  timestamp: string;
  anonymousId: string;
  userId?: string;
  sessionId?: string;
  accountId?: string;
  context?: EventContext;
}

IdentifyEvent

interface IdentifyEvent {
  type: 'identify';
  userId: string;
  traits?: UserTraits;
  timestamp: string;
  anonymousId: string;
  sessionId?: string;
  context?: EventContext;
}

PageEvent

interface PageEvent {
  type: 'page';
  name?: string;
  properties?: Record<string, unknown>;
  url: string;
  referrer?: string;
  timestamp: string;
  anonymousId: string;
  userId?: string;
  sessionId?: string;
  accountId?: string;
  context?: EventContext;
}

GroupEvent

interface GroupEvent {
  type: 'group';
  accountId: string;
  traits?: AccountTraits;
  timestamp: string;
  anonymousId: string;
  userId?: string;
  sessionId?: string;
  context?: EventContext;
}

EventContext

interface EventContext {
  library: {
    name: string;
    version: string;
  };
  userAgent: string;
  locale: string;
  timezone: string;
  screen?: {
    width: number;
    height: number;
  };
  page?: {
    url: string;
    path: string;
    referrer: string;
    title: string;
  };
}

Error Types

ErrorPayload

interface ErrorPayload {
  message: string;
  stack?: string;
  type?: string;
  level: 'warning' | 'error' | 'fatal';
  fingerprint: string;
  url?: string;
  breadcrumbs?: Breadcrumb[];
  tags?: Record<string, string>;
  context?: Record<string, unknown>;
  timestamp?: string;
  anonymousId?: string;
  userId?: string;
  sessionId?: string;
}

interface Breadcrumb {
  type: 'click' | 'navigation' | 'network' | 'console' | 'custom';
  message: string;
  timestamp?: string;
  data?: Record<string, unknown>;
}

Utility Types

LogLevel

type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';

Level	When to Use
`debug`	You're investigating something
`info`	Normal operations worth noting
`warn`	Something's sus but not broken
`error`	Something's broken
`fatal`	Everything's on fire

Constants

For reference, these are the internal constants. You probably don't need them, but they're exported if you do.

LIBRARY_INFO

const LIBRARY_INFO = {
  name: '@thisbefine/analytics',
  version: '0.1.0',
} as const;

DEFAULT_CONFIG

const DEFAULT_CONFIG = {
  host: 'https://thisbefine.com',
  flushAt: 20,
  flushInterval: 10000,
  sessionTimeout: 1800000,
  debug: false,
  respectDNT: true,
  maxRetries: 3,
} as const;

STORAGE_KEYS

Where stuff is stored in localStorage:

const STORAGE_KEYS = {
  ANONYMOUS_ID: 'tif_anonymous_id',
  USER_ID: 'tif_user_id',
  USER_TRAITS: 'tif_user_traits',
  ACCOUNT_ID: 'tif_account_id',
  ACCOUNT_TRAITS: 'tif_account_traits',
  SESSION_ID: 'tif_session_id',
  LAST_ACTIVITY: 'tif_last_activity',
  OPT_OUT: 'tif_opt_out',
} as const;

All prefixed with tif_ so they don't clash with your stuff.

TypeScript Types

On this page