Type Reference

All TypeScript types exported from @elcto/api.

REST Types

ApiResponse

Response wrapper for REST API calls.

interface ApiResponse<T> {
  data?: T;
  error?: string;
  status: number;
}

ApiRequestOptions

Options for REST API requests.

interface ApiRequestOptions {
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  body?: unknown;
  headers?: Record<string, string>;
  accessToken?: string;
}

GraphQL Types

GraphQLResponse

Response wrapper for GraphQL queries.

interface GraphQLResponse<T> {
  data?: T;
  errors?: Array<{ message: string; path?: string[] }>;
}

GraphQLRequestOptions

Options for GraphQL requests.

interface GraphQLRequestOptions {
  accessToken?: string;
  headers?: Record<string, string>;
}

WebSocket Types

WebSocketConfig

Configuration for WebSocket connections.

interface WebSocketConfig {
  accessToken?: string;
  autoReconnect?: boolean;
  reconnectDelay?: number;
  maxReconnectAttempts?: number;
}

WebSocketClient

WebSocket client interface.

interface WebSocketClient {
  socket: WebSocket;
  send: (data: unknown) => void;
  close: () => void;
  onMessage: (handler: WebSocketMessageHandler) => void;
  onError: (handler: WebSocketErrorHandler) => void;
  onClose: (handler: WebSocketCloseHandler) => void;
}

Handler Types

type WebSocketMessageHandler = (data: unknown) => void;
type WebSocketErrorHandler = (error: Event) => void;
type WebSocketCloseHandler = (event: CloseEvent) => void;

Server Message Types

// User status
type UserStatusMessageType = "accountDeleted" | "accountBanned" | "sessionRevoked" | "forceLogout";
type UserStatusMessage = AccountDeletedMessage | AccountBannedMessage | SessionRevokedMessage | ForceLogoutMessage;

// Permissions
type PermissionMessageType = "rolesUpdated" | "permissionsUpdated" | "rolePermissionsChanged";
type PermissionMessage = RolesUpdatedMessage | PermissionsUpdatedMessage | RolePermissionsChangedMessage;

// Account linking
type AccountLinkMessageType = "emailLinkVerified" | "emailChangeVerified";
type AccountLinkMessage = EmailLinkVerifiedMessage | EmailChangeVerifiedMessage;

// All server messages
type ServerMessage = UserStatusMessage | PermissionMessage | AccountLinkMessage;

User Types

UserProfile

User profile information.

interface UserProfile {
  name: string | null;
  picture: string | null;
  provider: string | null;
  primary_provider: string | null;
  last_login_at: string | null;
  created_at: string | null;
}

UserPermissions

User permissions and roles.

interface UserPermissions {
  /** Role names (e.g., "Admin", "Developer") - for display */
  roles: string[];
  /** Role IDs (e.g., "role_admin", "role_developer") - for programmatic checks */
  role_ids: string[];
  permissions: string[];
  is_super_admin: boolean;
}

tip

Use role_ids instead of roles for programmatic role checks. Role IDs are immutable and won't change if role names are renamed.

PlatformAccount

Connected platform account.

interface PlatformAccount {
  id: string;
  platform_id: string;
  platform_name: string;
  platform_slug: string;
  is_oauth: boolean;
  is_primary: boolean;
  username: string;
  email: string | null;
  avatar_url: string | null;
  created_at: string;
}

ActiveSession

Active login session information.

interface ActiveSession {
  id: string;
  ipAddress: string | null;
  userAgent: string | null;
  deviceType: string | null;
  browserName: string | null;
  osName: string | null;
  /** Auth provider slug used for this session (twitch, discord, email, etc.) */
  provider: string | null;
  /** Auth provider display name (Twitch, Discord, Email, etc.) */
  providerName: string | null;
  lastActivityAt: string | null;
  createdAt: string;
  expiresAt: string;
  isCurrent: boolean;
}

ActiveSessionsResponse

Response from active sessions API.

interface ActiveSessionsResponse {
  sessions: ActiveSession[];
  currentSessionId: string | null;
}

Audit Types

AuditEvent

Audit event record from the activity log.

interface AuditEvent {
  id: string;
  userId: string;
  eventType: string;
  resourceType?: string;
  resourceId?: string;
  actorId?: string;
  ipAddress?: string;
  userAgent?: string;
  description?: string;
  metadata?: Record<string, unknown>;
  status: "success" | "failure";
  errorMessage?: string;
  countryCode?: string;
  countryName?: string;
  city?: string;
  region?: string;
  sourceService?: string;
  createdAt: string;
  isReported: boolean;
}

sourceService Values:

