TypeScript Interfaces & Types

This page documents the current contract in src/types.ts.

Constants

export const MAX_TIMESTAMP = 86400 * 365;

export function errorMessage(e: unknown): string {
  return e instanceof Error ? e.message : String(e);
}

Literal Union Types

export type UISource = 'sidebar' | 'overlay' | 'window';
export type ExportFormat = 'json' | 'csv';
export type ReconciliationAction = 'update_path' | 'remove_bookmark' | 'search_similar';
export type DuplicateHandling = 'skip' | 'replace' | 'merge';
export type BookmarkColor =
  | 'red'
  | 'orange'
  | 'yellow'
  | 'green'
  | 'blue'
  | 'purple'
  | 'pink'
  | 'grey';
export type BatchTagAction = 'add' | 'remove';
export type CollectionAssignAction = 'add' | 'remove';
export type BookmarkNavigationScope = 'file' | 'all';

`BookmarkData`

interface BookmarkData {
  id: string;
  title: string;
  timestamp: number;
  filepath: string;
  description?: string;
  createdAt: string;
  updatedAt: string;
  tags: string[];
  color?: BookmarkColor;
  endTimestamp?: number;
  pinned?: boolean;
  thumbnailPath?: string;
  chapterTitle?: string;
  subtitleText?: string;
  scratchpad?: boolean;
}

`BookmarkUpdatableFields`

interface BookmarkUpdatableFields {
  title?: string;
  description?: string;
  tags?: string[];
  color?: BookmarkColor;
  endTimestamp?: number;
  pinned?: boolean;
  scratchpad?: boolean;
}

Import/Export Types

interface ImportOptions {
  duplicateHandling?: DuplicateHandling;
  preserveIds?: boolean;
}

interface ImportResult {
  success: boolean;
  importedCount: number;
  skippedCount: number;
  errorCount: number;
  errors?: string[];
  duplicates?: number;
}

type ExportResult =
  | { success: true; format: ExportFormat; content: string }
  | { success: false; error: string; format?: ExportFormat };

`BookmarkCollection`

interface BookmarkCollection {
  id: string;
  name: string;
  description?: string;
  bookmarkIds: string[];
  color?: BookmarkColor;
  icon?: string;
  createdAt: string;
  updatedAt: string;
}

`SmartCollection`

interface SmartCollectionFilters {
  searchTerm?: string;
  fileFilter?: string;
  tags?: string[];
  showOnlyUntagged?: boolean;
  showOnlyPinned?: boolean;
  showOnlyRangeBookmarks?: boolean;
  showOnlyScratchpad?: boolean;
  dateRange?: { start: string; end: string };
}

interface SmartCollection {
  id: string;
  name: string;
  description?: string;
  filters: SmartCollectionFilters;
  color?: BookmarkColor;
  icon?: string;
  createdAt: string;
  usageCount: number;
  builtin?: boolean;
}

Playback & Sort

interface PlaybackStatus {
  duration: number;
  position: number;
  chapters: ChapterInfo[];
}

interface SortPreferences {
  sortBy: string;
  sortDirection: 'asc' | 'desc';
}

`UIMessage`

interface UIMessage {
  type: string;
  payload?: Record<string, unknown>;
  sourceUI?: UISource;
}

`UIToBackendPayloadMap` (selected current entries)

interface UIToBackendPayloadMap {
  UI_READY: { uiType: UISource };
  ADD_BOOKMARK: {
    title?: string;
    timestamp?: number;
    description?: string;
    tags?: string[];
    color?: BookmarkColor;
    endTimestamp?: number;
  };
  UPDATE_BOOKMARK: { id: string; data: BookmarkUpdatableFields };
  IMPORT_BOOKMARKS: {
    bookmarks: unknown[];
    options?: ImportOptions;
    collections?: BookmarkCollection[];
    smartCollections?: SmartCollection[];
  };
  CREATE_COLLECTION: { name: string; description?: string; color?: BookmarkColor; icon?: string };
  CREATE_SMART_COLLECTION: {
    name: string;
    description?: string;
    filters: SmartCollectionFilters;
    color?: BookmarkColor;
    icon?: string;
  };
  BATCH_TAG: { ids: string[]; tags: string[]; action: BatchTagAction };
  SET_AB_LOOP: { bookmarkId: string };
  REQUEST_THUMBNAIL: { bookmarkId: string };
  SEEK_TO_TIMESTAMP: { timestamp: number };
}

`BackendToUIPayloadMap` (selected current entries)

interface BackendToUIPayloadMap {
  BOOKMARKS_UPDATED: BookmarkData[];
  COLLECTIONS_UPDATED: BookmarkCollection[];
  SMART_COLLECTIONS_UPDATED: SmartCollection[];
  BOOKMARK_DEFAULTS: BookmarkDefaults;
  IMPORT_RESULT: ImportResult;
  EXPORT_RESULT: ExportResult;
  PLAYBACK_STATUS: PlaybackStatus;
  RESUME_POSITION: { filepath: string; timestamp: number };
  BOOKMARK_NEAR_DUPLICATE: {
    existingBookmark: BookmarkData;
    proposedTimestamp: number;
    distance: number;
  };
  THUMBNAIL_READY: { bookmarkId: string; path: string };
  QUICK_BOOKMARK_CREATED: { bookmarkId: string; timestamp: number };
  ERROR: { message: string };
}

The full payload maps live in src/types.ts; keep docs as a practical contract summary and avoid adding message names not present in source.

Core Runtime Interfaces

interface IINACore {
  status: {
    path?: string;
    currentTime?: number;
    duration?: number;
    position?: number;
    metadata?: { title?: string };
  };
  window?: { loaded: boolean };
  seek?: (time: number, exact?: boolean) => void;
  seekTo?: (seconds: number) => void;
  osd?: (message: string) => void;
  open?: (url: string) => void;
  getChapters?: () => ChapterInfo[];
}

interface IINAUIAPI {
  loadFile: (path: string) => void;
  postMessage: (name: string, data?: any) => void;
  onMessage: (name: string, callback: (data: any) => void) => void;
}

`IINARuntimeDependencies`

interface IINARuntimeDependencies {
  console: IINAConsole;
  core: IINACore;
  preferences: IINAPreferences;
  menu: IINAMenu;
  event: IINAEvent;
  sidebar: IINASidebar;
  overlay: IINAOverlay;
  standaloneWindow: IINAStandaloneWindow;
  utils: IINAUtils;
  file: IINAFile;
  mpv?: IINAMpv;
  playlist?: IINAPlaylist;
}

Type Safety Notes

User-provided text fields are sanitized with stripHtmlTags() in backend update/import flows.

Time values are validated against MAX_TIMESTAMP, and invalid range endpoints (endTimestamp) are dropped.

Usage Examples

import {
  normalizeExportResult,
  type BookmarkData,
  type BookmarkUpdatableFields,
  type ExportResult,
} from './types';

const bookmark: BookmarkData = {
  id: 'abc123',
  title: 'Epic Scene',
  timestamp: 1234.5,
  filepath: '/Movies/Example.mp4',
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString(),
  tags: ['favorite'],
};

const updates: BookmarkUpdatableFields = {
  title: 'Updated Scene',
  pinned: true,
  color: 'purple',
};

const exportResult: ExportResult = normalizeExportResult({
  success: true,
  format: 'json',
  content: JSON.stringify([bookmark]),
});

Interfaces & Types

On this page