@tracearr/shared 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,2484 @@
+/**
+ * Core type definitions for Tracearr
+ */
+import type { webhookFormatSchema, sessionTargetSchema, statPeriodSchema } from './schemas.js';
+import type { z } from 'zod';
+type SessionTarget = z.infer<typeof sessionTargetSchema>;
+export type UserRole = 'owner' | 'admin' | 'viewer' | 'member' | 'disabled' | 'pending';
+export declare const ROLE_PERMISSIONS: Record<UserRole, number>;
+export declare const LOGIN_ROLES: UserRole[];
+export declare const canLogin: (role: UserRole) => boolean;
+export declare const hasMinRole: (userRole: UserRole, required: "owner" | "admin" | "viewer") => boolean;
+export declare const isOwner: (role: UserRole) => boolean;
+export declare const isActive: (role: UserRole) => boolean;
+export type ServerType = 'plex' | 'jellyfin' | 'emby';
+export interface Server {
+    id: string;
+    name: string;
+    type: ServerType;
+    url: string;
+    displayOrder?: number;
+    color?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface User {
+    id: string;
+    username: string;
+    name: string | null;
+    thumbnail: string | null;
+    email: string | null;
+    role: UserRole;
+    aggregateTrustScore: number;
+    totalViolations: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ServerUser {
+    id: string;
+    userId: string;
+    serverId: string;
+    externalId: string;
+    username: string;
+    email: string | null;
+    thumbUrl: string | null;
+    isServerAdmin: boolean;
+    trustScore: number;
+    joinedAt: Date | null;
+    lastActivityAt: Date | null;
+    removedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+    identityName?: string | null;
+}
+export interface ServerUserWithIdentity extends ServerUser {
+    serverName: string;
+    identityName: string | null;
+    role: UserRole;
+    identityServers?: {
+        id: string;
+        name: string;
+        serverUserId?: string;
+        removedAt?: string | null;
+    }[];
+    identityTrustScore?: number;
+}
+export interface ServerUserDetail extends ServerUserWithIdentity {
+    stats: {
+        totalSessions: number;
+        totalWatchTime: number;
+    };
+}
+export interface ViolationSummary {
+    id: string;
+    ruleId: string;
+    rule: {
+        name: string;
+        type: string;
+    };
+    serverUserId: string;
+    serverId: string;
+    serverName: string;
+    sessionId: string | null;
+    mediaTitle: string | null;
+    severity: string;
+    data: Record<string, unknown>;
+    createdAt: Date;
+    acknowledgedAt: Date | null;
+}
+export interface ServerUserFullDetail {
+    user: ServerUserDetail;
+    identity: {
+        userId: string;
+        aggregateTrustScore: number;
+        totalViolations: number;
+        serverUsers: {
+            id: string;
+            serverId: string;
+            serverName: string;
+            serverType: string;
+            username: string;
+            thumbUrl: string | null;
+            trustScore: number;
+            sessionCount: number;
+            removedAt: Date | null;
+        }[];
+        stats: {
+            totalSessions: number;
+            totalWatchTime: number;
+        };
+    };
+    sessions: {
+        data: Session[];
+        total: number;
+        hasMore: boolean;
+    };
+    locations: UserLocation[];
+    devices: UserDevice[];
+    violations: {
+        data: ViolationSummary[];
+        total: number;
+        hasMore: boolean;
+    };
+    terminations: {
+        data: TerminationLogWithDetails[];
+        total: number;
+        hasMore: boolean;
+    };
+}
+export interface AuthUser {
+    userId: string;
+    username: string;
+    role: UserRole;
+    serverIds: string[];
+    mobile?: boolean;
+    deviceId?: string;
+}
+export interface UserMergeResult {
+    targetUserId: string;
+    auditId: string;
+    movedServerUserIds: string[];
+    combinedServerUsers: {
+        sourceServerUserId: string;
+        targetServerUserId: string;
+        serverId: string;
+    }[];
+    wasSameServerCombine: boolean;
+    droppedRuleNames: string[];
+}
+export interface ServerUserSplitResult {
+    newUserId: string;
+    serverUserId: string;
+}
+export interface MergeSuggestionIdentity {
+    userId: string;
+    username: string;
+    name: string | null;
+    email: string | null;
+    role: UserRole;
+    loginCapable: boolean;
+    serverUsers: {
+        id: string;
+        serverId: string;
+        serverName: string;
+        username: string;
+        email: string | null;
+        removedAt: string | null;
+    }[];
+}
+export interface MergeSuggestion {
+    matchType: 'email' | 'username';
+    matchValue: string;
+    users: [MergeSuggestionIdentity, MergeSuggestionIdentity];
+    requiredTargetUserId: string | null;
+    wouldCombineSameServer: boolean;
+}
+export interface SetupStatus {
+    needsSetup: boolean;
+    requiresClaimCode: boolean;
+    hasServers: boolean;
+    hasJellyfinServers: boolean;
+    hasPasswordAuth: boolean;
+    authMethods: {
+        local: boolean;
+        plex: boolean;
+        oidc: boolean;
+        oidcProviderName: string | null;
+    };
+}
+export type SessionState = 'playing' | 'paused' | 'stopped';
+/** Supported media types */
+export declare const MEDIA_TYPES: readonly ["movie", "episode", "track", "live", "photo", "trailer", "unknown"];
+export type MediaType = (typeof MEDIA_TYPES)[number];
+/** Source video details from original media file */
+export interface SourceVideoDetails {
+    bitrate?: number;
+    framerate?: string;
+    dynamicRange?: string;
+    aspectRatio?: number;
+    profile?: string;
+    level?: string;
+    colorSpace?: string;
+    colorDepth?: number;
+}
+/** Source audio details from original media file */
+export interface SourceAudioDetails {
+    bitrate?: number;
+    channelLayout?: string;
+    language?: string;
+    sampleRate?: number;
+}
+/** Stream video details after transcode */
+export interface StreamVideoDetails {
+    bitrate?: number;
+    width?: number;
+    height?: number;
+    framerate?: string;
+    dynamicRange?: string;
+}
+/** Stream audio details after transcode */
+export interface StreamAudioDetails {
+    bitrate?: number;
+    channels?: number;
+    language?: string;
+}
+/** Transcode processing information */
+export interface TranscodeInfo {
+    containerDecision?: string;
+    sourceContainer?: string;
+    streamContainer?: string;
+    hwRequested?: boolean;
+    hwDecoding?: string;
+    hwEncoding?: string;
+    speed?: number;
+    throttled?: boolean;
+    reasons?: string[];
+}
+/** Subtitle stream information */
+export interface SubtitleInfo {
+    decision?: string;
+    codec?: string;
+    language?: string;
+    forced?: boolean;
+}
+/**
+ * Common fields for stream metadata tracking.
+ * Used by Session, ProcessedSession, MediaSession.quality, and test fixtures.
+ * All fields are nullable for backwards compatibility with existing sessions.
+ */
+export interface StreamDetailFields {
+    sourceVideoCodec: string | null;
+    sourceAudioCodec: string | null;
+    sourceAudioChannels: number | null;
+    sourceVideoWidth: number | null;
+    sourceVideoHeight: number | null;
+    sourceVideoDetails: SourceVideoDetails | null;
+    sourceAudioDetails: SourceAudioDetails | null;
+    streamVideoCodec: string | null;
+    streamAudioCodec: string | null;
+    streamVideoDetails: StreamVideoDetails | null;
+    streamAudioDetails: StreamAudioDetails | null;
+    transcodeInfo: TranscodeInfo | null;
+    subtitleInfo: SubtitleInfo | null;
+}
+/**
+ * Default values for stream detail fields (all null).
+ * Use with spread operator for test fixtures and initial values.
+ */
+export declare const DEFAULT_STREAM_DETAILS: StreamDetailFields;
+export interface Session extends StreamDetailFields {
+    id: string;
+    serverId: string;
+    serverName?: string;
+    serverUserId: string;
+    sessionKey: string;
+    state: SessionState;
+    mediaType: MediaType;
+    mediaTitle: string;
+    grandparentTitle: string | null;
+    seasonNumber: number | null;
+    episodeNumber: number | null;
+    year: number | null;
+    thumbPath: string | null;
+    ratingKey: string | null;
+    serverVersionKey: string | null;
+    parentRatingKey: string | null;
+    grandparentRatingKey: string | null;
+    mediaId: string | null;
+    showMediaId: string | null;
+    imdbId: string | null;
+    tmdbId: number | null;
+    tvdbId: number | null;
+    externalSessionId: string | null;
+    startedAt: Date;
+    stoppedAt: Date | null;
+    durationMs: number | null;
+    totalDurationMs: number | null;
+    progressMs: number | null;
+    lastPausedAt: Date | null;
+    pausedDurationMs: number;
+    referenceId: string | null;
+    watched: boolean;
+    ipAddress: string;
+    geoCity: string | null;
+    geoRegion: string | null;
+    geoCountry: string | null;
+    geoContinent: string | null;
+    geoPostal: string | null;
+    geoLat: number | null;
+    geoLon: number | null;
+    geoAsnNumber: number | null;
+    geoAsnOrganization: string | null;
+    playerName: string | null;
+    deviceId: string | null;
+    product: string | null;
+    device: string | null;
+    platform: string | null;
+    quality: string | null;
+    isTranscode: boolean;
+    videoDecision: string | null;
+    audioDecision: string | null;
+    bitrate: number | null;
+    channelTitle: string | null;
+    channelIdentifier: string | null;
+    channelThumb: string | null;
+    artistName: string | null;
+    albumName: string | null;
+    trackNumber: number | null;
+    discNumber: number | null;
+}
+export interface ActiveSession extends Session {
+    user: Pick<ServerUser, 'id' | 'username' | 'thumbUrl'> & {
+        identityName: string | null;
+    };
+    server: Pick<Server, 'id' | 'name' | 'type'>;
+    /** Whether this session can be terminated (some clients like Plexamp don't support termination) */
+    canTerminate: boolean;
+    /** True while the session is an unconfirmed pending entry; absent once confirmed. */
+    pending?: boolean;
+}
+export interface SessionSegment {
+    startedAt: string;
+    stoppedAt: string | null;
+    durationMs: number | null;
+    pausedDurationMs: number;
+}
+export interface SessionWithDetails extends Omit<Session, 'ratingKey' | 'externalSessionId'> {
+    user: Pick<ServerUser, 'id' | 'username' | 'thumbUrl'> & {
+        identityName: string | null;
+    };
+    server: Pick<Server, 'id' | 'name' | 'type'>;
+    segmentCount?: number;
+    segments?: SessionSegment[];
+}
+export type RuleType = 'impossible_travel' | 'simultaneous_locations' | 'device_velocity' | 'concurrent_streams' | 'geo_restriction' | 'account_inactivity';
+export interface ImpossibleTravelParams {
+    maxSpeedKmh: number;
+    ignoreVpnRanges?: boolean;
+    /** When true, exclude sessions from private/local network IPs from comparison */
+    excludePrivateIps?: boolean;
+}
+export interface SimultaneousLocationsParams {
+    minDistanceKm: number;
+    /** When true, exclude sessions from private/local network IPs from comparison */
+    excludePrivateIps?: boolean;
+}
+export interface DeviceVelocityParams {
+    maxIps: number;
+    windowHours: number;
+    /** When true, exclude private/local network IPs (192.168.x.x, 10.x.x.x, etc.) from unique IP count */
+    excludePrivateIps?: boolean;
+    /** When true, count by deviceId instead of IP - same device with different IPs counts as 1 */
+    groupByDevice?: boolean;
+}
+export interface ConcurrentStreamsParams {
+    maxStreams: number;
+    /** When true, exclude sessions from private/local network IPs from stream count */
+    excludePrivateIps?: boolean;
+}
+export type GeoRestrictionMode = 'blocklist' | 'allowlist';
+export interface GeoRestrictionParams {
+    mode: GeoRestrictionMode;
+    countries: string[];
+    /** When true, always allow sessions from private/local network IPs (default behavior, explicit option) */
+    excludePrivateIps?: boolean;
+}
+/** Time unit for inactivity threshold */
+export type AccountInactivityUnit = 'days' | 'weeks' | 'months';
+export interface AccountInactivityParams {
+    /** Inactivity threshold value (e.g., 30, 7, 3) */
+    inactivityValue: number;
+    /** Time unit for the inactivity threshold */
+    inactivityUnit: AccountInactivityUnit;
+}
+export type RuleParams = ImpossibleTravelParams | SimultaneousLocationsParams | DeviceVelocityParams | ConcurrentStreamsParams | GeoRestrictionParams | AccountInactivityParams;
+export interface Rule {
+    id: string;
+    name: string;
+    type: RuleType | null;
+    params: RuleParams | null;
+    description?: string | null;
+    severity?: ViolationSeverity;
+    conditions?: RuleConditions | null;
+    actions?: RuleActions | null;
+    serverId?: string | null;
+    userId?: string | null;
+    identityName?: string | null;
+    enforceAcrossServers?: boolean;
+    serverUserId: string | null;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
+export type ArrayOperator = 'in' | 'not_in';
+export type StringOperator = 'contains' | 'not_contains';
+export type Operator = ComparisonOperator | ArrayOperator | StringOperator;
+export type SessionBehaviorField = 'concurrent_streams' | 'active_session_distance_km' | 'travel_speed_kmh' | 'unique_ips_in_window' | 'unique_devices_in_window' | 'inactive_days' | 'current_pause_minutes' | 'total_pause_minutes';
+export type StreamQualityField = 'source_resolution' | 'output_resolution' | 'is_transcoding' | 'is_transcode_downgrade' | 'source_bitrate_mbps';
+export type TranscodingConditionValue = 'video' | 'audio' | 'video_or_audio' | 'neither';
+export type UserAttributeField = 'user_id' | 'trust_score' | 'account_age_days';
+export type DeviceClientField = 'device_type' | 'client_name' | 'platform';
+export type NetworkLocationField = 'is_local_network' | 'country' | 'ip_in_range';
+export type ScopeField = 'server_id' | 'media_type';
+export type ConditionField = SessionBehaviorField | StreamQualityField | UserAttributeField | DeviceClientField | NetworkLocationField | ScopeField;
+export type VideoResolution = '4K' | '1080p' | '720p' | '480p' | 'SD' | 'unknown';
+export type DeviceType = 'mobile' | 'tablet' | 'tv' | 'desktop' | 'browser' | 'unknown';
+export type Platform = 'ios' | 'android' | 'windows' | 'macos' | 'linux' | 'tvos' | 'androidtv' | 'roku' | 'webos' | 'tizen' | 'unknown';
+export type MediaTypeEnum = 'movie' | 'episode' | 'track' | 'photo' | 'live' | 'trailer';
+export type ConditionValue = string | number | boolean | string[] | number[];
+export interface ConditionEvidence {
+    field: ConditionField;
+    operator: Operator;
+    threshold: ConditionValue;
+    actual: unknown;
+    matched: boolean;
+    relatedSessionIds?: string[];
+    details?: Record<string, unknown>;
+}
+export interface GroupEvidence {
+    groupIndex: number;
+    matched: boolean;
+    conditions: ConditionEvidence[];
+}
+export interface Condition {
+    field: ConditionField;
+    operator: Operator;
+    value: ConditionValue;
+    params?: {
+        window_hours?: number;
+        exclude_same_device?: boolean;
+        exclude_same_ip?: boolean;
+        count_device_types?: DeviceType[];
+    };
+}
+export interface ConditionGroup {
+    conditions: Condition[];
+}
+export interface RuleConditions {
+    groups: ConditionGroup[];
+}
+export type ActionType = 'log_only' | 'notify' | 'adjust_trust' | 'set_trust' | 'reset_trust' | 'kill_stream' | 'message_client';
+export type NotificationChannelV2 = 'push' | 'discord' | 'email' | 'webhook';
+export interface LogOnlyAction {
+    type: 'log_only';
+    message?: string;
+}
+export interface NotifyAction {
+    type: 'notify';
+    channels: NotificationChannelV2[];
+    cooldown_minutes?: number;
+}
+export interface AdjustTrustAction {
+    type: 'adjust_trust';
+    amount: number;
+}
+export interface SetTrustAction {
+    type: 'set_trust';
+    value: number;
+}
+export interface ResetTrustAction {
+    type: 'reset_trust';
+}
+export interface KillStreamAction {
+    type: 'kill_stream';
+    /** Seconds to wait before killing. The kill only fires if the rule condition still holds after the wait; 0 (default) still re-checks once before killing. */
+    delay_seconds?: number;
+    require_confirmation?: boolean;
+    cooldown_minutes?: number;
+    /** Message to display to user before termination. If omitted, terminates silently. */
+    message?: string;
+    target?: SessionTarget;
+}
+export interface MessageClientAction {
+    type: 'message_client';
+    message: string;
+    target?: SessionTarget;
+}
+export type Action = LogOnlyAction | NotifyAction | AdjustTrustAction | SetTrustAction | ResetTrustAction | KillStreamAction | MessageClientAction;
+export interface RuleActions {
+    actions: Action[];
+}
+export interface RuleV2 {
+    id: string;
+    name: string;
+    description: string | null;
+    serverId: string | null;
+    serverUserId: string | null;
+    userId: string | null;
+    enforceAcrossServers: boolean;
+    isActive: boolean;
+    severity: ViolationSeverity;
+    conditions: RuleConditions;
+    actions: RuleActions;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ActionResult {
+    actionType: string;
+    success: boolean;
+    skipped?: boolean;
+    skipReason?: string;
+    errorMessage?: string;
+    executedAt?: string;
+}
+export type ViolationSeverity = 'low' | 'warning' | 'high';
+export interface Violation {
+    id: string;
+    ruleId: string;
+    serverUserId: string;
+    sessionId: string | null;
+    severity: ViolationSeverity;
+    data: Record<string, unknown>;
+    createdAt: Date;
+    acknowledgedAt: Date | null;
+}
+export interface ViolationSessionInfo {
+    id: string;
+    mediaTitle: string;
+    mediaType: MediaType;
+    grandparentTitle: string | null;
+    seasonNumber: number | null;
+    episodeNumber: number | null;
+    year: number | null;
+    ipAddress: string;
+    geoCity: string | null;
+    geoRegion: string | null;
+    geoCountry: string | null;
+    geoContinent: string | null;
+    geoPostal: string | null;
+    geoLat: number | null;
+    geoLon: number | null;
+    playerName: string | null;
+    device: string | null;
+    deviceId: string | null;
+    platform: string | null;
+    product: string | null;
+    quality: string | null;
+    startedAt: Date;
+}
+export interface ViolationWithDetails extends Violation {
+    rule: Pick<Rule, 'id' | 'name'> & {
+        type: RuleType | null;
+    };
+    user: Pick<ServerUser, 'id' | 'username' | 'thumbUrl' | 'serverId'> & {
+        identityName: string | null;
+        userId?: string;
+    };
+    server?: Pick<Server, 'id' | 'name' | 'type'>;
+    session?: ViolationSessionInfo;
+    relatedSessions?: ViolationSessionInfo[];
+    userHistory?: {
+        previousIPs: string[];
+        previousDevices: string[];
+        previousLocations: Array<{
+            city: string | null;
+            country: string | null;
+            ip: string;
+        }>;
+    };
+    /** Action results from V2 rule execution */
+    actionResults?: ActionResult[];
+    /** Condition evidence from V2 rule evaluation */
+    evidence?: GroupEvidence[];
+    /** Display names for server-user IDs found in evidence conditions (detail endpoint only) */
+    userNames?: Record<string, string>;
+}
+export interface DashboardStats {
+    activeStreams: number;
+    todayPlays: number;
+    todaySessions: number;
+    watchTimeHours: number;
+    alertsLast24h: number;
+    activeUsersToday: number;
+}
+export interface PlayStats {
+    date: string;
+    count: number;
+    serverId: string;
+}
+export interface UserStats {
+    serverUserId: string;
+    username: string;
+    thumbUrl: string | null;
+    playCount: number;
+    watchTimeHours: number;
+}
+export interface LocationUserInfo {
+    id: string;
+    username: string;
+    thumbUrl: string | null;
+}
+export interface LocationStats {
+    city: string | null;
+    region: string | null;
+    country: string | null;
+    lat: number;
+    lon: number;
+    count: number;
+    lastActivity?: Date;
+    firstActivity?: Date;
+    users?: LocationUserInfo[];
+    deviceCount?: number;
+    servers?: {
+        serverId: string;
+        count: number;
+    }[];
+}
+export interface LocationStatsSummary {
+    totalStreams: number;
+    uniqueLocations: number;
+    topCity: string | null;
+}
+export interface LocationFilterOptions {
+    users: {
+        id: string;
+        username: string;
+        identityName: string | null;
+        serverUserIds: string[];
+    }[];
+    servers: {
+        id: string;
+        name: string;
+    }[];
+    mediaTypes: MediaType[];
+}
+export interface LocationStatsResponse {
+    data: LocationStats[];
+    summary: LocationStatsSummary;
+    availableFilters: LocationFilterOptions;
+}
+export interface LibraryStats {
+    movies: number;
+    shows: number;
+    episodes: number;
+    tracks: number;
+}
+export interface DayOfWeekStats {
+    day: number;
+    name: string;
+    count: number;
+}
+export interface HourOfDayStats {
+    hour: number;
+    count: number;
+}
+export interface QualityStats {
+    directPlay: number;
+    directStream: number;
+    transcode: number;
+    total: number;
+    directPlayPercent: number;
+    directStreamPercent: number;
+    transcodePercent: number;
+}
+export interface TopUserStats {
+    /** Identity (person) id - plays/watch time are summed across all their accounts */
+    userId: string;
+    /** Representative account id, used for navigation (routes to /users/:id) */
+    serverUserId: string;
+    username: string;
+    identityName: string | null;
+    thumbUrl: string | null;
+    /** Representative account's server, used for avatar proxy */
+    serverId: string | null;
+    /** Identity-level aggregate trust score, not the representative account's own score */
+    trustScore: number;
+    playCount: number;
+    watchTimeHours: number;
+    topMediaType: string | null;
+    topContent: string | null;
+    /** Every server this identity has an account on, scoped to accessible servers */
+    identityServers?: {
+        id: string;
+        name: string;
+    }[];
+}
+export interface TopContentStats {
+    title: string;
+    type: string;
+    showTitle: string | null;
+    year: number | null;
+    playCount: number;
+    watchTimeHours: number;
+    thumbPath: string | null;
+    serverId: string | null;
+    ratingKey: string | null;
+}
+export interface PlatformStats {
+    platform: string | null;
+    count: number;
+}
+export interface ServerResourceDataPoint {
+    /** Unix timestamp */
+    at: number;
+    /** Timespan interval in seconds */
+    timespan: number;
+    /** System-wide CPU utilization percentage */
+    hostCpuUtilization: number;
+    /** Plex process CPU utilization percentage */
+    processCpuUtilization: number;
+    /** System-wide memory utilization percentage */
+    hostMemoryUtilization: number;
+    /** Plex process memory utilization percentage */
+    processMemoryUtilization: number;
+}
+export interface ServerResourceStats {
+    /** Server ID these stats belong to */
+    serverId: string;
+    /** Data points (newest first based on 'at' timestamp) */
+    data: ServerResourceDataPoint[];
+    /** When this data was fetched */
+    fetchedAt: Date;
+}
+export interface ServerBandwidthDataPoint {
+    /** Unix timestamp */
+    at: number;
+    /** Timespan interval in seconds */
+    timespan: number;
+    /** Total local (LAN) bandwidth in bytes for this interval */
+    lanBytes: number;
+    /** Total remote (WAN) bandwidth in bytes for this interval */
+    wanBytes: number;
+}
+export interface ServerBandwidthStats {
+    /** Server ID these stats belong to */
+    serverId: string;
+    /** Data points (newest first based on 'at' timestamp) */
+    data: ServerBandwidthDataPoint[];
+    /** When this data was fetched */
+    fetchedAt: Date;
+}
+export type WebhookFormat = z.infer<typeof webhookFormatSchema>;
+export type UnitSystem = 'metric' | 'imperial';
+export interface Settings {
+    allowGuestAccess: boolean;
+    unitSystem: UnitSystem;
+    discordWebhookUrl: string | null;
+    customWebhookUrl: string | null;
+    webhookFormat: WebhookFormat | null;
+    ntfyTopic: string | null;
+    ntfyAuthToken: string | null;
+    pushoverApiToken: string | null;
+    pushoverUserKey: string | null;
+    pollerEnabled: boolean;
+    pollerIntervalMs: number;
+    usePlexGeoip: boolean;
+    tautulliUrl: string | null;
+    tautulliApiKey: string | null;
+    externalUrl: string | null;
+    trustProxy: boolean;
+    mobileEnabled: boolean;
+    tailscaleEnabled: boolean;
+    tailscaleHostname: string | null;
+    backupScheduleType: BackupScheduleType;
+    backupScheduleTime: string;
+    backupScheduleDayOfWeek: number;
+    backupScheduleDayOfMonth: number;
+    backupRetentionCount: number;
+    pluginUpdateCheckEnabled: boolean;
+    pluginManifestUrl: string | null;
+    watchedThresholdMovie: number;
+    watchedThresholdTv: number;
+    watchedThresholdMusic: number;
+    publicApiRateLimitPerMinute: number;
+    imagePrecacheEnabled: boolean;
+    preferredPosterServerId: string | null;
+}
+export type TailscaleStatus = 'disabled' | 'starting' | 'awaiting_auth' | 'connected' | 'error' | 'stopping';
+export interface TailscaleExitNode {
+    id: string;
+    hostname: string;
+    dnsName: string;
+    ip: string;
+    online: boolean;
+    active: boolean;
+}
+export interface TailscaleInfo {
+    status: TailscaleStatus;
+    authUrl: string | null;
+    hostname: string | null;
+    dnsName: string | null;
+    tailnetName: string | null;
+    tailnetIp: string | null;
+    tailnetUrl: string | null;
+    exitNodes: TailscaleExitNode[];
+    error: string | null;
+    available: boolean;
+}
+export interface HeavyOpsWaitingFor {
+    jobType: 'import' | 'maintenance';
+    description: string;
+    startedAt: string;
+}
+export interface TautulliImportProgress {
+    status: 'idle' | 'waiting' | 'fetching' | 'processing' | 'complete' | 'error';
+    /** Expected total from API (may differ from actual if API count is stale) */
+    totalRecords: number;
+    /** Actual records fetched from API so far */
+    fetchedRecords: number;
+    /** Records processed (looped through) */
+    processedRecords: number;
+    /** New sessions inserted */
+    importedRecords: number;
+    /** Existing sessions updated with new data */
+    updatedRecords: number;
+    /** Total skipped (sum of duplicate + unknownUser + activeSession) */
+    skippedRecords: number;
+    /** Skipped: already exists in DB or duplicate in this import */
+    duplicateRecords: number;
+    /** Skipped: user not found in Tracearr (need to sync server first) */
+    unknownUserRecords: number;
+    /** Skipped: in-progress sessions without reference_id */
+    activeSessionRecords: number;
+    /** Records that failed to process */
+    errorRecords: number;
+    currentPage: number;
+    totalPages: number;
+    message: string;
+    /** Present when status='waiting' - what this job is waiting for */
+    waitingFor?: HeavyOpsWaitingFor;
+}
+export interface TautulliImportResult {
+    success: boolean;
+    imported: number;
+    updated: number;
+    /** Number of sessions linked via referenceId (resume chain detection) */
+    linked: number;
+    skipped: number;
+    errors: number;
+    message: string;
+    /** Details about users that were skipped (not found in Tracearr) */
+    skippedUsers?: {
+        tautulliUserId: number;
+        username: string;
+        recordCount: number;
+    }[];
+}
+export interface JellystatImportProgress {
+    status: 'idle' | 'waiting' | 'parsing' | 'enriching' | 'processing' | 'complete' | 'error';
+    totalRecords: number;
+    processedRecords: number;
+    importedRecords: number;
+    skippedRecords: number;
+    /** Number of records filtered out (theme songs, theme videos, trailers, etc.) */
+    filteredRecords: number;
+    errorRecords: number;
+    /** Number of media items enriched with metadata from Jellyfin */
+    enrichedRecords: number;
+    /** Current phase message */
+    message: string;
+    /** Present when status='waiting' - what this job is waiting for */
+    waitingFor?: HeavyOpsWaitingFor;
+}
+export interface JellystatImportResult {
+    success: boolean;
+    imported: number;
+    updated: number;
+    skipped: number;
+    /** Number of records filtered out (theme songs, theme videos, trailers, etc.) */
+    filtered: number;
+    errors: number;
+    enriched: number;
+    message: string;
+    /** Details about users that were skipped (not found in Tracearr) */
+    skippedUsers?: {
+        jellyfinUserId: string;
+        username: string | null;
+        recordCount: number;
+    }[];
+}
+export interface LibrarySyncProgress {
+    serverId: string;
+    serverName: string;
+    status: 'running' | 'complete' | 'error';
+    currentLibrary?: string;
+    currentLibraryName?: string;
+    totalLibraries: number;
+    processedLibraries: number;
+    totalItems: number;
+    processedItems: number;
+    message: string;
+    startedAt: string;
+    completedAt?: string;
+    error?: string;
+}
+export interface ServerToClientEvents {
+    'session:started': (session: ActiveSession) => void;
+    'session:stopped': (sessionId: string) => void;
+    'session:updated': (session: ActiveSession) => void;
+    'violation:new': (violation: ViolationWithDetails) => void;
+    'stats:updated': (stats: DashboardStats) => void;
+    'import:progress': (progress: TautulliImportProgress) => void;
+    'import:jellystat:progress': (progress: JellystatImportProgress) => void;
+    'maintenance:progress': (progress: MaintenanceJobProgress) => void;
+    'library:sync:progress': (progress: LibrarySyncProgress) => void;
+    'tasks:updated': (tasks: RunningTask[]) => void;
+    'version:update': (data: {
+        current: string;
+        latest: string;
+        releaseUrl: string;
+    }) => void;
+    'server:down': (data: {
+        serverId: string;
+        serverName: string;
+    }) => void;
+    'server:up': (data: {
+        serverId: string;
+        serverName: string;
+    }) => void;
+    'server:connection': (status: ServerConnectionStatus) => void;
+}
+export interface ClientToServerEvents {
+    'subscribe:sessions': () => void;
+    'unsubscribe:sessions': () => void;
+}
+export interface UserLocation {
+    city: string | null;
+    region: string | null;
+    country: string | null;
+    lat: number | null;
+    lon: number | null;
+    sessionCount: number;
+    lastSeenAt: Date;
+    ipAddresses: string[];
+}
+export interface DeviceLocation {
+    city: string | null;
+    region: string | null;
+    country: string | null;
+    sessionCount: number;
+    lastSeenAt: Date;
+}
+export interface UserDevice {
+    deviceId: string | null;
+    playerName: string | null;
+    product: string | null;
+    device: string | null;
+    platform: string | null;
+    sessionCount: number;
+    lastSeenAt: Date;
+    locations: DeviceLocation[];
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+/**
+ * Aggregate stats returned with history query results.
+ * These are computed across the entire filtered result set (not just current page).
+ */
+export interface HistoryAggregates {
+    /** Total watch time in milliseconds across all matching sessions */
+    totalWatchTimeMs: number;
+    /** Count of unique plays (grouped by reference_id) */
+    playCount: number;
+    /** Count of unique users in the result set */
+    uniqueUsers: number;
+    /** Count of unique content items watched */
+    uniqueContent: number;
+}
+/**
+ * Response shape for history/sessions queries with cursor-based pagination.
+ * Aggregate stats are fetched separately via /sessions/history/aggregates.
+ */
+export interface HistorySessionResponse {
+    data: SessionWithDetails[];
+    /** Cursor for fetching the next page (undefined if no more results) */
+    nextCursor?: string;
+    /** Whether more results exist beyond the current page */
+    hasMore: boolean;
+}
+/**
+ * Option item with count for filter dropdowns.
+ * Count represents number of plays with this value.
+ */
+export interface FilterOptionItem {
+    value: string;
+    count: number;
+}
+/**
+ * User option for user filter dropdown.
+ */
+export interface UserFilterOption {
+    id: string;
+    username: string;
+    thumbUrl: string | null;
+    serverId: string;
+    identityName: string | null;
+    /** All server account ids belonging to this person (identity), access-scoped. */
+    serverUserIds: string[];
+}
+/**
+ * Server option for server filter dropdown.
+ */
+export interface ServerFilterOption {
+    id: string;
+    name: string;
+    type: 'plex' | 'jellyfin' | 'emby';
+}
+/**
+ * Country option with session activity indicator.
+ * Used when includeAllCountries=true for rules builder.
+ */
+export interface CountryOption {
+    code: string;
+    name: string;
+    hasSessions: boolean;
+}
+/**
+ * Available filter options for the history page.
+ * Returned by GET /sessions/filter-options to populate dropdowns.
+ */
+export interface HistoryFilterOptions {
+    /** Available platforms (Windows, macOS, iOS, etc.) */
+    platforms: FilterOptionItem[];
+    /** Available products/apps (Plex for Windows, etc.) */
+    products: FilterOptionItem[];
+    /** Available device types (iPhone, Android TV, etc.) */
+    devices: FilterOptionItem[];
+    /** Available countries (codes with session count) */
+    countries: FilterOptionItem[];
+    /** Available cities */
+    cities: FilterOptionItem[];
+    /** Available users (with avatar info) */
+    users: UserFilterOption[];
+    /** Available servers (optional, included when requested) */
+    servers?: ServerFilterOption[];
+}
+/**
+ * Extended filter options for rules builder.
+ * Includes all countries with session indicators and servers.
+ */
+export interface RulesFilterOptions extends Omit<HistoryFilterOptions, 'countries'> {
+    /** All countries with session activity indicator */
+    countries: CountryOption[];
+    /** Available servers */
+    servers: ServerFilterOption[];
+}
+export interface ApiError {
+    statusCode: number;
+    error: string;
+    message: string;
+}
+export interface MobileToken {
+    id: string;
+    expiresAt: Date;
+    createdAt: Date;
+    usedAt: Date | null;
+}
+export interface MobilePairTokenResponse {
+    token: string;
+    expiresAt: Date;
+}
+export interface MobileSession {
+    id: string;
+    deviceName: string;
+    deviceId: string;
+    platform: 'ios' | 'android';
+    expoPushToken: string | null;
+    lastSeenAt: Date;
+    createdAt: Date;
+}
+export interface MobileConfig {
+    isEnabled: boolean;
+    sessions: MobileSession[];
+    serverName: string;
+    pendingTokens: number;
+    maxDevices: number;
+}
+export interface MobilePairRequest {
+    token: string;
+    deviceName: string;
+    deviceId: string;
+    platform: 'ios' | 'android';
+}
+export interface MobilePairResponse {
+    accessToken: string;
+    refreshToken: string;
+    server: {
+        id: string;
+        name: string;
+        type: 'plex' | 'jellyfin' | 'emby';
+    };
+    user: {
+        userId: string;
+        username: string;
+        role: 'owner';
+    };
+}
+export interface MobileQRPayload {
+    url: string;
+    token: string;
+    name: string;
+}
+export type NotificationEventType = 'violation_detected' | 'stream_started' | 'stream_stopped' | 'concurrent_streams' | 'new_device' | 'trust_score_changed' | 'server_down' | 'server_up' | 'plugin_update_available';
+export interface NotificationPreferences {
+    id: string;
+    mobileSessionId: string;
+    pushEnabled: boolean;
+    onViolationDetected: boolean;
+    onStreamStarted: boolean;
+    onStreamStopped: boolean;
+    onConcurrentStreams: boolean;
+    onNewDevice: boolean;
+    onTrustScoreChanged: boolean;
+    onServerDown: boolean;
+    onServerUp: boolean;
+    violationMinSeverity: number;
+    violationRuleTypes: string[];
+    maxPerMinute: number;
+    maxPerHour: number;
+    quietHoursEnabled: boolean;
+    quietHoursStart: string | null;
+    quietHoursEnd: string | null;
+    quietHoursTimezone: string;
+    quietHoursOverrideCritical: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface RateLimitStatus {
+    remainingMinute: number;
+    remainingHour: number;
+    resetMinuteIn: number;
+    resetHourIn: number;
+}
+export interface NotificationPreferencesWithStatus extends NotificationPreferences {
+    rateLimitStatus?: RateLimitStatus;
+}
+export type NotificationChannel = 'discord' | 'webhook' | 'push' | 'webToast';
+export interface NotificationChannelRouting {
+    id: string;
+    eventType: NotificationEventType;
+    discordEnabled: boolean;
+    webhookEnabled: boolean;
+    pushEnabled: boolean;
+    webToastEnabled: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface EncryptedPushPayload {
+    v: 1;
+    iv: string;
+    salt: string;
+    ct: string;
+    tag: string;
+}
+export interface PushNotificationPayload {
+    type: NotificationEventType;
+    title: string;
+    body: string;
+    data?: Record<string, unknown>;
+    channelId?: string;
+    badge?: number;
+    sound?: string | boolean;
+    priority?: 'default' | 'high';
+}
+export type SSEConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'fallback' | 'unsupported';
+export interface PlexSSENotification {
+    NotificationContainer: {
+        type: string;
+        size: number;
+        PlaySessionStateNotification?: PlexPlaySessionNotification[];
+        ActivityNotification?: PlexActivityNotification[];
+        StatusNotification?: PlexStatusNotification[];
+        TranscodeSession?: PlexTranscodeNotification[];
+        TimelineEntry?: PlexTimelineEntry[];
+    };
+}
+export interface PlexPlaySessionNotification {
+    sessionKey: string;
+    clientIdentifier: string;
+    guid: string;
+    ratingKey: string;
+    url: string;
+    key: string;
+    viewOffset: number;
+    playQueueItemID: number;
+    state: 'playing' | 'paused' | 'stopped' | 'buffering';
+}
+export interface PlexTimelineEntry {
+    identifier: string;
+    sectionID?: number;
+    itemID: number;
+    type: number;
+    title?: string;
+    state: number;
+    updatedAt?: number;
+}
+export interface PlexActivityNotification {
+    event: string;
+    uuid: string;
+    Activity: {
+        uuid: string;
+        type: string;
+        cancellable: boolean;
+        userID: number;
+        title: string;
+        subtitle: string;
+        progress: number;
+        Context?: {
+            key: string;
+        };
+    };
+}
+export interface PlexStatusNotification {
+    title: string;
+    description: string;
+    notificationName: string;
+}
+export interface PlexTranscodeNotification {
+    key: string;
+    throttled: boolean;
+    complete: boolean;
+    progress: number;
+    size: number;
+    speed: number;
+    error: boolean;
+    duration: number;
+    remaining: number;
+    context: string;
+    sourceVideoCodec: string;
+    sourceAudioCodec: string;
+    videoDecision: string;
+    audioDecision: string;
+    subtitleDecision: string;
+    protocol: string;
+    container: string;
+    videoCodec: string;
+    audioCodec: string;
+    audioChannels: number;
+    transcodeHwRequested: boolean;
+    transcodeHwDecoding: string;
+    transcodeHwEncoding: string;
+    transcodeHwDecodingTitle: string;
+    transcodeHwEncodingTitle: string;
+}
+export interface SSEConnectionStatus {
+    serverId: string;
+    serverName: string;
+    state: SSEConnectionState;
+    connectedAt: Date | null;
+    lastEventAt: Date | null;
+    reconnectAttempts: number;
+    error: string | null;
+    pluginVersion?: string | null;
+}
+export type PluginIssue = 'missing' | 'blocked' | 'restart_required' | 'malfunctioned' | 'unknown';
+export interface ServerConnectionStatus {
+    serverId: string;
+    serverName: string;
+    serverType: ServerType;
+    mode: 'realtime' | 'polling';
+    state: SSEConnectionState;
+    lastEventAt: string | null;
+    since: string | null;
+    error: string | null;
+    pluginVersion: string | null;
+    pluginUpdateAvailable: boolean;
+    pluginIssue: PluginIssue | null;
+}
+export type TerminationTrigger = 'manual' | 'rule';
+export interface TerminationLogWithDetails {
+    id: string;
+    sessionId: string;
+    serverId: string;
+    serverName: string | null;
+    serverUserId: string;
+    trigger: TerminationTrigger;
+    triggeredByUserId: string | null;
+    triggeredByUsername: string | null;
+    ruleId: string | null;
+    ruleName: string | null;
+    violationId: string | null;
+    reason: string | null;
+    success: boolean;
+    errorMessage: string | null;
+    createdAt: Date;
+    mediaTitle: string | null;
+    mediaType: MediaType | null;
+    grandparentTitle: string | null;
+    seasonNumber: number | null;
+    episodeNumber: number | null;
+    year: number | null;
+    artistName: string | null;
+    albumName: string | null;
+}
+export type PlexConnectionErrorCode = 'timeout' | 'dns' | 'refused' | 'unreachable' | 'reset' | 'tls' | 'http' | 'unknown';
+export interface PlexConnectionError {
+    code: PlexConnectionErrorCode;
+    message: string;
+    status?: number;
+}
+export interface PlexDiscoveredConnection {
+    uri: string;
+    local: boolean;
+    address: string;
+    port: number;
+    reachable: boolean;
+    latencyMs: number | null;
+    custom?: boolean;
+    error?: PlexConnectionError;
+}
+export interface PlexDiscoveredServer {
+    name: string;
+    platform: string;
+    version: string;
+    clientIdentifier: string;
+    recommendedUri: string | null;
+    connections: PlexDiscoveredConnection[];
+}
+export interface PlexAvailableServersResponse {
+    servers: PlexDiscoveredServer[];
+    hasPlexToken: boolean;
+}
+export interface PlexAccount {
+    id: string;
+    plexAccountId: string;
+    plexUsername: string | null;
+    plexEmail: string | null;
+    plexThumbnail: string | null;
+    allowLogin: boolean;
+    serverCount: number;
+    createdAt: Date;
+}
+export interface PlexAccountsResponse {
+    accounts: PlexAccount[];
+}
+export interface LinkPlexAccountRequest {
+    pin: string;
+}
+export interface LinkPlexAccountResponse {
+    account: PlexAccount;
+}
+export interface UnlinkPlexAccountResponse {
+    success: boolean;
+}
+export type MaintenanceJobCategory = 'normalization' | 'backfill' | 'cleanup';
+export type MaintenanceJobType = 'normalize_players' | 'normalize_countries' | 'fix_imported_progress' | 'rebuild_timescale_views' | 'normalize_codecs' | 'normalize_resolutions' | 'backfill_user_dates' | 'backfill_library_snapshots' | 'normalize_library_snapshots' | 'cleanup_old_chunks' | 'full_aggregate_rebuild' | 'repair_corrupted_chunks' | 'backfill_session_identity';
+export type MaintenanceJobStatus = 'idle' | 'waiting' | 'running' | 'complete' | 'error';
+export interface MaintenanceJobProgress {
+    type: MaintenanceJobType;
+    status: MaintenanceJobStatus;
+    totalRecords: number;
+    processedRecords: number;
+    updatedRecords: number;
+    skippedRecords: number;
+    errorRecords: number;
+    message: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** Present when status='waiting' - what this job is waiting for */
+    waitingFor?: HeavyOpsWaitingFor;
+}
+export interface MaintenanceJobResult {
+    success: boolean;
+    type: MaintenanceJobType;
+    processed: number;
+    updated: number;
+    skipped: number;
+    errors: number;
+    durationMs: number;
+    message: string;
+}
+export type RunningTaskType = 'library_sync' | 'tautulli_import' | 'jellystat_import' | 'maintenance';
+export interface RunningTask {
+    /** Unique task identifier */
+    id: string;
+    /** Task type for categorization */
+    type: RunningTaskType;
+    /** Human-readable task name */
+    name: string;
+    /** Current status */
+    status: 'pending' | 'waiting' | 'running' | 'complete' | 'error';
+    /** Progress percentage (0-100), null if indeterminate */
+    progress: number | null;
+    /** Current status message */
+    message: string;
+    /** When the task started */
+    startedAt: string;
+    /** Additional context (e.g., server name, job type) */
+    context?: string;
+    /** What the task is waiting for (only when status is 'waiting') */
+    waitingFor?: HeavyOpsWaitingFor;
+}
+export interface RunningTasksResponse {
+    tasks: RunningTask[];
+}
+export type EngagementTier = 'abandoned' | 'sampled' | 'engaged' | 'watched' | 'rewatched' | 'unknown';
+export type UserBehaviorType = 'inactive' | 'sampler' | 'casual' | 'completionist' | 'rewatcher';
+export interface ContentEngagement {
+    ratingKey: string;
+    mediaTitle: string;
+    showTitle: string | null;
+    mediaType: MediaType;
+    thumbPath: string | null;
+    serverId: string | null;
+    year: number | null;
+    plays: number;
+    completionPct: number;
+    engagementTier: EngagementTier;
+    cumulativeWatchedMs: number;
+    validSessions: number;
+    totalSessions: number;
+    firstWatchedAt: Date;
+    lastWatchedAt: Date;
+}
+export interface TopContentEngagement {
+    ratingKey: string;
+    title: string;
+    showTitle: string | null;
+    type: MediaType;
+    thumbPath: string | null;
+    serverId: string | null;
+    year: number | null;
+    totalPlays: number;
+    totalWatchHours: number;
+    uniqueViewers: number;
+    validSessions: number;
+    totalSessions: number;
+    completions: number;
+    rewatches: number;
+    abandonments: number;
+    completionRate: number;
+    abandonmentRate: number;
+}
+export interface ShowEngagement {
+    showTitle: string;
+    thumbPath: string | null;
+    serverId: string | null;
+    year: number | null;
+    totalEpisodeViews: number;
+    totalWatchHours: number;
+    uniqueViewers: number;
+    avgEpisodesPerViewer: number;
+    avgCompletionRate: number;
+    bingeScore: number;
+    validSessions: number;
+    totalSessions: number;
+}
+export interface UserEngagementProfile {
+    serverUserId: string;
+    username: string;
+    thumbUrl: string | null;
+    identityName: string | null;
+    contentStarted: number;
+    totalPlays: number;
+    totalWatchHours: number;
+    validSessionCount: number;
+    totalSessionCount: number;
+    abandonedCount: number;
+    sampledCount: number;
+    engagedCount: number;
+    watchedCount: number;
+    rewatchedCount: number;
+    completionRate: number;
+    behaviorType: UserBehaviorType;
+    favoriteMediaType: MediaType | null;
+}
+export interface EngagementTierBreakdown {
+    tier: EngagementTier;
+    count: number;
+    percentage: number;
+}
+export interface EngagementStats {
+    topContent: TopContentEngagement[];
+    topShows: ShowEngagement[];
+    engagementBreakdown: EngagementTierBreakdown[];
+    userProfiles: UserEngagementProfile[];
+    summary: {
+        totalPlays: number;
+        totalValidSessions: number;
+        totalAllSessions: number;
+        sessionInflationPct: number;
+        avgCompletionRate: number;
+    };
+}
+export interface ShowStatsResponse {
+    data: ShowEngagement[];
+    total: number;
+}
+export interface VersionInfo {
+    current: {
+        version: string;
+        tag: string | null;
+        commit: string | null;
+        buildDate: string | null;
+        isPrerelease: boolean;
+    };
+    latest: {
+        version: string;
+        tag: string;
+        releaseUrl: string;
+        publishedAt: string;
+        isPrerelease: boolean;
+        releaseName: string | null;
+        releaseNotes: string | null;
+    } | null;
+    updateAvailable: boolean;
+    lastChecked: string | null;
+}
+export interface DeviceCompatibilityRow {
+    deviceType: string;
+    videoCodec: string;
+    audioCodec: string;
+    sessionCount: number;
+    videoDirectCount: number;
+    audioDirectCount: number;
+    fullDirectCount: number;
+    anyTranscodeCount: number;
+    videoDirectPct: number;
+    audioDirectPct: number;
+    fullDirectPct: number;
+}
+export interface DeviceCompatibilityResponse {
+    data: DeviceCompatibilityRow[];
+    summary: {
+        totalSessions: number;
+        directPlayPct: number;
+        uniqueDevices: number;
+        uniqueCodecs: number;
+    };
+}
+export interface DeviceCompatibilityMatrix {
+    codecs: string[];
+    devices: {
+        device: string;
+        codecs: Record<string, {
+            sessions: number;
+            directPct: number;
+        }>;
+    }[];
+}
+export interface DeviceHealthRow {
+    serverId: string;
+    device: string;
+    sessions: number;
+    directPlayCount: number;
+    transcodeCount: number;
+    directPlayPct: number;
+}
+export interface DeviceHealthResponse {
+    data: DeviceHealthRow[];
+}
+export interface TranscodeHotspotRow {
+    serverId: string;
+    device: string;
+    videoCodec: string;
+    audioCodec: string;
+    sessions: number;
+    directCount: number;
+    transcodeCount: number;
+    directPlayPct: number;
+    pctOfTotalTranscodes: number;
+}
+export interface TranscodeHotspotsResponse {
+    data: TranscodeHotspotRow[];
+    totalTranscodes: number;
+}
+export interface TopTranscodingUserRow {
+    serverId: string;
+    serverUserId: string;
+    username: string;
+    identityName: string | null;
+    avatar: string | null;
+    totalSessions: number;
+    directPlayCount: number;
+    transcodeCount: number;
+    directPlayPct: number;
+    pctOfTotalTranscodes: number;
+}
+export interface TopTranscodingUsersResponse {
+    data: TopTranscodingUserRow[];
+    totalTranscodes: number;
+}
+export interface DailyBandwidthRow {
+    date: string;
+    /** Server this row belongs to - required for per-server chart series */
+    serverId: string;
+    sessions: number;
+    /** Total data transferred in bytes */
+    totalBytes: number;
+    /** Total data transferred in GB (human-readable) */
+    totalGb: number;
+    avgBitrate: number;
+    peakBitrate: number;
+    totalDurationMs: number;
+    avgBitrateMbps: number;
+    totalHours: number;
+}
+export interface DailyBandwidthResponse {
+    data: DailyBandwidthRow[];
+    usingAggregate: boolean;
+}
+export interface BandwidthTopUser {
+    username: string;
+    /** Display name from linked identity (null if no linked user) */
+    identityName: string | null;
+    /** Avatar URL from server user */
+    thumbUrl: string | null;
+    /** Representative account id, used for navigation (routes to /users/:id) */
+    serverUserId: string;
+    /** Representative account's server - a merged identity is one row, bytes summed across servers */
+    serverId: string;
+    /** Total data transferred in bytes */
+    totalBytes: number;
+    /** Total data transferred in GB (human-readable) */
+    totalGb: number;
+    sessions: number;
+    avgBitrate: number;
+    totalDurationMs: number;
+    avgBitrateMbps: number;
+    totalHours: number;
+}
+export interface BandwidthTopUsersResponse {
+    data: BandwidthTopUser[];
+}
+export interface BandwidthSummaryServerKpis {
+    totalSessions: number;
+    totalBytes: number;
+    totalGb: number;
+    avgBitrate: number;
+    peakBitrate: number;
+    minBitrate: number;
+    medianBitrate: number;
+    totalDurationMs: number;
+    uniqueUsers: number;
+    avgBitrateMbps: number;
+    peakBitrateMbps: number;
+    totalHours: number;
+}
+export interface BandwidthSummary {
+    totalSessions: number;
+    /** Total data transferred in bytes */
+    totalBytes: number;
+    /** Total data transferred in GB (human-readable) */
+    totalGb: number;
+    avgBitrate: number;
+    peakBitrate: number;
+    minBitrate: number;
+    medianBitrate: number;
+    totalDurationMs: number;
+    uniqueUsers: number;
+    avgBitrateMbps: number;
+    peakBitrateMbps: number;
+    totalHours: number;
+    /** Per-server KPI breakdown keyed by server ID (present when multiple servers selected) */
+    byServer?: Record<string, BandwidthSummaryServerKpis>;
+}
+export interface LibraryStatsResponse {
+    totalItems: number;
+    totalSizeBytes: string;
+    movieCount: number;
+    episodeCount: number;
+    showCount: number;
+    qualityBreakdown: {
+        count4k: number;
+        count1080p: number;
+        count720p: number;
+        countSd: number;
+    };
+    asOf: string | null;
+}
+export interface GrowthDataPoint {
+    day: string;
+    total: number;
+    additions: number;
+    /** Server that produced this data point (present in multi-server responses) */
+    serverId: string;
+}
+export interface LibraryGrowthResponse {
+    period: string;
+    movies: GrowthDataPoint[];
+    episodes: GrowthDataPoint[];
+    music: GrowthDataPoint[];
+}
+export interface QualityDataPoint {
+    day: string;
+    totalItems: number;
+    count4k: number;
+    count1080p: number;
+    count720p: number;
+    countSd: number;
+    pct4k: number;
+    pct1080p: number;
+    pct720p: number;
+    pctSd: number;
+    hevcCount: number;
+    h264Count: number;
+    av1Count: number;
+}
+export interface LibraryQualityResponse {
+    period: string;
+    mediaType: 'all' | 'movies' | 'shows';
+    data: QualityDataPoint[];
+}
+export interface StorageHistoryPoint {
+    day: string;
+    totalSizeBytes: string;
+}
+export interface StoragePrediction {
+    predicted: string;
+    min: string;
+    max: string;
+}
+export interface LibraryStorageResponse {
+    current: {
+        totalSizeBytes: string;
+        totalItems: number;
+        lastUpdated: string | null;
+    };
+    history: StorageHistoryPoint[];
+    growthRate: {
+        bytesPerDay: string;
+        bytesPerWeek: string;
+        bytesPerMonth: string;
+        /** Days of history behind the numbers; below minDataDays they are unusable */
+        fitDays?: number;
+        /**
+         * Which side of the mediaVersionsBackfilledAt changeover the fit ran on.
+         * 'preChangeover' means old-semantics history is standing in until the
+         * post-changeover side accumulates minDataDays of snapshots.
+         */
+        basis?: 'current' | 'preChangeover';
+    };
+    predictions: {
+        day30: StoragePrediction | null;
+        day90: StoragePrediction | null;
+        day365: StoragePrediction | null;
+        confidence: 'high' | 'medium' | 'low' | null;
+        minDataDays: number;
+        currentDataDays: number;
+        message?: string;
+    };
+}
+/** 'version' groups are one title whose single library item carries several
+ * physical files; the others group distinct items (copies) by identity. */
+export type MatchType = 'imdb' | 'tmdb' | 'tvdb' | 'fuzzy' | 'version';
+/** One physical file of a duplicate item */
+export interface DuplicateItemVersion {
+    resolution: string | null;
+    videoCodec: string | null;
+    fileSize: number | null;
+    filePath: string | null;
+    /**
+     * The same physical file already listed elsewhere in the group (equal byte
+     * size, the codebase-wide mirror heuristic). Jellyfin merged-version
+     * libraries list every file under every library entry; mirrors keep the
+     * listing honest without counting the file twice.
+     */
+    isMirror?: boolean;
+}
+export interface DuplicateItem {
+    id: string;
+    serverId: string;
+    serverName: string;
+    libraryId: string | null;
+    libraryName: string | null;
+    title: string;
+    year: number | null;
+    mediaType: string;
+    fileSize: number | null;
+    resolution: string | null;
+    versions: DuplicateItemVersion[];
+}
+export interface DuplicateGroup {
+    matchKey: string;
+    matchType: MatchType;
+    confidence: number;
+    serverCount: number;
+    /** All copies live on one server (cross-library copies or one item's versions) */
+    sameServer: boolean;
+    items: DuplicateItem[];
+    /**
+     * Distinct physical files in the group after mirror dedup. Optional only
+     * because responses cached before the field existed can still be served
+     * for up to an hour; the server always sets it.
+     */
+    uniqueFileCount?: number;
+    /** Mirror-deduped bytes: the same physical file (equal size) counts once */
+    totalStorageBytes: number;
+    /** Bytes freed by keeping only the best-quality file */
+    potentialSavingsBytes: number;
+}
+export interface DuplicatesSummary {
+    totalGroups: number;
+    totalDuplicateItems: number;
+    totalPotentialSavingsBytes: number;
+    byMatchType: {
+        imdb: number;
+        tmdb: number;
+        tvdb: number;
+        fuzzy: number;
+        version: number;
+    };
+}
+export interface DuplicatesResponse {
+    duplicates: DuplicateGroup[];
+    summary: DuplicatesSummary;
+    pagination: {
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+}
+export type StaleCategory = 'never_watched' | 'stale';
+export interface StaleItem {
+    id: string;
+    serverId: string;
+    serverName: string;
+    libraryId: string;
+    libraryName: string;
+    title: string;
+    mediaType: string;
+    year: number | null;
+    fileSize: number | null;
+    resolution: string | null;
+    addedAt: string;
+    lastWatched: string | null;
+    watchCount: number;
+    category: StaleCategory;
+    daysStale: number;
+}
+export interface StaleSummary {
+    neverWatched: {
+        count: number;
+        sizeBytes: number;
+    };
+    stale: {
+        count: number;
+        sizeBytes: number;
+    };
+    total: {
+        count: number;
+        sizeBytes: number;
+    };
+    threshold: {
+        days: number;
+    };
+}
+export interface StaleResponse {
+    items: StaleItem[];
+    summary: StaleSummary;
+    pagination: {
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+}
+/**
+ * A single "most watched" row returned by the watch endpoint.
+ * When multiple servers are in scope, the same title is collapsed
+ * into one row (deduped by external ID match key) and serverIds
+ * lists every server that has a copy of the title.
+ */
+export interface WatchItem {
+    id: string;
+    /** Primary server for this title (lowest sort value when deduped across servers). */
+    serverId: string;
+    serverName: string;
+    libraryId: string;
+    title: string;
+    mediaType: string;
+    year: number | null;
+    fileSize: number | null;
+    resolution: string | null;
+    addedAt: string;
+    /** Total play count summed across all servers for this title. */
+    watchCount: number;
+    /** Total watch duration summed across all servers for this title. */
+    totalWatchMs: number;
+    lastWatchedAt: string | null;
+    /** All server IDs that own a copy of this title (for per-title color dots). */
+    serverIds: string[];
+}
+export interface WatchSummary {
+    /** Distinct title count (deduped by external ID). */
+    totalItems: number;
+    /** Distinct titles with at least one play (deduped by external ID). */
+    watchedCount: number;
+    unwatchedCount: number;
+    watchedPct: number;
+    /** Sum of all watch durations across all servers. */
+    totalWatchMs: number;
+    avgWatchesPerItem: number;
+    /** Distinct titles fully completed (deduped by external ID), if available. */
+    completedCount: number;
+}
+export interface WatchResponse {
+    items: WatchItem[];
+    summary: WatchSummary;
+    pagination: {
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+}
+export type CompletionStatus = 'completed' | 'in_progress' | 'not_started';
+export interface CompletionItem {
+    id: string;
+    serverId: string;
+    serverName: string;
+    title: string;
+    mediaType: string;
+    completionPct: number;
+    watchedMs: number;
+    runtimeMs: number;
+    showTitle: string | null;
+    seasonNumber: number | null;
+    episodeNumber: number | null;
+    status: CompletionStatus;
+    lastWatchedAt: string | null;
+}
+export interface SeasonCompletion {
+    serverId: string;
+    serverName: string;
+    showTitle: string;
+    seasonNumber: number;
+    totalEpisodes: number;
+    completedEpisodes: number;
+    inProgressEpisodes: number;
+    completionPct: number;
+    status: CompletionStatus;
+}
+export interface SeriesCompletion {
+    serverId: string;
+    serverName: string;
+    showTitle: string;
+    totalSeasons: number;
+    completedSeasons: number;
+    totalEpisodes: number;
+    completedEpisodes: number;
+    avgSeasonCompletionPct: number;
+    status: CompletionStatus;
+}
+export interface CompletionSummary {
+    totalItems: number;
+    completedCount: number;
+    inProgressCount: number;
+    notStartedCount: number;
+    overallCompletionPct: number;
+}
+export interface CompletionPaginationInfo {
+    page: number;
+    pageSize: number;
+    total: number;
+}
+export type CompletionResponse = {
+    items: CompletionItem[];
+    summary: CompletionSummary;
+    pagination: CompletionPaginationInfo;
+} | {
+    seasons: SeasonCompletion[];
+    summary: CompletionSummary;
+    pagination: CompletionPaginationInfo;
+} | {
+    series: SeriesCompletion[];
+    summary: CompletionSummary;
+    pagination: CompletionPaginationInfo;
+};
+export type WatchedState = 'watched' | 'partial' | 'unwatched';
+export interface CatalogRowServerEntry {
+    serverId: string;
+    addedAt: string;
+    videoResolution: string | null;
+    fileSize: number | null;
+    /** Active physical files of this copy (1 for single-version titles) */
+    versionCount: number;
+}
+export interface CatalogRow {
+    mediaId: string;
+    mediaType: 'movie' | 'show';
+    title: string;
+    year: number | null;
+    genres: string[];
+    posterUrl: string | null;
+    posterVersion: string | null;
+    dominantColor: string | null;
+    servers: CatalogRowServerEntry[];
+    resolutionBest: string | null;
+    watchedState: WatchedState;
+    /** Same probe, scoped to the requesting admin's own identity instead of
+     * the anyone-grain lens - "have I personally watched this". */
+    watchedStateSelf: WatchedState;
+    plays: number;
+    viewers: number;
+}
+export interface CatalogResponseMeta {
+    /** Absolute row offset this window starts at, echoing the request. */
+    offset: number;
+    pageSize: number;
+    totalItems: number;
+    totalFileSize: number;
+}
+export interface CatalogResponse {
+    data: CatalogRow[];
+    meta: CatalogResponseMeta;
+}
+export interface CatalogLetterBucket {
+    /** '#' or 'A'..'Z'. */
+    letter: string;
+    count: number;
+}
+export interface CatalogLettersResponse {
+    letters: CatalogLetterBucket[];
+}
+export type ShelfRow = Omit<CatalogRow, 'plays' | 'viewers' | 'watchedStateSelf'>;
+/** Same period convention as statsQuerySchema/TimeRangeValue on the frontend. */
+export type ShelvesPeriod = z.infer<typeof statPeriodSchema>;
+export interface RecentlyAddedShelfRow extends ShelfRow {
+    /** Newly-tracked episode count for a show card; always null for movies. */
+    newEpisodes: number | null;
+}
+export interface MostPopularShelfRow extends ShelfRow {
+    plays: number;
+    viewers: number;
+    rank: number;
+}
+export interface DeadWeightRow extends ShelfRow {
+    fileBytes: number;
+    /** Null when the title's canonical media row has never had latest_added_at
+     * stamped (no active library copy has ever been synced). */
+    addedAt: string | null;
+}
+export interface ShelvesKpiWatchedInPeriod {
+    /** Distinct canonical titles (movies + shows) with >=1 play in the window. */
+    titlesTouched: number;
+    /** Total canonical titles (movies + shows) in scope, all-time. */
+    totalTitles: number;
+}
+export interface ShelvesKpiNewlyAdded {
+    /** Canonical titles (movies + shows) added within the window. */
+    count: number;
+    totalBytes: number;
+    /** Of the titles added in the window, how many have ever been played. */
+    playedCount: number;
+}
+export interface ShelvesKpiDeadWeight {
+    /** All-time never-watched canonical title count (not window-scoped). */
+    count: number;
+    totalBytes: number;
+}
+export interface ShelvesKpis {
+    watchedInPeriod: ShelvesKpiWatchedInPeriod;
+    /** Total watched time across the window, in seconds. */
+    hoursWatched: number;
+    newlyAdded: ShelvesKpiNewlyAdded;
+    /** Omitted when the request opts out via includeDeadWeight=false. */
+    deadWeight?: ShelvesKpiDeadWeight;
+}
+export interface ShelvesResponseMeta {
+    movies: number;
+    shows: number;
+    totalFileSize: number;
+}
+export interface ShelvesResponse {
+    period: ShelvesPeriod;
+    recentlyAddedMovies: RecentlyAddedShelfRow[];
+    recentlyAddedShows: RecentlyAddedShelfRow[];
+    mostPopularMovies: MostPopularShelfRow[];
+    mostPopularShows: MostPopularShelfRow[];
+    deadWeight?: DeadWeightRow[];
+    kpis: ShelvesKpis;
+    meta: ShelvesResponseMeta;
+}
+export interface GenreRow {
+    genre: string;
+    itemCount: number;
+    plays: number;
+    watchTimeMs: number;
+}
+export interface GenresResponse {
+    data: GenreRow[];
+}
+/** One physical file of a library copy */
+export interface MediaVersionEntry {
+    resolution: string | null;
+    videoCodec: string | null;
+    audioCodec: string | null;
+    dynamicRange: string | null;
+    container: string | null;
+    fileSize: number | null;
+}
+export interface MediaAvailabilityEntry {
+    serverId: string;
+    serverType: string;
+    libraryId: string;
+    /** Library display name, null until that server's library sync has recorded it. */
+    libraryName: string | null;
+    ratingKey: string;
+    addedAt: string;
+    removedAt: string | null;
+    videoResolution: string | null;
+    fileSize: number | null;
+    /** Show rows only: summed episode file bytes for this server+library; null for movies/episodes. */
+    episodeFileSize: number | null;
+    /** Show rows only: distinct episode resolutions ordered by frequency desc; null for movies/episodes. */
+    episodeResolutions: string[] | null;
+    /** Show rows only: active episode count for this server+library; null for movies/episodes. */
+    episodeCount: number | null;
+    /** Physical files of this copy, largest first. Empty for containers. */
+    versions: MediaVersionEntry[];
+}
+export interface MediaDetailResponse {
+    id: string;
+    mediaType: string;
+    title: string;
+    year: number | null;
+    imdbId: string | null;
+    tmdbId: number | null;
+    tvdbId: number | null;
+    genres: string[] | null;
+    showMediaId: string | null;
+    mergedIds: string[];
+    availability: MediaAvailabilityEntry[];
+    seasonCount: number | null;
+    episodeCount: number | null;
+}
+export interface MediaChildEntry {
+    id: string;
+    mediaType: 'season' | 'episode';
+    title: string;
+    seasonNumber: number | null;
+    episodeCount: number | null;
+    episodeNumber: number | null;
+    imdbId: string | null;
+    tmdbId: number | null;
+    tvdbId: number | null;
+    showMediaId: string | null;
+    genres: string[] | null;
+}
+export interface MediaChildrenResponse {
+    data: MediaChildEntry[];
+}
+export interface MediaStatsMeasures {
+    plays: number;
+    watchTimeMs: number;
+    uniqueUsers: number;
+}
+export interface MediaStatsWindow {
+    combined: MediaStatsMeasures;
+    perServer: (MediaStatsMeasures & {
+        serverId: string;
+        serverName: string | null;
+    })[];
+}
+export interface MediaStatsResponse {
+    mediaId: string;
+    mediaType: string;
+    windows: {
+        all_time: MediaStatsWindow;
+        last_30: MediaStatsWindow;
+        last_7: MediaStatsWindow;
+    };
+}
+export interface MediaWatcherEntry {
+    user: {
+        serverUserId: string;
+        userId: string;
+        serverId: string;
+        username: string | null;
+        identityName: string | null;
+        /** Identity thumbnail when set, else the server account's avatar. */
+        thumb: string | null;
+    };
+    plays: number;
+    watchTimeMs: number;
+    completionPct: number | null;
+    lastWatchedDay: string | null;
+    distinctEpisodesWatched: number | null;
+}
+export interface MediaWatchersResponse {
+    mediaId: string;
+    mediaType: string;
+    window: 'all_time' | 'last_30' | 'last_7';
+    watchers: MediaWatcherEntry[];
+}
+export interface MediaPlatformBreakdownEntry {
+    platform: string | null;
+    player: string | null;
+    plays: number;
+    watchTimeMs: number;
+}
+export interface MediaPlatformBreakdownResponse {
+    data: MediaPlatformBreakdownEntry[];
+}
+export interface SeasonHeatEpisode {
+    episodeNumber: number | null;
+    watchedState: WatchedState;
+}
+export interface SeasonHeatSeason {
+    seasonNumber: number | null;
+    title: string;
+    year: number | null;
+    episodeCount: number;
+    watchedCount: number;
+    watchedPct: number;
+    episodes: SeasonHeatEpisode[];
+}
+export interface MediaSeasonHeatResponse {
+    mediaId: string;
+    seasons: SeasonHeatSeason[];
+}
+/**
+ * A single binge-show row.
+ * When multiple servers are in scope, episodes of the same show across
+ * different servers are collapsed into one row (deduped by show matchKey).
+ */
+export interface BingeShow {
+    showTitle: string;
+    /** Server with the most episodes watched in this binge journey. */
+    primaryServerId: string;
+    thumbPath: string | null;
+    totalEpisodeWatches: number;
+    consecutiveEpisodes: number;
+    consecutivePct: number;
+    avgGapMinutes: number;
+    bingeScore: number;
+    maxEpisodesInOneDay: number;
+    /** All server IDs involved in this binge journey. */
+    serverIds: string[];
+}
+export interface HourlyDistribution {
+    hour: number;
+    watchCount: number;
+    totalWatchMs: number;
+    pctOfTotal: number;
+}
+export interface MonthlyTrend {
+    month: string;
+    watchCount: number;
+    totalWatchMs: number;
+    uniqueItems: number;
+    avgWatchesPerDay: number;
+}
+export interface PatternsResponse {
+    bingeShows: BingeShow[];
+    peakTimes: {
+        hourlyDistribution: HourlyDistribution[];
+        peakHour: number;
+        peakDayOfWeek: number;
+    };
+    seasonalTrends: {
+        monthlyTrends: MonthlyTrend[];
+        busiestMonth: string;
+        quietestMonth: string;
+    };
+    summary: {
+        totalWatchSessions: number;
+        avgSessionsPerDay: number;
+        bingeSessionsPct: number;
+    };
+}
+export type ValueCategory = 'low_value' | 'moderate_value' | 'high_value';
+export interface RoiItem {
+    id: string;
+    serverId: string;
+    serverName: string;
+    title: string;
+    mediaType: string;
+    year: number | null;
+    fileSizeBytes: number;
+    fileSizeGb: number;
+    watchCount: number;
+    totalWatchMs: number;
+    totalWatchHours: number;
+    lastWatchedAt: string | null;
+    daysSinceLastWatch: number | null;
+    watchHoursPerGb: number;
+    valueScore: number;
+    valueCategory: ValueCategory;
+    suggestDeletion: boolean;
+}
+export interface RoiSummary {
+    totalItems: number;
+    totalStorageGb: number;
+    totalWatchHours: number;
+    avgWatchHoursPerGb: number;
+    lowValueItems: number;
+    lowValueStorageGb: number;
+    potentialSavingsGb: number;
+}
+export interface ValueThresholds {
+    movie: {
+        lowValue: number;
+        highValue: number;
+    };
+    episode: {
+        lowValue: number;
+        highValue: number;
+    };
+    show: {
+        lowValue: number;
+        highValue: number;
+    };
+}
+export interface RoiResponse {
+    items: RoiItem[];
+    summary: RoiSummary;
+    thresholds: ValueThresholds;
+    pagination: {
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+}
+export interface TopMovie {
+    ratingKey: string;
+    title: string;
+    year: number | null;
+    thumbPath: string | null;
+    serverId: string;
+    /** All server IDs that own a copy of this title (for per-title color dots). */
+    serverIds?: string[];
+    totalPlays: number;
+    totalWatchHours: number;
+    uniqueViewers: number;
+    completionRate: number;
+}
+export interface TopMoviesSummary {
+    totalMovies: number;
+    totalWatchHours: number;
+}
+export interface TopMoviesResponse {
+    items: TopMovie[];
+    summary: TopMoviesSummary;
+    pagination: {
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+}
+export interface TopShow {
+    showTitle: string;
+    year: number | null;
+    thumbPath: string | null;
+    serverId: string;
+    /** All server IDs that own a copy of this title (for per-title color dots). */
+    serverIds?: string[];
+    totalEpisodeViews: number;
+    totalWatchHours: number;
+    uniqueViewers: number;
+    avgCompletionRate: number;
+    bingeScore: number;
+}
+export interface TopShowsSummary {
+    totalShows: number;
+    totalWatchHours: number;
+}
+export interface TopShowsResponse {
+    items: TopShow[];
+    summary: TopShowsSummary;
+    pagination: {
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+}
+/** Single codec entry with count and percentage */
+export interface CodecEntry {
+    codec: string;
+    count: number;
+    percentage: number;
+}
+/** Codec breakdown for a category (video, audio, or music) */
+export interface CodecBreakdown {
+    codecs: CodecEntry[];
+    total: number;
+}
+/** Response from /library/codecs endpoint */
+export interface LibraryCodecsResponse {
+    /** Video codecs for movies and episodes */
+    video: CodecBreakdown;
+    /** Audio codecs for movies and episodes */
+    audio: CodecBreakdown;
+    /** Audio channel configurations (Stereo, 5.1, 7.1, etc.) for movies and episodes */
+    channels: CodecBreakdown;
+    /** Audio codecs for music tracks */
+    music: CodecBreakdown;
+}
+/** Single resolution entry with count and percentage */
+export interface ResolutionEntry {
+    resolution: string;
+    count: number;
+    percentage: number;
+}
+/** Resolution breakdown for a media type */
+export interface ResolutionBreakdown {
+    count4k: number;
+    count1080p: number;
+    count720p: number;
+    countSd: number;
+    total: number;
+    entries: ResolutionEntry[];
+}
+/** Response from /library/resolution endpoint */
+export interface LibraryResolutionResponse {
+    /** Resolution breakdown for movies */
+    movies: ResolutionBreakdown;
+    /** Resolution breakdown for TV episodes */
+    tv: ResolutionBreakdown;
+}
+/** One server's library, for the catalog browse Library select. Grouped by
+ * server on the frontend when the account has more than one. */
+export interface LibraryOption {
+    serverId: string;
+    serverName: string;
+    libraryId: string;
+    name: string;
+    mediaType: string;
+}
+/** Response from /library/libraries endpoint */
+export interface LibrariesResponse {
+    data: LibraryOption[];
+}
+export interface BackupMetadata {
+    format: 1;
+    createdAt: string;
+    app: {
+        version: string;
+        commit: string;
+        tag: string;
+    };
+    database: {
+        pgVersion: string;
+        migrationCount: number;
+        latestMigration: string;
+        tableCount: number;
+        databaseSize: number;
+        timescaleVersion: string;
+        timescaleToolkitVersion: string | null;
+    };
+    counts: {
+        sessions: number;
+        users: number;
+        servers: number;
+        rules: number;
+        libraryItems: number;
+    };
+}
+export type RestorePhase = 'validating' | 'creating_restore_point' | 'shutting_down' | 'restoring_database' | 'running_migrations' | 'rebuilding_aggregates' | 'restarting' | 'complete' | 'failed';
+/** Ordered restore phases (excludes 'failed') for progress UI rendering. */
+export declare const RESTORE_PHASES: Exclude<RestorePhase, 'failed'>[];
+export interface RestoreProgress {
+    phase: RestorePhase;
+    message: string;
+    startedAt: string;
+    error?: string;
+    /** When phase is 'failed', indicates which phase the failure occurred in. */
+    failedAtPhase?: Exclude<RestorePhase, 'failed'>;
+}
+export type BackupType = 'manual' | 'scheduled' | 'uploaded';
+export interface BackupListItem {
+    filename: string;
+    size: number;
+    createdAt: string;
+    type: BackupType;
+    metadata: BackupMetadata;
+}
+export type BackupScheduleType = 'disabled' | 'daily' | 'weekly' | 'monthly';
+export {};
+//# sourceMappingURL=types.d.ts.map