Value	Description
`api`	Direct API calls
`id`	Heimdall ID app (account management)
`backend`	Heimdall Backend (admin console)
`policies`	Policies app
`discord_bot`	Discord bot
`twitch_bot`	Twitch bot

AuditEventPage

Paginated audit event response.

interface AuditEventPage {
  events: AuditEvent[];
  totalCount: number;
  page: number;
  limit: number;
  totalPages: number;
}

AuditEventQuery

Query parameters for filtering audit events.

interface AuditEventQuery {
  page?: number;
  limit?: number;
  eventType?: string;
  resourceType?: string;
  status?: string;
  userId?: string;  // Admin only
}

AuditEventReport

Report submitted for suspicious activity.

interface AuditEventReport {
  id: string;
  auditEventId: string;
  userId: string;
  reason: string;
  description?: string;
  status: "pending" | "reviewed" | "resolved" | "dismissed";
  reviewedBy?: string;
  reviewedAt?: string;
  resolutionNotes?: string;
  createdAt: string;
  updatedAt: string;
}

ReportAuditEventInput

Input for reporting an audit event.

interface ReportAuditEventInput {
  auditEventId: string;
  reason: "not_me" | "suspicious" | "unknown_device" | "unknown_location" | "other";
  description?: string;
}

ReportAuditEventResponse

Response from reporting an audit event.

interface ReportAuditEventResponse {
  success: boolean;
  report?: AuditEventReport;
  error?: string;
}

AuditReportPage (Admin)

Paginated audit reports response for admins.

interface AuditReportPage {
  reports: AuditEventReport[];
  totalCount: number;
  page: number;
  limit: number;
  totalPages: number;
}

UpdateAuditReportInput (Admin)

Input for updating an audit report status.

interface UpdateAuditReportInput {
  reportId: string;
  status: "reviewed" | "resolved" | "dismissed";
  resolutionNotes?: string;
}

UpdateAuditReportResponse (Admin)

Response from updating an audit report.

interface UpdateAuditReportResponse {
  success: boolean;
  report?: AuditEventReport;
  error?: string;
}

Audit Event Constants & Utilities

The library provides constants and helper functions for working with audit events.

AuditEventTypes

Type-safe constants for all audit event types:

import { AuditEventTypes } from "@elcto/api";

AuditEventTypes.LOGIN           // "login"
AuditEventTypes.LOGIN_FAILED    // "login_failed"
AuditEventTypes.LOGOUT          // "logout"
AuditEventTypes.TWO_FA_ENABLED  // "2fa_enabled"
AuditEventTypes.PASSWORD_CHANGED // "password_changed"
// ... and more

AuditEventLabels

Human-readable labels for event types:

import { AuditEventLabels, getAuditEventLabel } from "@elcto/api";

// Direct lookup
AuditEventLabels["login"]  // "Signed in"

// Helper function (with fallback)
getAuditEventLabel("login")         // "Signed in"
getAuditEventLabel("unknown_type")  // "unknown_type" (fallback)

Event Categories

Categorize events for filtering and display:

import {
  AuditEventCategories,
  getAuditEventCategory,
  type AuditEventCategory,
} from "@elcto/api";

// Categories: "security" | "account" | "sessions" | "oauth"
getAuditEventCategory("login")          // "security"
getAuditEventCategory("user_updated")   // "account"
getAuditEventCategory("session_created") // "sessions"
getAuditEventCategory("consent_granted") // "oauth"

Event Icons

Icon names for rendering audit event icons:

import {
  AuditEventIcons,
  getAuditEventIconName,
  type AuditIconName,
} from "@elcto/api";

// Icon names: "LogIn" | "LogOut" | "Shield" | "Key" | "User" | ...
getAuditEventIconName("login")       // "LogIn"
getAuditEventIconName("2fa_enabled") // "Shield"
getAuditEventIconName("password_changed") // "Key"

tip

Use the AuditIcon component from @elcto/ui to render these icons:

import { AuditIcon } from "@elcto/ui";
<AuditIcon eventType="login" className="w-4 h-4" />

Event Colors

Get colors for event categories and failure states:

import {
  AuditCategoryColors,
  AuditFailureColor,
  getAuditEventColor,
} from "@elcto/api";

// Color classes for categories
AuditCategoryColors.security  // "text-brand"
AuditCategoryColors.account   // "text-blue-400"
AuditCategoryColors.sessions  // "text-purple-400"
AuditCategoryColors.oauth     // "text-amber-400"

// Failure color
AuditFailureColor  // "text-[var(--error)]"

// Get color for specific event (considers failure state)
getAuditEventColor("login")        // "text-brand"
getAuditEventColor("login_failed") // "text-[var(--error)]"

Pre-built filter options for activity log dropdowns:

import { AuditFilterOptions, getAuditFilterEventTypes } from "@elcto/api";

