@bnhf/prismcast 1.3.4-2026.2.19

package/dist/config/userConfig.d.ts

@@ -0,0 +1,235 @@
+import type { Config, Nullable } from "../types/index.js";
+/**
+ * Metadata describing a single configuration setting. Note: Default values are not stored here to avoid duplication. Use getNestedValue(DEFAULTS, setting.path) to get
+ * the default value for a setting.
+ */
+export interface SettingMetadata {
+    description: string;
+    dependsOn?: string;
+    disabledReason?: string;
+    displayDivisor?: number;
+    displayPrecision?: number;
+    displayUnit?: string;
+    envVar: Nullable<string>;
+    label: string;
+    max?: number;
+    min?: number;
+    path: string;
+    type: "boolean" | "float" | "host" | "integer" | "path" | "port" | "string";
+    validValues?: string[];
+    unit?: string;
+}
+/**
+ * Metadata for all configurable settings, organized by category.
+ */
+export declare const CONFIG_METADATA: Record<string, SettingMetadata[]>;
+/**
+ * Partial browser configuration for user config file.
+ */
+export interface UserBrowserConfig {
+    executablePath?: Nullable<string>;
+    initTimeout?: number;
+}
+/**
+ * Partial HLS configuration for user config file.
+ */
+export interface UserHLSConfig {
+    idleTimeout?: number;
+    maxSegments?: number;
+    segmentDuration?: number;
+}
+/**
+ * Partial logging configuration for user config file.
+ */
+export interface UserLoggingConfig {
+    maxSize?: number;
+}
+/**
+ * Partial playback configuration for user config file.
+ */
+export interface UserPlaybackConfig {
+    bufferingGracePeriod?: number;
+    channelSelectorDelay?: number;
+    channelSwitchDelay?: number;
+    clickToPlayDelay?: number;
+    iframeInitDelay?: number;
+    maxPageReloads?: number;
+    monitorInterval?: number;
+    pageReloadWindow?: number;
+    sourceReloadDelay?: number;
+    stallCountThreshold?: number;
+    stallThreshold?: number;
+    sustainedPlaybackRequired?: number;
+}
+/**
+ * Partial recovery configuration for user config file.
+ */
+export interface UserRecoveryConfig {
+    backoffJitter?: number;
+    circuitBreakerThreshold?: number;
+    circuitBreakerWindow?: number;
+    maxBackoffDelay?: number;
+    stalePageCleanupInterval?: number;
+    stalePageGracePeriod?: number;
+}
+/**
+ * Partial server configuration for user config file.
+ */
+export interface UserServerConfig {
+    host?: string;
+    port?: number;
+}
+/**
+ * Partial streaming configuration for user config file.
+ */
+export interface UserStreamingConfig {
+    audioBitsPerSecond?: number;
+    captureMode?: string;
+    frameRate?: number;
+    maxConcurrentStreams?: number;
+    maxNavigationRetries?: number;
+    navigationTimeout?: number;
+    qualityPreset?: string;
+    videoBitsPerSecond?: number;
+    videoTimeout?: number;
+}
+/**
+ * Partial channels configuration for user config file.
+ */
+export interface UserChannelsConfig {
+    disabledPredefined?: string[];
+    enabledProviders?: string[];
+}
+/**
+ * Partial HDHomeRun configuration for user config file.
+ */
+export interface UserHdhrConfig {
+    deviceId?: string;
+    enabled?: boolean;
+    friendlyName?: string;
+    port?: number;
+}
+/**
+ * User configuration with all fields optional. This is the structure of the config.json file.
+ */
+export interface UserConfig {
+    browser?: UserBrowserConfig;
+    channels?: UserChannelsConfig;
+    hdhr?: UserHdhrConfig;
+    hls?: UserHLSConfig;
+    logging?: UserLoggingConfig;
+    playback?: UserPlaybackConfig;
+    recovery?: UserRecoveryConfig;
+    server?: UserServerConfig;
+    streaming?: UserStreamingConfig;
+}
+/**
+ * Result of loading user config, includes parse error flag for UI display.
+ */
+export interface UserConfigLoadResult {
+    config: UserConfig;
+    parseError: boolean;
+    parseErrorMessage?: string;
+}
+/**
+ * Returns the path to the user configuration file.
+ * @returns The absolute path to ~/.prismcast/config.json.
+ */
+export declare function getConfigFilePath(): string;
+/**
+ * Loads user configuration from the config file. Returns an empty config if the file doesn't exist, and sets parseError if the file exists but contains invalid
+ * JSON.
+ * @returns The loaded configuration with parse status.
+ */
+export declare function loadUserConfig(): Promise<UserConfigLoadResult>;
+/**
+ * Saves user configuration to the config file. Creates the data directory if it doesn't exist.
+ * @param config - The configuration to save.
+ * @throws If the file cannot be written.
+ */
+export declare function saveUserConfig(config: UserConfig): Promise<void>;
+/**
+ * Returns a map of setting paths to their environment variable values for settings that are overridden by environment variables.
+ * @returns Map of path -> env var value for overridden settings.
+ */
+export declare function getEnvOverrides(): Map<string, string>;
+/**
+ * Hard-coded default configuration values. These are the baseline values used when neither user config nor environment variables provide a value.
+ */
+export declare const DEFAULTS: Config;
+/**
+ * Gets a value from a nested object using a dot-separated path.
+ * @param obj - The object to read from.
+ * @param settingPath - Dot-separated path (e.g., "browser.viewport.width").
+ * @returns The value at the path, or undefined if not found.
+ */
+export declare function getNestedValue(obj: unknown, settingPath: string): unknown;
+/**
+ * Sets a value in a nested object using a dot-separated path, creating intermediate objects as needed.
+ * @param obj - The object to modify.
+ * @param settingPath - Dot-separated path (e.g., "browser.viewport.width").
+ * @param value - The value to set.
+ */
+export declare function setNestedValue(obj: Record<string, unknown>, settingPath: string, value: unknown): void;
+/**
+ * Merges user configuration with defaults and environment overrides to produce the final configuration. Priority: env vars > user config > defaults.
+ * @param userConfig - User configuration from the config file.
+ * @returns The merged configuration.
+ */
+export declare function mergeConfiguration(userConfig: UserConfig): Config;
+/**
+ * Metadata for a UI tab in the configuration interface.
+ */
+export interface UITab {
+    description: string;
+    displayName: string;
+    id: string;
+    settings: SettingMetadata[];
+}
+/**
+ * Metadata for a collapsible section within the Advanced tab.
+ */
+export interface AdvancedSection {
+    displayName: string;
+    id: string;
+    settings: SettingMetadata[];
+}
+/**
+ * Metadata for a non-collapsible section within the Settings tab. Uses the same structure as AdvancedSection for consistency.
+ */
+export type SettingsSection = AdvancedSection;
+/**
+ * Looks up a setting by its path.
+ * @param settingPath - The dot-separated path (e.g., "streaming.videoBitsPerSecond").
+ * @returns The setting metadata, or undefined if not found.
+ */
+export declare function getSettingByPath(settingPath: string): SettingMetadata | undefined;
+/**
+ * Returns the sections for the Settings tab with resolved setting metadata.
+ * @returns Array of section definitions.
+ */
+export declare function getSettingsTabSections(): SettingsSection[];
+/**
+ * Returns the UI tabs for the configuration interface. The Settings tab contains commonly-used options; the Advanced tab contains everything else.
+ * @returns Array of UI tab definitions.
+ */
+export declare function getUITabs(): UITab[];
+/**
+ * Returns the collapsible sections for the Advanced tab. Each section groups settings by their storage category.
+ * @returns Array of section definitions.
+ */
+export declare function getAdvancedSections(): AdvancedSection[];
+/**
+ * Checks if two values are equal for the purpose of default comparison. Handles null, undefined, and type coercion consistently.
+ * @param value - The value to check.
+ * @param defaultValue - The default value to compare against.
+ * @returns True if the values are considered equal.
+ */
+export declare function isEqualToDefault(value: unknown, defaultValue: unknown): boolean;
+/**
+ * Filters a user configuration object to remove values that match the defaults. This produces a minimal config file containing only the settings the user has actually
+ * customized. Empty nested objects are also removed.
+ * @param config - The user configuration to filter.
+ * @returns A new configuration object containing only non-default values.
+ */
+export declare function filterDefaults(config: UserConfig): UserConfig;