// Use in a select/dropdown
<select>
  {AuditFilterOptions.map(option => (
    <option key={option.value} value={option.value}>
      {option.label}
    </option>
  ))}
</select>

// Get event types for a category filter
getAuditFilterEventTypes("security")
// Returns: ["login", "login_failed", "2fa_enabled", ...]

Common Types

PaginationParams

Pagination parameters for list requests.

interface PaginationParams {
  page?: number;
  limit?: number;
  offset?: number;
}

PaginatedResponse

Paginated response wrapper.

interface PaginatedResponse<T> {
  items: T[];
  total: number;
  page: number;
  limit: number;
  hasMore: boolean;
}

ApiConfig

API configuration.

interface ApiConfig {
  apiUrl: string;
  wsUrl: string;
  hasSystemKey: boolean;
}

Hook Types

UseWebSocketOptions

Options for the useWebSocket hook.

interface UseWebSocketOptions extends WebSocketConfig {
  immediate?: boolean;
}

UseWebSocketReturn

Return value from useWebSocket hook.

interface UseWebSocketReturn {
  isConnected: boolean;
  lastMessage: unknown;
  send: (data: unknown) => void;
  connect: () => void;
  disconnect: () => void;
}

Role Constants

The library exports role ID constants for type-safe role checks:

import {
  ROLE_SUPER_ADMIN,    // "role_super_admin"
  ROLE_ADMIN,          // "role_admin"
  ROLE_MODERATOR,      // "role_moderator"
  ROLE_DEVELOPER,      // "role_developer"
  ROLE_USER,           // "role_user"
  PRIVILEGED_ROLE_IDS, // Array of admin/mod/dev role IDs
} from "@/lib/api";

Helper Functions

import {
  hasPrivilegedRole,  // Check if user has admin/mod/dev role
  hasRole,            // Check if user has specific role
  hasAnyRole,         // Check if user has any of specified roles
  hasAllRoles,        // Check if user has all specified roles
} from "@/lib/api";

// Usage
const { roleIds, isSuperAdmin } = usePermissions();

if (isSuperAdmin || hasPrivilegedRole(roleIds)) {
  // User can access admin features
}

if (hasRole(roleIds, ROLE_DEVELOPER)) {
  // User has developer role
}

Importing Types

All types can be imported from @/lib/api:

import type {
  // REST
  ApiResponse,
  ApiRequestOptions,

  // GraphQL
  GraphQLResponse,
  GraphQLRequestOptions,

  // WebSocket
  WebSocketConfig,
  WebSocketClient,
  ServerMessage,
  UserStatusMessage,
  PermissionMessage,

  // User
  UserProfile,
  UserPermissions,
  PlatformAccount,
  ActiveSession,
  ActiveSessionsResponse,

  // Audit
  AuditEvent,
  AuditEventPage,
  AuditEventQuery,
  AuditEventReport,
  ReportAuditEventInput,
  ReportAuditEventResponse,
  AuditReportPage,
  UpdateAuditReportInput,
  UpdateAuditReportResponse,

  // Common
  PaginationParams,
  PaginatedResponse,
  ApiConfig,

  // Hooks
  UseWebSocketOptions,
  UseWebSocketReturn,
} from "@/lib/api";

// Role constants and helpers (not types)
import {
  ROLE_SUPER_ADMIN,
  ROLE_ADMIN,
  ROLE_MODERATOR,
  ROLE_DEVELOPER,
  ROLE_USER,
  PRIVILEGED_ROLE_IDS,
  hasPrivilegedRole,
  hasRole,
  hasAnyRole,
  hasAllRoles,
} from "@/lib/api";

REST Types​

ApiResponse​

ApiRequestOptions​

GraphQL Types​

GraphQLResponse​

GraphQLRequestOptions​

WebSocket Types​

WebSocketConfig​

WebSocketClient​

Handler Types​

Server Message Types​

User Types​

UserProfile​

UserPermissions​

PlatformAccount​

ActiveSession​

ActiveSessionsResponse​

Audit Types​

AuditEvent​

AuditEventPage​

AuditEventQuery​

AuditEventReport​

ReportAuditEventInput​

ReportAuditEventResponse​

AuditReportPage (Admin)​

UpdateAuditReportInput (Admin)​

UpdateAuditReportResponse (Admin)​

Audit Event Constants & Utilities​

AuditEventTypes​

AuditEventLabels​

Event Categories​

Event Icons​

Event Colors​

Filter Options​

Common Types​

PaginationParams​

PaginatedResponse​

ApiConfig​

Hook Types​

UseWebSocketOptions​

UseWebSocketReturn​

Role Constants​

Helper Functions​

Importing Types​